@unbrained/pm-cli 2026.8.17 → 2026.8.19

package/dist/sdk/cli-contracts/flag-lexicon-contracts.js

@@ -0,0 +1,240 @@
+/**
+ * @module sdk/flag-lexicon-contracts
+ *
+ * Compiles command flags into a canonical concept lexicon with enforceable
+ * per-command growth budgets.
+ */
+
+!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]="19215662-5a8c-5b91-bc97-8dbdc1daff02")}catch(e){}}();
+import { hasSubcommandFlagContractsForCommand, resolveSubcommandFlagContractsForCommand, } from "./flag-contracts.js";
+import { PM_COMMAND_CAPABILITY_CONTRACTS, } from "../agent-capability-contracts.js";
+import { enrichCliFlagInvocationContracts } from "../flag-invocation-contracts.js";
+/** Memoized immutable canonical lexicon for this module instance. */
+let cachedPmFlagLexicon;
+/** Build the canonical lexicon lazily from the same contracts as CLI and MCP. */
+export function listPmFlagLexicon() {
+    if (cachedPmFlagLexicon !== undefined)
+        return cachedPmFlagLexicon;
+    const commandContracts = PM_COMMAND_CAPABILITY_CONTRACTS.filter(({ command }) => hasSubcommandFlagContractsForCommand(command));
+    const provisionalEntries = commandContracts.flatMap(({ command, family }) => enrichCliFlagInvocationContracts(command, resolveSubcommandFlagContractsForCommand(command)).map((contract) => ({
+        command,
+        family,
+        concept: contract.flag.slice(2),
+        flag: contract.flag,
+        aliases: Object.freeze([...(contract.aliases ?? [])]),
+        value_kind: (contract.repeatable
+            ? "list"
+            : contract.value_type),
+    })));
+    const compatibilityAliasFlags = new Set(provisionalEntries.flatMap((entry) => entry.aliases.map((alias) => `${entry.command}:${alias}`)));
+    const canonicalEntries = provisionalEntries.filter((entry) => !compatibilityAliasFlags.has(`${entry.command}:${entry.flag}`));
+    const kindsByConcept = new Map();
+    for (const entry of canonicalEntries) {
+        const kinds = kindsByConcept.get(entry.concept) ?? new Set();
+        kinds.add(entry.value_kind);
+        kindsByConcept.set(entry.concept, kinds);
+    }
+    cachedPmFlagLexicon = Object.freeze(canonicalEntries.map((entry) => Object.freeze({
+        ...entry,
+        concept: kindsByConcept.get(entry.concept)?.size === 1
+            ? entry.concept
+            : `${entry.concept}@${entry.command}`,
+    })));
+    return cachedPmFlagLexicon;
+}
+const PM_COMMAND_FLAG_BUDGET_MAXIMUMS = Object.freeze({
+    init: 30,
+    config: 35,
+    extension: 53,
+    package: 54,
+    packages: 54,
+    install: 26,
+    upgrade: 29,
+    create: 100,
+    copy: 24,
+    focus: 22,
+    list: 86,
+    "list-all": 85,
+    "list-draft": 84,
+    "list-open": 84,
+    "list-in-progress": 84,
+    "list-blocked": 84,
+    "list-closed": 84,
+    "list-canceled": 84,
+    aggregate: 37,
+    context: 45,
+    ctx: 45,
+    get: 30,
+    graph: 34,
+    search: 78,
+    duplicates: 24,
+    eval: 25,
+    next: 35,
+    history: 35,
+    events: 33,
+    "history-redact": 27,
+    "history-repair": 26,
+    "history-compact": 30,
+    "history-author-acknowledge": 28,
+    merge: 24,
+    schema: 40,
+    profile: 22,
+    activity: 35,
+    restore: 23,
+    update: 105,
+    "update-many": 140,
+    close: 31,
+    "close-many": 72,
+    delete: 24,
+    append: 24,
+    comments: 30,
+    notes: 34,
+    learnings: 26,
+    files: 39,
+    docs: 30,
+    deps: 32,
+    plan: 109,
+    test: 48,
+    "test-all": 37,
+    telemetry: 21,
+    stats: 29,
+    health: 36,
+    validate: 45,
+    assurance: 30,
+    gc: 22,
+    workspace: 23,
+    contracts: 29,
+    claim: 36,
+    release: 23,
+    "start-task": 23,
+    "pause-task": 23,
+    "close-task": 24,
+    meet: 33,
+    event: 33,
+    remind: 29,
+    "test-runs-worker": 25,
+});
+/** Return persisted no-growth ratchets with current counts derived from the canonical vocabulary. */
+export function listPmCommandFlagBudgets() {
+    const currentByCommand = new Map(Object.keys(PM_COMMAND_FLAG_BUDGET_MAXIMUMS).map((command) => [command, 0]));
+    for (const { command } of listPmFlagLexicon()) {
+        currentByCommand.set(command, Number(currentByCommand.get(command)) + 1);
+    }
+    return Object.freeze(Object.entries(PM_COMMAND_FLAG_BUDGET_MAXIMUMS).map(([command, maximum]) => Object.freeze({
+        command,
+        current: Number(currentByCommand.get(command)),
+        maximum,
+    })));
+}
+/** Append collisions between compatibility aliases and canonical spellings. */
+function appendAliasCollisionFindings(entries, canonicalOwners, findings) {
+    for (const entry of entries) {
+        for (const alias of entry.aliases) {
+            const owner = canonicalOwners.get(`${entry.command}:${alias}`);
+            if (owner === undefined || owner.flag === entry.flag)
+                continue;
+            findings.push({
+                code: "alias_collision",
+                command: entry.command,
+                detail: `${alias} aliases ${entry.flag} but is canonical for ${owner.flag}.`,
+            });
+        }
+    }
+}
+/** Append missing, stale, and exceeded command-budget findings. */
+function appendBudgetFindings(counts, budgets, findings) {
+    const budgetedCommands = new Set(budgets.map(({ command }) => command));
+    for (const command of counts.keys()) {
+        if (budgetedCommands.has(command))
+            continue;
+        findings.push({
+            code: "missing_budget",
+            command,
+            detail: `${command} has canonical flags but no persisted budget.`,
+        });
+    }
+    for (const budget of budgets) {
+        const actual = counts.get(budget.command) ?? 0;
+        if (actual === 0) {
+            findings.push({
+                code: "stale_budget",
+                command: budget.command,
+                detail: `${budget.command} has a persisted budget but no canonical flags.`,
+            });
+        }
+        if (actual <= budget.maximum)
+            continue;
+        findings.push({
+            code: "budget_exceeded",
+            command: budget.command,
+            detail: `${actual} canonical flags exceed the ratcheted maximum ${budget.maximum}.`,
+        });
+    }
+}
+/** Verify uniqueness, concept kind stability, alias safety, and flag budgets. */
+export function verifyPmFlagLexicon(entries = listPmFlagLexicon(), budgets = listPmCommandFlagBudgets()) {
+    const findings = [];
+    const canonicalOwners = new Map();
+    const conceptKinds = new Map();
+    const counts = new Map();
+    for (const entry of entries) {
+        const commandFlag = `${entry.command}:${entry.flag}`;
+        if (canonicalOwners.has(commandFlag)) {
+            findings.push({
+                code: "duplicate_canonical_flag",
+                command: entry.command,
+                detail: `${entry.flag} has more than one canonical row.`,
+            });
+        }
+        else {
+            canonicalOwners.set(commandFlag, entry);
+        }
+        counts.set(entry.command, (counts.get(entry.command) ?? 0) + 1);
+        const priorKind = conceptKinds.get(entry.concept);
+        if (priorKind !== undefined && priorKind !== entry.value_kind) {
+            findings.push({
+                code: "inconsistent_concept_kind",
+                command: entry.command,
+                detail: `${entry.concept} uses both ${priorKind} and ${entry.value_kind}.`,
+            });
+        }
+        else {
+            conceptKinds.set(entry.concept, entry.value_kind);
+        }
+    }
+    appendAliasCollisionFindings(entries, canonicalOwners, findings);
+    appendBudgetFindings(counts, budgets, findings);
+    findings.sort((left, right) => left.command.localeCompare(right.command) ||
+        left.code.localeCompare(right.code) ||
+        left.detail.localeCompare(right.detail));
+    return {
+        ok: findings.length === 0,
+        entry_count: entries.length,
+        budget_count: budgets.length,
+        findings,
+    };
+}
+/** Render a compact, generated family and command budget reference. Persisted budget rows are initialized to an explicit fallback so stale rows remain renderable. */
+export function renderPmFlagLexiconMarkdown() {
+    const lexicon = listPmFlagLexicon();
+    const budgets = listPmCommandFlagBudgets();
+    const familyByCommand = new Map(budgets.map(({ command }) => [command, "unknown"]));
+    for (const { command, family } of lexicon)
+        familyByCommand.set(command, family);
+    const rows = budgets.map(({ command, current, maximum }) => {
+        const family = familyByCommand.get(command);
+        return `| \`${command}\` | ${family} | ${current} | ${maximum} |`;
+    });
+    return [
+        "# Generated flag lexicon budgets",
+        "",
+        "This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not consume canonical budget.",
+        "",
+        "| Command | Capability family | Canonical flags | Maximum |",
+        "| --- | --- | ---: | ---: |",
+        ...rows,
+        "",
+    ].join("\n");
+}
+//# sourceMappingURL=flag-lexicon-contracts.js.map
+//# debugId=19215662-5a8c-5b91-bc97-8dbdc1daff02

package/dist/sdk/cli-contracts/grammar-contracts.d.ts

@@ -0,0 +1,151 @@
+/**
+ * @module sdk/cli-contracts/grammar-contracts
+ *
+ * Declares and verifies the agent-facing noun–verb grammar. The destination
+ * census is intentionally exact: live command contracts are compared with
+ * this checked-in table in both directions so adding or removing a command
+ * cannot silently bypass the architecture decision.
+ */
+import type { PmCommandAliasContract } from "./command-aliases.js";
+/** Canonical top-level domains an agent must retain to route pm operations. */
+export declare const PM_CLI_GRAMMAR_NOUNS: readonly ["item", "list", "context", "search", "graph", "history", "workspace", "package", "ops", "plan", "contracts", "help"];
+/** Shared verbs whose meaning transfers across domain nouns. */
+export declare const PM_CLI_SHARED_VERBS: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "repair", "restore", "run", "show", "uninstall", "verify"];
+/** Why a current command is permitted while the grammar migration proceeds. */
+export type PmCommandDestinationDisposition = "target_noun" | "consolidation" | "package_owned" | "keep_as_is";
+/** Exact destination decision for one command emitted by runtime contracts. */
+export interface PmCommandDestinationContract {
+    /** Current executable command path. */
+    command: string;
+    /** Canonical noun that owns the capability. */
+    noun: (typeof PM_CLI_GRAMMAR_NOUNS)[number];
+    /** Canonical noun-first invocation or family destination. */
+    target: string;
+    /** Why the current spelling remains in the executable surface. */
+    disposition: PmCommandDestinationDisposition;
+    /** PM item or package identifier owning the disposition. */
+    owner: string;
+    /** Reason required only for a deliberate keep-as-is exception. */
+    reason?: string;
+}
+/** Semantic value class for one positional slot, independent of its display label. */
+export type PmCommandPositionalValueKind = "action" | "integer" | "item_id" | "string";
+/** One ordered positional slot accepted by a command path. */
+export interface PmCommandPositionalSlotContract {
+    /** Stable agent-facing slot name. */
+    name: string;
+    /** Whether Commander and the SDK action both require the slot. */
+    required: boolean;
+    /** Whether the final slot consumes every remaining positional token. */
+    variadic: boolean;
+    /** Semantic value class used to compare shapes across commands. */
+    value_kind: PmCommandPositionalValueKind;
+    /** Whether the slot accepts more than one concept for compatibility. */
+    polymorphic: boolean;
+}
+/** Complete positional signature for one executable or virtual action path. */
+export interface PmCommandPositionalContract {
+    /** Normalized command path. */
+    command: string;
+    /** Ordered positional slots after the command path. */
+    slots: readonly PmCommandPositionalSlotContract[];
+}
+/** Discoverable positional action projected through help, contracts, and completion. */
+export interface PmPositionalActionContract extends PmCommandPositionalContract {
+    /** Commander command that dispatches the action positionally. */
+    parent: "assurance" | "plan" | "workspace snapshot";
+    /** Literal action token accepted in the parent's first positional slot. */
+    action: string;
+    /** Canonical flags applicable to this action-specific view. */
+    accepted_flags: readonly string[];
+    /** Concise action-specific intent. */
+    description: string;
+    /** Executable example suitable for recovery and help output. */
+    example: string;
+}
+/** Virtual action paths dispatched by positional parent commands. */
+export declare const PM_POSITIONAL_ACTION_CONTRACTS: readonly PmPositionalActionContract[];
+/** Resolve one declared signature without treating arbitrary object keys as commands. */
+export declare function resolvePmCommandPositionalContract(command: string): PmCommandPositionalContract | undefined;
+/** Resolve one action-specific help/contract view. */
+export declare function resolvePmPositionalActionContract(command: string): PmPositionalActionContract | undefined;
+/** Format the shared action-flag tip rendered by text and structured help. */
+export declare function formatPmPositionalActionFlagTip(acceptedFlags: readonly string[]): string;
+/** Checked-in exhaustive destination census for core and known package commands. */
+export declare const PM_COMMAND_DESTINATION_CONTRACTS: readonly PmCommandDestinationContract[];
+/** Exhaustive current command and positional-action signature table. */
+export declare const PM_COMMAND_POSITIONAL_CONTRACTS: readonly PmCommandPositionalContract[];
+/** Immutable grammar policy used by contracts and the CI gate. */
+export declare const PM_CLI_GRAMMAR_CONTRACT: {
+    readonly nouns: readonly ["item", "list", "context", "search", "graph", "history", "workspace", "package", "ops", "plan", "contracts", "help"];
+    readonly shared_verbs: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "repair", "restore", "run", "show", "uninstall", "verify"];
+    readonly scope_before_verb: true;
+    readonly visible_top_level_ceiling: 69;
+    readonly ceiling_raise_requires_pm_item: true;
+    readonly positional_shape_budget: 21;
+};
+/** One positional-signature drift finding. */
+export interface PmCommandPositionalFinding {
+    /** Stable remediation category. */
+    code: "missing_observed_signature" | "positional_shape_budget_exceeded" | "positional_signature_mismatch" | "stale_observed_signature";
+    /** Command path whose positional contract drifted. */
+    command: string;
+    /** Actionable mismatch detail. */
+    detail: string;
+}
+/** Complete positional grammar conformance receipt. */
+export interface PmCommandPositionalReport {
+    /** Whether the observed signatures exactly match the declaration. */
+    ok: boolean;
+    /** Declared command/action paths. */
+    declared_command_count: number;
+    /** Independently observed command/action paths. */
+    observed_command_count: number;
+    /** Number of distinct semantic positional shapes. */
+    positional_shape_count: number;
+    /** Maximum distinct shapes allowed without a tracked grammar decision. */
+    positional_shape_budget: number;
+    /** Stable positional conformance failures. */
+    findings: PmCommandPositionalFinding[];
+}
+/** Report explicit positional entries that no destination command declares. */
+export declare function verifyExplicitPositionalSlotCensus(explicitCommands: Iterable<string>, destinationCommands: Iterable<string>): PmCommandPositionalFinding[];
+/** Return the semantic shape identity used by the positional-shape budget. */
+export declare function positionalShapeKey(slots: readonly PmCommandPositionalSlotContract[]): string;
+/** Return the exact canonical identity of an ordered positional signature. */
+export declare function positionalSignatureKey(slots: readonly PmCommandPositionalSlotContract[]): string;
+/** Compare independently observed Commander signatures with the SDK declaration. */
+export declare function verifyPmCommandPositionalContracts(observed: readonly PmCommandPositionalContract[], options?: {
+    declared?: readonly PmCommandPositionalContract[];
+    positionalShapeBudget?: number;
+}): PmCommandPositionalReport;
+/** One self-correcting grammar-gate finding. */
+export interface PmCliGrammarFinding {
+    /** Stable diagnostic category suitable for automated remediation. */
+    code: "alias_target_missing" | "duplicate_destination" | "missing_destination" | "stale_destination" | "unknown_noun" | "visible_surface_ceiling_exceeded";
+    /** Exact command or alias spelling that violated the contract. */
+    spelling: string;
+    /** Human-readable explanation of the violated invariant. */
+    message: string;
+    /** Closest canonical invocation or corrective policy action. */
+    nearest_target: string;
+}
+/** Deterministic conformance report for the live command and alias surfaces. */
+export interface PmCliGrammarReport {
+    /** Whether every checked grammar invariant passed. */
+    ok: boolean;
+    /** Number of normalized live command paths evaluated. */
+    command_count: number;
+    /** Number of checked-in destination-census rows. */
+    destination_count: number;
+    /** Number of declared aliases omitted from default discovery. */
+    hidden_alias_count: number;
+    /** Number of distinct visible non-package single-token command paths. */
+    visible_top_level_count: number;
+    /** Maximum visible single-token command paths permitted by the ADR. */
+    visible_top_level_ceiling: number;
+    /** Self-correcting conformance diagnostics, empty when `ok` is true. */
+    findings: PmCliGrammarFinding[];
+}
+/** Verify exhaustive census parity, noun ownership, alias targets, and growth. */
+export declare function verifyPmCliGrammar(commands: readonly string[], aliases?: readonly PmCommandAliasContract[]): PmCliGrammarReport;