Introduce AGENTS.md file support

Author: karreiro

packages/cli-kit/src/public/node/fs.test.ts

@@ -20,6 +20,8 @@ import {
   glob,
   detectEOL,
   copyDirectoryContents,
+  symlink,
+  fileRealPath,
 } from './fs.js'
 import {joinPath} from './path.js'
 import {takeRandomFromArray} from '../common/array.js'
@@ -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(realPath).toBe(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')
+    })
+  })
+})

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,17 @@ 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)}...`)
+  await fsSymlink(target, path)
+}
+
 /**
  * Synchronously removes a file at the given path.
  *

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,102 @@ 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).toHaveBeenCalledWith('/path/to/theme/AGENTS.md', '/path/to/theme/.cursorrules')
   })
 
-  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()
+    // github, cursor, claude
+    expect(readFile).toHaveBeenCalledTimes(3)
+    expect(writeFile).toHaveBeenCalledTimes(3)
+    expect(symlink).toHaveBeenCalledTimes(3)
+    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/.cursorrules')
+    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 tempDir = '/tmp'
+  const themeRoot = '/path/to/theme'
+
+  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 AGENTS.md with prepended header for github instruction', async () => {
+    // When
+    await createAIInstructionFiles(tempDir, themeRoot, 'github')
+
+    // Then
+    expect(readFile).toHaveBeenCalledWith('/tmp/ai/github/copilot-instructions.md')
+    expect(writeFile).toHaveBeenCalledWith('/path/to/theme/AGENTS.md', '# AGENTS.md\n\nAI instruction content')
+    expect(symlink).toHaveBeenCalledWith('/path/to/theme/AGENTS.md', '/path/to/theme/copilot-instructions.md')
+  })
+
+  test('creates AGENTS.md and .cursorrules symlink for cursor instruction', async () => {
+    // When
+    await createAIInstructionFiles(tempDir, themeRoot, 'cursor')
+
+    // Then
+    expect(readFile).toHaveBeenCalledWith('/tmp/ai/github/copilot-instructions.md')
+    expect(writeFile).toHaveBeenCalledWith('/path/to/theme/AGENTS.md', '# AGENTS.md\n\nAI instruction content')
+    expect(symlink).toHaveBeenCalledWith('/path/to/theme/AGENTS.md', '/path/to/theme/.cursorrules')
+  })
+
+  test('creates AGENTS.md and CLAUDE.md symlink for claude instruction', async () => {
+    // When
+    await createAIInstructionFiles(tempDir, themeRoot, 'claude')
+
+    // Then
+    expect(readFile).toHaveBeenCalledWith('/tmp/ai/github/copilot-instructions.md')
+    expect(writeFile).toHaveBeenCalledWith('/path/to/theme/AGENTS.md', '# AGENTS.md\n\nAI instruction content')
+    expect(symlink).toHaveBeenCalledWith('/path/to/theme/AGENTS.md', '/path/to/theme/CLAUDE.md')
+  })
+
+  test('prepends header to source content', async () => {
+    // Given
+    const sourceContent = 'Original content from repo'
+    vi.mocked(readFile).mockResolvedValue(sourceContent as any)
+
+    // When
+    await createAIInstructionFiles(tempDir, themeRoot, 'github')
+
+    // Then
+    expect(writeFile).toHaveBeenCalledWith('/path/to/theme/AGENTS.md', `# AGENTS.md\n\n${sourceContent}`)
+  })
+})

packages/theme/src/cli/services/init.ts

@@ -1,13 +1,14 @@
 import {renderSelectPrompt, 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,
@@ -81,16 +82,16 @@ 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)
+            await Promise.all(
+              instructions.map((instruction) => createAIInstructionFiles(tempDir, themeRoot, instruction)),
+            )
           } catch (error) {
             throw new AbortError('Failed to create AI instructions')
           }
@@ -99,3 +100,23 @@ export async function createAIInstructions(themeRoot: string, aiInstruction: AII
     },
   ])
 }
+
+export async function createAIInstructionFiles(tempDir: string, themeRoot: string, instruction: AIInstruction) {
+  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 symlinkMap: {[key in Exclude<AIInstruction, 'all'>]: string} = {
+    github: 'copilot-instructions.md',
+    cursor: '.cursorrules',
+    claude: 'CLAUDE.md',
+  }
+
+  const symlinkName = symlinkMap[instruction as Exclude<AIInstruction, 'all'>]
+  const symlinkPath = joinPath(themeRoot, symlinkName)
+
+  await symlink(agentsPath, symlinkPath)
+}