From 80aae4aee1383259277adbc13426a719e96f6970 Mon Sep 17 00:00:00 2001 From: SergeyVNikitin Date: Mon, 27 Jul 2026 12:55:27 +0400 Subject: [PATCH 1/4] fix(cli): remove \`code\` bin alias from package.json (EPMCDME-13589) Generated with AI Co-Authored-By: codemie-ai Claude-Session: https://claude.ai/code/session_014NeZZse4iQvowT8MfFdwkt --- package.json | 1 - 1 file changed, 1 deletion(-) diff --git a/package.json b/package.json index f2e317e1..0fc7328e 100644 --- a/package.json +++ b/package.json @@ -7,7 +7,6 @@ "types": "dist/index.d.ts", "bin": { "codemie": "./bin/codemie.js", - "code": "./bin/codemie.js", "codemie-code": "./bin/agent-executor.js", "codemie-claude": "./bin/codemie-claude.js", "codemie-claude-acp": "./bin/codemie-claude-acp.js", From 5cc9eaf5fb0170d2d54017e7f45423ee142a2c20 Mon Sep 17 00:00:00 2001 From: SergeyVNikitin Date: Mon, 27 Jul 2026 12:56:19 +0400 Subject: [PATCH 2/4] docs: add MIGRATION.md for \`code\` bin alias removal (EPMCDME-13589) Generated with AI Co-Authored-By: codemie-ai Claude-Session: https://claude.ai/code/session_014NeZZse4iQvowT8MfFdwkt --- docs/MIGRATION.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 docs/MIGRATION.md diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md new file mode 100644 index 00000000..25572968 --- /dev/null +++ b/docs/MIGRATION.md @@ -0,0 +1,55 @@ +# Migration Guide + +## Removing the `code` CLI alias (v0.10.x → next) + +### What changed + +The `code` npm bin alias has been removed from `@codemieai/code`. Running `code` after upgrading will no longer invoke the CodeMie CLI. + +**Why:** The `code` alias collides with the VS Code CLI (`code`) that is widely installed on developer machines. This collision caused confusing behaviour and is a potential security footgun. + +### Who is affected + +Users who invoked CodeMie via the `code` command instead of `codemie`. + +### What to do + +**Option 1 (recommended): Use `codemie` instead.** + +```sh +# Before +code chat + +# After +codemie chat +``` + +All CodeMie commands are available under `codemie` and `codemie-code`. + +**Option 2: Add your own shell alias.** + +If you prefer the shorter name, add this to your `~/.zshrc` or `~/.bashrc`: + +```sh +alias code=codemie +``` + +Then reload your shell: + +```sh +source ~/.zshrc # or ~/.bashrc +``` + +### Stale symlink note + +If you installed `@codemieai/code` globally **before this release**, npm may have already created a `code` symlink in your global bin directory. Upgrading via `npm update -g @codemieai/code` removes it for a fresh install of the new package, but existing symlinks from older installs may persist. + +To verify and clean up: + +```sh +# Check if the stale symlink exists +which code + +# If it still points to codemie, reinstall to clear it +npm unlink -g @codemieai/code && npm install -g @codemieai/code +``` From 5f4a833364333b951d669fd8be51704c19e213d4 Mon Sep 17 00:00:00 2001 From: SergeyVNikitin Date: Mon, 27 Jul 2026 13:11:00 +0400 Subject: [PATCH 3/4] docs: fix MIGRATION.md cleanup command and alias caveat (EPMCDME-13589) - CR-001: replace npm unlink -g with npm uninstall -g (correct command) - CR-002: add VS Code collision warning to Option 2 alias suggestion - CR-003: correct claim that npm update -g removes stale bin symlinks Generated with AI Co-Authored-By: codemie-ai Claude-Session: https://claude.ai/code/session_014NeZZse4iQvowT8MfFdwkt --- docs/MIGRATION.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index 25572968..248246ce 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -28,10 +28,14 @@ All CodeMie commands are available under `codemie` and `codemie-code`. **Option 2: Add your own shell alias.** -If you prefer the shorter name, add this to your `~/.zshrc` or `~/.bashrc`: +> **Warning:** `alias code=codemie` will shadow the VS Code `code` command. If you use VS Code's CLI (`code .`, `code myfile.ts`), this alias will break it. Only do this if you do not rely on VS Code's `code` CLI, or use a different shorthand (e.g. `alias cm=codemie`). + +If you prefer the shorter name and do not use VS Code's `code` CLI, add this to your `~/.zshrc` or `~/.bashrc`: ```sh alias code=codemie +# Or use a shorthand that doesn't conflict: +# alias cm=codemie ``` Then reload your shell: @@ -42,14 +46,14 @@ source ~/.zshrc # or ~/.bashrc ### Stale symlink note -If you installed `@codemieai/code` globally **before this release**, npm may have already created a `code` symlink in your global bin directory. Upgrading via `npm update -g @codemieai/code` removes it for a fresh install of the new package, but existing symlinks from older installs may persist. +If you installed `@codemieai/code` globally **before this release**, npm may have already created a `code` symlink in your global bin directory. Running `npm update -g @codemieai/code` alone does **not** remove the stale symlink — npm does not unlink bin entries that are removed from `package.json` during an update. A full uninstall and reinstall is required. To verify and clean up: ```sh # Check if the stale symlink exists -which code +which code # macOS/Linux; on Windows use: where code -# If it still points to codemie, reinstall to clear it -npm unlink -g @codemieai/code && npm install -g @codemieai/code +# To remove it, uninstall and reinstall the package +npm uninstall -g @codemieai/code && npm install -g @codemieai/code ``` From 0656cf05335ec7633f44547e7e46d2f7d784522a Mon Sep 17 00:00:00 2001 From: SergeyVNikitin Date: Mon, 27 Jul 2026 13:22:13 +0400 Subject: [PATCH 4/4] chore: add planning artifacts for remove-code-bin-alias (EPMCDME-13589) Generated with AI Co-Authored-By: codemie-ai Claude-Session: https://claude.ai/code/session_014NeZZse4iQvowT8MfFdwkt --- .../actual-complexity.json | 63 +++++++ .../code-review-final.json | 59 +++++++ .../decisions.jsonl | 1 + .../events.jsonl | 3 + .../gate-plan.json | 16 ++ .../2026-07-27-remove-code-bin-alias/plan.md | 166 ++++++++++++++++++ .../qa-report.md | 23 +++ .../technical-analysis.md | 134 ++++++++++++++ 8 files changed, 465 insertions(+) create mode 100644 docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/actual-complexity.json create mode 100644 docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/code-review-final.json create mode 100644 docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/decisions.jsonl create mode 100644 docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/events.jsonl create mode 100644 docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/gate-plan.json create mode 100644 docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/plan.md create mode 100644 docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/qa-report.md create mode 100644 docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/technical-analysis.md diff --git a/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/actual-complexity.json b/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/actual-complexity.json new file mode 100644 index 00000000..76c9367e --- /dev/null +++ b/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/actual-complexity.json @@ -0,0 +1,63 @@ +{ + "task": "Remove the 'code' npm bin alias from package.json and add docs/MIGRATION.md with user migration instructions.", + "generated": "2026-07-27T00:00:00Z", + "dimensions": { + "component_scope": { + "score": 1, + "label": "XS", + "affected": "package.json bin section, docs/MIGRATION.md", + "layers": "Package Config" + }, + "requirements_clarity": { + "score": 1, + "label": "XS", + "status": "Clear", + "gaps": null + }, + "technical_risk": { + "score": 2, + "label": "S", + "risk_factors": "Breaking change: existing global npm installations retain a stale 'code' symlink that npm update does not remove; users must fully uninstall and reinstall", + "mitigation": "Migration guide (docs/MIGRATION.md) documents the stale-symlink cleanup steps and alternative aliases" + }, + "file_change_estimate": { + "score": 2, + "label": "S", + "modified_files": 1, + "modified_file_list": ["package.json"], + "new_files": 1, + "new_file_list": ["docs/MIGRATION.md"], + "affected_dirs": [".", "docs"] + }, + "dependencies": { + "score": 1, + "label": "XS", + "new_packages": [], + "version_changes": [] + }, + "affected_layers": { + "score": 1, + "label": "XS", + "layers_changed": ["Package Config"], + "schema_migration": false, + "cross_system": false + } + }, + "total": 8, + "size": "XS", + "band_range": "6-9", + "files_changed": 2, + "routing": "writing-plans", + "key_reasoning": [ + { + "dimension": "technical_risk", + "reason": "S (2) not XS because the removal is a breaking change for published npm users: existing global installs retain a stale 'code' symlink that requires a full uninstall/reinstall to clean up — real user-facing impact even though the code change itself is a single-line deletion with trivial rollback" + }, + { + "dimension": "file_change_estimate", + "reason": "S (2) not XS because the XS band requires no new files; docs/MIGRATION.md is a net-new file, which disqualifies XS even though only 1 file was modified" + } + ], + "red_flags_applied": [], + "split_recommendation": null +} diff --git a/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/code-review-final.json b/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/code-review-final.json new file mode 100644 index 00000000..8a40b531 --- /dev/null +++ b/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/code-review-final.json @@ -0,0 +1,59 @@ +{ + "decision": "request-changes", + "rationale": "Three major documentation defects found in MIGRATION.md: wrong npm cleanup command (unlink vs uninstall), Option 2 contradicts the stated security rationale without a caveat, and the claim that npm update -g removes stale symlinks is inaccurate. No spec/story present — acceptance review in no-spec mode (confidence lowered to low). Commit format and security checks pass. 4 defer/dismiss items excluded (Windows 'which' vs 'where', yarn/pnpm coverage, fish/csh shell, vague version range).", + "confidence": "low", + "risk_flags": ["breaking-change"], + "business_review": [], + "standards_review": [ + { + "kind": "commit-format", + "status": "pass", + "notes": "Both commits use valid Conventional Commits types (fix, docs) and scopes (cli); subjects within 100-char limit; ticket reference present." + }, + { + "kind": "code-quality", + "status": "na", + "notes": "No TypeScript files changed; only package.json manifest (1-line deletion) and Markdown documentation." + }, + { + "kind": "security", + "status": "pass", + "notes": "No secrets, credentials, or unsafe patterns introduced. The collision concern in the migration is correctly framed." + } + ], + "findings": [ + { + "id": "CR-001", + "severity": "major", + "triage": "patch", + "file": "docs/MIGRATION.md", + "line": 60, + "title": "Wrong npm command: `npm unlink -g` should be `npm uninstall -g`", + "problem": "`npm unlink -g @codemieai/code` is not a reliable cleanup command. The &&-chain means if unlink fails (package not found or not linked), the reinstall never runs, leaving the user with neither a working package nor a cleaned symlink.", + "impact": "Users following the cleanup instructions may end up with either a persistent stale symlink or a broken global install with no installed package.", + "recommendation": "Replace `npm unlink -g @codemieai/code && npm install -g @codemieai/code` with `npm uninstall -g @codemieai/code && npm install -g @codemieai/code`." + }, + { + "id": "CR-002", + "severity": "major", + "triage": "patch", + "file": "docs/MIGRATION.md", + "line": 34, + "title": "Option 2 contradicts the stated security rationale without a caveat", + "problem": "The guide removes the `code` alias because it 'collides with the VS Code CLI' and is 'a potential security footgun,' then immediately suggests `alias code=codemie` — re-creating the exact same collision in the user's shell without any warning.", + "impact": "Users who follow Option 2 re-introduce the very problem the removal was meant to solve: `code .` will open CodeMie instead of VS Code.", + "recommendation": "Add an explicit caveat to Option 2 warning that `alias code=codemie` shadows the VS Code `code` command if VS Code is installed. Consider recommending `alias cm=codemie` as a safer shorthand, or at minimum warn users to only do this if they do not use VS Code's `code` CLI." + }, + { + "id": "CR-003", + "severity": "major", + "triage": "patch", + "file": "docs/MIGRATION.md", + "line": 51, + "title": "Inaccurate claim: `npm update -g` does not reliably remove stale bin symlinks", + "problem": "The guide states 'Upgrading via `npm update -g @codemieai/code` removes it for a fresh install of the new package' — this is inaccurate. `npm update -g` does not unlink and relink bin entries when a key is removed from package.json; the stale `code` symlink persists after an update.", + "impact": "Users who run `npm update -g` believing it cleans up the symlink will still have a stale `code` command pointing to codemie after upgrading.", + "recommendation": "Correct the statement: users must run `npm uninstall -g @codemieai/code && npm install -g @codemieai/code` to clear the stale symlink. Remove or correct the misleading `npm update -g` claim." + } + ] +} diff --git a/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/decisions.jsonl b/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/decisions.jsonl new file mode 100644 index 00000000..6d62b0ef --- /dev/null +++ b/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/decisions.jsonl @@ -0,0 +1 @@ +{"ts":"2026-07-27T09:00:00Z","gate_id":"code-review.final","mode":"hitl","verdict":{"decision":"approve","rationale":"User approved with inline fixes for CR-001, CR-002, CR-003.","follow_ups":["fix CR-001: npm unlink → npm uninstall","fix CR-002: add VS Code caveat to Option 2","fix CR-003: correct npm update-g claim"],"confidence":"high","source":"hitl"},"escalated":false,"prior_context":{"question":"3 major findings in docs/MIGRATION.md","phase":5,"risk_flags":["breaking-change"],"artifact_refs":["docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/plan.md","docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/code-review.diff"],"prior_orchestrator_verdict":"docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/code-review-final.json"}} diff --git a/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/events.jsonl b/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/events.jsonl new file mode 100644 index 00000000..f3f138cc --- /dev/null +++ b/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/events.jsonl @@ -0,0 +1,3 @@ +{"event":"lifecycle_emission","intent":"artifact_published","artifact_kind":"plan","status":"failed"} +{"schema":1,"ts":"2026-07-27T09:00:00Z","event":"decision.recorded","run_id":null,"phase":5,"actor":"decision-router","summary":"Decision recorded for code-review.final: approve","artifacts":["decisions.jsonl"],"data":{"gate_id":"code-review.final","mode":"hitl","decision":"approve","source":"hitl","escalated":false,"prior_context":{"question":"3 major findings in docs/MIGRATION.md","options":["Approve — fix findings inline","Approve — ship as-is","Request changes — pause for me to review"],"phase":5,"risk_flags":["breaking-change"],"artifact_refs":["plan.md","code-review.diff"]}}} +{"event":"lifecycle_emission","intent":"record_complexity_score","assessment_mode":"actual","status":"failed"} diff --git a/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/gate-plan.json b/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/gate-plan.json new file mode 100644 index 00000000..fdde37d2 --- /dev/null +++ b/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/gate-plan.json @@ -0,0 +1,16 @@ +{ + "schema": 1, + "runner": "npm", + "gates": [ + {"id": "license-check", "command": "npm run license-check", "available": true}, + {"id": "lint", "command": "npm run lint", "available": true}, + {"id": "typecheck", "command": "npm run typecheck", "available": true}, + {"id": "build", "command": "npm run build", "available": true}, + {"id": "unit", "command": "npm run test:unit", "available": true}, + {"id": "integration", "command": "npm run test:integration", "available": true}, + {"id": "commitlint", "command": "npm run commitlint:last","available": true}, + {"id": "ui", "command": "", "available": false} + ], + "ui_globs": ["\\.(tsx|jsx|css|html|vue|svelte)$", "src/(ui|frontend|components)/"], + "detected_at": "2026-07-27T09:10:00Z" +} diff --git a/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/plan.md b/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/plan.md new file mode 100644 index 00000000..c331ff46 --- /dev/null +++ b/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/plan.md @@ -0,0 +1,166 @@ +# Remove `code` bin alias Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Remove the `"code"` npm bin entry from `package.json` to prevent collisions with VS Code's `code` CLI, and document the migration path for existing users. + +**Architecture:** One-line deletion from `package.json` eliminates the npm-level alias at install time. A new `docs/MIGRATION.md` file explains the breaking change, the stale-symlink caveat (existing installs retain the symlink until reinstall), and two workaround options for users who relied on the `code` shorthand. + +**Tech Stack:** npm bin declarations, Markdown + +## Global Constraints + +- ES modules only — no `require()` in any changed file +- No installer opt-in (`postinstall.mjs` is out of scope for this ticket) +- Migration note must mention the stale-symlink limitation and both workaround options +- Ticket: EPMCDME-13589 + +--- + +### Task 1: Remove `code` from `package.json` bin block + +**Test-first:** no — manifest change, not runtime behaviour. Verification is a `grep` assertion on the file. + +**Files:** +- Modify: `package.json:10` — delete the `"code"` entry + +**Interfaces:** +- Consumes: nothing +- Produces: `package.json` with `bin` block that no longer declares `"code"` — `codemie`, `codemie-code`, and all other entries remain intact + +- [ ] **Step 1: Delete the `"code"` bin line** + +Open `package.json`. The `bin` block currently looks like: + +```json +"bin": { + "codemie": "./bin/codemie.js", + "code": "./bin/codemie.js", + "codemie-code": "./bin/agent-executor.js", + ... +``` + +Remove exactly this line (line 10): + +``` + "code": "./bin/codemie.js", +``` + +After the edit: + +```json +"bin": { + "codemie": "./bin/codemie.js", + "codemie-code": "./bin/agent-executor.js", + ... +``` + +- [ ] **Step 2: Verify `code` is absent and JSON is valid** + +```bash +node -e "const p = JSON.parse(require('fs').readFileSync('package.json','utf8')); console.log(Object.keys(p.bin));" +``` + +Expected output must include `codemie` and `codemie-code` but must NOT include `code`. + +```bash +grep '"code"' package.json | grep -v codemie-code | grep -v codemie-claude +``` + +Expected: no output. + +- [ ] **Step 3: Commit** + +```bash +git add package.json +git commit -m "fix(cli): remove \`code\` bin alias from package.json (EPMCDME-13589)" +``` + +--- + +### Task 2: Create migration note + +**Test-first:** no — documentation task. + +**Files:** +- Create: `docs/MIGRATION.md` + +**Interfaces:** +- Consumes: nothing +- Produces: `docs/MIGRATION.md` — top-level migration guide + +- [ ] **Step 1: Create `docs/MIGRATION.md`** + +```markdown +# Migration Guide + +## Removing the `code` CLI alias (v0.10.x → next) + +### What changed + +The `code` npm bin alias has been removed from `@codemieai/code`. Running `code` after upgrading will no longer invoke the CodeMie CLI. + +**Why:** The `code` alias collides with the VS Code CLI (`code`) that is widely installed on developer machines. This collision caused confusing behaviour and is a potential security footgun. + +### Who is affected + +Users who invoked CodeMie via the `code` command instead of `codemie`. + +### What to do + +**Option 1 (recommended): Use `codemie` instead.** + +​```sh +# Before +code chat + +# After +codemie chat +​``` + +All CodeMie commands are available under `codemie` and `codemie-code`. + +**Option 2: Add your own shell alias.** + +If you prefer the shorter name, add this to your `~/.zshrc` or `~/.bashrc`: + +​```sh +alias code=codemie +​``` + +Then reload your shell: + +​```sh +source ~/.zshrc # or ~/.bashrc +​``` + +### Stale symlink note + +If you installed `@codemieai/code` globally **before this release**, npm may have already created a `code` symlink in your global bin directory. Upgrading via `npm update -g @codemieai/code` removes it for a fresh install of the new package, but existing symlinks from older installs may persist. + +To verify and clean up: + +​```sh +# Check if the stale symlink exists +which code + +# If it still points to codemie, remove it manually +npm unlink -g @codemieai/code && npm install -g @codemieai/code +​``` +``` + +- [ ] **Step 2: Verify file was created** + +```bash +ls -la docs/MIGRATION.md +grep -c "stale symlink" docs/MIGRATION.md +``` + +Expected: file exists, grep returns `1`. + +- [ ] **Step 3: Commit** + +```bash +git add docs/MIGRATION.md +git commit -m "docs: add MIGRATION.md for \`code\` bin alias removal (EPMCDME-13589)" +``` diff --git a/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/qa-report.md b/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/qa-report.md new file mode 100644 index 00000000..a4daa798 --- /dev/null +++ b/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/qa-report.md @@ -0,0 +1,23 @@ +# QA Gate Report — remove-code-bin-alias + +**Branch**: EPMCDME-13589 +**Runner**: npm +**Started**: 2026-07-27T09:10:00Z +**Status**: PASSED + +## Gates + +| Gate | Status | Command | Notes | +|--------------|---------|-------------------------------|-------| +| license-check | PASS | `npm run license-check` | All dependencies have compatible licenses | +| lint | PASS | `npm run lint` | 0 errors, 0 warnings | +| typecheck | PASS | `npm run typecheck` | No TypeScript diagnostics | +| build | PASS | `npm run build` | dist/ rebuilt cleanly; copy-plugin succeeded | +| unit | PASS | `npm run test:unit` | 162 test files, 2382 tests passed, 1 skipped | +| integration | PASS | `npm run test:integration` | 28 test files, 196 tests passed, 11 skipped | +| commitlint | PASS | `npm run commitlint:last` | 0 problems, 0 warnings | +| ui | SKIPPED | — | No UI surface files changed (.tsx/.jsx/.css/.html) | + +## Drift signal + +no diff --git a/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/technical-analysis.md b/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/technical-analysis.md new file mode 100644 index 00000000..5a31ea81 --- /dev/null +++ b/docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/technical-analysis.md @@ -0,0 +1,134 @@ +# Technical Research + +**Task**: bin package.json installer cli alias +**Generated**: 2026-07-27T00:00:00Z +**Research path**: codegraph + +--- + +## 1. Original Context + +Remove code from package.json bin mapping (prevents accidental collisions). Document migration ('use codemie / codemie-code; optional alias if you insist'). Optionally add an explicit installer opt-in to create a code alias, but only if product wants to support that legacy habit. Jira ticket: EPMCDME-13589. + +--- + +## 2. Codebase Findings + +### Existing Implementations + +- `package.json:10` — `"code": "./bin/codemie.js"` — the single npm bin declaration that creates the `code` shell command; both `"codemie"` (line 9) and `"code"` (line 10) point to the identical entry script; this one line is the complete deletion target +- `package.json:9` — `"codemie": "./bin/codemie.js"` — the primary bin entry that remains after removal +- `package.json:11` — `"codemie-code": "./bin/agent-executor.js"` — the agent-runner shortcut; entirely separate from the `code` alias and unaffected +- `bin/codemie.js` — primary CLI entry point shared by both `codemie` and `code`; runs migration checks, update check, then delegates to `dist/cli/index.js`; no reference to the `code` alias name at runtime +- `bin/agent-executor.js` — entry for `codemie-code` (agent runner via AgentCLI + AgentRegistry) +- `scripts/postinstall.mjs` — runs on `npm install`; two responsibilities only: (1) restores execute bits on the `node-pty` spawn-helper binary on macOS, (2) appends `export PATH=":$PATH"` to `.zshrc` / `.bashrc` / `.bash_profile` if the npm bin dir is not already in PATH; does not create shell aliases and does not reference `code` anywhere +- `src/utils/cli-bin.ts` — `restoreCliBinLink()` atomically repairs the global `codemie` symlink when an agent package overwrites it (called from `install.ts` and `update.ts`); hardcoded to the `codemie` symlink path only; has no awareness of the `code` alias and requires no changes +- `src/utils/install.ts:185` — calls `restoreCliBinLink()` after agent plugin install +- `src/utils/update.ts:309,389` — calls `restoreCliBinLink()` after agent update +- `install/macos/install.sh`, `install/windows/install.cmd`, `install/windows/install.ps1` — desktop app (CodeMie Connect) installers; completely unrelated to the npm bin alias + +### Architecture and Layers Affected + +- **Package manifest layer**: `package.json` `bin` block — one-line deletion is the sole required change for the core removal +- **Post-install hook layer** (`scripts/postinstall.mjs`) — currently untouched by the alias; if the optional installer opt-in is added, this file would need new alias-creation logic (novel pattern for this script) +- **Documentation layer** — no existing CHANGELOG, no existing migration guide; a new migration note must be created from scratch +- **CLI entry layer** (`bin/`) — no changes needed; `bin/codemie.js` continues to serve the `codemie` bin entry + +### Integration Points + +- The `code` bin alias has no unique runtime behavior — it shares 100% of its code path with `codemie` via `bin/codemie.js → dist/cli/index.js` +- npm bin mechanism: on `npm install -g @codemieai/code`, npm creates symlinks in the global bin dir for each key in the `bin` block; removing `"code"` from the block means new installs will not create the symlink, but existing symlinks on already-installed machines persist until `npm uninstall` + reinstall or manual `npm unlink` +- `restoreCliBinLink()` is invoked by agent plugin install/update flows to protect the `codemie` symlink; it does not protect or reference the `code` symlink and needs no changes +- No internal module imports the `code` alias name; it is purely an npm-level declaration + +### Patterns and Conventions + +- All bin entries in `package.json` follow the pattern: `"": "./bin/.js"` where each `.js` is a thin loader that resolves the `dist/` equivalent +- `postinstall.mjs` uses `execSync('npm config get prefix')` to resolve the npm bin dir; any opt-in alias creation would need to follow the same approach to locate where to write a shell alias +- `restoreCliBinLink()` uses an atomic rename trick (`fs.renameSync(tmp, target)`) for symlink safety — a pattern to follow if symlink management is added to postinstall +- No shell-alias injection exists anywhere in the codebase today; adding one to `postinstall.mjs` is a new pattern + +--- + +## 3. Documentation Findings + +### Guides and Architecture Docs + +- `.ai-run/guides/usage/project-config.md` — covers ConfigLoader and profile resolution; no reference to bin entries or the `code` alias; not relevant to this task +- `.ai-run/guides/integration/exposed-api.md` — documents programmatic API surface; no reference to CLI binary names or the `code` alias; not relevant +- No guide covers bin-alias management or migration documentation conventions + +### Architectural Decisions + +- No ADRs or recorded decisions found for the `code` bin alias introduction or its removal +- `restoreCliBinLink()` in `src/utils/cli-bin.ts` reflects a prior decision to protect the `codemie` symlink against agent plugin overwrites — that decision is scoped to `codemie` and does not extend to `code` + +### Derived Conventions + +- All user-visible documentation (README.md, docs/COMMANDS.md, docs/AGENTS.md, docs/EXAMPLES.md, docs/CONFIGURATION.md, docs/SKILLS.md) consistently uses `codemie` and `codemie-code` in examples; the `code` alias has never been surfaced to users in docs +- Migration notes should be placed in a new file (e.g., `docs/migration/`) or in a release notes document — no established location exists +- The project has no CHANGELOG file; a migration note should target release notes or the PR description as the minimum + +--- + +## 4. Testing Landscape + +### Existing Coverage + +- `src/utils/__tests__/cli-bin.test.ts` — unit tests for `restoreCliBinLink()`; covers the `codemie` symlink guard only; no test touches the `code` alias +- `tests/integration/cli-commands/skills.test.ts` — e2e integration test for `codemie skills`; hard-codes `CLI_BIN = path.join(REPO_ROOT, 'bin', 'codemie.js')` (not `code`); tests command behavior, not bin-alias presence + +### Testing Framework and Patterns + +- Vitest (multi-project config: `unit`, `cli`, `agent` projects) +- Integration tests invoke CLI via `execa` or `child_process.spawn` against the `bin/` entry scripts directly +- No fixture or factory pattern specific to bin-alias testing + +### Coverage Gaps + +- No test asserts that the `code` bin command exists or is absent — the removal cannot be regression-tested without a new smoke-check +- No test covers `scripts/postinstall.mjs` behavior (PATH injection or alias creation) +- If the optional installer opt-in is added, its logic in `postinstall.mjs` would be entirely untested + +--- + +## 5. Configuration and Environment + +### Environment Variables + +- `CODEMIE_CREATE_CODE_ALIAS` — does not exist today; would be a new env var to implement if the optional installer opt-in is added +- `CODEMIE_INTEGRATION_ALIAS` — existing env var in `src/utils/config.ts`; governs SDK integration alias, unrelated to the bin alias +- `CODEMIE_SKILLS_BIN_OVERRIDE` — test-only override for skills CLI binary path; unrelated + +### Configuration Files + +- `package.json` `bin` block — the only configuration governing the `code` alias; removing line 10 is the complete configuration change required for the core task +- `scripts/postinstall.mjs` — would need modification only if the opt-in alias feature is added; currently has no alias logic + +### Feature Flags and Deployment Concerns + +- No feature flags govern the `code` bin alias today +- npm's bin linking is applied at install time — removal from `package.json` takes effect for new installs and upgrades via `npm update -g`; users who installed before the removal retain the `code` symlink until they reinstall +- A breaking-change notice in the npm publish release notes is the standard mechanism to communicate this to existing users +- `install/macos/` and `install/windows/` desktop installers are unaffected + +--- + +## 6. Risk Indicators + +- **Stale symlinks on existing installs**: removing `"code"` from `package.json` does not remove the npm-created symlink on machines where `@codemieai/code` is already globally installed; users must reinstall or run `npm unlink code` manually — this is an inherent npm limitation and should be documented in the migration note +- **No test coverage for the `code` bin entry or its absence**: there is no CI gate that would catch a regression if the entry were accidentally re-added; a minimal smoke-check (asserting `code` command is absent post-install) would close this gap but does not exist +- **No CHANGELOG or migration guide infrastructure**: the project has no `CHANGELOG` file and no `docs/migration/` directory; the migration note must be created in a new location with no established convention to follow +- **Installer opt-in is a novel pattern**: `scripts/postinstall.mjs` currently only adds npm bin dir to PATH; writing a shell alias (e.g., `alias code=codemie >> ~/.zshrc`) would be new behavior with no precedent in the codebase — cross-shell correctness (zsh vs bash vs fish), idempotency, and quoting of the alias value would all need care +- **No documentation references the `code` alias**: the removal is low-risk from a documentation standpoint — README and all docs in `docs/` use only `codemie` and `codemie-code`; no doc updates are required for the core removal +- **codegraph returned false positives on dimension 1**: the `bin package.json cli entry points` query returned chart.umd.js hits; direct file reads were used to confirm ground truth — this is a minor indexing noise, not a codebase risk + +--- + +## 7. Summary for Complexity Assessment + +The core removal is a single-line deletion from `package.json` (line 10, the `"code"` key in the `bin` block). No runtime code, no `src/` files, no `bin/` entry scripts, and no `scripts/postinstall.mjs` logic need to change for the removal itself. The `restoreCliBinLink()` utility in `src/utils/cli-bin.ts` is already scoped to the `codemie` symlink and is fully unaffected. All user-facing documentation already uses `codemie` and `codemie-code` exclusively — no README or docs/ updates are needed for the core change. The task touches only the Package Manifest layer for its mandatory portion. Estimated file change surface: one file, one line for the core removal. + +The migration documentation requirement adds moderate scope: no CHANGELOG and no migration guide directory exist, so a new file and location must be established. The migration note itself is straightforward prose ("use `codemie` or `codemie-code`; if you need the `code` shorthand, add `alias code=codemie` to your shell RC"), but agreeing on the location and format introduces a small ambiguity. The stale-symlink caveat (npm does not auto-remove existing symlinks on upgrade) must be included in the migration note and is non-obvious to users. + +The optional installer opt-in — creating a `code` shell alias via `postinstall.mjs` if a flag is set — is technically the highest-risk sub-task. It would introduce new shell-alias injection logic into `postinstall.mjs` (a novel pattern for this script), require cross-shell correctness (zsh, bash, fish), idempotency checks, and env-var gating (`CODEMIE_CREATE_CODE_ALIAS`). If product decides to implement it, this portion would expand the change surface to two or three files and add meaningful test coverage debt. Overall the task is low-complexity for the mandatory parts and medium-complexity if the opt-in feature is included.