feat: allow custom docs folder (#32)

* feat: allow custom docs folder path via docsDir config

Add a docsDir option to .ai-devkit.json that allows users to
customize where AI documentation is stored instead of the hardcoded
docs/ai path. The init command now prompts for the docs directory,
and templates also support the new field.

Closes #31

* Add --docs-dir CLI flag to init command

Allows setting custom docs directory non-interactively via
`ai-devkit init --docs-dir .ai-docs`. Priority: CLI flag >
template config > interactive prompt > default (docs/ai).

* fix: replace hardcoded docs/ai in command templates with custom docsDir

When copying command templates, replace all `docs/ai` references with
the configured docsDir value. This affects copyCommands, copyGeminiSpecificFiles,
and copyCommandsToGlobal. Also fix init command to use docsDir-aware
template manager for environment setup.

* refactor: address PR review feedback for custom docs dir

- Rename config field from flat `docsDir` to namespaced `paths.docs`
- Change TemplateManager constructor to options object pattern
- Use {{docsDir}} template variables instead of naive string replacement
- Separate docsDir from LintOptions into standalone parameter
- Remove interactive prompt for docsDir during init
- Remove redundant DOCS_DIR constant re-export

* refactor: remove docsDir from InitTemplateConfig, use paths.docs only

Since the feature hasn't shipped yet, there's no need for backward
compatibility with docsDir in templates. This eliminates the dual-schema
confusion and simplifies the fallback chain.

* test: remove redundant docsDir unknown field test

The existing 'throws when unknown field exists' test already covers
this code path.

---------

Co-authored-by: sotatek <sotatek@Davids-Mac.local>

Author: hiiamtrong

package-lock.json

@@ -3,6 +3,12 @@ import { ui } from '../../util/terminal-ui';
 import { lintCommand, renderLintReport } from '../../commands/lint';
 import { LintReport, runLintChecks } from '../../services/lint/lint.service';
 
+jest.mock('../../lib/Config', () => ({
+  ConfigManager: jest.fn(() => ({
+    getDocsDir: jest.fn<() => Promise<string>>().mockResolvedValue('docs/ai')
+  }))
+}));
+
 jest.mock('../../services/lint/lint.service', () => ({
   runLintChecks: jest.fn()
 }));
@@ -46,7 +52,7 @@ describe('lint command', () => {
 
     await lintCommand({ feature: 'lint-command', json: true });
 
-    expect(mockedRunLintChecks).toHaveBeenCalledWith({ feature: 'lint-command', json: true });
+    expect(mockedRunLintChecks).toHaveBeenCalledWith({ feature: 'lint-command', json: true }, 'docs/ai');
     expect(mockedUi.text).toHaveBeenCalledWith(JSON.stringify(report, null, 2));
     expect(process.exitCode).toBe(0);
   });

packages/cli/src/__tests__/commands/lint.test.ts

@@ -254,6 +254,72 @@ describe('ConfigManager', () => {
     });
   });
 
+  describe('getDocsDir', () => {
+    it('should return custom docsDir when set in config', async () => {
+      const config: DevKitConfig = {
+        version: '1.0.0',
+        paths: { docs: '.ai-docs' },
+        environments: [],
+        phases: [],
+        createdAt: '2024-01-01T00:00:00.000Z',
+        updatedAt: '2024-01-01T00:00:00.000Z'
+      };
+
+      (mockFs.pathExists as any).mockResolvedValue(true);
+      (mockFs.readJson as any).mockResolvedValue(config);
+
+      const result = await configManager.getDocsDir();
+
+      expect(result).toBe('.ai-docs');
+    });
+
+    it('should return default docs/ai when docsDir is not set', async () => {
+      const config: DevKitConfig = {
+        version: '1.0.0',
+        environments: [],
+        phases: [],
+        createdAt: '2024-01-01T00:00:00.000Z',
+        updatedAt: '2024-01-01T00:00:00.000Z'
+      };
+
+      (mockFs.pathExists as any).mockResolvedValue(true);
+      (mockFs.readJson as any).mockResolvedValue(config);
+
+      const result = await configManager.getDocsDir();
+
+      expect(result).toBe('docs/ai');
+    });
+
+    it('should return default docs/ai when config does not exist', async () => {
+      (mockFs.pathExists as any).mockResolvedValue(false);
+
+      const result = await configManager.getDocsDir();
+
+      expect(result).toBe('docs/ai');
+    });
+  });
+
+  describe('setDocsDir', () => {
+    it('should update docsDir in config', async () => {
+      const config: DevKitConfig = {
+        version: '1.0.0',
+        environments: [],
+        phases: [],
+        createdAt: '2024-01-01T00:00:00.000Z',
+        updatedAt: '2024-01-01T00:00:00.000Z'
+      };
+
+      (mockFs.pathExists as any).mockResolvedValue(true);
+      (mockFs.readJson as any).mockResolvedValue(config);
+      (mockFs.writeJson as any).mockResolvedValue(undefined);
+
+      const result = await configManager.setDocsDir('.ai-docs');
+
+      expect(result.paths?.docs).toBe('.ai-docs');
+      expect(mockFs.writeJson).toHaveBeenCalled();
+    });
+  });
+
   describe('getEnvironments', () => {
     it('should return environments array when config exists', async () => {
       const config: DevKitConfig = {

packages/cli/src/__tests__/lib/Config.test.ts

@@ -88,6 +88,44 @@ environments:
     );
   });
 
+  it('loads template with paths.docs config', async () => {
+    mockFs.pathExists.mockResolvedValue(true as never);
+    mockFs.readFile.mockResolvedValue(`
+paths:
+  docs: .ai-docs
+environments:
+  - claude
+phases:
+  - requirements
+` as never);
+
+    const result = await loadInitTemplate('/tmp/init.yaml');
+
+    expect(result.paths?.docs).toBe('.ai-docs');
+    expect(result.environments).toEqual(['claude']);
+  });
+
+  it('throws when paths.docs is empty string', async () => {
+    mockFs.pathExists.mockResolvedValue(true as never);
+    mockFs.readFile.mockResolvedValue(`
+paths:
+  docs: "  "
+` as never);
+
+    await expect(loadInitTemplate('/tmp/init.yaml')).rejects.toThrow(
+      '"paths.docs" must be a non-empty string'
+    );
+  });
+
+  it('throws when paths is not an object', async () => {
+    mockFs.pathExists.mockResolvedValue(true as never);
+    mockFs.readFile.mockResolvedValue(JSON.stringify({ paths: 'invalid' }) as never);
+
+    await expect(loadInitTemplate('/tmp/init.json')).rejects.toThrow(
+      '"paths" must be an object'
+    );
+  });
+
   it('throws when unknown field exists', async () => {
     mockFs.pathExists.mockResolvedValue(true as never);
     mockFs.readFile.mockResolvedValue(`

packages/cli/src/__tests__/lib/InitTemplate.test.ts

@@ -14,7 +14,7 @@ describe('TemplateManager', () => {
   beforeEach(() => {
     mockFs = fs as jest.Mocked<typeof fs>;
     mockGetEnvironment = require('../../util/env').getEnvironment as jest.MockedFunction<any>;
-    templateManager = new TemplateManager('/test/target');
+    templateManager = new TemplateManager({ targetDir: '/test/target' });
 
     jest.clearAllMocks();
   });
@@ -36,10 +36,12 @@ describe('TemplateManager', () => {
       (mockFs.pathExists as any).mockResolvedValueOnce(true);
 
       (mockFs.readdir as any).mockResolvedValue(['command1.md', 'command2.toml']);
+      (mockFs.readFile as any).mockResolvedValue('command content');
+      (mockFs.writeFile as any).mockResolvedValue(undefined);
 
       const result = await (templateManager as any).setupSingleEnvironment(env);
 
-      expect(mockFs.copy).toHaveBeenCalledTimes(1);
+      expect(mockFs.writeFile).toHaveBeenCalledTimes(1);
       expect(result).toEqual([path.join(templateManager['targetDir'], env.commandPath, 'command1.md')]);
     });
 
@@ -56,6 +58,8 @@ describe('TemplateManager', () => {
       (mockFs.pathExists as any).mockResolvedValueOnce(true);
 
       (mockFs.readdir as any).mockResolvedValue(['command1.md']);
+      (mockFs.readFile as any).mockResolvedValue('command content');
+      (mockFs.writeFile as any).mockResolvedValue(undefined);
 
       const result = await (templateManager as any).setupSingleEnvironment(env);
 
@@ -79,27 +83,52 @@ describe('TemplateManager', () => {
       (mockFs.pathExists as any).mockResolvedValueOnce(true); // commands directory exists
 
       (mockFs.readdir as any).mockResolvedValue(mockCommandFiles);
+      (mockFs.readFile as any).mockResolvedValue('command content');
+      (mockFs.writeFile as any).mockResolvedValue(undefined);
 
       const result = await (templateManager as any).setupSingleEnvironment(env);
 
       expect(mockFs.ensureDir).toHaveBeenCalledWith(
         path.join(templateManager['targetDir'], env.commandPath)
       );
 
-      // Should only copy .md files (not .toml files)
-      expect(mockFs.copy).toHaveBeenCalledWith(
-        path.join(templateManager['templatesDir'], 'commands', 'command1.md'),
-        path.join(templateManager['targetDir'], env.commandPath, 'command1.md')
+      // Should only write .md files (not .toml files)
+      expect(mockFs.writeFile).toHaveBeenCalledWith(
+        path.join(templateManager['targetDir'], env.commandPath, 'command1.md'),
+        'command content'
       );
-      expect(mockFs.copy).toHaveBeenCalledWith(
-        path.join(templateManager['templatesDir'], 'commands', 'command3.md'),
-        path.join(templateManager['targetDir'], env.commandPath, 'command3.md')
+      expect(mockFs.writeFile).toHaveBeenCalledWith(
+        path.join(templateManager['targetDir'], env.commandPath, 'command3.md'),
+        'command content'
       );
 
       expect(result).toContain(path.join(templateManager['targetDir'], env.commandPath, 'command1.md'));
       expect(result).toContain(path.join(templateManager['targetDir'], env.commandPath, 'command3.md'));
     });
 
+    it('should replace docs/ai with custom docsDir in command content', async () => {
+      const customManager = new TemplateManager({ targetDir: '/test/target', docsDir: '.ai-docs' });
+      const env: EnvironmentDefinition = {
+        code: 'test-env',
+        name: 'Test Environment',
+        contextFileName: '.test-context.md',
+        commandPath: '.test',
+        isCustomCommandPath: false
+      };
+
+      (mockFs.pathExists as any).mockResolvedValueOnce(true);
+      (mockFs.readdir as any).mockResolvedValue(['command1.md']);
+      (mockFs.readFile as any).mockResolvedValue('Review {{docsDir}}/design/feature-{name}.md and {{docsDir}}/requirements/.');
+      (mockFs.writeFile as any).mockResolvedValue(undefined);
+
+      await (customManager as any).setupSingleEnvironment(env);
+
+      expect(mockFs.writeFile).toHaveBeenCalledWith(
+        path.join(customManager['targetDir'], env.commandPath, 'command1.md'),
+        'Review .ai-docs/design/feature-{name}.md and .ai-docs/requirements/.'
+      );
+    });
+
     it('should skip commands when isCustomCommandPath is true', async () => {
       const env: EnvironmentDefinition = {
         code: 'test-env',
@@ -235,6 +264,25 @@ This is the prompt content.`;
       );
       expect(result).toBe(path.join(templateManager['targetDir'], 'docs', 'ai', phase, 'README.md'));
     });
+
+    it('should use custom docsDir when provided', async () => {
+      const customManager = new TemplateManager({ targetDir: '/test/target', docsDir: '.ai-docs' });
+      const phase: Phase = 'design';
+
+      (mockFs.ensureDir as any).mockResolvedValue(undefined);
+      (mockFs.copy as any).mockResolvedValue(undefined);
+
+      const result = await customManager.copyPhaseTemplate(phase);
+
+      expect(mockFs.ensureDir).toHaveBeenCalledWith(
+        path.join(customManager['targetDir'], '.ai-docs', phase)
+      );
+      expect(mockFs.copy).toHaveBeenCalledWith(
+        path.join(customManager['templatesDir'], 'phases', `${phase}.md`),
+        path.join(customManager['targetDir'], '.ai-docs', phase, 'README.md')
+      );
+      expect(result).toBe(path.join(customManager['targetDir'], '.ai-docs', phase, 'README.md'));
+    });
   });
 
   describe('fileExists', () => {
@@ -263,6 +311,20 @@ This is the prompt content.`;
       );
       expect(result).toBe(false);
     });
+
+    it('should check custom docsDir path when provided', async () => {
+      const customManager = new TemplateManager({ targetDir: '/test/target', docsDir: 'custom/docs' });
+      const phase: Phase = 'testing';
+
+      (mockFs.pathExists as any).mockResolvedValue(true);
+
+      const result = await customManager.fileExists(phase);
+
+      expect(mockFs.pathExists).toHaveBeenCalledWith(
+        path.join(customManager['targetDir'], 'custom/docs', phase, 'README.md')
+      );
+      expect(result).toBe(true);
+    });
   });
 
   describe('setupMultipleEnvironments', () => {
@@ -633,12 +695,13 @@ description: Test
       mockGetEnvironment.mockReturnValue(envWithGlobal);
       (mockFs.ensureDir as any).mockResolvedValue(undefined);
       (mockFs.readdir as any).mockResolvedValue(mockCommandFiles);
-      (mockFs.copy as any).mockResolvedValue(undefined);
+      (mockFs.readFile as any).mockResolvedValue('command content');
+      (mockFs.writeFile as any).mockResolvedValue(undefined);
 
       const result = await templateManager.copyCommandsToGlobal('antigravity');
 
       expect(mockFs.ensureDir).toHaveBeenCalled();
-      expect(mockFs.copy).toHaveBeenCalledTimes(2); // Only .md files
+      expect(mockFs.writeFile).toHaveBeenCalledTimes(2); // Only .md files
       expect(result).toHaveLength(2);
     });
 
@@ -656,11 +719,12 @@ description: Test
       mockGetEnvironment.mockReturnValue(envWithGlobal);
       (mockFs.ensureDir as any).mockResolvedValue(undefined);
       (mockFs.readdir as any).mockResolvedValue(mockCommandFiles);
-      (mockFs.copy as any).mockResolvedValue(undefined);
+      (mockFs.readFile as any).mockResolvedValue('command content');
+      (mockFs.writeFile as any).mockResolvedValue(undefined);
 
       const result = await templateManager.copyCommandsToGlobal('codex');
 
-      expect(mockFs.copy).toHaveBeenCalledTimes(1);
+      expect(mockFs.writeFile).toHaveBeenCalledTimes(1);
       expect(result).toHaveLength(1);
     });