acp-vscode 0.3.8 → 0.4.0

package/.github/copilot-instructions.md

@@ -0,0 +1,80 @@
+# Copilot Instructions for acp-vscode
+
+These instructions guide AI assistants (like GitHub Copilot) in maintaining code quality and best practices for the acp-vscode project.
+
+## Quality Checks
+
+After making any major changes to the codebase, **you must run the quality checks script and ensure all checks pass**:
+
+```bash
+./scripts/quality-checks.sh
+```
+
+This script runs:
+- **ESLint** - Validates code style and best practices
+- **Jest Tests** - Ensures all unit tests pass
+- **package.json Validation** - Verifies the package configuration is valid
+
+### When to Run Quality Checks
+
+Run quality checks after:
+- Implementing new features
+- Fixing bugs
+- Refactoring code
+- Adding or modifying tests
+- Updating dependencies
+- Making any changes to source files
+
+### Fixing Quality Check Failures
+
+If any quality check fails:
+
+1. **Read the error output carefully** - Identify the specific files and line numbers that failed
+2. **Fix the issues incrementally** - Make small, focused changes to address each failure
+3. **Re-run the quality checks** - After each fix, run the quality checks again to verify the change
+4. **Iterate until all checks pass** - Continue fixing and testing until `./scripts/quality-checks.sh` exits with code 0
+
+### ESLint Failures
+
+If ESLint fails:
+- Review the linting rules in the project configuration
+- Fix code style issues (indentation, spacing, naming conventions)
+- Follow the existing code style patterns in the codebase
+- Many ESLint errors can be automatically fixed with: `npm run lint -- --fix`
+
+### Jest Test Failures
+
+If tests fail:
+- Run the test suite with: `npm test`
+- Review the test output to understand what assertions failed
+- Update or add tests to cover the new code
+- Ensure backward compatibility with existing tests
+- Do not disable or skip tests to make them pass
+
+## Code Quality Standards
+
+### Guidelines
+
+- **Consistency** - Follow the existing code style and patterns in the codebase
+- **Testing** - All new features should have corresponding tests
+- **Documentation** - Update README.md and other documentation as needed
+- **Git Hygiene** - Make atomic, well-described commits
+
+### Before Submitting Changes
+
+1. Run `./scripts/quality-checks.sh` and ensure all checks pass
+2. Verify no new warnings or errors were introduced
+3. Test the changes manually if applicable
+4. Review the changes for clarity and correctness
+
+## References
+
+- CI/CD Pipeline: [.github/workflows/ci.yml](./workflows/ci.yml)
+- Release Process: [scripts/release.sh](../scripts/release.sh)
+- Quality Checks: [scripts/quality-checks.sh](../scripts/quality-checks.sh)
+
+## Related Configuration Files
+
+- [package.json](../../package.json) - Project metadata and scripts
+- [jest.config.cjs](../../jest.config.cjs) - Jest test configuration
+- [.eslintrc or similar]() - ESLint configuration (if present)

package/README.md

@@ -102,6 +102,9 @@ acp-vscode list --refresh
 - Offline testing / injecting a local index
   - For tests or offline usage you can set `ACP_INDEX_JSON` to a JSON string representing the index. This bypasses network fetching entirely and the CLI will use the provided index verbatim.
 
+- Nested folder support
+  - The CLI automatically scans for prompts, agents, instructions, and skills at any folder depth. Items can be organized at the root level (`prompts/`, `agents/`, etc.) or in nested folders like `.github/prompts/`, `workflows/prompts/`, etc.
+
 - Multiple upstream repos
   - To index multiple repos set `ACP_REPOS_JSON` to a JSON array of repo descriptors. Example:
 
@@ -138,6 +141,8 @@ ACP_REPOS_JSON
 
 To support multiple upstream repos, set `ACP_REPOS_JSON` to a JSON array describing the repositories to index. Each repo object should contain at least an `id` and a `treeUrl`. Optionally include `rawBase` (the base URL to fetch raw file contents).
 
+**Important:** The default awesome-copilot repo is always included alongside your configured repos unless you explicitly set `ACP_EXCLUDE_DEFAULT_REPO=true` (environment variable). This means your custom repos are *additive* to the default, not replacements.
+
 Example:
 
 ```json
@@ -152,13 +157,28 @@ When multiple repos contain files with the same `id`, the fetcher adds an `_conf
 Local repo file (acp-repos.json)
 -------------------------------
 
-In addition to `ACP_REPOS_JSON` the CLI will look for a file named `acp-repos.json` in the `~/.acp` directory and use it to populate the upstream repo list if the environment variable is not set. This file should contain the same JSON array format as `ACP_REPOS_JSON` and is useful for per-user configuration without exporting environment variables. Precedence when building the repos list is:
+In addition to `ACP_REPOS_JSON` the CLI will look for a file named `acp-repos.json` in a local configuration directory and use it to populate the upstream repo list if the environment variable is not set. In normal usage (when `NODE_ENV` is not `development` or `test`), this file is expected at `~/.acp/acp-repos.json`. When `NODE_ENV` is set to `development` or `test`, the CLI instead looks for `./acp-repos.json` in the current working directory; this behavior exists primarily to support local development and automated tests. This file should contain the same JSON array format as `ACP_REPOS_JSON` and is useful for per-user configuration without exporting environment variables. **Like `ACP_REPOS_JSON`, the default awesome-copilot repo is always included alongside repos from this file unless you set `ACP_EXCLUDE_DEFAULT_REPO=true`.** Precedence when building the repos list is:
+
+1. `ACP_REPOS_JSON` environment variable (highest priority) — default repo is always added
+2. Local `acp-repos.json` file (if `ACP_REPOS_JSON` not set): in `~/.acp/acp-repos.json` by default, or `./acp-repos.json` when `NODE_ENV` is `development` or `test` — default repo is always added
+3. Built-in default repo (github/awesome-copilot) — used as fallback
+
+To exclude the default awesome-copilot repo entirely, set the `ACP_EXCLUDE_DEFAULT_REPO` environment variable to `true` or `1`.
+
+ACP_EXCLUDE_DEFAULT_REPO
 
-1. `ACP_REPOS_JSON` environment variable (highest priority)
-2. `~/.acp/acp-repos.json` file (if present)
-3. Built-in default repo (github/awesome-copilot)
+By default, the awesome-copilot repository is always included in the index regardless of whether you've configured custom repos via `ACP_REPOS_JSON` or `acp-repos.json`. This makes custom repos *additive* rather than replacements.
+
+If you want to exclude the default awesome-copilot repo, set `ACP_EXCLUDE_DEFAULT_REPO=true` or `ACP_EXCLUDE_DEFAULT_REPO=1`:
+
+```bash
+# Exclude default repo and use only custom repos
+export ACP_EXCLUDE_DEFAULT_REPO=true
+export ACP_REPOS_JSON='[{"id":"myrepo","treeUrl":"...","rawBase":"..."}]'
+acp-vscode list
+```
 
-Note: when running in development or tests the CLI will attempt to read `acp-repos.json` from the current working directory instead of `~/.acp` to keep test fixtures and local development predictable.
+When this is set to any value other than `true` or `1`, the default repo will be included (default behavior).
 
 Dry-run:
 

package/__tests__/commands-actions.test.js

@@ -5,6 +5,7 @@ function makeCli() {
     _action: null,
     command() { return cli; },
     option() { return cli; },
+    example() { return cli; },
     action(fn) { cli._action = fn; return cli; }
   };
   return cli;

package/__tests__/fetcher-nested-and-default.test.js

@@ -0,0 +1,461 @@
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+const axios = require('axios');
+jest.mock('axios');
+
+let fetcher;
+let fetchIndex;
+let diskPaths;
+const cache = require('../src/cache');
+
+describe('fetcher nested folders and default repo behavior', () => {
+  const tmp = path.join(os.tmpdir(), `acp-fetcher-nested-${Date.now()}`);
+  const origCwd = process.cwd();
+
+  beforeAll(async () => {
+    await fs.ensureDir(tmp);
+    process.chdir(tmp);
+    process.env.NODE_ENV = 'test';
+    // require after chdir so diskPaths uses tmp cwd
+    fetcher = require('../src/fetcher');
+    fetchIndex = fetcher.fetchIndex;
+    diskPaths = fetcher.diskPaths;
+  });
+
+  afterAll(async () => {
+    process.chdir(origCwd);
+    await fs.remove(tmp);
+  });
+
+  beforeEach(async () => {
+    cache.del('index');
+    const { DISK_CACHE_DIR } = diskPaths();
+    await fs.remove(DISK_CACHE_DIR).catch(() => {});
+    // Clean up acp-repos.json file from previous tests
+    const baseDir = process.cwd();
+    const repoFile = path.join(baseDir, 'acp-repos.json');
+    await fs.remove(repoFile).catch(() => {});
+    axios.get.mockReset();
+    // Clear env vars
+    delete process.env.ACP_INDEX_JSON;
+    delete process.env.ACP_REPOS_JSON;
+    delete process.env.ACP_EXCLUDE_DEFAULT_REPO;
+  });
+
+  test('scans .github folder for prompts alongside root-level prompts', async () => {
+    const testRepoConfig = [
+      {
+        id: 'test-repo',
+        treeUrl: 'https://api.test/tree',
+        rawBase: 'https://raw.test'
+      }
+    ];
+    process.env.ACP_REPOS_JSON = JSON.stringify(testRepoConfig);
+
+    axios.get.mockImplementation((url) => {
+      if (url === 'https://api.test/tree') {
+        return Promise.resolve({
+          status: 200,
+          data: {
+            tree: [
+              // Root level prompts
+              { type: 'blob', path: 'prompts/root-prompt.prompt.md' },
+              // .github folder prompts
+              { type: 'blob', path: '.github/prompts/github-prompt.prompt.md' },
+              // Root level agents
+              { type: 'blob', path: 'agents/root-agent.agent.md' },
+              // .github folder agents
+              { type: 'blob', path: '.github/agents/github-agent.agent.md' }
+            ]
+          }
+        });
+      }
+      // Mock content fetches
+      if (url.includes('raw.test')) {
+        return Promise.resolve({
+          status: 200,
+          data: '---\ntitle: "Test Item"\n---\nContent'
+        });
+      }
+      return Promise.reject(new Error('Unexpected URL'));
+    });
+
+    const idx = await fetchIndex();
+
+    // Should find both root and .github prompts
+    expect(idx.prompts).toHaveLength(2);
+    const promptIds = idx.prompts.map(p => p.id).sort();
+    expect(promptIds).toContain('root-prompt');
+    expect(promptIds).toContain('github-prompt');
+
+    // Should find both root and .github agents
+    expect(idx.agents).toHaveLength(2);
+    const agentIds = idx.agents.map(a => a.id).sort();
+    expect(agentIds).toContain('root-agent');
+    expect(agentIds).toContain('github-agent');
+  });
+
+  test('finds items in arbitrarily nested folder structures', async () => {
+    const testRepoConfig = [
+      {
+        id: 'test-repo',
+        treeUrl: 'https://api.test/tree',
+        rawBase: 'https://raw.test'
+      }
+    ];
+    process.env.ACP_REPOS_JSON = JSON.stringify(testRepoConfig);
+
+    axios.get.mockImplementation((url) => {
+      if (url === 'https://api.test/tree') {
+        return Promise.resolve({
+          status: 200,
+          data: {
+            tree: [
+              // Various nesting levels
+              { type: 'blob', path: 'prompts/p1.prompt.md' },
+              { type: 'blob', path: '.github/prompts/p2.prompt.md' },
+              { type: 'blob', path: 'workflows/prompts/p3.prompt.md' },
+              { type: 'blob', path: 'docs/.github/prompts/p4.prompt.md' }
+            ]
+          }
+        });
+      }
+      if (url.includes('raw.test')) {
+        return Promise.resolve({
+          status: 200,
+          data: '---\ntitle: "Test"\n---\nContent'
+        });
+      }
+      return Promise.reject(new Error('Unexpected URL'));
+    });
+
+    const idx = await fetchIndex();
+
+    // Should find all prompts regardless of nesting level
+    expect(idx.prompts).toHaveLength(4);
+    const promptIds = idx.prompts.map(p => p.id).sort();
+    expect(promptIds).toContain('p1');
+    expect(promptIds).toContain('p2');
+    expect(promptIds).toContain('p3');
+    expect(promptIds).toContain('p4');
+  });
+
+  test('always includes default awesome-copilot repo when ACP_REPOS_JSON is set', async () => {
+    const customRepoConfig = [
+      {
+        id: 'custom-repo',
+        treeUrl: 'https://api.test/custom',
+        rawBase: 'https://raw.test/custom'
+      }
+    ];
+    process.env.ACP_REPOS_JSON = JSON.stringify(customRepoConfig);
+
+    axios.get.mockImplementation((url) => {
+      if (url.includes('test/custom')) {
+        return Promise.resolve({
+          status: 200,
+          data: { tree: [{ type: 'blob', path: 'prompts/custom.prompt.md' }] }
+        });
+      }
+      if (url.includes('.com/repos/github/awesome-copilot')) {
+        return Promise.resolve({
+          status: 200,
+          data: { tree: [{ type: 'blob', path: 'prompts/default.prompt.md' }] }
+        });
+      }
+      if (url.includes('raw.')) {
+        return Promise.resolve({
+          status: 200,
+          data: '---\ntitle: "Test"\n---\nContent'
+        });
+      }
+      return Promise.reject(new Error('Unexpected URL'));
+    });
+
+    const idx = await fetchIndex();
+
+    // Should have prompts from both custom and default repos
+    expect(idx.prompts.length).toBeGreaterThanOrEqual(2);
+    expect(idx._repos.some(r => r.id === 'custom-repo')).toBe(true);
+    expect(idx._repos.some(r => r.id === 'awesome-copilot')).toBe(true);
+  });
+
+  test('always includes default awesome-copilot repo when acp-repos.json file is used', async () => {
+    const fileRepoConfig = [
+      {
+        id: 'file-repo',
+        treeUrl: 'https://api.test/file',
+        rawBase: 'https://raw.test/file'
+      }
+    ];
+    const baseDir = process.cwd();
+    const repoFile = path.join(baseDir, 'acp-repos.json');
+    await fs.writeJson(repoFile, fileRepoConfig);
+
+    axios.get.mockImplementation((url) => {
+      if (url.includes('test/file')) {
+        return Promise.resolve({
+          status: 200,
+          data: { tree: [{ type: 'blob', path: 'prompts/file-item.prompt.md' }] }
+        });
+      }
+      if (url.includes('.com/repos/github/awesome-copilot')) {
+        return Promise.resolve({
+          status: 200,
+          data: { tree: [{ type: 'blob', path: 'prompts/default-item.prompt.md' }] }
+        });
+      }
+      if (url.includes('raw.')) {
+        return Promise.resolve({
+          status: 200,
+          data: '---\ntitle: "Test"\n---\nContent'
+        });
+      }
+      return Promise.reject(new Error('Unexpected URL'));
+    });
+
+    const idx = await fetchIndex();
+
+    // Should have repos from both file config and default
+    expect(idx._repos.some(r => r.id === 'file-repo')).toBe(true);
+    expect(idx._repos.some(r => r.id === 'awesome-copilot')).toBe(true);
+  });
+
+  test('respects ACP_EXCLUDE_DEFAULT_REPO when set to "true"', async () => {
+    process.env.ACP_EXCLUDE_DEFAULT_REPO = 'true';
+    const customRepoConfig = [
+      {
+        id: 'custom-repo',
+        treeUrl: 'https://api.test/custom',
+        rawBase: 'https://raw.test/custom'
+      }
+    ];
+    process.env.ACP_REPOS_JSON = JSON.stringify(customRepoConfig);
+
+    axios.get.mockImplementation((url) => {
+      if (url.includes('test/custom')) {
+        return Promise.resolve({
+          status: 200,
+          data: { tree: [{ type: 'blob', path: 'prompts/custom.prompt.md' }] }
+        });
+      }
+      if (url.includes('raw.test')) {
+        return Promise.resolve({
+          status: 200,
+          data: '---\ntitle: "Test"\n---\nContent'
+        });
+      }
+      // Should not be called for awesome-copilot
+      if (url.includes('.com/repos/github/awesome-copilot')) {
+        return Promise.reject(new Error('Should not fetch default repo when excluded'));
+      }
+      return Promise.reject(new Error('Unexpected URL'));
+    });
+
+    const idx = await fetchIndex();
+
+    // Should only have custom repo, not default
+    expect(idx._repos).toHaveLength(1);
+    expect(idx._repos[0].id).toBe('custom-repo');
+  });
+
+  test('respects ACP_EXCLUDE_DEFAULT_REPO when set to "1"', async () => {
+    process.env.ACP_EXCLUDE_DEFAULT_REPO = '1';
+
+    axios.get.mockImplementation((url) => {
+      // Default repo should not be called
+      if (url.includes('.com/repos/github/awesome-copilot')) {
+        return Promise.reject(new Error('Should not fetch default repo when excluded'));
+      }
+      // No other repos configured
+      return Promise.reject(new Error('Unexpected URL'));
+    });
+
+    // Should throw an error when no repos are configured and default is excluded
+    await expect(fetchIndex()).rejects.toThrow(
+      'No repos configured. When ACP_EXCLUDE_DEFAULT_REPO is set, you must configure at least one repo'
+    );
+  });
+
+  test('includes default repo even if already in ACP_REPOS_JSON to avoid duplicates', async () => {
+    const configWithDefault = [
+      {
+        id: 'awesome-copilot',
+        treeUrl: 'https://api.github.com/repos/github/awesome-copilot/git/trees/main?recursive=1',
+        rawBase: 'https://raw.githubusercontent.com/github/awesome-copilot/main'
+      },
+      {
+        id: 'custom-repo',
+        treeUrl: 'https://api.test/custom',
+        rawBase: 'https://raw.test/custom'
+      }
+    ];
+    process.env.ACP_REPOS_JSON = JSON.stringify(configWithDefault);
+
+    axios.get.mockImplementation((url) => {
+      if (url.includes('test/custom')) {
+        return Promise.resolve({
+          status: 200,
+          data: { tree: [{ type: 'blob', path: 'prompts/custom.prompt.md' }] }
+        });
+      }
+      if (url.includes('.com/repos/github/awesome-copilot')) {
+        return Promise.resolve({
+          status: 200,
+          data: { tree: [{ type: 'blob', path: 'prompts/default.prompt.md' }] }
+        });
+      }
+      if (url.includes('raw.')) {
+        return Promise.resolve({
+          status: 200,
+          data: '---\ntitle: "Test"\n---\nContent'
+        });
+      }
+      return Promise.reject(new Error('Unexpected URL'));
+    });
+
+    const idx = await fetchIndex();
+
+    // Should have two repos (awesome-copilot and custom), not duplicates
+    const repoIds = idx._repos.map(r => r.id);
+    expect(repoIds.filter(id => id === 'awesome-copilot')).toHaveLength(1);
+    expect(repoIds).toContain('custom-repo');
+  });
+
+  test('verbose logging shows .github folder discovery', async () => {
+    const testRepoConfig = [
+      {
+        id: 'test-repo',
+        treeUrl: 'https://api.test/tree',
+        rawBase: 'https://raw.test'
+      }
+    ];
+    process.env.ACP_REPOS_JSON = JSON.stringify(testRepoConfig);
+
+    const logs = [];
+    const originalLog = console.log;
+    console.log = jest.fn(msg => logs.push(msg));
+
+    try {
+      axios.get.mockImplementation((url) => {
+        if (url === 'https://api.test/tree') {
+          return Promise.resolve({
+            status: 200,
+            data: {
+              tree: [
+                { type: 'blob', path: 'prompts/root.prompt.md' },
+                { type: 'blob', path: '.github/prompts/github.prompt.md' }
+              ]
+            }
+          });
+        }
+        if (url.includes('raw.test')) {
+          return Promise.resolve({
+            status: 200,
+            data: '---\ntitle: "Test"\n---\nContent'
+          });
+        }
+        return Promise.reject(new Error('Unexpected URL'));
+      });
+
+      await fetchIndex({ verbose: true });
+
+      // Should show that items were found at any depth
+      expect(logs.some(l => l.includes('searched at any depth'))).toBe(true);
+      expect(logs.some(l => l.includes('found 2 prompts items'))).toBe(true);
+    } finally {
+      console.log = originalLog;
+    }
+  });
+
+  test('verbose logging shows default repo inclusion when ACP_REPOS_JSON is used', async () => {
+    const testRepoConfig = [
+      {
+        id: 'test-repo',
+        treeUrl: 'https://api.test/tree',
+        rawBase: 'https://raw.test'
+      }
+    ];
+    process.env.ACP_REPOS_JSON = JSON.stringify(testRepoConfig);
+
+    const logs = [];
+    const originalLog = console.log;
+    console.log = jest.fn(msg => logs.push(msg));
+
+    try {
+      axios.get.mockImplementation((url) => {
+        if (url.includes('test/tree')) {
+          return Promise.resolve({
+            status: 200,
+            data: { tree: [{ type: 'blob', path: 'prompts/p.prompt.md' }] }
+          });
+        }
+        if (url.includes('github.com/repos/github/awesome-copilot')) {
+          return Promise.resolve({
+            status: 200,
+            data: { tree: [{ type: 'blob', path: 'prompts/p.prompt.md' }] }
+          });
+        }
+        if (url.includes('raw.')) {
+          return Promise.resolve({
+            status: 200,
+            data: '---\ntitle: "Test"\n---\nContent'
+          });
+        }
+        return Promise.reject(new Error('Unexpected URL'));
+      });
+
+      await fetchIndex({ verbose: true });
+
+      expect(logs.some(l => l.includes('including default repo: awesome-copilot'))).toBe(true);
+      expect(logs.some(l => l.includes('final repos list:'))).toBe(true);
+      expect(logs.some(l => l.includes('awesome-copilot'))).toBe(true);
+      expect(logs.some(l => l.includes('test-repo'))).toBe(true);
+    } finally {
+      console.log = originalLog;
+    }
+  });
+
+  test('verbose logging shows default repo exclusion', async () => {
+    process.env.ACP_EXCLUDE_DEFAULT_REPO = 'true';
+    const customRepoConfig = [
+      {
+        id: 'custom-repo',
+        treeUrl: 'https://api.test/custom',
+        rawBase: 'https://raw.test/custom'
+      }
+    ];
+    process.env.ACP_REPOS_JSON = JSON.stringify(customRepoConfig);
+
+    const logs = [];
+    const originalLog = console.log;
+    console.log = jest.fn(msg => logs.push(msg));
+
+    try {
+      axios.get.mockImplementation((url) => {
+        if (url.includes('test/custom')) {
+          return Promise.resolve({
+            status: 200,
+            data: { tree: [{ type: 'blob', path: 'prompts/p.prompt.md' }] }
+          });
+        }
+        if (url.includes('raw.test')) {
+          return Promise.resolve({
+            status: 200,
+            data: '---\ntitle: "Test"\n---\nContent'
+          });
+        }
+        return Promise.reject(new Error('Unexpected URL'));
+      });
+
+      await fetchIndex({ verbose: true });
+
+      expect(logs.some(l => l.includes('default repo excluded via ACP_EXCLUDE_DEFAULT_REPO'))).toBe(true);
+      expect(logs.some(l => l.includes('final repos list:'))).toBe(true);
+      expect(logs.filter(l => l.includes('awesome-copilot')).length).toBe(0);
+    } finally {
+      console.log = originalLog;
+    }
+  });
+});