Introduce AGENTS.md file support

karreiro · karreiro · commit 6f306eec8128 · 2025-12-02T13:24:35.000+01:00
diff --git a/.changeset/forty-steaks-decide.md b/.changeset/forty-steaks-decide.md
@@ -0,0 +1,6 @@
+---
+'@shopify/cli-kit': minor
+'@shopify/theme': minor
+---
+
+Introduce `AGENTS.md` file support in `shopify theme init`
diff --git a/packages/cli-kit/src/public/node/fs.test.ts b/packages/cli-kit/src/public/node/fs.test.ts
@@ -20,8 +20,10 @@ import {
   glob,
   detectEOL,
   copyDirectoryContents,
+  symlink,
+  fileRealPath,
 } from './fs.js'
-import {joinPath} from './path.js'
+import {joinPath, normalizePath} from './path.js'
 import {takeRandomFromArray} from '../common/array.js'
 import {beforeEach, describe, expect, test, vi} from 'vitest'
 import FastGlob from 'fast-glob'
@@ -488,3 +490,59 @@ describe('unixFileIsOwnedByCurrentUser', () => {
     })
   })
 })
+
+describe('symlink', () => {
+  test('creates a symbolic link to a file', async () => {
+    await inTemporaryDirectory(async (tmpDir) => {
+      // Given
+      const targetFile = joinPath(tmpDir, 'target.txt')
+      const linkPath = joinPath(tmpDir, 'link.txt')
+      const content = 'test content'
+      await writeFile(targetFile, content)
+
+      // When
+      await symlink(targetFile, linkPath)
+
+      // Then
+      await expect(fileExists(linkPath)).resolves.toBe(true)
+      await expect(readFile(linkPath)).resolves.toEqual(content)
+      const realPath = await fileRealPath(linkPath)
+      expect(normalizePath(realPath)).toBe(normalizePath(targetFile))
+    })
+  })
+
+  test('creates a symbolic link to a directory', async () => {
+    await inTemporaryDirectory(async (tmpDir) => {
+      // Given
+      const targetDir = joinPath(tmpDir, 'target-dir')
+      const linkPath = joinPath(tmpDir, 'link-dir')
+      const testFile = joinPath(targetDir, 'test.txt')
+      const content = 'directory content'
+      await mkdir(targetDir)
+      await writeFile(testFile, content)
+
+      // When
+      await symlink(targetDir, linkPath)
+
+      // Then
+      await expect(fileExists(linkPath)).resolves.toBe(true)
+      await expect(readFile(joinPath(linkPath, 'test.txt'))).resolves.toEqual(content)
+    })
+  })
+
+  test('symbolic link points to the correct target', async () => {
+    await inTemporaryDirectory(async (tmpDir) => {
+      // Given
+      const targetFile = joinPath(tmpDir, 'original.txt')
+      const linkPath = joinPath(tmpDir, 'symlink.txt')
+      await writeFile(targetFile, 'original content')
+
+      // When
+      await symlink(targetFile, linkPath)
+      await writeFile(targetFile, 'modified content')
+
+      // Then
+      await expect(readFile(linkPath)).resolves.toEqual('modified content')
+    })
+  })
+})
diff --git a/packages/cli-kit/src/public/node/fs.ts b/packages/cli-kit/src/public/node/fs.ts
@@ -48,6 +48,7 @@ import {
   rename as fsRename,
   unlink as fsUnlink,
   readdir as fsReaddir,
+  symlink as fsSymlink,
 } from 'fs/promises'
 import {pathToFileURL as pathToFile} from 'url'
 import * as os from 'os'
@@ -264,6 +265,31 @@ export async function renameFile(from: string, to: string): Promise<void> {
   await fsRename(from, to)
 }
 
+/**
+ * Creates a symbolic link.
+ *
+ * @param target - Path that the symlink points to.
+ * @param path - Path where the symlink will be created.
+ */
+export async function symlink(target: string, path: string): Promise<void> {
+  outputDebug(outputContent`Creating symbolic link from ${outputToken.path(path)} to ${outputToken.path(target)}...`)
+
+  // On Windows, we need to specify the type of symlink (file or dir)
+  let type: 'file' | 'dir' | 'junction' = 'file'
+
+  try {
+    const stats = await fsLstat(target)
+    if (stats.isDirectory()) {
+      type = 'junction'
+    }
+    // eslint-disable-next-line no-catch-all/no-catch-all
+  } catch {
+    // If we can't stat the target, assume it's a file
+  }
+
+  await fsSymlink(target, path, type)
+}
+
 /**
  * Synchronously removes a file at the given path.
  *
diff --git a/packages/theme/src/cli/services/init.test.ts b/packages/theme/src/cli/services/init.test.ts
@@ -1,7 +1,7 @@
-import {cloneRepoAndCheckoutLatestTag, cloneRepo, createAIInstructions} from './init.js'
+import {cloneRepoAndCheckoutLatestTag, cloneRepo, createAIInstructions, createAIInstructionFiles} from './init.js'
 import {describe, expect, vi, test, beforeEach} from 'vitest'
 import {downloadGitRepository, removeGitRemote} from '@shopify/cli-kit/node/git'
-import {rmdir, fileExists, copyDirectoryContents} from '@shopify/cli-kit/node/fs'
+import {rmdir, fileExists, readFile, writeFile, symlink} from '@shopify/cli-kit/node/fs'
 import {joinPath} from '@shopify/cli-kit/node/path'
 
 vi.mock('@shopify/cli-kit/node/git')
@@ -11,7 +11,9 @@ vi.mock('@shopify/cli-kit/node/fs', async () => {
     ...actual,
     fileExists: vi.fn(),
     rmdir: vi.fn(),
-    copyDirectoryContents: vi.fn(),
+    readFile: vi.fn(),
+    writeFile: vi.fn(),
+    symlink: vi.fn(),
     inTemporaryDirectory: vi.fn(async (callback) => {
       // eslint-disable-next-line node/no-callback-literal
       return callback('/tmp')
@@ -151,26 +153,97 @@ describe('createAIInstructions()', () => {
 
   beforeEach(() => {
     vi.mocked(joinPath).mockImplementation((...paths) => paths.join('/'))
+    vi.mocked(readFile).mockResolvedValue('Sample AI instructions content' as any)
+    vi.mocked(writeFile).mockResolvedValue()
+    vi.mocked(symlink).mockResolvedValue()
   })
 
-  test('creates AI instructions if it exists', async () => {
+  test('creates AI instructions for a single instruction type', async () => {
     // Given
     vi.mocked(downloadGitRepository).mockResolvedValue()
-    vi.mocked(copyDirectoryContents).mockResolvedValue()
 
     // When
     await createAIInstructions(destination, 'cursor')
 
     // Then
     expect(downloadGitRepository).toHaveBeenCalled()
-    expect(copyDirectoryContents).toHaveBeenCalledWith('/tmp/ai/cursor', '/path/to/theme/.cursor')
+    expect(readFile).toHaveBeenCalledWith('/tmp/ai/github/copilot-instructions.md')
+    expect(writeFile).toHaveBeenCalledWith('/path/to/theme/AGENTS.md', expect.stringContaining('# AGENTS.md'))
+    expect(symlink).not.toHaveBeenCalled()
   })
 
-  test('throws an error when the AI instructions directory does not exist', async () => {
+  test('creates AI instructions for all instruction types when "all" is selected', async () => {
     // Given
     vi.mocked(downloadGitRepository).mockResolvedValue()
-    vi.mocked(copyDirectoryContents).mockRejectedValue(new Error('Directory does not exist'))
+
+    // When
+    await createAIInstructions(destination, 'all')
+
+    // Then
+    expect(downloadGitRepository).toHaveBeenCalled()
+    expect(readFile).toHaveBeenCalledTimes(1)
+    expect(writeFile).toHaveBeenCalledTimes(1)
+    expect(symlink).toHaveBeenCalledTimes(2)
+    expect(symlink).toHaveBeenCalledWith('/path/to/theme/AGENTS.md', '/path/to/theme/copilot-instructions.md')
+    expect(symlink).toHaveBeenCalledWith('/path/to/theme/AGENTS.md', '/path/to/theme/CLAUDE.md')
+  })
+
+  test('throws an error when file operations fail', async () => {
+    // Given
+    vi.mocked(downloadGitRepository).mockResolvedValue()
+    vi.mocked(readFile).mockRejectedValue(new Error('File not found'))
 
     await expect(createAIInstructions(destination, 'cursor')).rejects.toThrow('Failed to create AI instructions')
   })
 })
+
+describe('createAIInstructionFiles()', () => {
+  const themeRoot = '/path/to/theme'
+  const agentsPath = '/path/to/theme/AGENTS.md'
+
+  beforeEach(() => {
+    vi.mocked(joinPath).mockImplementation((...paths) => paths.join('/'))
+    vi.mocked(readFile).mockResolvedValue('AI instruction content' as any)
+    vi.mocked(writeFile).mockResolvedValue()
+    vi.mocked(symlink).mockResolvedValue()
+  })
+
+  test('creates symlink for github instruction', async () => {
+    // Givin/When
+    await createAIInstructionFiles(themeRoot, agentsPath, 'github')
+
+    // Then
+    expect(symlink).toHaveBeenCalledWith('/path/to/theme/AGENTS.md', '/path/to/theme/copilot-instructions.md')
+  })
+
+  test('does not create symlink for cursor instruction (uses AGENTS.md natively)', async () => {
+    // When
+    await createAIInstructionFiles(themeRoot, agentsPath, 'cursor')
+
+    // Then
+    expect(symlink).not.toHaveBeenCalled()
+  })
+
+  test('creates symlink for claude instruction', async () => {
+    // When
+    await createAIInstructionFiles(themeRoot, agentsPath, 'claude')
+
+    // Then
+    expect(symlink).toHaveBeenCalledWith('/path/to/theme/AGENTS.md', '/path/to/theme/CLAUDE.md')
+  })
+
+  test('falls back to copying file when symlink fails with EPERM', async () => {
+    // Given
+    vi.mocked(symlink).mockRejectedValue(new Error('EPERM: operation not permitted'))
+    vi.mocked(readFile).mockResolvedValue('AGENTS.md content' as any)
+
+    // When
+    const result = await createAIInstructionFiles(themeRoot, agentsPath, 'github')
+
+    // Then
+    expect(symlink).toHaveBeenCalled()
+    expect(readFile).toHaveBeenCalledWith(agentsPath)
+    expect(writeFile).toHaveBeenCalledWith('/path/to/theme/copilot-instructions.md', 'AGENTS.md content')
+    expect(result.copiedFile).toBe('copilot-instructions.md')
+  })
+})
diff --git a/packages/theme/src/cli/services/init.ts b/packages/theme/src/cli/services/init.ts
@@ -1,13 +1,14 @@
-import {renderSelectPrompt, renderTasks} from '@shopify/cli-kit/node/ui'
+import {renderSelectPrompt, renderWarning, renderTasks} from '@shopify/cli-kit/node/ui'
 import {downloadGitRepository, removeGitRemote} from '@shopify/cli-kit/node/git'
 import {joinPath} from '@shopify/cli-kit/node/path'
-import {rmdir, fileExists, inTemporaryDirectory, copyDirectoryContents} from '@shopify/cli-kit/node/fs'
+import {rmdir, fileExists, inTemporaryDirectory, readFile, writeFile, symlink} from '@shopify/cli-kit/node/fs'
 import {AbortError} from '@shopify/cli-kit/node/error'
 
 export const SKELETON_THEME_URL = 'https://github.com/Shopify/skeleton-theme.git'
 const AI_INSTRUCTIONS_REPO_URL = 'https://github.com/Shopify/theme-liquid-docs.git'
 
 const SUPPORTED_AI_INSTRUCTIONS = {
+  all: 'All',
   github: 'VS Code (GitHub Copilot)',
   cursor: 'Cursor',
   claude: 'Claude',
@@ -57,7 +58,7 @@ async function removeDirectory(path: string) {
 
 export async function promptAIInstruction() {
   const aiChoice = (await renderSelectPrompt({
-    message: 'Include LLM instructions in the theme?',
+    message: 'Which LLM instruction file would you like to include in your theme?',
     choices: [
       ...Object.entries(SUPPORTED_AI_INSTRUCTIONS).map(([key, value]) => ({
         label: value,
@@ -71,6 +72,8 @@ export async function promptAIInstruction() {
 }
 
 export async function createAIInstructions(themeRoot: string, aiInstruction: AIInstruction) {
+  const createdFiles: string[] = []
+
   await renderTasks([
     {
       title: `Adding AI instructions into ${themeRoot}`,
@@ -81,21 +84,78 @@ export async function createAIInstructions(themeRoot: string, aiInstruction: AII
             destination: tempDir,
             shallow: true,
           })
-          const aiSrcDir = joinPath(tempDir, 'ai', aiInstruction)
-
-          let aiDestDir = themeRoot
 
-          if (aiInstruction !== 'claude') {
-            aiDestDir = joinPath(themeRoot, `.${aiInstruction}`)
-          }
+          const instructions =
+            aiInstruction === 'all'
+              ? (Object.keys(SUPPORTED_AI_INSTRUCTIONS).filter((key) => key !== 'all') as AIInstruction[])
+              : [aiInstruction]
 
           try {
-            await copyDirectoryContents(aiSrcDir, aiDestDir)
+            const sourcePath = joinPath(tempDir, 'ai', 'github', 'copilot-instructions.md')
+            const sourceContent = await readFile(sourcePath)
+
+            const agentsPath = joinPath(themeRoot, 'AGENTS.md')
+            const agentsContent = `# AGENTS.md\n\n${sourceContent}`
+            await writeFile(agentsPath, agentsContent)
+
+            const results = await Promise.all(
+              instructions.map((instruction) => createAIInstructionFiles(themeRoot, agentsPath, instruction)),
+            )
+
+            // Collect files that were copied instead of symlinked
+            results.forEach((result) => {
+              if (result.copiedFile) {
+                createdFiles.push(result.copiedFile)
+              }
+            })
           } catch (error) {
             throw new AbortError('Failed to create AI instructions')
           }
         })
       },
     },
   ])
+
+  if (createdFiles.length > 0) {
+    renderWarning({
+      headline: 'Files created instead of symlinks.',
+      body: `Shopify CLI attempted to create symbolic links between AGENTS.md and ${createdFiles.join(
+        ', ',
+      )}, but your system doesn't have Developer Mode enabled or symlinks are disabled. Separate files were created instead.`,
+    })
+  }
+}
+
+export async function createAIInstructionFiles(
+  themeRoot: string,
+  agentsPath: string,
+  instruction: AIInstruction,
+): Promise<{copiedFile?: string}> {
+  if (instruction === 'cursor') {
+    // Cursor natively supports AGENTS.md, so no symlink needed
+    return {}
+  }
+
+  const symlinkMap: {[key in Exclude<AIInstruction, 'all' | 'cursor'>]: string} = {
+    github: 'copilot-instructions.md',
+    claude: 'CLAUDE.md',
+  }
+
+  const symlinkName = symlinkMap[instruction as Exclude<AIInstruction, 'all' | 'cursor'>]
+  const symlinkPath = joinPath(themeRoot, symlinkName)
+
+  try {
+    await symlink(agentsPath, symlinkPath)
+    return {}
+  } catch (error) {
+    // On Windows, symlinks may require admin privileges or Developer Mode
+    // Fall back to copying the file if symlink creation fails
+    if (error instanceof Error) {
+      const agentsContent = await readFile(agentsPath)
+      await writeFile(symlinkPath, agentsContent)
+      return {copiedFile: symlinkName}
+    } else {
+      throw error
+    }
+  }
 }
