.

.

Author: karreiro

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

@@ -273,7 +273,24 @@ export async function renameFile(from: string, to: string): Promise<void> {
  */
 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)
+
+  // On Windows, we need to specify the type of symlink (file or dir)
+  // Check if target is a directory
+  let type: 'file' | 'dir' | 'junction' = 'file'
+
+  try {
+    const stats = await fsLstat(target)
+    if (stats.isDirectory()) {
+      // Use junction for directories on Windows (doesn't require admin privileges)
+      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
+    // This handles cases where the target doesn't exist yet
+  }
+
+  await fsSymlink(target, path, type)
 }
 
 /**

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

@@ -181,9 +181,10 @@ describe('createAIInstructions()', () => {
 
     // Then
     expect(downloadGitRepository).toHaveBeenCalled()
-    // github, cursor, claude
-    expect(readFile).toHaveBeenCalledTimes(3)
-    expect(writeFile).toHaveBeenCalledTimes(3)
+    // Read source file once, write AGENTS.md once
+    expect(readFile).toHaveBeenCalledTimes(1)
+    expect(writeFile).toHaveBeenCalledTimes(1)
+    // Create symlinks for github, cursor, claude
     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')
@@ -200,8 +201,8 @@ describe('createAIInstructions()', () => {
 })
 
 describe('createAIInstructionFiles()', () => {
-  const tempDir = '/tmp'
   const themeRoot = '/path/to/theme'
+  const agentsPath = '/path/to/theme/AGENTS.md'
 
   beforeEach(() => {
     vi.mocked(joinPath).mockImplementation((...paths) => paths.join('/'))
@@ -210,45 +211,53 @@ describe('createAIInstructionFiles()', () => {
     vi.mocked(symlink).mockResolvedValue()
   })
 
-  test('creates AGENTS.md with prepended header for github instruction', async () => {
+  test('creates symlink for github instruction', async () => {
     // When
-    await createAIInstructionFiles(tempDir, themeRoot, 'github')
+    const result = await createAIInstructionFiles(themeRoot, agentsPath, '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')
+    expect(result.copiedFile).toBeUndefined()
   })
 
-  test('creates AGENTS.md and .cursorrules symlink for cursor instruction', async () => {
+  test('creates symlink for cursor instruction', async () => {
     // When
-    await createAIInstructionFiles(tempDir, themeRoot, 'cursor')
+    const result = await createAIInstructionFiles(themeRoot, agentsPath, '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')
+    expect(result.copiedFile).toBeUndefined()
   })
 
-  test('creates AGENTS.md and CLAUDE.md symlink for claude instruction', async () => {
+  test('creates symlink for claude instruction', async () => {
     // When
-    await createAIInstructionFiles(tempDir, themeRoot, 'claude')
+    const result = await createAIInstructionFiles(themeRoot, agentsPath, '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')
+    expect(result.copiedFile).toBeUndefined()
   })
 
-  test('prepends header to source content', async () => {
+  test('falls back to copying file when symlink fails with EPERM', async () => {
     // Given
-    const sourceContent = 'Original content from repo'
-    vi.mocked(readFile).mockResolvedValue(sourceContent as any)
+    vi.mocked(symlink).mockRejectedValue(new Error('EPERM: operation not permitted'))
+    vi.mocked(readFile).mockResolvedValue('AGENTS.md content' as any)
 
     // When
-    await createAIInstructionFiles(tempDir, themeRoot, 'github')
+    const result = await createAIInstructionFiles(themeRoot, agentsPath, 'github')
 
     // Then
-    expect(writeFile).toHaveBeenCalledWith('/path/to/theme/AGENTS.md', `# AGENTS.md\n\n${sourceContent}`)
+    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')
+  })
+
+  test('throws error when symlink fails with non-EPERM error', async () => {
+    // Given
+    vi.mocked(symlink).mockRejectedValue(new Error('Some other error'))
+
+    // When/Then
+    await expect(createAIInstructionFiles(themeRoot, agentsPath, 'github')).rejects.toThrow('Some other error')
   })
 })

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

@@ -1,4 +1,4 @@
-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, readFile, writeFile, symlink} from '@shopify/cli-kit/node/fs'
@@ -72,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}`,
@@ -89,26 +91,47 @@ export async function createAIInstructions(themeRoot: string, aiInstruction: AII
               : [aiInstruction]
 
           try {
-            await Promise.all(
-              instructions.map((instruction) => createAIInstructionFiles(tempDir, themeRoot, instruction)),
+            const sourcePath = joinPath(tempDir, 'ai', 'github', 'copilot-instructions.md')
+            const sourceContent = await readFile(sourcePath)
+
+            // Create AGENTS.md once
+            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')
           }
         })
       },
     },
   ])
-}
 
-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)
+  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}> {
   const symlinkMap: {[key in Exclude<AIInstruction, 'all'>]: string} = {
     github: 'copilot-instructions.md',
     cursor: '.cursorrules',
@@ -118,5 +141,18 @@ export async function createAIInstructionFiles(tempDir: string, themeRoot: strin
   const symlinkName = symlinkMap[instruction as Exclude<AIInstruction, 'all'>]
   const symlinkPath = joinPath(themeRoot, symlinkName)
 
-  await symlink(agentsPath, symlinkPath)
+  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
+    }
+  }
 }