@theglitchking/babel-fish 1.0.2 → 2.0.0

package/.claude/templates/operational-runbook.md.template

@@ -0,0 +1,40 @@
+# {{PROJECT_NAME}} — Operational Runbook
+
+> Auto-loaded every session. Contains operational knowledge that cannot be derived from code.
+> This file grows over time as the team discovers gotchas, quirks, and procedures.
+> **Edit this file manually** — it is NOT overwritten on regeneration.
+
+## Environment Differences
+
+<!-- TODO: Document how dev/staging/prod differ (DB, deploy method, secrets, URLs) -->
+
+| | Dev | Staging | Production |
+|---|---|---|---|
+| **URL** | | | |
+| **Database** | | | |
+| **Deploy** | | | |
+| **Secrets** | | | |
+
+## Known Issues & Workarounds
+
+<!-- This section fills in naturally. When you hit a non-obvious issue, add it here. -->
+<!-- Examples: "HMR doesn't work on WSL2", "port 6543 breaks migrations" -->
+
+_No known issues documented yet. When you encounter a non-obvious problem and its solution, add it here so future sessions don't re-discover it._
+
+## Deploy Procedures
+
+<!-- TODO: Document how to deploy to each environment -->
+
+## Key Commands
+
+| Command | What It Does |
+|---------|-------------|
+| `python .claude/project-map/generate.py --force` | Force-regenerate project map |
+| `python .claude/project-map/grader.py` | Grade map quality (0-100%) |
+| `bash .githooks/install.sh` | (Re)install git hooks |
+| `bash .claude/install.sh` | Re-run full plugin installer |
+
+## Dev Credentials
+
+<!-- Add test/dev credentials here (NEVER production secrets) -->

package/.claude/templates/project-vocabulary.md.template

@@ -0,0 +1,25 @@
+# {{PROJECT_NAME}} — Project Vocabulary
+
+> Auto-loaded every session. Maps human language to exact code locations.
+> Regenerated automatically via pre-commit hook. Do not edit the auto-generated rows.
+
+## Feature → Code Location
+
+| You Say | Frontend | Backend | Model/Table |
+|---------|----------|---------|-------------|
+| _(vocabulary populates as source code is added)_ | | | |
+
+## Infrastructure Vocabulary
+
+| You Say | What It Is | Key Details |
+|---------|-----------|-------------|
+| project | {{PROJECT_NAME}} | {{LANGUAGE}} / {{FRAMEWORK}} stack |
+
+## Quick Actions
+
+| You Say | What To Do |
+|---------|-----------|
+| regenerate map | `python .claude/project-map/generate.py --force` |
+| grade map | `python .claude/project-map/grader.py` |
+| view project map | `cat .claude/project-map/PROJECT_MAP.md` |
+| install hooks | `bash .githooks/install.sh` |

package/.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Official marketplace for babel-fish - Codebase introspection and vocabulary translation for AI coding assistants",
-    "version": "1.0.2"
+    "version": "2.0.0"
   },
   "plugins": [
     {
       "name": "babel-fish",
       "description": "Auto-generates a project map, vocabulary translation layer, and developer skill for any codebase. Introspects routes, models, services, features, infrastructure, and session history to give Claude instant full-stack context. Self-updates via pre-commit hook.",
-      "version": "1.0.2",
+      "version": "2.0.0",
       "author": {
         "name": "TheGlitchKing"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "babel-fish",
   "description": "Auto-generates a project map, vocabulary translation layer, and developer skill for any codebase. Introspects routes, models, services, features, infrastructure, and session history to give Claude instant full-stack context. Self-updates via pre-commit hook.",
-  "version": "1.0.2",
+  "version": "2.0.0",
   "author": {
     "name": "TheGlitchKing",
     "email": "theglitchking@users.noreply.github.com"

package/.githooks/install.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+git config core.hooksPath .githooks
+chmod +x .githooks/*
+echo "Git hooks installed (.githooks/ directory configured)"

package/.githooks/pre-commit

@@ -0,0 +1,22 @@
+#!/bin/bash
+# ── Codebase Mapper: regenerate project map on relevant changes ──
+STAGED_FILES=$(git diff --cached --name-only 2>/dev/null || true)
+EXTENSIONS_PATTERN='\.(py|ts|tsx|js|jsx|go|java|yaml|yml)$|docker-compose|package\.json|Cargo\.toml|go\.mod'
+if echo "$STAGED_FILES" | grep -qE "$EXTENSIONS_PATTERN" 2>/dev/null; then
+    MAP_SCRIPT=".claude/project-map/generate.py"
+    if [ -f "$MAP_SCRIPT" ]; then
+        PYTHON=""
+        if [ -f ".venv/bin/python3" ]; then PYTHON=".venv/bin/python3"
+        elif command -v python3 &>/dev/null; then PYTHON="python3"
+        elif command -v python &>/dev/null; then PYTHON="python"
+        fi
+        if [ -n "$PYTHON" ]; then
+            echo "[codebase-mapper] Regenerating project map..."
+            if $PYTHON "$MAP_SCRIPT" 2>/dev/null; then
+                git add .claude/project-map/PROJECT_MAP.md .claude/project-map/checksums.json \
+                        .claude/project-map/sections/*.md .claude/project-map/learned-vocabulary.json 2>/dev/null || true
+            fi
+        fi
+    fi
+fi
+# ── End Codebase Mapper ──────────────────────────────────────────────────────

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [2.0.0] — 2026-04-19
+
+### Breaking changes
+
+- **Package is now ESM (`"type": "module"`).** If anything imports from
+  `@theglitchking/babel-fish` via `require()` (the package has no `main`,
+  so this is unlikely), you'll need to switch to `import`. The CLI
+  (`npx @theglitchking/babel-fish <cmd>`) is unaffected.
+- **Node >= 20** (was >= 16). Matches the rest of the Glitch Kingdom
+  plugin ecosystem and the runtime.
+- CLI is now `commander`-based. Subcommands, flags, and arguments
+  behave the same as before — `init`, `dry-run`, `regen`, `grade`, and
+  `help` all work identically — but you now also get `--help` and
+  `--version` on every subcommand.
+
+### Migration
+
+No user-facing code changes required — just:
+
+```bash
+npm install @theglitchking/babel-fish@latest
+
+# Or if you used the curl|bash installer (unaffected):
+curl -sSL https://raw.githubusercontent.com/TheGlitchKing/babel-fish/main/install.sh | bash
+```
+
+Your existing `.claude/project-map/` infrastructure and `.githooks/pre-commit`
+keep working — this release doesn't touch them. The only net-new files
+added to your project are `.claude/babel-fish.json` (update policy —
+defaults to `nudge`) and a SessionStart hook entry in
+`.claude/settings.json` (only if that file exists and the plugin
+marketplace version isn't already handling it).
+
+### Added
+
+- Adopts
+  [`@theglitchking/claude-plugin-runtime`](https://github.com/TheGlitchKing/claude-plugin-runtime)
+  (`^0.1.0`) for standardized update management and postinstall wiring.
+- **Postinstall** (`scripts/link-skills.js`) symlinks
+  `skills/babel-fish-developer-skill/` into `<project>/.claude/skills/`
+  so Claude Code picks it up automatically. If you later run
+  `npx @theglitchking/babel-fish init`, the install script's `cp`
+  replaces the symlink with a regular copy — either way the skill is
+  discoverable.
+- **SessionStart hook** (`hooks/session-start.js`) checks npm for a
+  newer version at session start and acts per policy (off / nudge /
+  auto). Default is `nudge` — a one-liner notification, no automatic
+  changes.
+- **Slash + CLI subcommands:**
+  - `/babel-fish:update` / `babel-fish update`
+  - `/babel-fish:policy [auto|nudge|off]` / `babel-fish policy`
+  - `/babel-fish:status` / `babel-fish status`
+  - `/babel-fish:relink` / `babel-fish relink`
+
+### Opt-outs
+
+| Variable | Effect |
+|---|---|
+| `BABEL_FISH_UPDATE_POLICY` | One-shot policy override |
+| `BABEL_FISH_SKIP_LINK=1` | Skip skill symlinking in postinstall |
+| `BABEL_FISH_SKIP_HOOK_REGISTER=1` | Skip writing the SessionStart hook into `.claude/settings.json` |
+
+---
+
+## [1.0.2] and earlier
+
+See git history:
+https://github.com/TheGlitchKing/babel-fish/commits/main

package/README.md

@@ -119,6 +119,24 @@ bash babel-fish/.claude/install.sh /path/to/your/project
 
 ---
 
+## Update management *(2.0.0+)*
+
+Every install ships with an update policy controlling what happens at session start when a newer version is available on npm. Default is `nudge` (one-liner notification, no automatic changes).
+
+```bash
+babel-fish status          # installed / latest / policy / hook state
+babel-fish policy auto     # auto-update on session start
+babel-fish policy nudge    # one-liner nudge only (default)
+babel-fish policy off      # silent
+babel-fish update          # update now
+```
+
+Slash-command parity: `/babel-fish:status`, `/babel-fish:policy <mode>`, `/babel-fish:update`, `/babel-fish:relink`.
+
+See [CHANGELOG.md](./CHANGELOG.md) for the full 2.0.0 release notes, breaking-change details, and env-var opt-outs.
+
+---
+
 ## What the Installer Does
 
 1. Checks for Python ≥ 3.8 (installs if missing)

package/bin/babel-fish.js

@@ -1,94 +1,101 @@
 #!/usr/bin/env node
-'use strict';
 
-const { execSync, spawnSync } = require('child_process');
-const path = require('path');
-const fs = require('fs');
+import { program } from "commander";
+import { registerUpdateCommands } from "@theglitchking/claude-plugin-runtime";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
 
-const INSTALL_SH = path.join(__dirname, '..', '.claude', 'install.sh');
-const args = process.argv.slice(2);
-const command = args[0] || 'init';
+const require_ = createRequire(import.meta.url);
+const { version } = require_("../package.json");
 
-const helpText = `
-  babel-fish — gives your AI assistant instant codebase context
-
-  Usage:
-    npx @theglitchking/babel-fish [command] [options]
-
-  Commands:
-    init [path]    Install babel-fish into a project (default: current dir)
-    dry-run [path] Preview all changes without applying them
-    regen          Force-regenerate the project map
-    grade          Grade the current project map quality
-    help           Show this help
-
-  Examples:
-    npx @theglitchking/babel-fish init
-    npx @theglitchking/babel-fish init /path/to/project
-    npx @theglitchking/babel-fish dry-run
-    npx @theglitchking/babel-fish regen
-`;
+const PKG = "@theglitchking/babel-fish";
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const INSTALL_SH = join(PACKAGE_ROOT, ".claude", "install.sh");
 
 function requireBash() {
-  const result = spawnSync('bash', ['--version'], { stdio: 'ignore' });
-  if (result.status !== 0) {
-    console.error('  ✗ bash is required but not found.');
+  const r = spawnSync("bash", ["--version"], { stdio: "ignore" });
+  if (r.status !== 0) {
+    console.error("  ✗ bash is required but not found.");
     process.exit(1);
   }
 }
 
-function run(bashArgs, opts = {}) {
+function runBash(bashArgs, opts = {}) {
   requireBash();
-  const result = spawnSync('bash', bashArgs, {
-    stdio: 'inherit',
-    ...opts,
+  const r = spawnSync("bash", bashArgs, { stdio: "inherit", ...opts });
+  if (r.status !== 0) process.exit(r.status ?? 1);
+}
+
+function runRelink(cwd) {
+  const linker = join(cwd, "node_modules", "@theglitchking", "babel-fish", "scripts", "link-skills.js");
+  const script = existsSync(linker) ? linker : resolve(PACKAGE_ROOT, "scripts", "link-skills.js");
+  if (!existsSync(script)) {
+    console.error("link-skills.js not found — is the package installed?");
+    return;
+  }
+  spawnSync(process.execPath, [script], {
+    cwd,
+    env: { ...process.env, INIT_CWD: cwd },
+    stdio: "inherit",
   });
-  if (result.status !== 0) process.exit(result.status);
 }
 
-switch (command) {
-  case 'init':
-  case '--auto': {
-    const target = args[1] || process.cwd();
+program
+  .name("babel-fish")
+  .description("babel-fish — gives your AI assistant instant codebase context")
+  .version(version);
+
+registerUpdateCommands(program, {
+  packageName: PKG,
+  pluginName: "babel-fish",
+  configFile: "babel-fish.json",
+  onAfterUpdate: (cwd) => runRelink(cwd),
+});
+
+program
+  .command("init [path]")
+  .description("Install babel-fish into a project (default: current dir)")
+  .action((path) => {
+    const target = path || process.cwd();
     console.log(`\n  babel-fish init → ${target}\n`);
-    run([INSTALL_SH, target]);
-    break;
-  }
+    runBash([INSTALL_SH, target]);
+  });
 
-  case 'dry-run': {
-    const target = args[1] || process.cwd();
-    run([INSTALL_SH, '--dry-run', target]);
-    break;
-  }
+program
+  .command("dry-run [path]")
+  .description("Preview all changes without applying them")
+  .action((path) => {
+    const target = path || process.cwd();
+    runBash([INSTALL_SH, "--dry-run", target]);
+  });
 
-  case 'regen': {
-    const generatePy = path.join(process.cwd(), '.claude', 'project-map', 'generate.py');
-    if (!fs.existsSync(generatePy)) {
-      console.error('  ✗ .claude/project-map/generate.py not found. Run `babel-fish init` first.');
+program
+  .command("regen")
+  .description("Force-regenerate the project map")
+  .action(() => {
+    const generatePy = join(process.cwd(), ".claude", "project-map", "generate.py");
+    if (!existsSync(generatePy)) {
+      console.error("  ✗ .claude/project-map/generate.py not found. Run `babel-fish init` first.");
       process.exit(1);
     }
-    run(['python3', generatePy, '--force'], { shell: false });
-    break;
-  }
+    const r = spawnSync("python3", [generatePy, "--force"], { stdio: "inherit" });
+    process.exit(r.status ?? 0);
+  });
 
-  case 'grade': {
-    const graderPy = path.join(process.cwd(), '.claude', 'project-map', 'grader.py');
-    if (!fs.existsSync(graderPy)) {
-      console.error('  ✗ .claude/project-map/grader.py not found. Run `babel-fish init` first.');
+program
+  .command("grade")
+  .description("Grade the current project map quality")
+  .action(() => {
+    const graderPy = join(process.cwd(), ".claude", "project-map", "grader.py");
+    if (!existsSync(graderPy)) {
+      console.error("  ✗ .claude/project-map/grader.py not found. Run `babel-fish init` first.");
       process.exit(1);
     }
-    spawnSync('python3', [graderPy], { stdio: 'inherit' });
-    break;
-  }
-
-  case 'help':
-  case '--help':
-  case '-h':
-    console.log(helpText);
-    break;
+    const r = spawnSync("python3", [graderPy], { stdio: "inherit" });
+    process.exit(r.status ?? 0);
+  });
 
-  default:
-    console.error(`  Unknown command: ${command}`);
-    console.log(helpText);
-    process.exit(1);
-}
+program.parse();

package/commands/policy.md

@@ -0,0 +1,16 @@
+---
+description: Get or set the babel-fish update policy (auto | nudge | off)
+allowed-tools: Bash(npx:*)
+argument-hint: "[auto|nudge|off]"
+---
+
+Arguments: $ARGUMENTS
+
+- If `$ARGUMENTS` is empty, run `npx --no @theglitchking/babel-fish policy` and report the current policy and config path.
+- If `$ARGUMENTS` is one of `auto`, `nudge`, `off`, run `npx --no @theglitchking/babel-fish policy $ARGUMENTS` and confirm the new setting to the user.
+- If `$ARGUMENTS` is anything else, tell the user the valid values are `auto`, `nudge`, `off`.
+
+Policies:
+- `auto`  — auto-run `npm update @theglitchking/babel-fish` at session start when a newer version is available.
+- `nudge` — print a one-liner when a newer version is available (default).
+- `off`   — do not check for updates.

package/commands/relink.md

@@ -0,0 +1,6 @@
+---
+description: Re-run the skill linker — refresh symlinks from node_modules into .claude/skills/
+allowed-tools: Bash(npx:*)
+---
+
+Run `npx --no @theglitchking/babel-fish relink` and report the result.

package/commands/status.md

@@ -0,0 +1,6 @@
+---
+description: Show installed version, latest available version, current update policy, and hook registration state
+allowed-tools: Bash(npx:*)
+---
+
+Run `npx --no @theglitchking/babel-fish status` and relay the output to the user verbatim.

package/commands/update.md

@@ -0,0 +1,6 @@
+---
+description: Update babel-fish to the latest version (runs npm update + re-links skills)
+allowed-tools: Bash(npx:*)
+---
+
+Run `npx --no @theglitchking/babel-fish update` and report the before/after versions to the user. If the project doesn't have a local install, fall back to `npx -y @theglitchking/babel-fish update` and note that in your summary.

package/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "description": "babel-fish SessionStart hook — nudges/auto-updates per policy.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.js\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/session-start.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// babel-fish SessionStart hook. Runs the runtime's update check per
+// policy (off / nudge / auto). No plugin-specific .mcp.json reconcile.
+
+import { runSessionStart } from "@theglitchking/claude-plugin-runtime";
+
+await runSessionStart({
+  packageName: "@theglitchking/babel-fish",
+  pluginName: "babel-fish",
+  configFile: "babel-fish.json",
+});

package/package.json

@@ -1,20 +1,32 @@
 {
   "name": "@theglitchking/babel-fish",
-  "version": "1.0.2",
+  "version": "2.0.0",
   "description": "Gives your AI coding assistant instant, accurate knowledge of every route, model, service, feature, and infrastructure element in your codebase.",
+  "type": "module",
   "bin": {
     "babel-fish": "bin/babel-fish.js"
   },
+  "scripts": {
+    "postinstall": "node scripts/link-skills.js"
+  },
   "files": [
     "bin/",
+    "commands/",
+    "hooks/",
+    "scripts/link-skills.js",
     ".claude-plugin/",
+    ".claude/",
+    ".githooks/",
     "skills/",
     "install.sh",
     "checksums.json",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "keywords": [
+    "claude-code",
+    "plugin",
     "codebase-context",
     "project-map",
     "vocabulary",
@@ -35,6 +47,10 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@theglitchking/claude-plugin-runtime": "^0.1.0",
+    "commander": "^14.0.0"
   }
 }

package/scripts/link-skills.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// Postinstall — delegates to @theglitchking/claude-plugin-runtime.
+// babel-fish ships one skill (skills/babel-fish-developer-skill/) which
+// the runtime symlinks into <project>/.claude/skills/ so Claude Code
+// can discover it. Runtime also writes the default update-policy config
+// and registers the SessionStart hook (with plugin-vs-npm dedup).
+//
+// NOTE: npm install only handles the skill + update policy. To get the
+// full project-map infra (.claude/project-map/generate.py, the
+// pre-commit hook, rules files), users still run:
+//   npx @theglitchking/babel-fish init
+
+import { runPostinstall } from "@theglitchking/claude-plugin-runtime";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+try {
+  runPostinstall({
+    packageName: "@theglitchking/babel-fish",
+    pluginName: "babel-fish",
+    configFile: "babel-fish.json",
+    skillsDir: "skills",
+    packageRoot,
+    hookCommand:
+      "node ./node_modules/@theglitchking/babel-fish/hooks/session-start.js",
+  });
+} catch (err) {
+  console.warn(`[babel-fish] postinstall failed: ${err?.message || err}`);
+}