@unbrained/pm-cli 2026.5.10 → 2026.5.12

package/.claude-plugin/marketplace.json

@@ -1,19 +1,19 @@
 {
-  "name": "pm-cli",
+  "name": "pm",
   "owner": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "1.0.0"
+    "version": "1.3.0"
   },
   "plugins": [
     {
       "name": "pm-cli",
       "source": "./plugins/pm-cli-claude",
-      "description": "Native pm CLI integration for Claude Code — 18 MCP tools, workflow skills, slash commands, session context injection, and a coordination subagent for git-based project management without leaving Claude Code.",
-      "version": "1.0.0",
+      "description": "Native pm CLI integration for Claude Code — 18 MCP tools, 5 workflow skills, 14 slash commands, 3 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
+      "version": "1.3.0",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/AGENTS.md

@@ -321,120 +321,7 @@ Recover previous state:
 pm restore pm-a1b2 2026-02-17T11:15:03.120Z
 ```
 
-## 9) Pi Tool Wrapper Usage
-
-The built-in Pi wrapper exposes one tool: `pm`.
-Reference implementation source lives at `.pi/extensions/pm-cli/index.ts` as a Pi agent extension module.
-`pm install` has been removed; install bundled managed runtime extensions via `pm extension --install beads|todos` (or explicit `.agents/pm/extensions/<name>` paths) when needed.
-Load the Pi wrapper in Pi with `pi -e ./.pi/extensions/pm-cli/index.ts` (or copy it into your Pi extensions directory).
-Use `action: "completion"` with `shell: "bash"|"zsh"|"fish"` to forward to `pm completion <shell>`.
-Use `action: "calendar"` for date-centric event views (`view`, `date`, `from`, `to`, `past`, `fullPeriod`, `type`, `tag`, `priority`, `status`, `assignee`, `sprint`, `release`, `limit`, `format`).
-Use `action: "aggregate"` for grouped decomposition checks (`groupBy`, `count`, `includeUnparented`, list-style filters).
-Use `action: "dedupe-audit"` for duplicate corpus checks (`mode`, `threshold`, `limit`, list-style filters).
-Use `action: "normalize"` for lifecycle metadata hygiene scans (`dryRun`) and explicit apply mode (`apply`) with list-style filter targeting.
-Use `action: "validate"` with optional check toggles (`checkMetadata`, `checkResolution`, `checkFiles`, `checkHistoryDrift`) and optional `scanMode` (`default|tracked-all`) for standalone audit workflows.
-Use `action: "extension-doctor"` for consolidated extension diagnostics with optional `scope` and `detail` (`summary|deep`).
-For `list*` wrapper actions, use projection/sort controls (`compact`, `fields`, `sort`, `order`) plus `includeBody` when body projection is needed.
-For `comments-audit`, use governance filters (`parent`, `tag`, `sprint`, `release`, `priority`) in addition to status/type/assignee filters.
-For `health`, use vector refresh controls (`checkOnly`, `noRefresh`, `refreshVectors`) while keeping strict flags available (`strictDirectories`, `strictExit`, `failOnWarn`).
-For `create` and `update`, use camelCase wrapper parameters for the canonical CLI scalar fields such as `parent`, `reviewer`, `risk`, `confidence`, `sprint`, `release`, `blockedBy`, `blockedReason`, `unblockNote`, `definitionOfReady`, `order`, `goal`, `objective`, `value`, `impact`, `outcome`, `whyNow`, `reporter`, `severity`, `environment`, `reproSteps`, `resolution`, `expectedResult`, `actualResult`, `affectedVersion`, `fixedVersion`, `component`, `regression`, and `customerImpact`; use `createMode` (`strict|progressive`) when staged creation is needed, `appendStable` for minimal-diff file-link appends, `allowAuditUpdate` for ownership-safe metadata-only non-owner updates, `allowAuditDepUpdate` for ownership-safe dependency-only non-owner updates, `allowAuditComment` for additive non-owner comment writes, repeatable `reminder` values for persistent reminders (`at=<iso|relative>,text=<text>`), and repeatable `typeOption` values for custom type metadata.
-For `contracts`, use projection controls (`flagsOnly`, `availabilityOnly`) when you need narrow machine-readable payloads; with `command` selected, contract output is command-scoped by default.
-For `completion`, use `eagerTags` only when embedding static tags in generated scripts is required; default generated scripts resolve tags lazily at runtime.
-For `activity`, use `id`, `op`, `author`, `from`, `to`, `limit`, and `stream` (`rows|ndjson|jsonl` or boolean true) for deterministic timeline filtering/export.
-For `test` and `test-all`, prefer explicit runtime parity/strictness parameters when needed: `pmContext` (`schema|tracker|auto`), `checkContext`, `autoPmContext`, `failOnContextMismatch`, `failOnSkipped`, and `requireAssertionsForPm`.
-For `gc`, use `dryRun` and repeatable `gcScope` (`index`, `embeddings`, `runtime`) for no-side-effect previews and targeted cleanup.
-
-### Example: list open tasks
-
-```json
-{
-  "action": "list-open",
-  "limit": 10
-}
-```
-
-### Example: create item
-
-```json
-{
-  "action": "create",
-  "title": "Implement extension loader",
-  "description": "Load global and project extensions with precedence.",
-  "type": "Feature",
-  "status": "open",
-  "priority": 1,
-  "tags": "extensions,core",
-  "body": "",
-  "deadline": "+14d",
-  "estimate": 120,
-  "acceptanceCriteria": "Loader applies deterministic precedence for core global and project extensions.",
-  "author": "maintainer-agent",
-  "message": "Create extension loader task",
-  "assignee": "maintainer-agent",
-  "parent": "pm-epic01",
-  "reviewer": "maintainer-reviewer",
-  "risk": "medium",
-  "confidence": "high",
-  "sprint": "maintainer-loop",
-  "release": "v0.1",
-  "blockedBy": "pm-arch-review",
-  "blockedReason": "Awaiting architecture sign-off",
-  "unblockNote": "Resume implementation once review notes are resolved",
-  "reporter": "maintainer-agent",
-  "severity": "medium",
-  "environment": "cli",
-  "reproSteps": "Create conflicting extension registrations across project/global scopes",
-  "resolution": "Apply deterministic precedence in extension loader bootstrap",
-  "expectedResult": "Loader applies project-over-global precedence deterministically",
-  "actualResult": "Registration order currently varies by load path",
-  "affectedVersion": "v0.1",
-  "fixedVersion": "v0.2",
-  "component": "extension-host",
-  "regression": "false",
-  "customerImpact": "Unpredictable extension behavior increases operator overhead",
-  "definitionOfReady": "Extension loading behavior is clarified in docs.",
-  "order": 1,
-  "goal": "Release-hardening",
-  "objective": "Ship deterministic extension loading",
-  "value": "Makes extension behavior predictable for agents and humans",
-  "impact": "Reduces configuration and precedence drift",
-  "outcome": "Extension loader applies deterministic precedence",
-  "whyNow": "Extension loading is foundational for the remaining roadmap",
-  "dep": ["id=pm-epic01,kind=parent,author=maintainer-agent,created_at=now"],
-  "comment": ["author=maintainer-agent,created_at=now,text=Why this task exists align extension load precedence behavior."],
-  "note": ["author=maintainer-agent,created_at=now,text=Initial implementation plan wire loader in runtime bootstrap."],
-  "learning": [],
-  "linkedFile": ["path=src/core/extensions/loader.ts,scope=project,note=planned implementation file"],
-  "linkedTest": ["command=node scripts/run-tests.mjs test,scope=project,timeout_seconds=240,note=sandbox-safe regression"],
-  "doc": ["path=docs/ARCHITECTURE.md,scope=project,note=implementation reference"]
-}
-```
-
-### Example: append body update
-
-```json
-{
-  "action": "append",
-  "id": "pm-a1b2",
-  "body": "Implemented lock TTL and stale lock override."
-}
-```
-
-Expected wrapper return shape:
-
-```json
-{
-  "content": [
-    { "type": "text", "text": "..." }
-  ],
-  "details": {
-    "action": "create",
-    "item": {}
-  }
-}
-```
-
-## 10) Multi-Agent Etiquette
+## 9) Multi-Agent Etiquette
 
 - Claim before heavy edits.
 - Release when blocked or context-switching.
@@ -442,7 +329,7 @@ Expected wrapper return shape:
 - Avoid silent force-claim unless policy allows and conflict is stale.
 - Keep item descriptions stable; append details in body/notes/comments.
 
-## 11) Troubleshooting for Agents
+## 10) Troubleshooting for Agents
 
 Lock conflict:
 
@@ -467,7 +354,7 @@ Extension issues:
 - when debugging runtime behavior changes, inspect parser/preflight/service override collisions in health/profile diagnostics (last registration wins)
 - use SDK contracts from `@unbrained/pm-cli/sdk` (not internal `src/core/...` imports) for extension authoring and examples
 
-## 12) Dogfood Logging Protocol (Required)
+## 11) Dogfood Logging Protocol (Required)
 
 From now on in this repository, all implementation work must be tracked through `pm` items and `pm` mutations.
 

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2026.5.12] - 2026-05-12
+
+### Changed
+- Added `pm install '*'` / `pm install all` to install all bundled first-party pm packages, including shell-expanded `pm install *`, and added typechecking for TypeScript-authored package sources.
+- Added `pm upgrade` for package-first maintenance, including dry-run planning, CLI/SDK npm self-upgrade, managed package refresh from recorded sources, SDK/MCP action contracts, and docs/help coverage.
+- Moved the Beads and Todo import/export bridges out of active project extension state so they are sourced from the first-party `packages/pm-beads` and `packages/pm-todos` package roots and installed on demand.
+
+## [2026.5.11] - 2026-05-11
+
+### Added
+- Claude Code plugin v1.3.0: added `pm-triage-agent`, `pm-verification-agent`, and `pm-delivery-chain` subagents for full end-to-end pm workflow orchestration without leaving Claude Code.
+- Claude Code plugin: registered `pm` as the canonical marketplace ID so the plugin installs via `/plugin install pm-cli@pm` (both `pm` and `pm-cli` marketplace IDs resolve to the same plugin).
+- Claude Code plugin: rewrote session-start hook to use native `dist/pi/native.js` modules when available (repo checkout), falling back to `npx @unbrained/pm-cli` — no global `pm` CLI required.
+
 ## [2026.5.10] - 2026-05-10
 
 ### Changed

package/PRD.md

@@ -43,9 +43,9 @@ Existing trackers either rely on hosted backends, store state in non-diff-friend
 - Provide safe mutation under concurrent access (claim/release + lock + atomic writes).
 - Default stdout to TOON; support `--json` parity for every command.
 - Provide extension architecture for commands, schema, rendering, import/export, search adapters, and hooks.
-- Ship bundled managed extension sources:
-  - Beads import (`beads` alias, installed via `pm extension --install`)
-  - todos.ts import/export (`todos` alias, installed via `pm extension --install`)
+- Ship first-party installable package sources:
+  - Beads import (`packages/pm-beads`, installed via `pm install`)
+  - todos.ts import/export (`packages/pm-todos`, installed via `pm install`)
   - Pi agent extension wrapper source module
 - Provide optional semantic search with provider + vector-store adapters.
 
@@ -1327,7 +1327,7 @@ export interface ExtensionApi {
 - Mandatory migration resolution is deterministic: `status` equal to `"applied"` (case-insensitive) is treated as resolved; any other/missing status is unresolved.
 - Force-capable write commands may bypass the guard with explicit `--force`; write commands without `--force` remain blocked until blockers resolve.
 
-## 15) Bundled Managed Extensions Required in v1
+## 15) First-Party Installable Packages Required in v1
 
 ### A) Beads import
 
@@ -1337,8 +1337,8 @@ Command:
 
 Current baseline status (release-hardening):
 
-- Command is packaged in bundled managed extension source (`.agents/pm/extensions/beads`) using `activate(api)` and `api.registerCommand({ name, run })` for `beads import`.
-- Command path is available only after extension install/activation in selected scope (`pm extension --install beads` or explicit path install).
+- Command is packaged in the first-party package root (`packages/pm-beads`) using `activate(api)` and `api.registerCommand({ name, run })` for `beads import`.
+- Command path is available only after package install/activation in selected scope (`pm install packages/pm-beads`, package aliases, or explicit package source install).
 
 Behavior:
 
@@ -1359,8 +1359,8 @@ Commands:
 
 Current baseline status (release-hardening):
 
-- Commands are packaged in bundled managed extension source (`.agents/pm/extensions/todos`) using `activate(api)` and `api.registerCommand({ name, run })` for `todos import` and `todos export`.
-- Command paths are available only after extension install/activation in selected scope (`pm extension --install todos` or explicit path install).
+- Commands are packaged in the first-party package root (`packages/pm-todos`) using `activate(api)` and `api.registerCommand({ name, run })` for `todos import` and `todos export`.
+- Command paths are available only after package install/activation in selected scope (`pm install packages/pm-todos`, package aliases, or explicit package source install).
 
 Behavior:
 
@@ -1711,10 +1711,10 @@ Definition of Done:
 Checklist:
 
 - [x] extension manifest loader + sandboxed execution boundary (deterministic manifest discovery, precedence, failure-isolated runtime loading, realpath/symlink-resolved entry containment enforcement, command-handler context snapshot isolation for `args`/`options`/`global`, per-hook context snapshot isolation, and dynamic extension command loose-option parsing hardening (null-prototype option maps + prototype-pollution key rejection) are implemented; broader command sandbox API surface is post-v0.1 roadmap)
-- [x] hook lifecycle (extension `activate(api)` baseline with deterministic hook registration is implemented; registration now validates hook handlers as functions at activation time, per-hook context snapshot isolation prevents mutation leakage across hook callbacks and caller state, and `beforeCommand`/`afterCommand` command-lifecycle execution plus baseline read/write/index call-site wiring for core item-store reads/writes, create/restore item and history writes, settings read/write operations, history/activity history-directory scans and history-stream reads, health history-directory scans plus history-stream path dispatch, search item/linked reads, reindex flows, stats/health/gc command file-system paths (including `pm gc` onIndex dispatch with mode `gc` and deterministic cache-target totals), lock file read/write/unlink operations, init directory bootstrap ensure-write dispatch, and bundled managed beads/todos import-export source/item/history file operations are implemented)
+- [x] hook lifecycle (extension `activate(api)` baseline with deterministic hook registration is implemented; registration now validates hook handlers as functions at activation time, per-hook context snapshot isolation prevents mutation leakage across hook callbacks and caller state, and `beforeCommand`/`afterCommand` command-lifecycle execution plus baseline read/write/index call-site wiring for core item-store reads/writes, create/restore item and history writes, settings read/write operations, history/activity history-directory scans and history-stream reads, health history-directory scans plus history-stream path dispatch, search item/linked reads, reindex flows, stats/health/gc command file-system paths (including `pm gc` onIndex dispatch with mode `gc` and deterministic cache-target totals), lock file read/write/unlink operations, init directory bootstrap ensure-write dispatch, and first-party Beads/Todos package source/item/history file operations are implemented)
 - [x] renderer and command extension points (deterministic core-command override + renderer override registration/dispatch is implemented with failure containment, extension command handlers for declared command paths including dynamically surfaced non-core paths are implemented, dynamic command help now surfaces `registerFlags` metadata deterministically, deep snapshot isolation for override/renderer result contexts is implemented, and override/renderer execution now includes cloned command `args`/`options`/`global` snapshots plus `pm_root` metadata for contextual deterministic extension output behavior)
-- [x] bundled managed beads import extension (bundled source packaging in `.agents/pm/extensions/beads`, install-only command surfacing through `pm extension`, Beads JSONL field mapping, deterministic defaults, `op: "import"` history entries, and parity polish implemented)
-- [x] bundled managed todos import/export extension (bundled source packaging in `.agents/pm/extensions/todos`, install-only command surfacing through `pm extension`, todos markdown round-trip, canonical optional metadata preservation including planning/workflow and issue fields, hierarchical ID preservation, and `med` alias normalization implemented)
+- [x] first-party Beads import package (`packages/pm-beads`) with install-only command surfacing through `pm install`, Beads JSONL field mapping, deterministic defaults, `op: "import"` history entries, and parity polish implemented)
+- [x] first-party Todos import/export package (`packages/pm-todos`) with install-only command surfacing through `pm install`, todos markdown round-trip, canonical optional metadata preservation including planning/workflow and issue fields, hierarchical ID preservation, and `med` alias normalization implemented)
 - [x] Pi tool wrapper extension source module (Pi agent extension module at `.pi/extensions/pm-cli/index.ts` with full v0.1 action dispatch parity, including `completion` + `shell` mapping, camelCase parameter surface for all canonical scalar metadata, explicit empty-string passthrough, numeric-flag stringification, claim/release parity, packaged CLI fallback, and distribution packaging polish implemented)
 
 Definition of Done:

package/README.md

@@ -16,7 +16,7 @@
 | Command families and examples | [Command Reference](docs/COMMANDS.md) |
 | Settings, storage, search, and output | [Configuration](docs/CONFIGURATION.md) |
 | Safe test execution and linked tests | [Testing](docs/TESTING.md) |
-| Extension authoring | [Extensions](docs/EXTENSIONS.md) and [SDK](docs/SDK.md) |
+| Package and extension authoring | [Packages and Extensions](docs/EXTENSIONS.md) and [SDK](docs/SDK.md) |
 | Pi native package | [Pi Package](docs/PI_PACKAGE.md) |
 | Codex native integration | [Codex Plugin](docs/CODEX_PLUGIN.md) |
 | Maintainer release process (daily auto-release + local parity) | [Releasing](docs/RELEASING.md) |
@@ -51,13 +51,31 @@ Project-local invocation also works:
 npx @unbrained/pm-cli --help
 ```
 
+For Claude Code, install the native plugin (no `pm` CLI required):
+
+```
+/plugin install pm-cli@pm
+```
+
+This registers 18 MCP tools, 5 workflow skills, 14 slash commands, 3 subagents, hybrid TUI tracking, and a session-start context hook — all without shelling out to the `pm` CLI.
+
 For Pi, install the native package integration after publish:
 
 ```bash
 pi install npm:@unbrained/pm-cli
 ```
 
-This registers a native `pm` tool, Pi skills, and prompt templates without requiring Pi to run the `pm` shell command.
+This registers a native `pm` tool, custom TUI panels/renderers (`/pm-board`, `/pm-item`, `/pm-history`), Pi skills, prompt templates, and optional pi-subagents setup without requiring Pi to run the `pm` shell command.
+
+`pm` packages use the same package-first vocabulary:
+
+```bash
+pm install ./my-package
+pm package manage --project
+pm package doctor --detail summary
+```
+
+The legacy `pm extension ...` command remains available for existing automation.
 
 ## 60 Second Example
 

package/dist/cli/argv-utils.d.ts

@@ -0,0 +1,5 @@
+export declare function normalizeLongFlag(flag: string): string;
+export declare function normalizeLongOptionFlag(token: string): string | undefined;
+export declare function extractProvidedOptionFlags(argv: string[]): string[];
+export declare function quoteCommandArg(arg: string): string;
+export declare function renderPmCommand(argv: string[]): string;

package/dist/cli/argv-utils.js

@@ -0,0 +1,34 @@
+export function normalizeLongFlag(flag) {
+    return `--${flag
+        .replace(/^--?/, "")
+        .replace(/_/g, "-")
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()}`;
+}
+export function normalizeLongOptionFlag(token) {
+    if (!token.startsWith("--")) {
+        return undefined;
+    }
+    const key = token.includes("=") ? token.slice(0, token.indexOf("=")) : token;
+    return normalizeLongFlag(key);
+}
+export function extractProvidedOptionFlags(argv) {
+    const provided = new Set();
+    for (const token of argv) {
+        const normalized = normalizeLongOptionFlag(token);
+        if (normalized) {
+            provided.add(normalized);
+        }
+    }
+    return [...provided].sort((left, right) => left.localeCompare(right));
+}
+export function quoteCommandArg(arg) {
+    if (/^[A-Za-z0-9._:/@=-]+$/.test(arg)) {
+        return arg;
+    }
+    return `"${arg.replace(/(["\\$`])/g, "\\$1")}"`;
+}
+export function renderPmCommand(argv) {
+    return `pm ${argv.map((token) => quoteCommandArg(token)).join(" ")}`;
+}
+//# sourceMappingURL=argv-utils.js.map

package/dist/cli/argv-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argv-utils.js","sourceRoot":"/","sources":["cli/argv-utils.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,KAAK,IAAI;SACb,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;SACnB,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC;SAClB,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,WAAW,EAAE,EAAE,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,KAAa;IACnD,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAC7E,OAAO,iBAAiB,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,IAAc;IACvD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,IAAI,EAAE,CAAC;QACzB,MAAM,UAAU,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;QAClD,IAAI,UAAU,EAAE,CAAC;YACf,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,IAAI,uBAAuB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACtC,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAc;IAC5C,OAAO,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACvE,CAAC","sourcesContent":["export function normalizeLongFlag(flag: string): string {\n  return `--${flag\n    .replace(/^--?/, \"\")\n    .replace(/_/g, \"-\")\n    .replace(/([a-z0-9])([A-Z])/g, \"$1-$2\")\n    .toLowerCase()}`;\n}\n\nexport function normalizeLongOptionFlag(token: string): string | undefined {\n  if (!token.startsWith(\"--\")) {\n    return undefined;\n  }\n  const key = token.includes(\"=\") ? token.slice(0, token.indexOf(\"=\")) : token;\n  return normalizeLongFlag(key);\n}\n\nexport function extractProvidedOptionFlags(argv: string[]): string[] {\n  const provided = new Set<string>();\n  for (const token of argv) {\n    const normalized = normalizeLongOptionFlag(token);\n    if (normalized) {\n      provided.add(normalized);\n    }\n  }\n  return [...provided].sort((left, right) => left.localeCompare(right));\n}\n\nexport function quoteCommandArg(arg: string): string {\n  if (/^[A-Za-z0-9._:/@=-]+$/.test(arg)) {\n    return arg;\n  }\n  return `\"${arg.replace(/([\"\\\\$`])/g, \"\\\\$1\")}\"`;\n}\n\nexport function renderPmCommand(argv: string[]): string {\n  return `pm ${argv.map((token) => quoteCommandArg(token)).join(\" \")}`;\n}\n"]}

package/dist/cli/bootstrap-args.d.ts

@@ -15,4 +15,19 @@ export declare function parseBootstrapHelpRequest(argv: string[]): BootstrapHelp
 export declare function parseBootstrapCommandName(argv: string[]): string | undefined;
 export declare function applyBootstrapPagerPolicy(argv: string[]): void;
 export declare function normalizeLegacyExtensionActionSyntax(argv: string[]): string[];
+type BootstrapNormalizationReason = "legacy_extension_action" | "flag_alias" | "flag_typo" | "bare_key_value";
+type BootstrapNormalizationConfidence = "high" | "medium";
+export interface BootstrapNormalizationEvent {
+    from: string;
+    to: string[];
+    reason: BootstrapNormalizationReason;
+    confidence: BootstrapNormalizationConfidence;
+}
+export interface BootstrapInvocationNormalizationResult {
+    argv: string[];
+    commandName: string | undefined;
+    trace: BootstrapNormalizationEvent[];
+}
+export declare function normalizeBootstrapInvocation(argv: string[]): BootstrapInvocationNormalizationResult;
 export declare function parseBootstrapTypeValue(argv: string[]): string | undefined;
+export {};

package/dist/cli/bootstrap-args.js

@@ -1,3 +1,5 @@
+import { resolveSubcommandFlagContractsForCommand } from "../sdk/cli-contracts.js";
+import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
 function parseBootstrapPathToken(token, next) {
     if (token === "--path") {
         if (typeof next === "string" && next.length > 0) {
@@ -220,6 +222,215 @@ export function normalizeLegacyExtensionActionSyntax(argv) {
     }
     return [...argv.slice(0, extensionIndex + 1), forcedActionFlag, ...argv.slice(extensionIndex + 2)];
 }
+function normalizeFlagKeyToken(raw) {
+    const withoutPrefix = raw.replace(/^--?/, "");
+    return withoutPrefix
+        .replace(/_/g, "-")
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase();
+}
+function toComparableFlagKey(raw) {
+    return normalizeFlagKeyToken(raw).replace(/-/g, "");
+}
+function markUnambiguousFlag(map, key, canonicalFlag) {
+    const existing = map.get(key);
+    if (existing === undefined) {
+        map.set(key, canonicalFlag);
+        return;
+    }
+    if (existing !== canonicalFlag) {
+        map.set(key, null);
+    }
+}
+function collectLongFlagCandidates(contract) {
+    const candidates = [];
+    const pushLongFlag = (value) => {
+        if (typeof value !== "string") {
+            return;
+        }
+        if (!value.startsWith("--")) {
+            return;
+        }
+        candidates.push(value);
+    };
+    pushLongFlag(contract.flag);
+    for (const alias of contract.aliases ?? []) {
+        pushLongFlag(alias);
+    }
+    return candidates;
+}
+function buildFlagLookup(commandName) {
+    const contracts = resolveSubcommandFlagContractsForCommand(commandName);
+    const canonicalByNormalized = new Map();
+    const canonicalByCompact = new Map();
+    const canonicalComparablesMap = new Map();
+    for (const contract of contracts) {
+        const longCandidates = collectLongFlagCandidates(contract);
+        if (longCandidates.length === 0) {
+            continue;
+        }
+        const canonicalFlag = `--${normalizeFlagKeyToken(longCandidates[0])}`;
+        for (const candidate of longCandidates) {
+            markUnambiguousFlag(canonicalByNormalized, normalizeFlagKeyToken(candidate), canonicalFlag);
+            markUnambiguousFlag(canonicalByCompact, toComparableFlagKey(candidate), canonicalFlag);
+        }
+        const comparable = toComparableFlagKey(canonicalFlag);
+        if (!canonicalComparablesMap.has(canonicalFlag)) {
+            canonicalComparablesMap.set(canonicalFlag, comparable);
+        }
+    }
+    return {
+        canonicalByNormalized,
+        canonicalByCompact,
+        canonicalComparables: [...canonicalComparablesMap.entries()].map(([canonicalFlag, comparable]) => ({
+            canonicalFlag,
+            comparable,
+        })),
+    };
+}
+function resolveCanonicalFlag(rawKey, lookup) {
+    const normalizedKey = normalizeFlagKeyToken(rawKey);
+    const direct = lookup.canonicalByNormalized.get(normalizedKey);
+    if (typeof direct === "string") {
+        return {
+            flag: direct,
+            reason: "flag_alias",
+            confidence: "high",
+        };
+    }
+    const comparableKey = normalizedKey.replace(/-/g, "");
+    const compactMatch = lookup.canonicalByCompact.get(comparableKey);
+    if (typeof compactMatch === "string") {
+        return {
+            flag: compactMatch,
+            reason: "flag_alias",
+            confidence: "high",
+        };
+    }
+    const maxDistance = comparableKey.length >= 8 ? 2 : 1;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    let bestFlag;
+    let tied = false;
+    for (const candidate of lookup.canonicalComparables) {
+        const distance = levenshteinDistanceWithinLimit(comparableKey, candidate.comparable, maxDistance);
+        if (distance === null) {
+            continue;
+        }
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            bestFlag = candidate.canonicalFlag;
+            tied = false;
+            continue;
+        }
+        if (distance === bestDistance && bestFlag !== candidate.canonicalFlag) {
+            tied = true;
+        }
+    }
+    if (!bestFlag || tied || !Number.isFinite(bestDistance) || bestDistance <= 0) {
+        return null;
+    }
+    return {
+        flag: bestFlag,
+        reason: "flag_typo",
+        confidence: bestDistance >= 2 ? "medium" : "high",
+    };
+}
+function parseBareKeyValueToken(token) {
+    if (token.includes("://")) {
+        return null;
+    }
+    const match = token.match(/^([A-Za-z][A-Za-z0-9_-]{1,63})([:=])(.*)$/);
+    if (!match) {
+        return null;
+    }
+    const key = match[1];
+    const value = match[3];
+    if (value.length === 0) {
+        return null;
+    }
+    return {
+        key,
+        value,
+    };
+}
+function normalizeLongOptionToken(token, lookup) {
+    if (!token.startsWith("--")) {
+        return { tokens: [token] };
+    }
+    const equalsIndex = token.indexOf("=");
+    const key = equalsIndex >= 0 ? token.slice(0, equalsIndex) : token;
+    const inlineValue = equalsIndex >= 0 ? token.slice(equalsIndex + 1) : undefined;
+    const resolution = resolveCanonicalFlag(key, lookup);
+    if (!resolution) {
+        return { tokens: [token] };
+    }
+    const normalizedToken = inlineValue === undefined ? resolution.flag : `${resolution.flag}=${inlineValue}`;
+    if (normalizedToken === token) {
+        return { tokens: [token] };
+    }
+    return {
+        tokens: [normalizedToken],
+        event: {
+            from: token,
+            to: [normalizedToken],
+            reason: resolution.reason,
+            confidence: resolution.confidence,
+        },
+    };
+}
+export function normalizeBootstrapInvocation(argv) {
+    const trace = [];
+    const legacyNormalized = normalizeLegacyExtensionActionSyntax(argv);
+    if (legacyNormalized.length !== argv.length || legacyNormalized.some((token, index) => token !== argv[index])) {
+        trace.push({
+            from: argv.join(" "),
+            to: [...legacyNormalized],
+            reason: "legacy_extension_action",
+            confidence: "high",
+        });
+    }
+    const commandName = parseBootstrapCommandName(legacyNormalized);
+    const lookup = buildFlagLookup(commandName);
+    const normalizedArgv = [];
+    for (let index = 0; index < legacyNormalized.length; index += 1) {
+        const token = legacyNormalized[index];
+        if (token === "--") {
+            normalizedArgv.push(...legacyNormalized.slice(index));
+            break;
+        }
+        const previous = normalizedArgv[normalizedArgv.length - 1];
+        if (token.startsWith("--")) {
+            const normalizedToken = normalizeLongOptionToken(token, lookup);
+            normalizedArgv.push(...normalizedToken.tokens);
+            if (normalizedToken.event) {
+                trace.push(normalizedToken.event);
+            }
+            continue;
+        }
+        const bareKeyValue = parseBareKeyValueToken(token);
+        if (bareKeyValue &&
+            !(typeof previous === "string" && previous.startsWith("-"))) {
+            const resolution = resolveCanonicalFlag(bareKeyValue.key, lookup);
+            if (resolution) {
+                const replacement = [resolution.flag, bareKeyValue.value];
+                normalizedArgv.push(...replacement);
+                trace.push({
+                    from: token,
+                    to: replacement,
+                    reason: "bare_key_value",
+                    confidence: resolution.confidence,
+                });
+                continue;
+            }
+        }
+        normalizedArgv.push(token);
+    }
+    return {
+        argv: normalizedArgv,
+        commandName,
+        trace,
+    };
+}
 export function parseBootstrapTypeValue(argv) {
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index];