acp-vscode 0.3.0

package/.eslintrc.json

@@ -0,0 +1,12 @@
+{
+  "env": {
+    "node": true,
+    "es2021": true,
+    "jest": true
+  },
+  "extends": "eslint:recommended",
+  "parserOptions": {
+    "ecmaVersion": 12
+  },
+  "rules": {}
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Install dependencies
+        run: npm ci
+      - name: Run tests
+        run: npm test

package/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+# Best practices:
+# - Bump the package version locally with `npm version <major|minor|patch>` which creates a git tag.
+#   Then push the tag: `git push --follow-tags` (or `git push origin vX.Y.Z`).
+# - Alternatively, use a release manager like `semantic-release` to automate versioning and changelogs.
+# - This workflow runs when a tag matching `v*.*.*` is pushed. Ensure you create/tag using the v-prefixed semver format.
+# - Secrets required:
+#   - `NPM_TOKEN` (used for npm publish)
+#   - The default `GITHUB_TOKEN` is provided automatically by Actions for creating releases.
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # Minimal permissions required for publishing to npm and creating a release
+    permissions:
+      contents: write # needed to create a release
+      packages: write # not strictly required for npm but useful if you use GitHub Packages
+    steps:
+      # Fetch full history so tags and changelog generation work correctly
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      - name: Install
+        run: npm ci
+      - name: Run tests
+        run: npm test
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish
+      - name: Create GitHub Release
+        # Create a GitHub Release for the pushed tag. Uses the git ref by default.
+        uses: ncipollo/release-action@v1
+        with:
+          # Generate release notes automatically based on merged PRs and commits
+          generateReleaseNotes: true
+          # Use the tag from the push event (no need to pass 'tag')
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+## Contributing
+
+Thanks for contributing! This file explains how to run tests and the CLI locally.
+
+Development setup
+-----------------
+
+- Install dependencies:
+
+```bash
+npm install
+```
+
+- Run the CLI locally (help):
+
+```bash
+node ./bin/acp-vscode.js --help
+```
+
+Running tests
+-------------
+
+- Run the test suite with Jest:
+
+```bash
+npm test
+```
+
+- Tests use `ACP_INDEX_JSON` and other environment variables in some cases. To run tests or manual checks offline, generate a JSON index and set `ACP_INDEX_JSON` before running the command:
+
+```bash
+export ACP_INDEX_JSON='{"prompts":[],"chatmodes":[],"instructions":[]}'
+npm test
+```
+
+Key notes for contributors
+--------------------------
+- The fetcher writes a small on-disk cache to `./.acp-cache/index.json`. Tests may create or read this file. If you see stale results during development, remove the directory:
+
+```bash
+rm -rf .acp-cache
+```
+
+- The CLI supports `ACP_REPOS_JSON` to override the upstream repo list when fetching.
+
+- Keep changes small and unit-tested. There are unit and integration tests under `__tests__/`.
+
+Submitting a PR
+----------------
+
+- Open a pull request against `main` with an explanatory title and tests for behavior changes.
+- The repository is configured to run tests on PRs. Ensure tests pass locally before opening the PR.
+
+Contact
+-------
+
+If you need help, open an issue on the repository or mention the maintainers in your PR.

package/PRD.md

@@ -0,0 +1,25 @@
+# Product Requirements Document: acp-vscode
+
+Goal: create an npm CLI (acp-vscode) to fetch prompts, chatmodes, and instructions from https://github.com/github/awesome-copilot and install them into VS Code workspace or user profile.
+
+Requirements:
+- fetch resources from the GitHub repo and cache index for 30 minutes (in-memory and on-disk)
+- install into workspace (`.github/chatmodes`, `.github/prompts`) or VS Code user profile (prompts folder under the VS Code User directory, or `.github/*` under VS Code User for chatmodes/instructions)
+- list available items and filter by type
+- search items using cached index
+- install single or multiple instruction files by name
+- include help, tests, CI (GitHub Actions), README, and publish-ready `package.json`
+
+Additional Notes:
+- Provide `--dry-run` mode on install to preview files without writing
+- Add release workflow that publishes to npm when a semantic tag (vMAJOR.MINOR.PATCH) is pushed; requires the `NPM_TOKEN` secret
+
+- Add an `uninstall` command to remove installed items from workspace or user profile
+- Require explicit confirmation for user-targeted uninstall or allow `--yes` to bypass confirmation
+
+Behavior and implementation details
+
+The PRD should describe high-level goals and acceptance criteria. For concrete usage, examples, and troubleshooting steps (cache removal, env var usage, completion examples), see the `README.md` which contains command examples and diagnostic tips.
+
+
+Non-goals: automatic PRs, editor integrations (this is CLI-only)

package/README.md

@@ -0,0 +1,236 @@
+# acp-vscode
+
+acp-vscode is a small CLI to fetch and install chatmodes, prompts and instructions from the GitHub "awesome-copilot" repository into your VS Code workspace or VS Code User profile.
+
+Install (when published):
+
+```bash
+npm install -g acp-vscode
+# or run locally
+node ./bin/acp-vscode.js --help
+```
+
+Commands:
+- install <workspace|user> [names...]
+  - target: `workspace` or `user`
+  - names: optional list of ids or names to install (supports `repo:id` form)
+  - type: specify with the option `--type <type>` (prompts|chatmodes|instructions|all). For backwards compatibility you can still pass the type as the first positional name (e.g. `install workspace prompts p1 p2`). Note: the `install` command also accepts a deliberate typo alias `--referesh` (alias for `--refresh`) to preserve historical behavior.
+- list [type]
+  - list items available. type can be `prompts`, `chatmodes`, `instructions`, or `all`
+- search <query>
+  - search across items
+- uninstall <workspace|user> <type> [names...]
+  - remove installed files from workspace or user profile; use `--yes` to skip confirmation when targeting `user`.
+- completion [shell]
+  - print a simple shell completion script for `bash` or `zsh` (default `bash`)
+
+Output formats
+---------------
+
+Both `list` and `search` support a machine-readable JSON output via the `--json` (or `-j`) flag. When provided the commands will emit an array of items (objects with `type`, `id`, and `name`) instead of the human-friendly table.
+
+Example (JSON):
+
+```bash
+acp-vscode list prompts --json
+acp-vscode search "find me" --json
+```
+
+Examples:
+
+Install all prompts to workspace:
+
+```bash
+acp-vscode install workspace prompts
+```
+
+Install specific instructions to user profile (preferred):
+
+```bash
+acp-vscode install user --type instructions "Instruction Name"
+```
+
+Or (legacy positional type):
+
+```bash
+acp-vscode install user instructions "Instruction Name"
+```
+
+Completion examples
+-------------------
+
+Print a `bash` completion helper and save it for interactive use:
+
+```bash
+acp-vscode completion bash > /etc/bash_completion.d/acp-vscode
+# or source it in your shell for testing
+acp-vscode completion bash | source /dev/stdin
+```
+
+For `zsh` add the script snippet to your `.zshrc` (the command prints a small helper function):
+
+```bash
+acp-vscode completion zsh >> ~/.zshrc
+```
+
+Uninstall examples
+------------------
+
+Remove two prompts from workspace:
+
+```bash
+acp-vscode uninstall workspace prompts one two
+```
+
+Remove a prompt from the user profile without confirmation:
+
+```bash
+acp-vscode uninstall user prompts my-prompt --yes
+```
+
+Troubleshooting
+---------------
+
+- Cache and stale index
+  - The CLI writes a disk cache at `./.acp-cache/index.json` (30 minute TTL). If you see stale results or want to force a fresh fetch, remove the cache file and retry:
+
+```bash
+rm -rf .acp-cache
+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.
+
+- Multiple upstream repos
+  - To index multiple repos set `ACP_REPOS_JSON` to a JSON array of repo descriptors. Example:
+
+```json
+[ { "id": "r1", "treeUrl": "https://api.github.com/repos/org/repo1/git/trees/main?recursive=1", "rawBase": "https://raw.githubusercontent.com/org/repo1/main" } ]
+```
+
+- Verbose logging
+  - Add `--verbose` to commands to see extra diagnostic messages during fetch, cache clearing, and install/uninstall operations.
+
+Cache: the CLI caches the fetched GitHub index in-memory and on-disk for 30 minutes to reduce network calls. The on-disk cache is stored under the current working directory in `.acp-cache/index.json`.
+
+Configuration (environment variables)
+
+Environment variables
+
+ACP_INDEX_JSON
+
+You can inject a full, pre-built index via the `ACP_INDEX_JSON` environment variable. This should be a JSON string representing the index shape the fetcher returns, for example:
+
+```json
+{
+  "prompts": [{ "id": "p1", "name": "Prompt 1", "repo": "r1", "url": "https://..." }],
+  "chatmodes": [],
+  "instructions": []
+}
+```
+
+This is useful for tests or offline runs. When present, the fetcher will parse and return this value verbatim.
+
+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).
+
+Example:
+
+```json
+[
+  { "id": "r1", "treeUrl": "https://api.github.com/repos/org/repo1/git/trees/main?recursive=1", "rawBase": "https://raw.githubusercontent.com/org/repo1/main" },
+  { "id": "r2", "treeUrl": "https://api.github.com/repos/org/repo2/git/trees/main?recursive=1", "rawBase": "https://raw.githubusercontent.com/org/repo2/main" }
+]
+```
+
+When multiple repos contain files with the same `id`, the fetcher adds an `_conflicts` array to the returned index listing conflicted ids. Consumers will display items as `repo:id` when necessary to disambiguate.
+
+Dry-run:
+
+You can preview what would be installed without writing files using --dry-run:
+
+```bash
+acp-vscode install workspace prompts --dry-run
+```
+
+Other notes
+
+Global flags
+
+- `--verbose` enables extra logging across commands.
+- `--refresh` is a global top-level flag but currently only applied by the `list` and `search` commands to force clearing in-memory and on-disk caches. The `install` command accepts a `--referesh` alias (typo preserved) which also triggers cache clearing when provided to `install`.
+
+Commands reference
+------------------
+
+Short reference for each command, key options, and quick examples.
+
+- install <workspace|user> [names...]
+  - Description: Install prompts/chatmodes/instructions into a workspace or VS Code user profile.
+  - Options: `-t, --type <type>` (prompts|chatmodes|instructions|all), `--dry-run`, `--referesh` (alias for refresh), `--verbose`
+  - Examples:
+    - Install all prompts into the current workspace:
+      - `acp-vscode install workspace prompts`
+    - Install instruction by name into user profile (preferred):
+      - `acp-vscode install user --type instructions "Instruction Name"`
+
+- list [type]
+  - Description: List available items. Type can be `prompts`, `chatmodes`, `instructions`, or `all` (default).
+  - Options: `-r, --refresh` (clear caches and refetch), `-j, --json`, `--verbose`
+  - Examples:
+    - `acp-vscode list chatmodes`
+    - `acp-vscode list --json`
+
+- search <query>
+  - Description: Search the index for matching items (name, id or content).
+  - Options: `-r, --refresh`, `-j, --json`, `--verbose`
+  - Examples:
+    - `acp-vscode search "temperature"`
+
+- uninstall <workspace|user> <type> [names...]
+  - Description: Remove installed files from workspace or user profile. When targeting `user` you'll be prompted for confirmation unless you pass `--yes`.
+  - Options: `--yes`, `--verbose`
+  - Examples:
+    - `acp-vscode uninstall workspace prompts one two`
+
+- completion [shell]
+  - Description: Print a small shell completion snippet for `bash` or `zsh`.
+  - Examples:
+    - `acp-vscode completion bash`
+
+
+Publishing:
+
+This repository includes a release workflow that publishes to npm when a tag like v0.1.0 is pushed. You must add an `NPM_TOKEN` secret in the repository settings for the workflow to authenticate with npm.
+
+Publish checklist:
+
+1. Update `package.json` fields: `version`, `repository.url`, `bugs.url`, `author`.
+2. Create a repo secret `NPM_TOKEN` in GitHub (Settings → Secrets → Actions). Generate the token with npm's access token UI.
+3. Create a release tag and push it, e.g.:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+4. The release workflow will run tests and publish the package to npm on success.
+
+Uninstall and confirmation:
+
+To remove installed files:
+
+```bash
+acp-vscode uninstall workspace prompts one two
+```
+
+If you're uninstalling from the VS Code user profile, the CLI will prompt for confirmation. Use `--yes` to skip the prompt:
+
+```bash
+acp-vscode uninstall user prompts one --yes
+```
+
+
+

package/__tests__/cache.test.js

@@ -0,0 +1,7 @@
+const cache = require('../src/cache');
+
+test('cache set and get', () => {
+  cache.set('x', { a: 1 });
+  const v = cache.get('x');
+  expect(v).toEqual({ a: 1 });
+});

package/__tests__/commands-actions.test.js

@@ -0,0 +1,58 @@
+const cache = require('../src/cache');
+const fs = require('fs-extra');
+const path = require('path');
+
+function makeCli() {
+  const cli = {
+    _action: null,
+    command() { return cli; },
+    option() { return cli; },
+    action(fn) { cli._action = fn; return cli; }
+  };
+  return cli;
+}
+
+describe('command actions (search, list, install)', () => {
+  afterEach(() => {
+    cache.del('index');
+    delete process.env.ACP_INDEX_JSON;
+  });
+
+  test('searchCommand action prints matches and respects ACP_INDEX_JSON', async () => {
+    process.env.ACP_INDEX_JSON = JSON.stringify({ prompts: [{ id: 's1', name: 'SearchMe', repo: 'r1' }], chatmodes: [], instructions: [], _conflicts: [] });
+    const stubCli = makeCli();
+    const sc = require('../src/commands/search');
+    sc.searchCommand(stubCli);
+    const logs = [];
+    jest.spyOn(console, 'log').mockImplementation((...args) => logs.push(args.join(' ')));
+    await stubCli._action('searchme', { refresh: true, verbose: false });
+    expect(logs.some(l => l.includes('s1'))).toBe(true);
+    console.log.mockRestore();
+  });
+
+  test('listCommand action prints header and items', async () => {
+    process.env.ACP_INDEX_JSON = JSON.stringify({ prompts: [{ id: 'p1', name: 'Prompt One', repo: 'r1' }], chatmodes: [], instructions: [], _conflicts: [] });
+    const stubCli = makeCli();
+    const lc = require('../src/commands/list');
+    lc.listCommand(stubCli);
+    const logs = [];
+    jest.spyOn(console, 'log').mockImplementation((...args) => logs.push(args.join(' ')));
+    await stubCli._action('prompts', { refresh: true, verbose: false });
+    // The printed output should include a header line with Type and ID
+    expect(logs.some(l => /Type\s+ID/.test(l))).toBe(true);
+    console.log.mockRestore();
+  });
+
+  test('installCommand action supports dry-run and type option', async () => {
+    process.env.ACP_INDEX_JSON = JSON.stringify({ prompts: [{ id: 'p1', name: 'P1', repo: 'r1', content: 'x' }], chatmodes: [], instructions: [], _conflicts: [] });
+    const stubCli = makeCli();
+    const ic = require('../src/commands/install');
+    ic.installCommand(stubCli);
+    const logs = [];
+    jest.spyOn(console, 'log').mockImplementation((...args) => logs.push(args.join(' ')));
+    await stubCli._action('workspace', ['p1'], { type: 'prompts', 'dry-run': true });
+    expect(logs.some(l => l.includes('[dry-run]'))).toBe(true);
+    console.log.mockRestore();
+  });
+
+});

package/__tests__/commands.test.js

@@ -0,0 +1,28 @@
+jest.mock('../src/fetcher');
+const { fetchIndex } = require('../src/fetcher');
+const cache = require('../src/cache');
+const { listItems } = require('../src/commands/list');
+const { searchIndex } = require('../src/commands/search');
+
+const FIXTURE_INDEX = {
+  prompts: [{ id: 'p1', name: 'Prompt One' }],
+  chatmodes: [{ id: 'c1', name: 'Chat Mode One' }],
+  instructions: [{ id: 'i1', name: 'Instruction One' }]
+};
+
+beforeEach(() => {
+  fetchIndex.mockResolvedValue(FIXTURE_INDEX);
+  cache.del('index');
+});
+
+test('listItems returns items', async () => {
+  const items = listItems(FIXTURE_INDEX);
+  expect(items.find(i => i.type === 'prompt')).toBeTruthy();
+  expect(items.find(i => i.type === 'chatmode')).toBeTruthy();
+  expect(items.find(i => i.type === 'instruction')).toBeTruthy();
+});
+
+test('searchIndex finds query', async () => {
+  const results = searchIndex(FIXTURE_INDEX, 'One');
+  expect(results.length).toBeGreaterThanOrEqual(3);
+});

package/__tests__/e2e.test.js

@@ -0,0 +1,40 @@
+const { execFileSync } = require('child_process');
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+
+const CLI = path.join(__dirname, '..', 'bin', 'acp-vscode.js');
+
+describe('e2e CLI', () => {
+  const tmp = path.join(os.tmpdir(), `acp-e2e-${Date.now()}`);
+  beforeAll(async () => {
+    await fs.ensureDir(tmp);
+  });
+  afterAll(async () => {
+    await fs.remove(tmp).catch(() => {});
+  });
+
+  test('install workspace prompts writes only to workspace and cleans up', () => {
+    const index = { prompts: [{ id: 'p1', name: 'p1', content: { body: 'ok' } }] };
+    const env = Object.assign({}, process.env, { ACP_INDEX_JSON: JSON.stringify(index) });
+    // run install pointing at tmp as cwd
+    execFileSync('node', [CLI, 'install', 'workspace', 'prompts'], { cwd: tmp, env });
+    const installedDir = path.join(tmp, '.github', 'prompts');
+    expect(fs.existsSync(installedDir)).toBe(true);
+    const files = fs.readdirSync(installedDir);
+    expect(files.length).toBeGreaterThan(0);
+    // ensure VS Code user profile was not touched (we won't check actual user dir), just ensure cwd-based user didn't receive files
+    const userPrompts = path.join(tmp, 'prompts');
+    expect(fs.existsSync(userPrompts)).toBe(false);
+    // cleanup
+    fs.removeSync(installedDir);
+    expect(fs.existsSync(installedDir)).toBe(false);
+  });
+
+  test('unknown option shows friendly error', () => {
+    const { spawnSync } = require('child_process');
+    const res = spawnSync('node', [CLI, '--no-such-option'], { encoding: 'utf8' });
+    const out = `${res.stdout || ''}${res.stderr || ''}${res.error ? res.error.message : ''}`;
+    expect(out).toMatch(/Run `acp-vscode --help`/);
+  });
+});

package/__tests__/fetcher-tree.test.js

@@ -0,0 +1,55 @@
+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;
+
+describe('fetcher tree -> index conversion', () => {
+  const tmp = path.join(os.tmpdir(), `acp-fetcher-tree-${Date.now()}`);
+  const origCwd = process.cwd();
+
+  beforeAll(async () => {
+    await fs.ensureDir(tmp);
+    process.chdir(tmp);
+    // 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 () => {
+    const { DISK_CACHE_DIR } = diskPaths();
+    await fs.remove(DISK_CACHE_DIR).catch(() => {});
+    axios.get.mockReset();
+  });
+
+  test('constructs index from git tree', async () => {
+    const tree = [
+      { path: 'prompts/p1.prompt.md', type: 'blob' },
+      { path: 'chatmodes/c1.chatmode.md', type: 'blob' },
+      { path: 'instructions/i1.instructions.md', type: 'blob' }
+    ];
+    axios.get.mockResolvedValue({ status: 200, data: { tree } });
+
+    const idx = await fetchIndex();
+
+    expect(idx).toBeTruthy();
+    expect(Array.isArray(idx.prompts)).toBe(true);
+    expect(Array.isArray(idx.chatmodes)).toBe(true);
+    expect(Array.isArray(idx.instructions)).toBe(true);
+
+    expect(idx.prompts[0].path).toBe('prompts/p1.prompt.md');
+    expect(idx.prompts[0].url).toBe('https://raw.githubusercontent.com/github/awesome-copilot/main/prompts/p1.prompt.md');
+    expect(idx.chatmodes[0].path).toBe('chatmodes/c1.chatmode.md');
+    expect(idx.instructions[0].path).toBe('instructions/i1.instructions.md');
+  });
+});