@theglitchking/babel-fish 1.0.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,44 @@
+{
+  "name": "babel-fish-marketplace",
+  "owner": {
+    "name": "TheGlitchKing",
+    "email": "theglitchking@users.noreply.github.com"
+  },
+  "metadata": {
+    "description": "Official marketplace for babel-fish - Codebase introspection and vocabulary translation for AI coding assistants",
+    "version": "1.0.1"
+  },
+  "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.1",
+      "author": {
+        "name": "TheGlitchKing"
+      },
+      "homepage": "https://github.com/TheGlitchKing/babel-fish",
+      "repository": "https://github.com/TheGlitchKing/babel-fish.git",
+      "license": "MIT",
+      "keywords": [
+        "codebase-context",
+        "project-map",
+        "vocabulary",
+        "developer-skill",
+        "introspection",
+        "drift-management",
+        "claude-code"
+      ],
+      "category": "developer-tools",
+      "tags": [
+        "codebase-context",
+        "introspection",
+        "project-map"
+      ],
+      "source": {
+        "source": "npm",
+        "package": "@theglitchking/babel-fish"
+      },
+      "strict": true
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "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.1",
+  "author": {
+    "name": "TheGlitchKing",
+    "email": "theglitchking@users.noreply.github.com"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/TheGlitchKing/babel-fish",
+  "repository": "https://github.com/TheGlitchKing/babel-fish",
+  "keywords": [
+    "codebase-context",
+    "project-map",
+    "vocabulary",
+    "developer-skill",
+    "introspection",
+    "drift-management"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 TheGlitchKing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,267 @@
+# babel-fish
+
+![babel-fish](babel.jpg)
+
+**Gives your AI coding assistant instant, accurate knowledge of every route, model, service, feature, and infrastructure element in your codebase.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Status: Production Ready](https://img.shields.io/badge/Status-Production%20Ready-green.svg)]()
+[![GitHub: TheGlitchKing/babel-fish](https://img.shields.io/badge/GitHub-TheGlitchKing%2Fbabel--fish-blue)](https://github.com/TheGlitchKing/babel-fish)
+
+---
+
+## What Does This Do?
+
+Babel Fish creates a translation layer between a human and an LLM. It provides a natural feature-based conversation for the human, and a direct mapping to tools, targets, models, and file paths for the AI. Babel Fish auto-generates a living project map for your codebase and teaches your AI assistant your vocabulary — so you spend zero time re-explaining your project every session.
+
+| Without Babel Fish | With Babel Fish |
+|-------------------|-----------------|
+| "The deals page is at `features/deal-pipeline/DealPipeline.tsx`" | *Already mapped* |
+| AI scans 200 files to find a route | *Loads 1 section, 5KB* |
+| Stale context after a refactor | *Pre-commit hook auto-regenerates* |
+| Re-explain your stack every session | *Vocabulary auto-loaded on start* |
+| "Where is the background job for invoices?" | *Checks section 08 directly* |
+
+**In short:** Your AI assistant knows your codebase cold from the first message.
+
+---
+
+## What Gets Generated
+
+A 19-section project map, split into focused files so the AI loads only what's relevant per task:
+
+| Section | What It Contains |
+|---------|-----------------|
+| `01-vocabulary.md` | Plain-English → exact file path mapping |
+| `02-service-topology.md` | How your services connect |
+| `03-environment.md` | Env vars (secrets redacted) |
+| `04-api-routes.md` | Every route with method, path, handler |
+| `05-data-models.md` | Models and their fields |
+| `06-schemas.md` | Validation schemas (Pydantic, Zod, etc.) |
+| `07-services.md` | Business logic layer |
+| `08-background-jobs.md` | Queues, workers, cron tasks |
+| `09-frontend-features.md` | Components and pages |
+| `10-tools-commands.md` | CLI commands and scripts |
+| `11-migrations.md` | Database migration history |
+| `12-import-chains.md` | Key import dependency trees |
+| `13-frontend-backend-map.md` | Which frontend calls which API |
+| `14-reverse-proxy.md` | Nginx/Caddy routing config |
+| `15-auth-config.md` | Auth strategy and guards |
+| `16-infra-profile.md` | Docker, Terraform, cloud config |
+| `17-learned-vocabulary.md` | Aliases mined from your sessions |
+| `18-dead-code.md` | Unused exports and orphaned files |
+| `19-doc-pointers.md` | Links to external docs |
+
+Plus:
+- **`PROJECT_MAP.md`** — TOC and quick routing guide (always loaded first)
+- **`project-vocabulary.md`** — auto-loaded every session
+- **`operational-runbook.md`** — gotchas and deploy procedures, grows over time
+- **Developer skill** — loads only the 2-3 sections relevant to your current task
+
+---
+
+## Install
+
+### Option 1: npx (recommended — no curl, verified by npm registry)
+
+```bash
+# Preview all changes before applying (nothing is modified)
+npx @theglitchking/babel-fish dry-run
+
+# Install
+npx @theglitchking/babel-fish init
+
+# Or target a specific project
+npx @theglitchking/babel-fish init /path/to/your/project
+```
+
+---
+
+### Option 2: Curl one-liner (checksum-verified)
+
+Always preview before running anything from the internet:
+
+```bash
+# Preview first — shows every file that will be created, nothing is modified
+curl -sSL https://raw.githubusercontent.com/TheGlitchKing/babel-fish/main/install.sh | bash -s -- --dry-run
+
+# Install
+curl -sSL https://raw.githubusercontent.com/TheGlitchKing/babel-fish/main/install.sh | bash
+
+# Or target a specific path
+curl -sSL https://raw.githubusercontent.com/TheGlitchKing/babel-fish/main/install.sh | bash -s -- /path/to/your/project
+```
+
+The remote installer verifies a SHA256 checksum against `checksums.json` before executing anything. If the file has been tampered with in transit, the installer aborts.
+
+---
+
+### Option 3: Via Glitch Kingdom Marketplace (Claude Code)
+
+Run these inside a Claude Code session:
+
+```
+/plugin marketplace add TheGlitchKing/glitch-kingdom-of-plugins
+/plugin install TheGlitchKing/babel-fish
+```
+
+> The first command registers the Glitch Kingdom marketplace. You only need to run it once — after that, `/plugin install` works for all Glitch Kingdom plugins.
+
+---
+
+### Option 4: Clone and run
+
+```bash
+git clone https://github.com/TheGlitchKing/babel-fish.git
+bash babel-fish/.claude/install.sh --dry-run /path/to/your/project  # preview first
+bash babel-fish/.claude/install.sh /path/to/your/project
+```
+
+---
+
+## What the Installer Does
+
+1. Checks for Python ≥ 3.8 (installs if missing)
+2. Detects your stack (language, framework, database, ORM, auth, infra)
+3. Runs `generate.py` → grades with `grader.py` (iterates up to 3× until 90%+ quality)
+4. Renders your developer skill and rules files
+5. Installs the pre-commit hook (auto-regenerates map on source file changes)
+6. Updates `CLAUDE.md` with a project map pointer
+7. Prints a full quality report
+
+---
+
+## Quality Grading
+
+Every install is graded 0–100% across 7 categories. Must score ≥ 90% to pass (up to 3 iterations):
+
+| Category | Weight | What It Checks |
+|----------|--------|----------------|
+| Section completeness | 25% | All 19 sections generated |
+| Vocabulary accuracy | 20% | Entries map to real files |
+| Import chain validity | 15% | Chains trace to real modules |
+| Secret safety | 15% | No API keys, passwords, or tokens leaked |
+| Section size bounds | 10% | Each section 0.1–50KB |
+| Structural integrity | 10% | Valid markdown, working TOC links |
+| Checksum functionality | 5% | Re-run skips when nothing changed |
+
+A full report is written to `.claude/project-map/reports/install-report.md`.
+
+---
+
+## Using the Developer Skill
+
+After install, a skill is available:
+
+```
+/<your-project-slug>-developer
+```
+
+It reads `PROJECT_MAP.md` and uses the Quick Routing table to load only the 2-3 sections relevant to your current task — typically 5–20KB of context instead of 100KB+.
+
+---
+
+## Keeping the Map Current
+
+The pre-commit hook regenerates the map automatically whenever source files change. To force a manual regeneration:
+
+```bash
+python .claude/project-map/generate.py --force
+```
+
+To re-grade the current output:
+
+```bash
+python .claude/project-map/grader.py
+```
+
+---
+
+## Learned Vocabulary
+
+Every AI session is mined for vocabulary. When you say "the numbers page" and the AI opens `DealAnalyzerV2.tsx`, that alias is recorded with a score (frequency × recency). Aliases with a score ≥ 5 appear in `17-learned-vocabulary.md` automatically.
+
+Run the miner manually:
+
+```bash
+python .claude/project-map/mine-sessions.py
+```
+
+---
+
+## Operational Runbook
+
+`.claude/rules/operational-runbook.md` is loaded every session and grows over time. When you encounter a non-obvious operational issue, the developer skill prompts:
+
+> "This looks like operational knowledge worth documenting. Want me to add it to the runbook? (Y/n)"
+
+Entries follow a simple format: symptom → cause → fix. This is the anti-drift mechanism — knowledge that can't be derived from code lives here.
+
+---
+
+## File Structure
+
+```
+.claude/
+├── project-map/
+│   ├── generate.py              # Introspection script
+│   ├── grader.py                # Quality grader
+│   ├── mine-sessions.py         # Session vocabulary miner
+│   ├── PROJECT_MAP.md           # TOC + quick routing guide
+│   ├── sections/                # 19 focused section files
+│   ├── reports/                 # Install and iteration reports
+│   ├── checksums.json           # Skip regeneration if unchanged
+│   └── learned-vocabulary.json  # Persisted session aliases
+├── rules/
+│   ├── project-vocabulary.md    # Auto-loaded every session
+│   └── operational-runbook.md   # Auto-loaded every session
+└── skills/
+    └── <project>-developer-skill/
+        └── SKILL.md
+.githooks/
+├── pre-commit                   # Auto-regenerates map on commit
+└── install.sh                   # Register hooks: bash .githooks/install.sh
+```
+
+---
+
+## Supported Stacks
+
+| Language | Frameworks |
+|----------|-----------|
+| Python | FastAPI, Django, Flask |
+| TypeScript / JavaScript | Next.js, NestJS, Express, React, Vue, Svelte |
+| Go | Gin, Echo, Chi, stdlib |
+| Java | Spring Boot |
+| Any | docker-compose, nginx, Caddy, Terraform, Prisma, SQLAlchemy, TypeORM |
+
+---
+
+## Requirements
+
+- AI coding assistant (Claude Code, Cursor, or compatible)
+- Python ≥ 3.8 (auto-installed if missing)
+- Bash
+- Optional: `pip install pyyaml` for docker-compose YAML parsing (regex fallback included)
+
+---
+
+## 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%) |
+| `python .claude/project-map/mine-sessions.py` | Mine session vocabulary |
+| `bash .githooks/install.sh` | (Re)install git hooks |
+| `bash .claude/install.sh` | Re-run full plugin installer |
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+---
+
+**Made by [TheGlitchKing](https://github.com/TheGlitchKing)**

package/bin/babel-fish.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+'use strict';
+
+const { execSync, spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const INSTALL_SH = path.join(__dirname, '..', '.claude', 'install.sh');
+const args = process.argv.slice(2);
+const command = args[0] || 'init';
+
+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
+`;
+
+function requireBash() {
+  const result = spawnSync('bash', ['--version'], { stdio: 'ignore' });
+  if (result.status !== 0) {
+    console.error('  ✗ bash is required but not found.');
+    process.exit(1);
+  }
+}
+
+function run(bashArgs, opts = {}) {
+  requireBash();
+  const result = spawnSync('bash', bashArgs, {
+    stdio: 'inherit',
+    ...opts,
+  });
+  if (result.status !== 0) process.exit(result.status);
+}
+
+switch (command) {
+  case 'init':
+  case '--auto': {
+    const target = args[1] || process.cwd();
+    console.log(`\n  babel-fish init → ${target}\n`);
+    run([INSTALL_SH, target]);
+    break;
+  }
+
+  case 'dry-run': {
+    const target = args[1] || process.cwd();
+    run([INSTALL_SH, '--dry-run', target]);
+    break;
+  }
+
+  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.');
+      process.exit(1);
+    }
+    run(['python3', generatePy, '--force'], { shell: false });
+    break;
+  }
+
+  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.');
+      process.exit(1);
+    }
+    spawnSync('python3', [graderPy], { stdio: 'inherit' });
+    break;
+  }
+
+  case 'help':
+  case '--help':
+  case '-h':
+    console.log(helpText);
+    break;
+
+  default:
+    console.error(`  Unknown command: ${command}`);
+    console.log(helpText);
+    process.exit(1);
+}

package/checksums.json

@@ -0,0 +1,4 @@
+{
+  "install_sh": "3fa520851ef80139d792ade3e6008e4356678153f39414f79c1920bf2a69dab1",
+  "note": "SHA256 of .claude/install.sh — verified by the remote installer before execution"
+}

package/install.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# Babel Fish — Remote Installer
+#
+# Usage:
+#   curl -sSL https://raw.githubusercontent.com/TheGlitchKing/babel-fish/main/install.sh | bash
+#   curl -sSL https://raw.githubusercontent.com/TheGlitchKing/babel-fish/main/install.sh | bash -s -- /path/to/project
+#   curl -sSL https://raw.githubusercontent.com/TheGlitchKing/babel-fish/main/install.sh | bash -s -- --dry-run
+#
+# What this script does (readable before you run it):
+#   1. Creates a temp dir
+#   2. git clone --depth=1 https://github.com/TheGlitchKing/babel-fish.git into it
+#   3. Runs .claude/install.sh <target> from the cloned copy
+#   4. Deletes the temp dir on exit
+#
+# Nothing is written outside of <target>/.claude/ and <target>/.githooks/
+# Run with --dry-run to preview all changes without applying them.
+
+set -euo pipefail
+
+REPO="https://github.com/TheGlitchKing/babel-fish.git"
+CHECKSUM_URL="https://raw.githubusercontent.com/TheGlitchKing/babel-fish/main/checksums.json"
+TMP_DIR="$(mktemp -d)"
+TARGET=""
+DRY_RUN_FLAG=""
+
+# Parse args
+for arg in "$@"; do
+    case "$arg" in
+        --dry-run) DRY_RUN_FLAG="--dry-run" ;;
+        -*) ;;
+        *) TARGET="$arg" ;;
+    esac
+done
+
+TARGET="${TARGET:-$(pwd)}"
+
+cleanup() { rm -rf "$TMP_DIR"; }
+trap cleanup EXIT
+
+echo ""
+echo "  Babel Fish — Remote Installer"
+echo "  Repository: $REPO"
+echo "  Target:     $TARGET"
+if [ -n "$DRY_RUN_FLAG" ]; then
+    echo "  Mode:       DRY RUN (preview only, nothing will be modified)"
+fi
+echo ""
+
+# Verify checksum if sha256sum is available
+if command -v sha256sum >/dev/null 2>&1 && command -v curl >/dev/null 2>&1; then
+    echo "  Fetching checksum manifest..."
+    CHECKSUMS_JSON="$(curl -sSL "$CHECKSUM_URL" 2>/dev/null || echo "")"
+    if [ -n "$CHECKSUMS_JSON" ]; then
+        EXPECTED_SHA="$(echo "$CHECKSUMS_JSON" | grep -o '"install_sh": *"[^"]*"' | grep -o '[a-f0-9]\{64\}' || echo "")"
+        if [ -n "$EXPECTED_SHA" ]; then
+            # Clone and verify
+            echo "  Cloning plugin source..."
+            git clone --depth=1 --quiet "$REPO" "$TMP_DIR/babel-fish"
+            ACTUAL_SHA="$(sha256sum "$TMP_DIR/babel-fish/.claude/install.sh" | cut -d' ' -f1)"
+            if [ "$ACTUAL_SHA" != "$EXPECTED_SHA" ]; then
+                echo ""
+                echo "  ✗ CHECKSUM MISMATCH — aborting for your safety."
+                echo "    Expected: $EXPECTED_SHA"
+                echo "    Got:      $ACTUAL_SHA"
+                echo ""
+                echo "  This may indicate the file was tampered with in transit."
+                echo "  Please report this at https://github.com/TheGlitchKing/babel-fish/issues"
+                exit 1
+            fi
+            echo "  ✓ Checksum verified"
+        else
+            echo "  Cloning plugin source..."
+            git clone --depth=1 --quiet "$REPO" "$TMP_DIR/babel-fish"
+        fi
+    else
+        echo "  Cloning plugin source..."
+        git clone --depth=1 --quiet "$REPO" "$TMP_DIR/babel-fish"
+    fi
+else
+    echo "  Cloning plugin source..."
+    git clone --depth=1 --quiet "$REPO" "$TMP_DIR/babel-fish"
+fi
+
+echo "  Running installer..."
+echo ""
+bash "$TMP_DIR/babel-fish/.claude/install.sh" $DRY_RUN_FLAG "$TARGET"

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@theglitchking/babel-fish",
+  "version": "1.0.1",
+  "description": "Gives your AI coding assistant instant, accurate knowledge of every route, model, service, feature, and infrastructure element in your codebase.",
+  "bin": {
+    "babel-fish": "bin/babel-fish.js"
+  },
+  "scripts": {
+    "postinstall": "node bin/babel-fish.js init --auto"
+  },
+  "files": [
+    "bin/",
+    ".claude-plugin/",
+    "skills/",
+    "install.sh",
+    "checksums.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "codebase-context",
+    "project-map",
+    "vocabulary",
+    "developer-skill",
+    "ai",
+    "llm",
+    "ai-coding",
+    "context-management"
+  ],
+  "author": "TheGlitchKing",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheGlitchKing/babel-fish.git"
+  },
+  "homepage": "https://github.com/TheGlitchKing/babel-fish",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/skills/babel-fish-developer-skill/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: babel-fish-developer-skill
+description: |
+  Full-stack developer context for any project with Babel Fish installed.
+  Provides instant access to project map, vocabulary translation, and infrastructure details.
+  Invoke when working on any feature, bug, or infrastructure task.
+---
+
+# /babel-fish-developer — Developer Context
+
+You are a developer working on this project. This skill gives you complete
+knowledge of every route, model, service, feature, and infrastructure component
+via an auto-generated project map.
+
+## On Trigger — Load Only What You Need
+
+The project map is split into section files at `.claude/project-map/sections/`.
+Do NOT read them all. Start with:
+
+```
+Read: .claude/project-map/PROJECT_MAP.md
+```
+
+Use the Quick Routing table to pick which 2-3 sections to load.
+
+## Section Routing
+
+| Task | Read These Sections |
+|------|-------------------|
+| Feature / UX work | 01-vocabulary → 09-frontend → 04-routes |
+| Add a model or field | 05-models → 06-schemas → 12-import-chains |
+| Troubleshoot error | 02-topology → 03-environment → 14-proxy |
+| Infrastructure / scaling | 16-infra-profile → 02-topology |
+| Auth / security | 15-auth-config → 19-doc-pointers |
+| What tools exist | 10-tools-commands |
+| Background jobs | 08-background-jobs |
+
+## Keeping the Map Current
+
+Regenerates automatically via pre-commit hook.
+Force: `python .claude/project-map/generate.py --force`
+
+## Growing the Runbook
+
+When you encounter a non-obvious operational issue, suggest adding it:
+
+> "This looks like operational knowledge worth documenting. Want me to add it
+> to the runbook? (Y/n)"
+
+If agreed, append a concise entry (symptom → cause → fix) to
+`.claude/rules/operational-runbook.md`.