@unbrained/pm-cli 2026.8.26 → 2026.8.28

package/dist/sdk/agent/task-transcript-contracts.js

@@ -0,0 +1,198 @@
+/**
+ * @module sdk/agent-task-transcript-contracts
+ *
+ * Defines and validates replayable agent-task transcripts without adding the
+ * SDK-only parser to ordinary CLI command bundles.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="006109f8-cb09-5a91-8929-7ac7521753b6")}catch(e){}}();
+import { isPmSuccessfulExitCode, resolvePmCommandExitContract, } from "../cli-contracts/command-exit-contracts.js";
+import { parseBootstrapCommandName } from "../cli-contracts/bootstrap-command-scanner.js";
+import { PM_OUTPUT_ENVELOPE_KINDS, resolvePmCommandOutputEnvelope, } from "../output-contracts.js";
+/** Stable schema version for replayable agent-task transcript corpora. */
+export const PM_AGENT_TASK_TRANSCRIPT_VERSION = 2;
+/** Supported strategies for measuring one transcript step's output cost. */
+export const PM_AGENT_TASK_ACCOUNTING_MODES = [
+    "self_reported",
+    "independent_transport",
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readTranscriptString(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`${field} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function readTranscriptStringArray(value, field, preserveWhitespace = false) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new TypeError(`${field} must be a non-empty string array`);
+    }
+    return value.map((entry, index) => {
+        const normalized = readTranscriptString(entry, `${field}[${String(index)}]`);
+        return preserveWhitespace ? entry : normalized;
+    });
+}
+function readOptionalTranscriptString(value, field) {
+    return value === undefined ? undefined : readTranscriptString(value, field);
+}
+function readExpectedFieldValues(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value) || Object.keys(value).length === 0) {
+        throw new TypeError(`${field} must be a non-empty object`);
+    }
+    const entries = Object.entries(value).map(([path, expectedValue]) => {
+        if (path.length === 0 ||
+            path.split(".").some((segment) => segment.length === 0)) {
+            throw new TypeError(`${field} must use dot-separated own-property paths`);
+        }
+        if (expectedValue !== null &&
+            typeof expectedValue !== "string" &&
+            typeof expectedValue !== "boolean" &&
+            (typeof expectedValue !== "number" || !Number.isFinite(expectedValue))) {
+            throw new TypeError(`${field} values must be JSON primitives`);
+        }
+        return [path, expectedValue];
+    });
+    return Object.fromEntries(entries);
+}
+function assertTranscriptStepOutputContract(field, args, exitCode, outputKind, errorCode, refusalSurface) {
+    if (outputKind === "refusal") {
+        if (isPmSuccessfulExitCode(exitCode) ||
+            errorCode === undefined ||
+            refusalSurface === undefined) {
+            throw new TypeError(`${field} refusal steps require a non-success exit, error code, and refusal surface`);
+        }
+        return;
+    }
+    if (errorCode !== undefined || refusalSurface !== undefined) {
+        throw new TypeError(`${field} only refusal steps may declare expected_error_code or expected_refusal_surface`);
+    }
+    const command = parseBootstrapCommandName(args);
+    if (command === undefined) {
+        throw new TypeError(`${field}.args must identify a command after global flags`);
+    }
+    const exitContract = resolvePmCommandExitContract(command);
+    if (!isPmSuccessfulExitCode(exitCode) ||
+        (exitCode !== 0 &&
+            !exitContract?.exit_codes.some((declaredExitCode) => declaredExitCode === exitCode))) {
+        throw new TypeError(`${field} successful output must use exit code 0 or a command-declared successful effect exit`);
+    }
+    const declaredKind = resolvePmCommandOutputEnvelope(command).kind;
+    if (outputKind !== declaredKind) {
+        throw new TypeError(`${field} expected ${outputKind}, but ${command} declares ${declaredKind}`);
+    }
+}
+function parseAgentTaskTranscriptStep(value, taskId, index) {
+    if (!isRecord(value)) {
+        throw new TypeError(`tasks.${taskId}.steps[${String(index)}] must be an object`);
+    }
+    const field = `tasks.${taskId}.steps[${String(index)}]`;
+    const id = readTranscriptString(value.id, `${field}.id`);
+    const args = readTranscriptStringArray(value.args, `${field}.args`, true);
+    const expectedExitCode = value.expected_exit_code;
+    if (typeof expectedExitCode !== "number" ||
+        !Number.isSafeInteger(expectedExitCode)) {
+        throw new TypeError(`${field}.expected_exit_code must be a safe integer`);
+    }
+    const rawOutputKind = value.expected_output_kind;
+    if (rawOutputKind !== "refusal" &&
+        !PM_OUTPUT_ENVELOPE_KINDS.includes(rawOutputKind)) {
+        throw new TypeError(`${field}.expected_output_kind is unsupported`);
+    }
+    const expectedOutputKind = rawOutputKind;
+    const rawAccountingMode = value.expected_accounting_mode;
+    if (!PM_AGENT_TASK_ACCOUNTING_MODES.includes(rawAccountingMode)) {
+        throw new TypeError(`${field}.expected_accounting_mode is unsupported`);
+    }
+    const expectedAccountingMode = rawAccountingMode;
+    if (expectedAccountingMode === "independent_transport" &&
+        expectedOutputKind !== "refusal") {
+        throw new TypeError(`${field} independent_transport accounting is supported only for refusal steps`);
+    }
+    const requiredFields = readTranscriptStringArray(value.required_fields, `${field}.required_fields`);
+    if (requiredFields.some((requiredField) => requiredField.split(".").some((segment) => segment.length === 0))) {
+        throw new TypeError(`${field}.required_fields must contain dot-separated own-property paths`);
+    }
+    const expectedFieldValues = readExpectedFieldValues(value.expected_field_values, `${field}.expected_field_values`);
+    const expectedErrorCode = readOptionalTranscriptString(value.expected_error_code, `${field}.expected_error_code`);
+    const expectedRefusalSurface = readOptionalTranscriptString(value.expected_refusal_surface, `${field}.expected_refusal_surface`);
+    const recoveryFor = readOptionalTranscriptString(value.recovery_for, `${field}.recovery_for`);
+    assertTranscriptStepOutputContract(field, args, expectedExitCode, expectedOutputKind, expectedErrorCode, expectedRefusalSurface);
+    return {
+        id,
+        args,
+        expected_exit_code: expectedExitCode,
+        expected_output_kind: expectedOutputKind,
+        expected_accounting_mode: expectedAccountingMode,
+        required_fields: requiredFields,
+        ...(expectedFieldValues
+            ? { expected_field_values: expectedFieldValues }
+            : {}),
+        ...(expectedErrorCode ? { expected_error_code: expectedErrorCode } : {}),
+        ...(expectedRefusalSurface
+            ? { expected_refusal_surface: expectedRefusalSurface }
+            : {}),
+        ...(recoveryFor ? { recovery_for: recoveryFor } : {}),
+    };
+}
+function parseAgentTaskTranscript(value, index) {
+    if (!isRecord(value)) {
+        throw new TypeError(`tasks[${String(index)}] must be an object`);
+    }
+    const id = readTranscriptString(value.id, `tasks[${String(index)}].id`);
+    const description = readTranscriptString(value.description, `tasks.${id}.description`);
+    if (!Array.isArray(value.steps) || value.steps.length === 0) {
+        throw new TypeError(`tasks.${id}.steps must be a non-empty array`);
+    }
+    const steps = value.steps.map((step, stepIndex) => parseAgentTaskTranscriptStep(step, id, stepIndex));
+    const priorSteps = new Map();
+    for (const step of steps) {
+        if (priorSteps.has(step.id)) {
+            throw new TypeError(`tasks.${id} contains duplicate step id ${step.id}`);
+        }
+        if (step.recovery_for !== undefined) {
+            const refusal = priorSteps.get(step.recovery_for);
+            if (refusal?.expected_output_kind !== "refusal" ||
+                step.expected_output_kind === "refusal") {
+                throw new TypeError(`tasks.${id}.${step.id} recovery_for must reference an earlier refusal and declare successful output`);
+            }
+        }
+        priorSteps.set(step.id, step);
+    }
+    if (steps.at(-1)?.expected_output_kind === "refusal") {
+        throw new TypeError(`tasks.${id} completed task must terminate with successful output`);
+    }
+    for (const step of steps) {
+        if (step.expected_output_kind === "refusal" &&
+            !steps.some((candidate) => candidate.recovery_for === step.id)) {
+            throw new TypeError(`tasks.${id}.${step.id} refusal must have a later successful recovery_for step`);
+        }
+    }
+    return { id, description, steps };
+}
+/** Parse and fail closed on malformed or internally inconsistent transcripts. */
+export function parsePmAgentTaskTranscriptCorpus(value) {
+    if (!isRecord(value)) {
+        throw new TypeError("agent-task transcript corpus must be an object");
+    }
+    if (value.version !== PM_AGENT_TASK_TRANSCRIPT_VERSION) {
+        throw new TypeError(`agent-task transcript corpus version must be ${String(PM_AGENT_TASK_TRANSCRIPT_VERSION)}`);
+    }
+    if (!Array.isArray(value.tasks) || value.tasks.length === 0) {
+        throw new TypeError("agent-task transcript corpus tasks must be non-empty");
+    }
+    const tasks = value.tasks.map((task, index) => parseAgentTaskTranscript(task, index));
+    const taskIds = new Set();
+    for (const task of tasks) {
+        if (taskIds.has(task.id)) {
+            throw new TypeError(`duplicate agent-task transcript id ${task.id}`);
+        }
+        taskIds.add(task.id);
+    }
+    return { version: PM_AGENT_TASK_TRANSCRIPT_VERSION, tasks };
+}
+//# sourceMappingURL=task-transcript-contracts.js.map
+//# debugId=006109f8-cb09-5a91-8929-7ac7521753b6

package/dist/sdk/agent-capability-contracts.js

@@ -5,7 +5,7 @@
  * surfaces from one public SDK contract.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="51e187c6-d48f-59e8-ad23-c72670ade3cc")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d8f3f734-9adf-56f3-a5ba-c8b6407c4a89")}catch(e){}}();
 import { PM_CORE_COMMAND_NAMES } from "./cli-contracts/enum-contracts.js";
 const CORE_COMMANDS = new Set([
     "claim",
@@ -244,6 +244,8 @@ const CAPABILITY_FAMILY_ORDER = [
 ];
 const CAPABILITY_ROUTING_EXCLUDED_ALIASES = new Set([
     "ctx",
+    "extension",
+    "install",
     "item-reopen",
     "list-all",
     "list-blocked",
@@ -252,6 +254,8 @@ const CAPABILITY_ROUTING_EXCLUDED_ALIASES = new Set([
     "list-draft",
     "list-in-progress",
     "list-open",
+    "packages",
+    "upgrade",
 ]);
 /** Group the command registry for progressive-disclosure routing surfaces. */
 export function listPmCommandCapabilityGroups(contracts = PM_COMMAND_CAPABILITY_CONTRACTS) {
@@ -420,4 +424,4 @@ export function renderPmCapabilityRoutingMarkdown(contracts = PM_COMMAND_CAPABIL
     ].join("\n");
 }
 //# sourceMappingURL=agent-capability-contracts.js.map
-//# debugId=51e187c6-d48f-59e8-ad23-c72670ade3cc
+//# debugId=d8f3f734-9adf-56f3-a5ba-c8b6407c4a89

package/dist/sdk/annotations.d.ts

@@ -25,6 +25,8 @@ export interface AnnotationCommandOptions {
     includeMeta?: boolean;
     /** Return the complete collection after a mutation instead of the bounded mutation receipt. */
     fullHistory?: boolean;
+    /** Append only when no entry has the same resolved author and text. */
+    ifAbsent?: boolean;
 }
 /** Identifies the single annotation mutation represented by a bounded response. */
 export interface AnnotationMutationReceipt {
@@ -32,8 +34,8 @@ export interface AnnotationMutationReceipt {
     action: "add" | "edit" | "delete";
     /** Stable one-based collection position targeted by the mutation. */
     entry_index: number;
-    /** Number of stored entries changed by the mutation. */
-    changed_count: 1;
+    /** Number of stored entries changed by the mutation attempt. */
+    changed_count: 0 | 1;
     /** Whether the response includes the complete post-mutation collection. */
     full_history_included: boolean;
 }
@@ -133,6 +135,7 @@ export type AnnotationCommandResult<TKey extends string, TEntry extends Annotati
     limit?: number;
     mutation_receipt?: AnnotationMutationReceipt;
     omission_receipt?: AnnotationOmissionReceipt;
+    changed?: boolean;
 };
 /** Implements limit annotation entries for the public runtime surface of this module. */
 export declare function limitAnnotationEntries<TEntry>(values: TEntry[], limit: number | undefined): TEntry[];

package/dist/sdk/annotations.js

@@ -4,7 +4,7 @@
  * Implements the pm annotation command command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="39acab93-f9ad-5b95-871e-625d912f1322")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6d20a21c-ac67-5712-9f63-b10ffc0e2c64")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { readFile } from "node:fs/promises";
 import { isFileAbsentError } from "../core/fs/fs-utils.js";
@@ -217,6 +217,13 @@ function assertAnnotationAddValueIsNotFlagLike(raw, config) {
  * with the same structured recovery bundle.
  */
 function assertAnnotationMessageHasTextSource(config, options) {
+    if (options.ifAbsent === true &&
+        !["add", "stdin", "file"].includes(config.input.mode)) {
+        throw new PmCliError(`--if-absent requires a ${config.collectionKey.replace(/s$/, "")} append`, EXIT_CODE.USAGE, {
+            code: "annotation_if_absent_without_append",
+            required: "Combine --if-absent with one append text source; omit it for list, edit, and delete operations.",
+        });
+    }
     if (config.input.mode !== "list" || options.message === undefined) {
         return;
     }
@@ -230,6 +237,19 @@ function assertAnnotationMessageHasTextSource(config, options) {
         ],
     });
 }
+/** Append one annotation entry or return the matching entry for an idempotent retry. */
+function appendAnnotationEntry(document, collectionKey, author, text, ifAbsent, createEntry) {
+    const entries = readAnnotationEntries(document.metadata, collectionKey);
+    const existingIndex = ifAbsent
+        ? entries.findIndex((entry) => entry.author === author && entry.text === text)
+        : -1;
+    if (existingIndex >= 0) {
+        return { changedFields: [], entryIndex: existingIndex + 1 };
+    }
+    entries.push(createEntry({ created_at: nowIso(), author, text }));
+    document.metadata[collectionKey] = entries;
+    return { changedFields: [collectionKey], entryIndex: entries.length };
+}
 /** Implements run annotation command for the public runtime surface of this module. */
 export async function runAnnotationCommand(id, options, global, config) {
     assertAnnotationMessageHasTextSource(config, options);
@@ -325,6 +345,7 @@ export async function runAnnotationCommand(id, options, global, config) {
         }, options.fullHistory === true);
     }
     let result;
+    let entryIndex = 0;
     try {
         result = await mutateItem({
             pmRoot,
@@ -335,12 +356,11 @@ export async function runAnnotationCommand(id, options, global, config) {
             message: options.message,
             force: options.force,
             bypassAssigneeConflict: config.bypassOwnershipConflict,
+            skipNoop: options.ifAbsent === true,
             mutate(document) {
-                const entries = readAnnotationEntries(document.metadata, config.collectionKey);
-                const entryInput = { created_at: nowIso(), author, text };
-                entries.push(config.createEntry(entryInput));
-                document.metadata[config.collectionKey] = entries;
-                return { changedFields: [config.collectionKey] };
+                const appended = appendAnnotationEntry(document, config.collectionKey, author, text, options.ifAbsent === true, config.createEntry);
+                entryIndex = appended.entryIndex;
+                return { changedFields: appended.changedFields };
             },
         });
     }
@@ -350,8 +370,11 @@ export async function runAnnotationCommand(id, options, global, config) {
     const allEntries = readAnnotationEntries(result.item, config.collectionKey);
     return renderAnnotationResult(result.item.id, config.collectionKey, allEntries, limit, options.includeMeta === true, {
         action: "add",
-        entryIndex: allEntries.length,
-        entry: allEntries.at(-1),
+        entryIndex,
+        entry: allEntries[entryIndex - 1],
+        changedCount: options.ifAbsent === true
+            ? Math.min(result.changedFields.length, 1)
+            : undefined,
     }, options.fullHistory === true);
 }
 /** Implements resolve annotation index for the public runtime surface of this module. */
@@ -367,6 +390,36 @@ export function resolveAnnotationIndex(oneBasedIndex, count, collectionKey) {
     }
     return oneBasedIndex - 1;
 }
+/** Build the mutation and omission receipts attached to bounded annotation results. */
+function renderAnnotationMutationReceipts(collectionKey, mutation, historyOmitted) {
+    if (mutation === undefined)
+        return {};
+    return {
+        mutation_receipt: {
+            action: mutation.action,
+            entry_index: mutation.entryIndex,
+            changed_count: mutation.changedCount ?? 1,
+            full_history_included: !historyOmitted,
+        },
+        omission_receipt: {
+            has_omissions: historyOmitted,
+            omitted_field_group_count: historyOmitted ? 1 : 0,
+            omitted_field_groups: historyOmitted
+                ? [
+                    {
+                        name: `${collectionKey}_history`,
+                        restore_with: {
+                            selector: "full_history",
+                            cli_flag: "--full-history",
+                            sdk_option: "fullHistory",
+                            mcp_option: "full",
+                        },
+                    },
+                ]
+                : [],
+        },
+    };
+}
 function renderAnnotationResult(id, collectionKey, allEntries, limit, includeMeta, mutation, fullHistory = false) {
     const entries = mutation === undefined || fullHistory
         ? limitAnnotationEntries(allEntries, mutation !== undefined && fullHistory ? undefined : limit)
@@ -378,6 +431,9 @@ function renderAnnotationResult(id, collectionKey, allEntries, limit, includeMet
         id,
         [collectionKey]: entries,
         count: entries.length,
+        ...(mutation?.changedCount === undefined
+            ? {}
+            : { changed: mutation.changedCount === 1 }),
         ...([includeMeta, mutation !== undefined].includes(true)
             ? {
                 total_count: allEntries.length,
@@ -386,34 +442,8 @@ function renderAnnotationResult(id, collectionKey, allEntries, limit, includeMet
                 ...(limit !== undefined ? { limit } : {}),
             }
             : {}),
-        ...(mutation === undefined
-            ? {}
-            : {
-                mutation_receipt: {
-                    action: mutation.action,
-                    entry_index: mutation.entryIndex,
-                    changed_count: 1,
-                    full_history_included: !historyOmitted,
-                },
-                omission_receipt: {
-                    has_omissions: historyOmitted,
-                    omitted_field_group_count: historyOmitted ? 1 : 0,
-                    omitted_field_groups: historyOmitted
-                        ? [
-                            {
-                                name: `${collectionKey}_history`,
-                                restore_with: {
-                                    selector: "full_history",
-                                    cli_flag: "--full-history",
-                                    sdk_option: "fullHistory",
-                                    mcp_option: "full",
-                                },
-                            },
-                        ]
-                        : [],
-                },
-            }),
+        ...renderAnnotationMutationReceipts(collectionKey, mutation, historyOmitted),
     };
 }
 //# sourceMappingURL=annotations.js.map
-//# debugId=39acab93-f9ad-5b95-871e-625d912f1322
+//# debugId=6d20a21c-ac67-5712-9f63-b10ffc0e2c64

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

@@ -53,15 +53,9 @@ export interface BootstrapHelpRequest {
 }
 /** Implements parse bootstrap help request for the public runtime surface of this module. */
 export declare function parseBootstrapHelpRequest(argv: string[]): BootstrapHelpRequest;
-/**
- * Index of the command token in argv — the first non-flag token, skipping the
- * value-consuming/global bootstrap flags. Returns undefined when there is none
- * (bare invocation, only global flags, or a leading `--`). Single source of truth
- * for command-position scanning shared by {@link parseBootstrapCommandName} and the
- * command-alias rewrite so their precedence rules can never drift apart.
- */
+/** Locate the command token after global bootstrap flags and their values. */
 export declare function findBootstrapCommandTokenIndex(argv: string[]): number | undefined;
-/** Implements parse bootstrap command name for the public runtime surface of this module. */
+/** Resolve the normalized command name from bootstrap invocation arguments. */
 export declare function parseBootstrapCommandName(argv: string[]): string | undefined;
 /** Implements apply bootstrap pager policy for the public runtime surface of this module. */
 export declare function applyBootstrapPagerPolicy(argv: string[]): () => void;

package/dist/sdk/cli-bootstrap.js

@@ -4,24 +4,14 @@
  * Provides public bootstrap argument normalization for embedded CLI hosts.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d45455ca-9496-5b8c-906c-d33d3d890e68")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3d35c0f5-e1b8-5fd8-8fd7-c754a21784a1")}catch(e){}}();
 import { EXECUTABLE_COMMAND_ALIASES, PM_COMMAND_ALIAS_CONTRACTS, renderPmCommandAliasMigrationHint, resolvePmCommandAlias, resolveSubcommandFlagContractsForCommand, } from "./cli-contracts.js";
 export { EXECUTABLE_COMMAND_ALIASES, PM_COMMAND_ALIAS_CONTRACTS, renderPmCommandAliasMigrationHint, resolvePmCommandAlias, };
 import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { normalizeItemAddressInvocation } from "./agent/item-addressing.js";
-const GLOBAL_VALUE_CONSUMING_FLAGS = new Set([
-    "--pm-path",
-    "--path",
-    "--author",
-    "--output-include",
-    "--output-limit",
-    "--output-budget",
-    "--output-format",
-    "--output-session",
-    "--output-cursor",
-]);
+import { BOOTSTRAP_BOOLEAN_FLAGS, GLOBAL_VALUE_CONSUMING_FLAGS, consumesBootstrapValue, findBootstrapCommandTokenIndex as findContractBootstrapCommandTokenIndex, isInlineGlobalValueToken, parseBootstrapCommandName as parseContractBootstrapCommandName, } from "./cli-contracts/bootstrap-command-scanner.js";
 const OUTPUT_VALUE_FLAGS = new Set([
     "--output-include",
     "--output-limit",
@@ -30,27 +20,6 @@ const OUTPUT_VALUE_FLAGS = new Set([
     "--output-session",
     "--output-cursor",
 ]);
-/** Whether a global value-consuming flag uses its inline `--flag=value` form. */
-const isInlineGlobalValueToken = (token) => {
-    const equalsIndex = token.indexOf("=");
-    return (equalsIndex > 0 &&
-        GLOBAL_VALUE_CONSUMING_FLAGS.has(token.slice(0, equalsIndex)));
-};
-/** Whether a bootstrap value flag consumes its following token. */
-const consumesBootstrapValue = (flag, next) => {
-    if (typeof next !== "string")
-        return false;
-    return flag === "--path" || flag === "--pm-path" || !next.startsWith("-");
-};
-const BOOTSTRAP_BOOLEAN_FLAGS = new Set([
-    "--no-extensions",
-    "--no-pager",
-    "--json",
-    "--quiet",
-    "--lean",
-    "--token-accounting",
-    "--output-row-contract",
-]);
 /** Consume one bootstrap-global token and update the accumulated parse state. */
 function consumeBootstrapGlobalToken(argv, index, state) {
     const token = argv[index];
@@ -196,41 +165,13 @@ export function parseBootstrapHelpRequest(argv) {
         commandPathTokens,
     };
 }
-/**
- * Index of the command token in argv — the first non-flag token, skipping the
- * value-consuming/global bootstrap flags. Returns undefined when there is none
- * (bare invocation, only global flags, or a leading `--`). Single source of truth
- * for command-position scanning shared by {@link parseBootstrapCommandName} and the
- * command-alias rewrite so their precedence rules can never drift apart.
- */
+/** Locate the command token after global bootstrap flags and their values. */
 export function findBootstrapCommandTokenIndex(argv) {
-    for (let index = 0; index < argv.length; index += 1) {
-        const token = argv[index];
-        if (token === "--") {
-            return undefined;
-        }
-        if (GLOBAL_VALUE_CONSUMING_FLAGS.has(token)) {
-            index += consumesBootstrapValue(token, argv[index + 1]) ? 1 : 0;
-            continue;
-        }
-        if (isInlineGlobalValueToken(token) ||
-            BOOTSTRAP_BOOLEAN_FLAGS.has(token) ||
-            token === "--profile" ||
-            token === "--id-only" ||
-            token === "--explain") {
-            continue;
-        }
-        if (token.startsWith("-")) {
-            continue;
-        }
-        return index;
-    }
-    return undefined;
+    return findContractBootstrapCommandTokenIndex(argv);
 }
-/** Implements parse bootstrap command name for the public runtime surface of this module. */
+/** Resolve the normalized command name from bootstrap invocation arguments. */
 export function parseBootstrapCommandName(argv) {
-    const index = findBootstrapCommandTokenIndex(argv);
-    return index === undefined ? undefined : argv[index].trim().toLowerCase();
+    return parseContractBootstrapCommandName(argv);
 }
 function shouldDisablePagerForInvocation(argv, bootstrapGlobal) {
     if (bootstrapGlobal.noPager) {
@@ -895,4 +836,4 @@ export const _testOnly = {
     resolveCanonicalFlag,
 };
 //# sourceMappingURL=cli-bootstrap.js.map
-//# debugId=d45455ca-9496-5b8c-906c-d33d3d890e68
+//# debugId=3d35c0f5-e1b8-5fd8-8fd7-c754a21784a1

package/dist/sdk/cli-contracts/bootstrap-command-scanner.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @module sdk/cli-contracts/bootstrap-command-scanner
+ *
+ * Resolves command position from shell-free argv without loading CLI runtime
+ * normalization, error, filesystem, or item-addressing dependencies.
+ */
+/** Global options that consume a following value when one is present. */
+export declare const GLOBAL_VALUE_CONSUMING_FLAGS: Set<string>;
+/** Boolean global options ignored while locating the command token. */
+export declare const BOOTSTRAP_BOOLEAN_FLAGS: Set<string>;
+/** Whether a global value-consuming flag uses its inline `--flag=value` form. */
+export declare function isInlineGlobalValueToken(token: string): boolean;
+/** Whether a bootstrap value flag consumes its following token. */
+export declare function consumesBootstrapValue(flag: string, next: string | undefined): boolean;
+/**
+ * Locate the first command token after global flags and their values.
+ *
+ * A leading `--` terminates command discovery. Unknown flags are ignored so
+ * later command-specific validation can return the canonical diagnostic.
+ */
+export declare function findBootstrapCommandTokenIndex(argv: readonly string[]): number | undefined;
+/** Resolve the normalized command name from shell-free invocation arguments. */
+export declare function parseBootstrapCommandName(argv: readonly string[]): string | undefined;

package/dist/sdk/cli-contracts/bootstrap-command-scanner.js

@@ -0,0 +1,80 @@
+/**
+ * @module sdk/cli-contracts/bootstrap-command-scanner
+ *
+ * Resolves command position from shell-free argv without loading CLI runtime
+ * normalization, error, filesystem, or item-addressing dependencies.
+ */
+/** Global options that consume a following value when one is present. */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9d04e30a-caf5-59b4-8853-9df39c1728aa")}catch(e){}}();
+export const GLOBAL_VALUE_CONSUMING_FLAGS = new Set([
+    "--pm-path",
+    "--path",
+    "--author",
+    "--output-include",
+    "--output-limit",
+    "--output-budget",
+    "--output-format",
+    "--output-session",
+    "--output-cursor",
+]);
+/** Boolean global options ignored while locating the command token. */
+export const BOOTSTRAP_BOOLEAN_FLAGS = new Set([
+    "--no-extensions",
+    "--no-pager",
+    "--json",
+    "--quiet",
+    "--lean",
+    "--token-accounting",
+    "--output-row-contract",
+    "--all",
+]);
+/** Whether a global value-consuming flag uses its inline `--flag=value` form. */
+export function isInlineGlobalValueToken(token) {
+    const equalsIndex = token.indexOf("=");
+    return (equalsIndex > 0 &&
+        GLOBAL_VALUE_CONSUMING_FLAGS.has(token.slice(0, equalsIndex)));
+}
+/** Whether a bootstrap value flag consumes its following token. */
+export function consumesBootstrapValue(flag, next) {
+    if (typeof next !== "string")
+        return false;
+    return flag === "--path" || flag === "--pm-path" || !next.startsWith("-");
+}
+/**
+ * Locate the first command token after global flags and their values.
+ *
+ * A leading `--` terminates command discovery. Unknown flags are ignored so
+ * later command-specific validation can return the canonical diagnostic.
+ */
+export function findBootstrapCommandTokenIndex(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--") {
+            return undefined;
+        }
+        if (GLOBAL_VALUE_CONSUMING_FLAGS.has(token)) {
+            index += consumesBootstrapValue(token, argv[index + 1]) ? 1 : 0;
+            continue;
+        }
+        if (isInlineGlobalValueToken(token) ||
+            BOOTSTRAP_BOOLEAN_FLAGS.has(token) ||
+            token === "--profile" ||
+            token === "--id-only" ||
+            token === "--explain") {
+            continue;
+        }
+        if (token.startsWith("-")) {
+            continue;
+        }
+        return index;
+    }
+    return undefined;
+}
+/** Resolve the normalized command name from shell-free invocation arguments. */
+export function parseBootstrapCommandName(argv) {
+    const index = findBootstrapCommandTokenIndex(argv);
+    return index === undefined ? undefined : argv[index].trim().toLowerCase();
+}
+//# sourceMappingURL=bootstrap-command-scanner.js.map
+//# debugId=9d04e30a-caf5-59b4-8853-9df39c1728aa