@unbrained/pm-cli 2026.5.6 → 2026.5.11

package/dist/sdk/cli-contracts.js

@@ -19,6 +19,30 @@ export const PM_EXTENSION_SERVICE_NAME_CONTRACTS = [
     "item_store_write",
     "item_store_delete",
 ];
+export const PM_EXTENSION_POLICY_MODE_CONTRACTS = ["off", "warn", "enforce"];
+export const PM_EXTENSION_TRUST_MODE_CONTRACTS = ["off", "warn", "enforce"];
+export const PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS = ["none", "restricted", "strict"];
+export const PM_EXTENSION_POLICY_SURFACE_CONTRACTS = [
+    "commands.override",
+    "commands.handler",
+    "hooks.beforecommand",
+    "hooks.aftercommand",
+    "hooks.onwrite",
+    "hooks.onread",
+    "hooks.onindex",
+    "schema.flags",
+    "schema.itemfields",
+    "schema.itemtypes",
+    "schema.migrations",
+    "parser.override",
+    "preflight.override",
+    "services.override",
+    "renderers.override",
+    "importers.importer",
+    "importers.exporter",
+    "search.provider",
+    "search.vectorstore",
+];
 function normalizeUniqueStringList(values) {
     return [...new Set(Array.from(values).filter((value) => value.trim().length > 0))];
 }
@@ -73,6 +97,7 @@ export const PM_CORE_COMMAND_NAMES = [
     "list-canceled",
     "aggregate",
     "dedupe-audit",
+    "guide",
     "calendar",
     "cal",
     "context",
@@ -121,11 +146,13 @@ export const PM_TOOL_ACTIONS = [
     "extension-uninstall",
     "extension-explore",
     "extension-manage",
+    "extension-reload",
     "extension-doctor",
     "extension-adopt",
     "extension-adopt-all",
     "extension-activate",
     "extension-deactivate",
+    "extension",
     "create",
     "list",
     "list-all",
@@ -137,8 +164,11 @@ export const PM_TOOL_ACTIONS = [
     "list-canceled",
     "aggregate",
     "dedupe-audit",
+    "guide",
     "calendar",
+    "cal",
     "context",
+    "ctx",
     "get",
     "search",
     "reindex",
@@ -183,6 +213,21 @@ export const PM_TOOL_ACTIONS = [
     "pause-task",
     "close-task",
 ];
+export function isPmToolAction(value) {
+    return PM_TOOL_ACTIONS.includes(value);
+}
+export function isPmExtensionCapabilityContract(value) {
+    return PM_EXTENSION_CAPABILITY_CONTRACTS.includes(value);
+}
+export function isPmExtensionServiceNameContract(value) {
+    return PM_EXTENSION_SERVICE_NAME_CONTRACTS.includes(value);
+}
+export function isPmExtensionPolicyModeContract(value) {
+    return PM_EXTENSION_POLICY_MODE_CONTRACTS.includes(value);
+}
+export function isPmExtensionPolicySurfaceContract(value) {
+    return PM_EXTENSION_POLICY_SURFACE_CONTRACTS.includes(value);
+}
 export const PI_LIST_FILTER_OPTION_CONTRACTS = [
     { param: "type", flag: "--type" },
     { param: "tag", flag: "--tag" },
@@ -506,6 +551,8 @@ export const COMMENTS_AUDIT_FLAG_CONTRACTS = [
 ];
 export const COMMENTS_FLAG_CONTRACTS = [
     { flag: "--add" },
+    { flag: "--stdin" },
+    { flag: "--file" },
     { flag: "--limit" },
     { flag: "--author" },
     { flag: "--message" },
@@ -569,6 +616,17 @@ export const CONFIG_FLAG_CONTRACTS = [
     { flag: "--clear-criteria" },
     { flag: "--format" },
     { flag: "--policy" },
+    { flag: "--default-depth" },
+    { flag: "--activity-limit" },
+    { flag: "--stale-threshold-days" },
+    { flag: "--section-hierarchy" },
+    { flag: "--section-activity" },
+    { flag: "--section-progress" },
+    { flag: "--section-blockers" },
+    { flag: "--section-files" },
+    { flag: "--section-workload" },
+    { flag: "--section-staleness" },
+    { flag: "--section-tests" },
 ];
 export const EXTENSION_FLAG_CONTRACTS = [
     { flag: "--init" },
@@ -577,6 +635,8 @@ export const EXTENSION_FLAG_CONTRACTS = [
     { flag: "--uninstall" },
     { flag: "--explore" },
     { flag: "--manage" },
+    { flag: "--reload" },
+    { flag: "--watch" },
     { flag: "--doctor" },
     { flag: "--adopt" },
     { flag: "--adopt-all" },
@@ -1077,6 +1137,15 @@ export const CONTEXT_FLAG_CONTRACTS = [
     { flag: "--release" },
     { flag: "--limit" },
     { flag: "--format" },
+    { flag: "--depth" },
+    { flag: "--section" },
+    { flag: "--activity-limit" },
+    { flag: "--stale-threshold" },
+];
+export const GUIDE_FLAG_CONTRACTS = [
+    { flag: "--list" },
+    { flag: "--format" },
+    { flag: "--depth" },
 ];
 export const DEPS_FLAG_CONTRACTS = [
     { flag: "--format" },
@@ -1111,6 +1180,156 @@ export const CONTRACTS_FLAG_CONTRACTS = [
 export const COMPLETION_FLAG_CONTRACTS = [
     { flag: "--eager-tags" },
 ];
+function toUniqueFlagContracts(contracts) {
+    const seen = new Set();
+    const unique = [];
+    for (const contract of contracts) {
+        const aliasKey = (contract.aliases ?? []).join(",");
+        const key = `${contract.flag}|${contract.short ?? ""}|${aliasKey}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        unique.push(contract);
+    }
+    return unique;
+}
+function withSubcommandGlobalFlags(contracts) {
+    return withFlagAliasMetadata(toUniqueFlagContracts([...SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, ...contracts]));
+}
+const LIST_COMMAND_NAME_CONTRACTS = new Set([
+    "list",
+    "list-all",
+    "list-draft",
+    "list-open",
+    "list-in-progress",
+    "list-blocked",
+    "list-closed",
+    "list-canceled",
+]);
+const NO_SURFACE_COMMAND_NAME_CONTRACTS = new Set([
+    "get",
+    "stats",
+    "reindex",
+    "beads",
+    "todos",
+    "beads-import",
+    "todos-import",
+    "todos-export",
+    "help",
+]);
+function normalizeCommandNameForContracts(commandName) {
+    if (typeof commandName !== "string") {
+        return "";
+    }
+    return commandName.trim().toLowerCase();
+}
+export function resolveSubcommandFlagContractsForCommand(commandName) {
+    const normalized = normalizeCommandNameForContracts(commandName);
+    if (normalized.length === 0) {
+        return withSubcommandGlobalFlags([]);
+    }
+    if (LIST_COMMAND_NAME_CONTRACTS.has(normalized)) {
+        return withSubcommandGlobalFlags(LIST_FILTER_FLAG_CONTRACTS);
+    }
+    if (NO_SURFACE_COMMAND_NAME_CONTRACTS.has(normalized)) {
+        return withSubcommandGlobalFlags([]);
+    }
+    if (normalized === "templates") {
+        return withSubcommandGlobalFlags(CREATE_FLAG_CONTRACTS);
+    }
+    if (normalized === "cal") {
+        return withSubcommandGlobalFlags(CALENDAR_FLAG_CONTRACTS);
+    }
+    if (normalized === "ctx") {
+        return withSubcommandGlobalFlags(CONTEXT_FLAG_CONTRACTS);
+    }
+    if (normalized === "test-runs-worker") {
+        return withSubcommandGlobalFlags(TEST_RUNS_FLAG_CONTRACTS);
+    }
+    switch (normalized) {
+        case "init":
+            return withSubcommandGlobalFlags(INIT_FLAG_CONTRACTS);
+        case "config":
+            return withSubcommandGlobalFlags(CONFIG_FLAG_CONTRACTS);
+        case "extension":
+            return withSubcommandGlobalFlags(EXTENSION_FLAG_CONTRACTS);
+        case "create":
+            return withSubcommandGlobalFlags(CREATE_FLAG_CONTRACTS);
+        case "aggregate":
+            return withSubcommandGlobalFlags(AGGREGATE_FLAG_CONTRACTS);
+        case "dedupe-audit":
+            return withSubcommandGlobalFlags(DEDUPE_AUDIT_FLAG_CONTRACTS);
+        case "comments-audit":
+            return withSubcommandGlobalFlags(COMMENTS_AUDIT_FLAG_CONTRACTS);
+        case "calendar":
+            return withSubcommandGlobalFlags(CALENDAR_FLAG_CONTRACTS);
+        case "context":
+            return withSubcommandGlobalFlags(CONTEXT_FLAG_CONTRACTS);
+        case "search":
+            return withSubcommandGlobalFlags(SEARCH_FLAG_CONTRACTS);
+        case "history":
+            return withSubcommandGlobalFlags(HISTORY_FLAG_CONTRACTS);
+        case "activity":
+            return withSubcommandGlobalFlags(ACTIVITY_FLAG_CONTRACTS);
+        case "restore":
+            return withSubcommandGlobalFlags(RESTORE_FLAG_CONTRACTS);
+        case "update":
+            return withSubcommandGlobalFlags(UPDATE_FLAG_CONTRACTS);
+        case "update-many":
+            return withSubcommandGlobalFlags(UPDATE_MANY_FLAG_CONTRACTS);
+        case "normalize":
+            return withSubcommandGlobalFlags(NORMALIZE_FLAG_CONTRACTS);
+        case "close":
+            return withSubcommandGlobalFlags(CLOSE_FLAG_CONTRACTS);
+        case "delete":
+            return withSubcommandGlobalFlags(DELETE_FLAG_CONTRACTS);
+        case "append":
+            return withSubcommandGlobalFlags(APPEND_FLAG_CONTRACTS);
+        case "comments":
+            return withSubcommandGlobalFlags(COMMENTS_FLAG_CONTRACTS);
+        case "notes":
+            return withSubcommandGlobalFlags(NOTES_FLAG_CONTRACTS);
+        case "learnings":
+            return withSubcommandGlobalFlags(LEARNINGS_FLAG_CONTRACTS);
+        case "files":
+            return withSubcommandGlobalFlags(FILES_FLAG_CONTRACTS);
+        case "docs":
+            return withSubcommandGlobalFlags(DOCS_FLAG_CONTRACTS);
+        case "deps":
+            return withSubcommandGlobalFlags(DEPS_FLAG_CONTRACTS);
+        case "test":
+            return withSubcommandGlobalFlags(TEST_FLAG_CONTRACTS);
+        case "test-all":
+            return withSubcommandGlobalFlags(TEST_ALL_FLAG_CONTRACTS);
+        case "test-runs":
+            return withSubcommandGlobalFlags(TEST_RUNS_FLAG_CONTRACTS);
+        case "health":
+            return withSubcommandGlobalFlags(HEALTH_FLAG_CONTRACTS);
+        case "validate":
+            return withSubcommandGlobalFlags(VALIDATE_FLAG_CONTRACTS);
+        case "gc":
+            return withSubcommandGlobalFlags(GC_FLAG_CONTRACTS);
+        case "contracts":
+            return withSubcommandGlobalFlags(CONTRACTS_FLAG_CONTRACTS);
+        case "claim":
+            return withSubcommandGlobalFlags(CLAIM_FLAG_CONTRACTS);
+        case "release":
+            return withSubcommandGlobalFlags(RELEASE_FLAG_CONTRACTS);
+        case "start-task":
+            return withSubcommandGlobalFlags(START_TASK_FLAG_CONTRACTS);
+        case "pause-task":
+            return withSubcommandGlobalFlags(PAUSE_TASK_FLAG_CONTRACTS);
+        case "close-task":
+            return withSubcommandGlobalFlags(CLOSE_TASK_FLAG_CONTRACTS);
+        case "guide":
+            return withSubcommandGlobalFlags(GUIDE_FLAG_CONTRACTS);
+        case "completion":
+            return withSubcommandGlobalFlags(COMPLETION_FLAG_CONTRACTS);
+        default:
+            return withSubcommandGlobalFlags([]);
+    }
+}
 export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     const aliasAwareContracts = withFlagAliasMetadata(flagContracts);
     const scoped = aliasAwareContracts
@@ -1465,6 +1684,8 @@ const PM_TOOL_PARAMETER_PROPERTIES = {
     sharedHostSafe: { type: "boolean" },
     detail: { type: "string", enum: ["summary", "deep"] },
     trace: { type: "boolean" },
+    reload: { type: "boolean" },
+    watch: { type: "boolean" },
     runtimeProbe: { type: "boolean" },
     fixManagedState: { type: "boolean" },
     pmContext: { type: "string", enum: ["schema", "tracker", "auto"] },
@@ -1520,6 +1741,7 @@ const PM_TOOL_PARAMETER_PROPERTIES = {
     collapse: { type: "string", enum: ["none", "repeated"] },
     summary: { type: "boolean" },
     shell: { type: "string", enum: ["bash", "zsh", "fish"] },
+    stdin: { type: "boolean" },
     file: { type: "string" },
     preserveSourceIds: { type: "boolean" },
     folder: { type: "string" },
@@ -1666,11 +1888,38 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
     "extension-uninstall": { required: ["target"], optional: ["scope"] },
     "extension-explore": { optional: ["scope"] },
     "extension-manage": { optional: ["scope", "runtimeProbe", "fixManagedState"] },
+    "extension-reload": { optional: ["scope", "watch"] },
     "extension-doctor": { optional: ["scope", "detail", "trace", "fixManagedState", "strictExit", "failOnWarn"] },
     "extension-adopt": { required: ["target"], optional: ["scope", "github", "ref"] },
     "extension-adopt-all": { optional: ["scope"] },
     "extension-activate": { required: ["target"], optional: ["scope"] },
     "extension-deactivate": { required: ["target"], optional: ["scope"] },
+    extension: {
+        optional: [
+            "target",
+            "scope",
+            "github",
+            "ref",
+            "init",
+            "install",
+            "uninstall",
+            "explore",
+            "manage",
+            "reload",
+            "doctor",
+            "adopt",
+            "adoptAll",
+            "activate",
+            "deactivate",
+            "runtimeProbe",
+            "fixManagedState",
+            "detail",
+            "trace",
+            "watch",
+            "strictExit",
+            "failOnWarn",
+        ],
+    },
     create: {
         required: ["title", "description", "type", "status", "priority", "message"],
         optional: CREATE_CONTRACT_PARAMETER_KEYS,
@@ -1685,8 +1934,11 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
     "list-canceled": { optional: LIST_CONTRACT_PARAMETER_KEYS },
     aggregate: { optional: AGGREGATE_CONTRACT_PARAMETER_KEYS },
     "dedupe-audit": { optional: DEDUPE_AUDIT_CONTRACT_PARAMETER_KEYS },
+    guide: { optional: ["format", "depth"] },
     calendar: { optional: CALENDAR_CONTRACT_PARAMETER_KEYS },
+    cal: { optional: CALENDAR_CONTRACT_PARAMETER_KEYS },
     context: { optional: CONTEXT_CONTRACT_PARAMETER_KEYS },
+    ctx: { optional: CONTEXT_CONTRACT_PARAMETER_KEYS },
     get: { required: ["id"] },
     search: {
         optional: SEARCH_CONTRACT_PARAMETER_KEYS,
@@ -1702,7 +1954,10 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
     close: { required: ["id", "text"], optional: ["validateClose", ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS] },
     delete: { required: ["id"], optional: AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS },
     append: { required: ["id", "body"], optional: AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS },
-    comments: { required: ["id"], optional: ["text", "add", "limit", "allowAuditComment", ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS] },
+    comments: {
+        required: ["id"],
+        optional: ["text", "add", "stdin", "file", "limit", "allowAuditComment", ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS],
+    },
     "comments-audit": {
         optional: [
             "status",
@@ -1860,6 +2115,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
     "pause-task": { required: ["id"], optional: AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS },
     "close-task": { required: ["id", "text"], optional: AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS },
 };
+export const PM_TOOL_ACTION_PARAMETER_CONTRACTS = PM_TOOL_ACTION_SCHEMA_CONTRACTS;
 const PM_TOOL_PARAMETER_METADATA = {
     action: {
         description: "Tool action to execute.",
@@ -1879,6 +2135,12 @@ const PM_TOOL_PARAMETER_METADATA = {
     trace: {
         description: "When true for extension-doctor, include actionable registration traces in deep diagnostics.",
     },
+    reload: {
+        description: "When true for extension action payloads, trigger cache-busted extension module reload.",
+    },
+    watch: {
+        description: "When true for extension-reload/extension action payloads, enable watch mode semantics.",
+    },
     runtimeProbe: {
         description: "When true for extension-manage, run a doctor-like runtime activation probe for parity fields.",
     },
@@ -2190,6 +2452,13 @@ const PM_TOOL_PARAMETER_METADATA = {
     allowAuditComment: {
         description: "For comments action, allow non-owner append-only comment audits without requiring --force.",
     },
+    stdin: {
+        description: "When true for comments action, read comment text from piped stdin (supports multiline markdown).",
+    },
+    file: {
+        description: "Path to input file for actions that read payload text (for example comments --file or beads-import --file).",
+        examples: ["notes/comment.md", "import.json"],
+    },
     allowAuditUpdate: {
         description: "Allow non-owner metadata-only update audits without requiring --force.",
     },
@@ -2379,7 +2648,53 @@ export const PM_TOOL_PARAMETERS_SCHEMA = {
     $schema: "https://json-schema.org/draft/2020-12/schema",
     $id: "https://unbrained.dev/schemas/pm-cli/tool-parameters-v4.schema.json",
     title: "pm-cli Pi wrapper parameters (action-scoped strict schema)",
-    "x-schema-version": "4.0.0",
+    "x-schema-version": "4.0.1",
+    type: "object",
     oneOf: PM_TOOL_ACTIONS.map((action) => buildActionScopedToolSchema(action)),
 };
+function toProviderCompatibleParameterDefinition(key, definition) {
+    const decorated = decorateToolParameterDefinition(key, definition);
+    if (typeof decorated.type === "string") {
+        return decorated;
+    }
+    const anyOf = Array.isArray(decorated.anyOf) ? decorated.anyOf : [];
+    const firstTypedVariant = anyOf.find((variant) => typeof variant.type === "string");
+    if (firstTypedVariant) {
+        const { anyOf: _anyOf, ...rest } = decorated;
+        return {
+            ...rest,
+            type: firstTypedVariant.type,
+        };
+    }
+    const { anyOf: _anyOf, ...rest } = decorated;
+    return {
+        ...rest,
+        type: "string",
+    };
+}
+function buildProviderCompatiblePiToolSchema() {
+    const properties = {
+        action: {
+            type: "string",
+            description: PM_TOOL_PARAMETER_METADATA.action?.description ?? "Tool action to execute.",
+        },
+        options: {
+            type: "object",
+            additionalProperties: true,
+            description: "Advanced command options object forwarded to the selected pm action.",
+        },
+    };
+    for (const key of Object.keys(PM_TOOL_PARAMETER_PROPERTIES).sort()) {
+        properties[key] = toProviderCompatibleParameterDefinition(key, PM_TOOL_PARAMETER_PROPERTIES[key]);
+    }
+    return {
+        title: "pm-cli Pi tool parameters (provider-compatible flat schema)",
+        "x-schema-version": "1.0.0",
+        type: "object",
+        additionalProperties: false,
+        required: ["action"],
+        properties,
+    };
+}
+export const PM_PI_TOOL_PARAMETERS_SCHEMA = buildProviderCompatiblePiToolSchema();
 //# sourceMappingURL=cli-contracts.js.map