@laitszkin/apollo-toolkit 3.2.1 → 3.3.0

package/AGENTS.md

@@ -4,8 +4,9 @@
 
 - This repository is a skill catalog: each top-level skill lives in its own directory and is installable when that directory contains `SKILL.md`.
 - Typical skill layout is lightweight and consistent: `SKILL.md`, `README.md`, `LICENSE`, plus optional `agents/`, `references/`, and `scripts/`.
-- The npm package exposes an `apollo-toolkit` CLI that stages a managed copy under `~/.apollo-toolkit` and copies each skill folder into selected target directories.
-- `scripts/install_skills.sh` and `scripts/install_skills.ps1` remain available for local/curl installs and mirror the managed-home copy behavior.
+- The npm package exposes an `apollo-toolkit` CLI that stages a managed copy under `~/.apollo-toolkit` and copies or symlinks each skill folder into selected target directories.
+- The installer writes a `.apollo-toolkit-manifest.json` per target directory to track installed skills, historical skill names, and install mode for future uninstall and deduplication.
+- `scripts/install_skills.sh` and `scripts/install_skills.ps1` remain available for local/curl installs and mirror the managed-home install behavior with symlink/copy choice and uninstall support.
 
 ## Core Business Flow
 
@@ -20,7 +21,9 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can research a topic deeply and produce evidence-based deliverables.
 - Users can research the latest completed market week and produce a PDF watchlist of tradeable instruments for the coming week.
 - Users can turn a marked weekly finance PDF into a concise evidence-based financial event report.
-- Users can install Apollo Toolkit through npm or npx and interactively choose one or more target skill directories to populate with copied skills.
+- Users can install Apollo Toolkit through npm or npx and interactively choose one or more target skill directories to populate with copied or symlinked skills, with the option to include codex-exclusive skills in non-codex targets.
+- Users can uninstall all Apollo Toolkit-installed skills from all targets or specific targets via `apltk uninstall`.
+- Users can choose between symlink mode (auto-update via git pull) and copy mode (stable snapshot) with `--symlink` / `--copy` flags.
 - Users can run bundled helper tools through `apltk tools` and direct `apltk <tool>` commands for selected packaged skill scripts.
 - Users can design and implement new features through a spec-first workflow.
 - Users can generate shared feature planning artifacts for approval-gated workflows, including parallel multi-spec batches coordinated through one batch-level `coordination.md`.
@@ -72,7 +75,11 @@ This repository enables users to install and run a curated set of reusable agent
 - `python3 scripts/validate_skill_frontmatter.py` - 驗證所有頂層技能 `SKILL.md` 的 frontmatter。
 - `python3 scripts/validate_openai_agent_config.py` - 驗證所有技能 `agents/openai.yaml` 設定。
 - `./scripts/install_skills.sh codex` - 用本地安裝腳本把技能安裝到 Codex 目錄。
-- `./scripts/install_skills.sh all` - 用本地安裝腳本同步安裝到所有支援目標。
+- `./scripts/install_skills.sh codex --symlink` - 以 symlink 模式安裝（推薦）。
+- `./scripts/install_skills.sh all --copy` - 以複製模式安裝到所有支援目標。
+- `./scripts/install_skills.sh uninstall` - 從所有目標移除已安裝的技能。
+- `./scripts/install_skills.sh uninstall codex` - 只從 codex 目標移除。
+- `node bin/apollo-toolkit.js uninstall` - 透過 CLI 移除所有已安裝技能。
 
 ## Core Project Purpose
 

package/CHANGELOG.md

@@ -4,8 +4,26 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+### Added
+- (None yet)
+
+## [v3.3.0] - 2026-04-26
+
+### Added
+- Add `apltk uninstall` command to remove all installed skills from all targets (or specific targets) via manifest-based cleanup.
+- Add symlink install mode (`--symlink`) so skills auto-update when `git pull` runs in `~/.apollo-toolkit`, removing the need to re-run the installer after patch updates.
+- Add `--copy` flag to explicitly select copy mode when symlink is not desired.
+- Add interactive prompt during install that explains symlink pros/cons and lets the user choose between symlink and copy mode.
+- Add interactive prompt to optionally install codex-exclusive skills into non-codex targets during global install.
+- Add `.apollo-toolkit-manifest.json` per target directory to track installed skills, historical skill names, and install mode for future uninstall and deduplication.
+- Add `listAllKnownSkillNames()` to combine current and historically-appeared skill names with automatic deduplication.
+- Add `uninstall` subcommand to `scripts/install_skills.sh` and `scripts/install_skills.ps1`.
+- Add `--symlink` / `--copy` flags to both shell and PowerShell install scripts.
+
+## [v3.2.2] - 2026-04-25
+
 ### Changed
-- None yet.
+- Tighten `implement-specs-with-worktree` so targeted Rust verification must avoid multi-filter `cargo test` invocations and rerun any zero-test selector before treating the worktree spec as validated.
 
 ## [v3.2.1] - 2026-04-24
 

package/README.md

@@ -65,9 +65,26 @@ The interactive installer:
 - shows a branded `Apollo Toolkit` terminal welcome screen with a short staged reveal
 - installs a managed copy into `~/.apollo-toolkit`
 - lets you multi-select `codex`, `openclaw`, `trae`, `agents`, `claude-code`, or `all`
-- copies `~/.apollo-toolkit/<skill>` into each selected target
+- asks whether to install skills as **symlinks** (recommended) or **file copies**
+- lets you choose whether to include codex-exclusive skills in non-codex targets
+- copies or symlinks `~/.apollo-toolkit/<skill>` into each selected target
 - removes stale previously installed skill directories that existed in the previous installed version but no longer exist in the current package skill list
 - replaces legacy symlink-based installs created by older Apollo Toolkit installers with real copied directories
+- writes a manifest (`.apollo-toolkit-manifest.json`) per target for future uninstall and skill tracking
+
+### Symlink vs Copy
+
+| Mode | Pro | Con |
+| --- | --- | --- |
+| **Symlink** (recommended) | Auto-updates when you `git pull` in `~/.apollo-toolkit`; no need to re-run installer after patch updates | Changes pushed to the repo automatically reflect in your skills — you may receive updates you did not intend to accept |
+| **Copy** | Stable snapshot; won't change until you re-run the installer | Must manually re-run `apltk` after each toolkit update to get the latest skills |
+
+### Uninstall
+
+```bash
+apltk uninstall          # Remove all installed skills from all targets
+apltk uninstall codex    # Remove only from codex
+```
 
 ### Global install
 
@@ -98,6 +115,13 @@ npx @laitszkin/apollo-toolkit codex openclaw
 npx @laitszkin/apollo-toolkit all
 ```
 
+Add `--symlink` (recommended) or `--copy` to skip the interactive prompt:
+
+```bash
+npx @laitszkin/apollo-toolkit codex --symlink
+npx @laitszkin/apollo-toolkit all --copy
+```
+
 ### Optional overrides
 
 ```bash
@@ -121,24 +145,27 @@ Installers still live in `scripts/` for local repository usage and curl / iwr in
 ```bash
 ./scripts/install_skills.sh
 ./scripts/install_skills.sh codex
-./scripts/install_skills.sh openclaw
-./scripts/install_skills.sh trae
-./scripts/install_skills.sh agents
-./scripts/install_skills.sh all
+./scripts/install_skills.sh codex --symlink
+./scripts/install_skills.sh all --copy
+./scripts/install_skills.sh uninstall
+./scripts/install_skills.sh uninstall codex trae
 ```
 
 ```powershell
 ./scripts/install_skills.ps1
 ./scripts/install_skills.ps1 codex
-./scripts/install_skills.ps1 agents
-./scripts/install_skills.ps1 all
+./scripts/install_skills.ps1 agents --symlink
+./scripts/install_skills.ps1 all --copy
+./scripts/install_skills.ps1 uninstall
+./scripts/install_skills.ps1 uninstall codex trae
 ```
 
 ### Curl / iwr one-liners
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/LaiTszKin/apollo-toolkit/main/scripts/install_skills.sh | bash
-curl -fsSL https://raw.githubusercontent.com/LaiTszKin/apollo-toolkit/main/scripts/install_skills.sh | bash -s -- codex
+curl -fsSL https://raw.githubusercontent.com/LaiTszKin/apollo-toolkit/main/scripts/install_skills.sh | bash -s -- codex --symlink
+curl -fsSL https://raw.githubusercontent.com/LaiTszKin/apollo-toolkit/main/scripts/install_skills.sh | bash -s -- uninstall
 ```
 
 ```powershell

package/implement-specs-with-worktree/SKILL.md

@@ -25,7 +25,7 @@ description: >-
 
 - Evidence: Read and understand the complete specs set before starting implementation, identify the authoritative parent branch that the worktree should inherit from, verify whether the requested scope is already implemented on that parent branch or current main working tree, and when the requested plan path is missing from the current worktree verify where the authoritative copy actually lives before substituting any nearby spec.
 - Execution: Create or use an isolated worktree for implementation only when the requested spec still needs work, sync the exact approved plan set into that worktree when it is missing there, create the worktree branch from the same parent branch as the worktree base, use the spec-set name as the canonical branch/worktree name, prefer direct `git` ref checks over brittle shell inference when deciding whether a branch or worktree already exists, and commit to a local branch when done.
-- Quality: Complete all planned tasks, run relevant tests, backfill the spec documents with actual completion status, avoid dragging unrelated sibling specs into the worktree just because they share a batch directory, revert unrelated formatter-only noise outside the spec-owned scope before committing, and if branch/worktree creation reports ambiguous state re-check the actual git refs and worktree list before retrying.
+- Quality: Complete all planned tasks, run relevant tests, backfill the spec documents with actual completion status, avoid dragging unrelated sibling specs into the worktree just because they share a batch directory, revert unrelated formatter-only noise outside the spec-owned scope before committing, if branch/worktree creation reports ambiguous state re-check the actual git refs and worktree list before retrying, and when using targeted Rust `cargo test` selectors remember Cargo accepts only one positional test filter so each distinct selector needs its own confirmed command.
 - Output: Keep the worktree branch clean with only the intended implementation commits.
 
 ## Goal
@@ -109,6 +109,8 @@ Use branch naming from `references/branch-naming.md`.
   - E2E tests for key user-visible paths
   - Adversarial tests for abuse paths
 - Run relevant tests and fix failures.
+- When using targeted Rust `cargo test` commands, pass at most one positional test filter per invocation; if multiple selectors are needed, run separate commands or a broader confirmed selector.
+- Treat any targeted test command that executes zero tests as non-verification and rerun with a selector that proves the intended coverage actually ran.
 - Do not skip testing even for seemingly small changes.
 
 ### 5) Backfill completion status

package/lib/cli.js

@@ -6,9 +6,12 @@ const {
   TARGET_DEFINITIONS,
   VALID_MODES,
   installLinks,
+  listAllKnownSkillNames,
+  listCodexSkillNames,
   normalizeModes,
   resolveToolkitHome,
   syncToolkitHome,
+  uninstallSkills,
   getTargetRoots,
 } = require('./installer');
 const { formatToolList, getToolCommand, runTool } = require('./tool-runner');
@@ -41,7 +44,7 @@ function color(text, code, enabled) {
     return text;
   }
 
-  return `\u001b[${code}m${text}\u001b[0m`;
+  return `[${code}m${text}`;
 }
 
 function sleep(ms) {
@@ -134,6 +137,7 @@ function buildHelpText({ version, colorEnabled }) {
     'Usage:',
     `  apltk [install] [${buildModeUsagePattern()}]...`,
     `  apollo-toolkit [install] [${buildModeUsagePattern()}]...`,
+    '  apltk uninstall',
     '  apltk tools',
     '  apltk <tool> [...args]',
     '  apltk tools <tool> [...args]',
@@ -143,6 +147,7 @@ function buildHelpText({ version, colorEnabled }) {
     'Examples:',
     '  apltk',
     '  apltk codex openclaw',
+    '  apltk uninstall',
     '  npx @laitszkin/apollo-toolkit',
     '  npx @laitszkin/apollo-toolkit codex openclaw',
     '  npm i -g @laitszkin/apollo-toolkit',
@@ -194,8 +199,24 @@ function parseArguments(argv) {
     toolkitHome: null,
     toolName: null,
     toolArgs: [],
+    linkMode: null, // 'copy' | 'symlink' | null (prompt)
   };
 
+  if (args[0] === 'uninstall') {
+    result.command = 'uninstall';
+    args.shift();
+    // remaining args could be specific modes
+    while (args.length > 0) {
+      const arg = args.shift();
+      if (arg === '--help' || arg === '-h') {
+        result.showHelp = true;
+      } else {
+        result.modes.push(arg);
+      }
+    }
+    return result;
+  }
+
   if (args[0] === 'tools' || args[0] === 'tool') {
     args.shift();
     if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
@@ -234,6 +255,16 @@ function parseArguments(argv) {
       continue;
     }
 
+    if (arg === '--symlink') {
+      result.linkMode = 'symlink';
+      continue;
+    }
+
+    if (arg === '--copy') {
+      result.linkMode = 'copy';
+      continue;
+    }
+
     if (arg === 'install') {
       continue;
     }
@@ -246,7 +277,7 @@ function parseArguments(argv) {
 
 function clearScreen(output) {
   if (output.isTTY) {
-    output.write('\u001b[2J\u001b[H');
+    output.write('');
   }
 }
 
@@ -315,20 +346,20 @@ async function promptForModes({ stdin, stdout, version, env }) {
 
     const onData = (chunk) => {
       const value = chunk.toString('utf8');
-      if (value === '\u0003') {
+      if (value === '') {
         cleanup();
         reject(new Error('Installation cancelled.'));
         return;
       }
 
-      if (value === '\u001b[A' || value === 'k') {
+      if (value === '' || value === 'k') {
         cursor = (cursor - 1 + TARGET_OPTIONS.length) % TARGET_OPTIONS.length;
         message = '';
         renderSelectionScreen({ output: stdout, version, cursor, selected, message, env });
         return;
       }
 
-      if (value === '\u001b[B' || value === 'j') {
+      if (value === '' || value === 'j') {
         cursor = (cursor + 1) % TARGET_OPTIONS.length;
         message = '';
         renderSelectionScreen({ output: stdout, version, cursor, selected, message, env });
@@ -349,7 +380,7 @@ async function promptForModes({ stdin, stdout, version, env }) {
         return;
       }
 
-      if (value.toLowerCase() === 'q' || value === '\u001b') {
+      if (value.toLowerCase() === 'q' || value === '') {
         cleanup();
         reject(new Error('Installation cancelled.'));
         return;
@@ -374,11 +405,77 @@ async function promptForModes({ stdin, stdout, version, env }) {
   });
 }
 
-async function confirmInstall({ stdin, stdout, version, toolkitHome, modes, env }) {
+async function promptYesNo({ stdin, stdout, env, question, defaultYes = true }) {
+  if (!stdin.isTTY || !stdout.isTTY) {
+    return defaultYes;
+  }
+
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const hint = defaultYes ? '[Y/n]' : '[y/N]';
+    const answer = await rl.question(`${question} ${hint} `);
+    const trimmed = answer.trim().toLowerCase();
+    if (trimmed === '') {
+      return defaultYes;
+    }
+    return trimmed === 'y' || trimmed === 'yes';
+  } finally {
+    rl.close();
+  }
+}
+
+function buildSymlinkInfo({ colorEnabled }) {
+  return [
+    '',
+    color('Symlink mode:', '1', colorEnabled),
+    `  ${color('Pro:', '1;32', colorEnabled)} Skills auto-update when you ${color('git pull', '1;33', colorEnabled)} in ~/.apollo-toolkit`,
+    `  ${color('Pro:', '1;32', colorEnabled)} No need to re-run installer after patch updates`,
+    `  ${color('Con:', '1;31', colorEnabled)} Changes pushed to the repo automatically reflect in your skills -`,
+    `       you may receive updates you did not intend to accept`,
+    '',
+  ].join('\n');
+}
+
+async function promptSymlinkChoice({ stdin, stdout, env, colorEnabled }) {
+  stdout.write(buildSymlinkInfo({ colorEnabled }));
+  return promptYesNo({
+    stdin,
+    stdout,
+    env,
+    question: 'Install skills as symlinks (recommended)?',
+    defaultYes: true,
+  });
+}
+
+// Ask user whether to include codex-exclusive skills in non-codex targets.
+async function promptIncludeExclusiveSkills({ stdin, stdout, env, colorEnabled, codexSkillNames, nonCodexModes }) {
+  if (codexSkillNames.length === 0 || nonCodexModes.length === 0) {
+    return false;
+  }
+
+  stdout.write([
+    '',
+    color('Exclusive skills detected:', '1;33', colorEnabled),
+    `  The following skills are exclusive to codex: ${codexSkillNames.join(', ')}`,
+    `  Your selected non-codex targets: ${nonCodexModes.join(', ')}`,
+    '',
+  ].join('\n'));
+
+  return promptYesNo({
+    stdin,
+    stdout,
+    env,
+    question: `Install codex-exclusive skills to ${nonCodexModes.join(', ')} as well?`,
+    defaultYes: false,
+  });
+}
+
+async function confirmInstall({ stdin, stdout, version, toolkitHome, modes, linkMode, env }) {
   const colorEnabled = supportsColor(stdout, env);
   stdout.write(`${buildBanner({ version, colorEnabled })}\n\n`);
   stdout.write(`Apollo Toolkit home: ${toolkitHome}\n`);
-  stdout.write(`Targets: ${modes.join(', ')}\n\n`);
+  stdout.write(`Targets: ${modes.join(', ')}\n`);
+  stdout.write(`Install mode: ${linkMode === 'symlink' ? 'symlink (auto-update via git pull)' : 'copy (manual reinstall for updates)'}\n\n`);
 
   const targets = await getTargetRoots(modes, env).catch((error) => {
     throw error;
@@ -408,6 +505,7 @@ function printSummary({ stdout, version, toolkitHome, modes, installResult, env
   stdout.write('\n');
   stdout.write(`Apollo Toolkit home: ${toolkitHome}\n`);
   stdout.write(`Installed skills: ${installResult.skillNames.length}\n`);
+  stdout.write(`Install mode: ${installResult.linkMode === 'symlink' ? 'symlink' : 'copy'}\n`);
   stdout.write(`Targets: ${modes.join(', ')}\n\n`);
 
   for (const target of installResult.targets) {
@@ -415,6 +513,22 @@ function printSummary({ stdout, version, toolkitHome, modes, installResult, env
   }
 }
 
+function printUninstallSummary({ stdout, uninstallResult, env }) {
+  const colorEnabled = supportsColor(stdout, env);
+
+  if (uninstallResult.length === 0) {
+    stdout.write(color('No Apollo Toolkit installations found.\n', '1;33', colorEnabled));
+    return;
+  }
+
+  stdout.write(color('Uninstall complete.', '1;32', colorEnabled));
+  stdout.write('\n\n');
+  for (const result of uninstallResult) {
+    stdout.write(`${color(result.target, '1', colorEnabled)} (${result.root})\n`);
+    stdout.write(`  Removed: ${result.removedSkills.join(', ')}\n`);
+  }
+}
+
 async function run(argv, context = {}) {
   const sourceRoot = context.sourceRoot || path.resolve(__dirname, '..');
   const stdout = context.stdout || process.stdout;
@@ -425,14 +539,17 @@ async function run(argv, context = {}) {
 
   try {
     const parsed = parseArguments(argv);
+
     if (parsed.showHelp) {
       stdout.write(`${buildHelpText({ version: packageJson.version, colorEnabled: supportsColor(stdout, env) })}\n`);
       return 0;
     }
+
     if (parsed.showToolsHelp) {
       stdout.write(`${buildToolsHelp({ version: packageJson.version, colorEnabled: supportsColor(stdout, env) })}\n`);
       return 0;
     }
+
     if (parsed.command === 'tool') {
       return (context.runTool || runTool)(parsed.toolName, parsed.toolArgs, {
         sourceRoot,
@@ -443,6 +560,39 @@ async function run(argv, context = {}) {
       });
     }
 
+    // --- Uninstall flow ---
+    if (parsed.command === 'uninstall') {
+      const toolkitHome = parsed.toolkitHome || resolveToolkitHome(env);
+      const modes = parsed.modes.length > 0 ? normalizeModes(parsed.modes) : null;
+
+      // Show what will be removed
+      const allKnown = await listAllKnownSkillNames({ toolkitHome, modes: modes || [], env });
+      stdout.write(color(`Apollo Toolkit home: ${toolkitHome}\n`, '2', supportsColor(stdout, env)));
+
+      const confirmed = await promptYesNo({
+        stdin,
+        stdout,
+        env,
+        question: `This will remove all Apollo Toolkit-installed skills${modes ? ` from: ${modes.join(', ')}` : ' from all targets'}. Continue?`,
+        defaultYes: false,
+      });
+
+      if (!confirmed) {
+        stdout.write('Uninstall cancelled.\n');
+        return 1;
+      }
+
+      const uninstallResult = await uninstallSkills({ env, modes });
+      printUninstallSummary({ stdout, uninstallResult, env });
+
+      if (allKnown.length > 0) {
+        stdout.write(`\nPreviously known skills (may still exist elsewhere): ${allKnown.join(', ')}\n`);
+      }
+
+      return 0;
+    }
+
+    // --- Install flow ---
     const updateResult = await checkForPackageUpdate({
       packageName: packageJson.name,
       currentVersion: packageJson.version,
@@ -463,12 +613,39 @@ async function run(argv, context = {}) {
       ? normalizeModes(parsed.modes)
       : normalizeModes(await promptForModes({ stdin, stdout, version: packageJson.version, env }));
 
+    const colorEnabled = supportsColor(stdout, env);
+
+    // Determine link mode
+    let linkMode = parsed.linkMode;
+    if (!linkMode) {
+      linkMode = (await promptSymlinkChoice({ stdin, stdout, env, colorEnabled })) ? 'symlink' : 'copy';
+    }
+
+    // Determine whether to include exclusive (codex) skills in non-codex targets
+    const nonCodexModes = modes.filter((m) => m !== 'codex');
+    const codexSkillNames = await listCodexSkillNames(toolkitHome).catch(() => []);
+    const includeExclusiveSkills = await promptIncludeExclusiveSkills({
+      stdin,
+      stdout,
+      env,
+      colorEnabled,
+      codexSkillNames,
+      nonCodexModes,
+    });
+
+    // syncToolkitHome needs to include the codex container when exclusive skills
+    // are requested, so the source files are available for symlink/copy.
+    const effectiveModes = includeExclusiveSkills
+      ? [...new Set([...modes, 'codex'])]
+      : modes;
+
     const confirmed = await confirmInstall({
       stdin,
       stdout,
       version: packageJson.version,
       toolkitHome,
       modes,
+      linkMode,
       env,
     });
 
@@ -481,13 +658,15 @@ async function run(argv, context = {}) {
       sourceRoot,
       toolkitHome,
       version: packageJson.version,
-      modes,
+      modes: effectiveModes,
     });
 
     const installResult = await installLinks({
       toolkitHome,
       modes,
       previousSkillNames: syncResult.previousSkillNames,
+      linkMode,
+      includeExclusiveSkills,
       env: {
         ...env,
         APOLLO_TOOLKIT_HOME: toolkitHome,
@@ -509,6 +688,8 @@ module.exports = {
   buildToolsHelp,
   parseArguments,
   promptForModes,
+  promptSymlinkChoice,
+  promptIncludeExclusiveSkills,
   readPackageJson,
   run,
 };