@unbrained/pm-cli 2026.5.6 → 2026.5.11

package/.pi/skills/pm-native/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: pm-native
+description: Native pm integration for Pi. Use when planning, claiming, updating, linking files/tests/docs, validating, or closing pm CLI work through the Pi pm tool instead of shelling out to the pm CLI.
+license: MIT
+compatibility: Pi coding-agent with the @unbrained/pm-cli Pi package installed.
+metadata:
+  owner: unbrained
+  domain: pm-cli
+  scope: pi-native
+---
+
+# pm Native for Pi
+
+Use the `pm` tool for project-management operations. Do not run `pm ...` through bash when the native tool is available. In interactive Pi, use `/pm-board`, `/pm-item <id>`, `/pm-history <id>`, `/pm-actions`, and `/pm-workflows` when the user would benefit from seeing tracker state in the TUI.
+
+## Required Loop
+
+1. Orient before creating work:
+   - `pm` action `context` with `limit: 10`
+   - `pm` action `search` with relevant keywords
+   - `pm` action `list-open` and `list-in-progress`
+2. Claim work with action `claim` or `start-task`.
+3. Mutate with explicit `author`.
+4. Link evidence:
+   - action `files` with `add`
+   - action `docs` with `add`
+   - action `test` with sandbox-safe commands
+5. Verify with action `test`, `validate`, and project test commands when appropriate.
+6. Close with action `close-task` or `close`, then release if needed.
+7. For exact feature support, call `pm` action `contracts` or `guide` instead of guessing flags.
+
+## Common Tool Calls
+
+- Context: `{ "action": "context", "limit": 10 }`
+- Search: `{ "action": "search", "query": "pi native extension", "limit": 10 }`
+- Claim: `{ "action": "claim", "id": "pm-1234", "author": "pi-agent" }`
+- Link file: `{ "action": "files", "id": "pm-1234", "add": ["path=src/file.ts,scope=project,note=implementation"], "author": "pi-agent" }`
+- Add comment: `{ "action": "comments", "id": "pm-1234", "add": ["Evidence: build and tests passed"], "author": "pi-agent" }`
+- Close: `{ "action": "close-task", "id": "pm-1234", "text": "All acceptance criteria met", "author": "pi-agent", "validateClose": "warn" }`
+- Extension lifecycle: `{ "action": "extension", "install": true, "target": "todos", "scope": "project" }`
+- Templates: `{ "action": "templates-list" }`
+- Managed tests: `{ "action": "test-runs-list" }`
+
+Use `pm guide` topics through action `guide` for deeper command docs. The bundled Pi package also provides project subagent definitions (`pm-triage-agent`, `pm-verification-agent`) and a `pm-native-delivery` chain for installations that use pi-subagents.

package/.pi/skills/pm-release/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: pm-release
+description: Release-readiness workflow for pm projects in Pi. Use when running final validation, coverage, package checks, GitHub checks, and closure evidence through the native pm integration.
+license: MIT
+compatibility: Pi coding-agent with the @unbrained/pm-cli Pi package installed.
+metadata:
+  owner: unbrained
+  domain: pm-cli
+  scope: release
+---
+
+# pm Release Workflow for Pi
+
+Use the native `pm` tool for tracker state and linked evidence. Use shell only for non-pm project build/test commands.
+
+## Release Checklist
+
+1. `pm` action `context` with `depth: "standard"`.
+2. Run linked tests with `pm` action `test` and `run: true` for active work items.
+3. Run validation with `pm` action `validate`, usually `checkResolution: true`, `checkHistoryDrift: true`, and relevant file checks.
+4. Run package install/discovery smoke for Pi packages:
+   - local: `pi install -l .` or `pi -e .`
+   - npm after publish: `pi install npm:@unbrained/pm-cli`
+5. Use `gh` only to inspect GitHub checks after pushing.
+6. Add a `comments` evidence entry with exact command summaries.
+7. Close/release the pm item with `close-task` once acceptance criteria are met.
+
+## Evidence Format
+
+Record:
+- Changed package resources (`pi.extensions`, `pi.skills`, `pi.prompts`)
+- Native pm tool smoke result
+- Build/test/coverage result
+- Pi install smoke result
+- GitHub checks status

package/AGENTS.md

@@ -7,7 +7,7 @@ This document defines how coding agents must use `pm` for planning, execution, a
 - Use `pm` as the system of record for project work.
 - Prefer deterministic, script-friendly command usage (`--json` when strict parsing is needed).
 - Default to TOON output when human + model readability and low token use are desired (calendar command is the intentional exception and defaults to markdown unless overridden).
-- Treat TOON as the canonical item-document format in this repo; `front_matter` is an internal model key, while TOON item metadata is stored as top-level object fields.
+- Treat TOON as the canonical item-document format in this repo; item metadata is modeled as `metadata` internally and stored as top-level object fields in TOON.
 - Never make destructive item changes outside `pm` mutations.
 - Every mutation must produce a history entry.
 

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- Added top-level `ok` fields to `pm test --run --json` and `pm test-all --json` so agents can gate linked-test execution without parsing every result row.
+- Capped and truncated semantic reindex embedding payloads for local Ollama providers, with adaptive timeout splitting, to avoid full-corpus reindex failures on large item bodies.
+
 ## [2026.5.6] - 2026-05-06
 
 ### Changed

package/PRD.md

@@ -73,7 +73,7 @@ Existing trackers either rely on hosted backends, store state in non-diff-friend
 
 From `todos.ts`:
 
-- Item file format = JSON front-matter at file start, blank line, then markdown body.
+- Legacy import format = JSON front-matter at file start, blank line, then markdown body.
 - ID normalization accepts optional `#` and optional prefix.
 - Claim/release is represented in-record (`assignee`).
 - Locking model:
@@ -246,16 +246,16 @@ Constraints:
 
 ## 7) Item File Format
 
-Each item is one document at `<type-folder>/<id>.toon` (default) or `<type-folder>/<id>.md` (JSON+Markdown alternative).
+Each item is one TOON document at `<type-folder>/<id>.toon`. Legacy `<type-folder>/<id>.md` files are read only for migration.
 
 Format:
 
-1. TOON root-object metadata keys (default) or JSON object metadata block (markdown format).
-2. Optional `body` field / markdown body.
+1. TOON root-object metadata keys.
+2. Optional `body` field.
 
 ### 7.1 Canonical item-metadata schema
 
-`front_matter` remains the internal field name in TypeScript (`ItemDocument.front_matter`), but TOON documents store the same metadata as top-level keys.
+`metadata` is the internal TypeScript field name (`ItemDocument.metadata`), and TOON documents store the same metadata as top-level keys.
 
 Required fields:
 
@@ -500,7 +500,7 @@ Canonical patch document shape:
 
 ```json
 {
-  "front_matter": { "...": "..." },
+  "metadata": { "...": "..." },
   "body": "markdown text"
 }
 ```
@@ -517,7 +517,7 @@ Canonical patch document shape:
 
 1. Resolve item or matching history stream for ID and load full history.
 2. Replay patches from initial create through target version/timestamp.
-3. Rebuild exact canonical document (`front_matter` + `body`).
+3. Rebuild exact canonical document (`metadata` + `body`).
 4. Write item atomically.
 5. Append a `restore` history event with patch from pre-restore state to restored state.
 
@@ -717,7 +717,7 @@ Help and error UX note:
 - `pm restore <ID> <TIMESTAMP|VERSION>`
 - `pm config <project|global> set definition-of-done --criterion <text>`
 - `pm config <project|global> get definition-of-done`
-- `pm config <project|global> set item-format --format toon|json_markdown`
+- `pm config <project|global> set item-format --format toon`
 - `pm config <project|global> get item-format`
 - `pm config <project|global> set history-missing-stream-policy --policy auto_create|strict_error`
 - `pm config <project|global> get history-missing-stream-policy`
@@ -970,7 +970,7 @@ Contract compatibility policy keeps command names/flags/aliases stable while all
 | `pm calendar` / `pm cal` | `--view agenda|day|week|month`, `--date`, `--from`/`--to` (agenda), `--past`, `--full-period` (day/week/month only), list-like filters (`type`, `tag`, `priority`, `status`, `assignee`, `sprint`, `release`, `limit`), source controls (`--include`), and recurrence bounds (`--recurrence-lookahead-days`, `--recurrence-lookback-days`, `--occurrence-limit`) | `{ view, output_default, now, anchor, range, filters, summary, events, days }` where `range` includes period metadata (`period_start`, `period_end`, `full_period`), `summary` includes deterministic aggregate breakdown fields (`by_kind`, `by_type`, `by_status`, `recurring_events`), and markdown output includes rich event detail tokens by default |
 | `pm context` / `pm ctx` | `--date`, `--from`/`--to`, `--past`, list-like filters (`type`, `tag`, `priority`, `assignee`, `sprint`, `release`, `limit`), `--format` | `{ output_default, now, window, filters, summary, high_level, low_level, blocked_fallback, agenda }` (defaults to TOON unless `--format` or `--json` override) |
 | `pm beads import [--file <path\|->] [--preserve-source-ids]` | optional Beads JSONL source path (`.beads/issues.jsonl` auto-discovered first, then `issues.jsonl`; implicit `sync_base.jsonl` fallback is refused as unsafe; `--file -` requires piped stdin and fails fast on interactive TTY stdin) | `{ ok, source, imported, skipped, ids, warnings }` |
-| `pm todos import --folder <path?>` | optional todos markdown source folder (defaults to `.pi/todos`); preserves canonical optional `ItemFrontMatter` metadata when present and applies deterministic defaults for missing PM fields | `{ ok, folder, imported, skipped, ids, warnings }` |
+| `pm todos import --folder <path?>` | optional todos markdown source folder (defaults to `.pi/todos`); preserves canonical optional `ItemMetadata` fields when present and applies deterministic defaults for missing PM fields | `{ ok, folder, imported, skipped, ids, warnings }` |
 | `pm todos export --folder <path?>` | optional todos markdown destination folder (defaults to `.pi/todos`) | `{ ok, folder, exported, ids, warnings }` |
 | `pm create ...` | required `--title` + `--description` + `--type`; strict mode is default (`--create-mode strict`) and enforces type-governed required options; progressive mode (`--create-mode progressive`) supports staged omission of type-level required create fields/repeatables; optional `--template` reusable defaults | `{ item, changed_fields, warnings }` |
 | `pm templates save <NAME> ...` | template name + create-compatible option payload (subset of create flags, including repeatable entries) | `{ name, path, template, saved_at }` |
@@ -986,7 +986,7 @@ Contract compatibility policy keeps command names/flags/aliases stable while all
 | `pm start-task <ID>` | lifecycle alias command (`claim` + `update --status in_progress`) with optional `--author`, `--message`, `--force` | `{ id, action: "start_task", claim, update }` |
 | `pm pause-task <ID>` | lifecycle alias command (`update --status open` + `release`) with optional `--author`, `--message`, `--force` | `{ id, action: "pause_task", update, release }` |
 | `pm close-task <ID> <TEXT>` | lifecycle alias command (`close` + `release`) with optional `--author`, `--message`, `--validate-close`, `--force` | `{ id, action: "close_task", close, release }` |
-| `pm comments <ID> [TEXT] --add/--limit` | id + optional positional comment text shorthand + comment text/limit (`--add` accepts plain text, `text=<value>`, markdown `text: <value>`, or stdin token `-`; positional `TEXT` is shorthand for `--add <TEXT>`; ambiguous CSV-like key fragments such as `text=hello,scope:project` remain plain text unless `text` is explicit); optional mutation metadata flags `--author`/`--message`/`--force`; additive ownership-safe audit path `--allow-audit-comment` for non-owner append-only comments | `{ id, comments, count }` |
+| `pm comments <ID> [TEXT] --add/--stdin/--file/--limit` | id + optional positional comment text shorthand + comment text/limit (`--add` accepts plain text, `text=<value>`, markdown `text: <value>`, or stdin token `-`; `--stdin` reads multiline markdown from piped stdin; `--file <path>` reads multiline markdown from a file; positional `TEXT` is shorthand for `--add <TEXT>`; ambiguous CSV-like key fragments such as `text=hello,scope:project` remain plain text unless `text` is explicit); exactly one comment source must be provided per mutation invocation (`[TEXT]`, `--add`, `--stdin`, or `--file`); optional mutation metadata flags `--author`/`--message`/`--force`; additive ownership-safe audit path `--allow-audit-comment` for non-owner append-only comments | `{ id, comments, count }` |
 | `pm comments-audit` | optional governance filters (`--status`, `--type`, `--assignee`, `--assignee-filter`, `--parent`, `--tag`, `--sprint`, `--release`, `--priority`, `--limit-items`) plus latest/full-history export mode controls (`--latest`, `--full-history`; mutually exclusive, `--latest 0` allowed for summary-only rows) | `{ items, count, summary, filters, export, now, warnings? }` where `summary` includes additive totals/coverage/by-type metrics, `filters.full_history` and `export.mode` indicate latest vs full-history behavior, and `export.row_count` is deterministic (`0` in summary-only latest mode); in full-history mode, `rows[]` includes flat per-comment export entries for NDJSON-friendly downstream processing |
 | `pm notes <ID> [TEXT] --add/--limit` | id + optional positional note text shorthand + note text/limit (`--add` accepts plain text, `text=<value>`, markdown `text: <value>`, or stdin token `-`; positional `TEXT` is shorthand for `--add <TEXT>`; ambiguous CSV-like key fragments such as `text=hello,scope:project` remain plain text unless `text` is explicit); optional mutation metadata flags `--author`/`--message`/`--force`; additive ownership-safe audit path `--allow-audit-comment` for non-owner append-only notes | `{ id, notes, count }` |
 | `pm learnings <ID> [TEXT] --add/--limit` | id + optional positional learning text shorthand + learning text/limit (`--add` accepts plain text, `text=<value>`, markdown `text: <value>`, or stdin token `-`; positional `TEXT` is shorthand for `--add <TEXT>`; ambiguous CSV-like key fragments such as `text=hello,scope:project` remain plain text unless `text` is explicit); optional mutation metadata flags `--author`/`--message`/`--force`; additive ownership-safe audit path `--allow-audit-comment` for non-owner append-only learnings | `{ id, learnings, count }` |
@@ -1010,7 +1010,7 @@ Contract compatibility policy keeps command names/flags/aliases stable while all
 
 List command row projection:
 
-- Default `list*` rows contain `ItemFrontMatter` fields only.
+- Default `list*` rows contain `ItemMetadata` fields only.
 - `--compact` projects deterministic compact fields (`id`, `title`, `status`, `type`, `priority`, `parent`, `updated_at`).
 - `--fields <csv>` projects caller-selected list fields.
 - With `--include-body`, each row additionally includes `body` and `filters.include_body` is `true` (`null` when omitted in JSON; omitted in sparse TOON).
@@ -1027,8 +1027,8 @@ Examples:
 
 - `list*`:
   - `{ items, count, filters, now }`
-  - default rows: `ItemFrontMatter`
-  - with `--include-body`: `ItemFrontMatter + body`
+  - default rows: `ItemMetadata`
+  - with `--include-body`: `ItemMetadata + body`
 - `search`:
   - `{ query, mode, items, count, filters, now }`
 - `get`:
@@ -1369,7 +1369,7 @@ Behavior:
   - `title -> title`
   - `body -> body`
   - imported IDs, including hierarchical suffixes such as `pm-legacy.1.2`, are preserved verbatim when provided in todos front matter
-  - canonical PM front-matter fields round-trip when present, including planning/workflow metadata (`definition_of_ready`, `order`, `goal`, `objective`, `value`, `impact`, `outcome`, `why_now`, `reviewer`, `risk`, `confidence`, `sprint`, `release`, `blocked_by`, `blocked_reason`, `unblock_note`) and issue metadata (`reporter`, `severity`, `environment`, `repro_steps`, `resolution`, `expected_result`, `actual_result`, `affected_version`, `fixed_version`, `component`, `regression`, `customer_impact`)
+  - canonical PM metadata fields round-trip when present, including planning/workflow metadata (`definition_of_ready`, `order`, `goal`, `objective`, `value`, `impact`, `outcome`, `why_now`, `reviewer`, `risk`, `confidence`, `sprint`, `release`, `blocked_by`, `blocked_reason`, `unblock_note`) and issue metadata (`reporter`, `severity`, `environment`, `repro_steps`, `resolution`, `expected_result`, `actual_result`, `affected_version`, `fixed_version`, `component`, `regression`, `customer_impact`)
   - `confidence`, `risk`, and `severity` text aliases normalize deterministically (`med -> medium`)
 - Missing PM fields get deterministic defaults:
   - `description = ""`
@@ -1653,7 +1653,7 @@ Definition of Done:
 Checklist:
 
 - [x] Item schema model + validation
-- [x] Parser/serializer for markdown item files
+- [x] Parser/serializer for TOON item files plus legacy markdown migration reader
 - [x] ID generation + normalization
 - [x] Lock acquire/release with TTL and conflict handling
 - [x] Core commands: init/create/get/update/append/claim/release/close/delete complete
@@ -1750,6 +1750,6 @@ Definition of Done:
   - unknown values retained in import metadata notes if lossy mapping is required
 - Hierarchical IDs from imports are preserved verbatim; new IDs generated by core default to flat `prefix-token`.
 - TOON formatting follows deterministic encoding with stable object keys; internal serializer may use a thin compatibility layer to ensure strict consistency across Node versions.
-- For `create`, `before_hash` is computed from canonical empty document: `{ "front_matter": {}, "body": "" }`.
+- For `create`, `before_hash` is computed from the legacy-compatible canonical empty hash document: `{ "front_matter": {}, "body": "" }` (history patch payloads use `metadata` paths).
 - If create item write succeeds but history append fails, implementation MUST rollback the new item file before returning failure.
 - ID normalization helper behavior (`#` prefix, missing configured prefix, case-insensitive input) is required in core utilities even before all commands expose it.

package/README.md

@@ -17,11 +17,22 @@
 | 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) |
+| 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) |
 | Contributor internals | [Architecture](docs/ARCHITECTURE.md) |
 
 Full documentation starts at [docs/README.md](docs/README.md).
 
+Use local in-CLI routing when an agent should stay inside terminal context:
+
+```bash
+pm guide
+pm guide quickstart
+pm guide commands --depth standard
+pm guide skills --depth deep --format markdown
+```
+
 ## Install
 
 `pm-cli` requires Node.js 20 or newer.
@@ -40,6 +51,22 @@ 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, 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.
+
 ## 60 Second Example
 
 ```bash
@@ -78,6 +105,8 @@ pm list-in-progress --limit 20
 
 If no relevant item exists, create a parent lineage before child work, claim the child item, link changed files/docs/tests, and leave evidence comments before closing. The full workflow is in the [Agent Guide](docs/AGENT_GUIDE.md).
 
+For token-aware local routing, use `pm guide workflows` and then drill into related topics (`commands`, `skills`, `release`) only when needed.
+
 ## Release Automation
 
 - Daily release preparation runs in `.github/workflows/auto-release.yml`.
@@ -94,6 +123,7 @@ If no relevant item exists, create a parent lineage before child work, claim the
 - Built-in types include `Epic`, `Feature`, `Task`, `Chore`, `Issue`, `Decision`, `Event`, `Reminder`, `Milestone`, and `Meeting`.
 - Output defaults to sparse TOON. Use `--json` for strict parsing.
 - `pm contracts` is the machine-readable command and schema contract surface for agents.
+- `pm guide` is the local progressive-disclosure docs and skills index for agents.
 
 ## Tracker References
 
@@ -105,10 +135,6 @@ This documentation refresh is tracked through `pm`:
 
 Docs should link to relevant `pm` items, and `pm` items should link back to changed docs through `pm docs`.
 
-## Privacy Boundary
-
-Private production operations material is local-only, gitignored, and intentionally not linked from public documentation or packaged release files. Keep public docs focused on user-facing CLI behavior and safe contribution workflows.
-
 ## License
 
 [MIT](LICENSE)

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];