@unbrained/pm-cli 2026.8.7 → 2026.8.8

package/dist/sdk/completion.js

@@ -4,7 +4,7 @@
  * Implements the pm completion 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]="8acb405a-140e-532c-81c0-e8153ea30dc0")}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]="6c9648d7-ab14-5e0d-8793-86ae13643fa6")}catch(e){}}();
 import { EXIT_CODE, PmCliError } from "./runtime-primitives.js";
 import { listPmCommandsForTier } from "./agent-capability-contracts.js";
 import { SCAFFOLD_CAPABILITIES } from "./extension/scaffold.js";
@@ -599,13 +599,13 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
         `      COMPREPLY=(${compgen(`${LIFECYCLE_ACTIONS} ${PACKAGE_LIFECYCLE_FLAGS}`)})`,
         "      ;;",
         "    comments)",
-        `      COMPREPLY=(${compgen("--add --body --stdin --file --edit --delete --limit --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("--add --body --stdin --file --edit --delete --limit --full-history --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    notes)",
-        `      COMPREPLY=(${compgen("--add --add-json --stdin --file --edit --delete --limit --since --event-type --include-meta --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("--add --add-json --stdin --file --edit --delete --limit --since --event-type --include-meta --full-history --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    learnings)",
-        `      COMPREPLY=(${compgen("--add --stdin --file --edit --delete --limit --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("--add --stdin --file --edit --delete --limit --full-history --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    files)",
         `      COMPREPLY=(${compgen("discover lookup --add --add-glob --remove --migrate --list --apply --note --append-stable --validate-paths --scope --limit --offset --no-truncate --strict-read --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
@@ -1354,6 +1354,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--edit[Replace the comment at 1-based index (text from positional/--add/--stdin/--file)]:index' \\
             '--delete[Delete the comment at 1-based index]:index' \\
             '--limit[Return only latest n entries]:number' \\
+            '--full-history[Return complete post-mutation history]' \\
             '--author[Entry author (falls back to PM_AUTHOR/settings)]:author' \\
             '--message[History message]:message' \\
             '--force[Force override]' \\
@@ -1372,6 +1373,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--since[Return structured events at or after an ISO timestamp]:timestamp' \\
             '--event-type[Return structured events with this top-level type]:event_type' \\
             '--include-meta[Include result counts and truncation metadata]' \\
+            '--full-history[Return complete post-mutation history]' \\
             '--author[Entry author (falls back to PM_AUTHOR/settings)]:author' \\
             '--message[History message]:message' \\
             '--force[Force override]' \\
@@ -1386,6 +1388,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--edit[Replace the entry at a 1-based index]:index' \\
             '--delete[Delete the entry at a 1-based index]:index' \\
             '--limit[Return only latest n entries]:number' \\
+            '--full-history[Return complete post-mutation history]' \\
             '--author[Entry author (falls back to PM_AUTHOR/settings)]:author' \\
             '--message[History message]:message' \\
             '--force[Force override]' \\
@@ -2415,6 +2418,7 @@ complete -c pm -n '__fish_seen_subcommand_from notes' -l file -d 'Read entry tex
 complete -c pm -n '__fish_seen_subcommand_from notes' -l edit -d 'Replace the entry at a 1-based index' -r
 complete -c pm -n '__fish_seen_subcommand_from notes' -l delete -d 'Delete the entry at a 1-based index' -r
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l limit -d 'Return only latest n entries' -r
+complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l full-history -d 'Return complete post-mutation history'
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l author -d 'Entry author' -r
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l message -d 'History message' -r
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l force -d 'Force override'
@@ -2743,4 +2747,4 @@ export function runCompletion(shell, itemTypes = [], tags = [], eagerTagExpansio
     };
 }
 //# sourceMappingURL=completion.js.map
-//# debugId=8acb405a-140e-532c-81c0-e8153ea30dc0
+//# debugId=6c9648d7-ab14-5e0d-8793-86ae13643fa6

package/dist/sdk/contracts.d.ts

@@ -4,6 +4,7 @@
  * Exposes command and action contract data without loading SDK runtime code.
  */
 export * from "./cli-contracts.js";
+export * from "./cli-contracts/command-exit-contracts.js";
 export * from "./context-intent-contracts.js";
 export * from "./error-code-catalog.js";
 export * from "./generated-error-code-catalog.js";

package/dist/sdk/contracts.js

@@ -4,8 +4,9 @@
  * Exposes command and action contract data without loading SDK runtime code.
  */
 
-!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]="8c442738-13e6-5bf5-b60d-1439c3255f1a")}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]="65e53d90-6fff-59df-bdfc-0d2387b5a28d")}catch(e){}}();
 export * from "./cli-contracts.js";
+export * from "./cli-contracts/command-exit-contracts.js";
 export * from "./context-intent-contracts.js";
 export * from "./error-code-catalog.js";
 export * from "./generated-error-code-catalog.js";
@@ -14,4 +15,4 @@ export * from "./output-token-accounting.js";
 export * from "./output-contracts.js";
 export * from "./read-output-contracts.js";
 //# sourceMappingURL=contracts.js.map
-//# debugId=8c442738-13e6-5bf5-b60d-1439c3255f1a
+//# debugId=65e53d90-6fff-59df-bdfc-0d2387b5a28d

package/dist/sdk/environment/host-environment-errors.d.ts

@@ -0,0 +1,27 @@
+import { PmCliError } from "../../core/shared/errors.js";
+/** Optional stable codes used by an existing SDK surface for each fault class. */
+export interface HostEnvironmentFaultCodeOverrides {
+    /** Code used for quota and storage exhaustion. */
+    capacity?: string;
+    /** Code used for access policy and read-only filesystems. */
+    permission?: string;
+    /** Code used for file-descriptor and memory exhaustion. */
+    resource?: string;
+}
+/** Context and compatibility controls for a host-environment boundary. */
+export interface HostEnvironmentBoundaryOptions {
+    /** Existing surface-specific codes that must remain compatible. */
+    codes?: HostEnvironmentFaultCodeOverrides;
+    /** Human explanation of why the operation needs host resources. */
+    why?: string;
+    /** Additional ordered recovery guidance. */
+    nextSteps?: readonly string[];
+    /** Copyable retry command when one is safe. */
+    suggestedRetry?: string;
+}
+/** Return a declared host errno only when it represents recoverable environment state. */
+export declare function classifyHostEnvironmentFault(error: unknown): string | null;
+/** Translate one known host fault into a stable path-redacted SDK refusal. */
+export declare function translateHostEnvironmentFault(error: unknown, operation: string, options?: HostEnvironmentBoundaryOptions): PmCliError | null;
+/** Run one SDK filesystem stage and translate only declared host faults. */
+export declare function withHostEnvironmentBoundary<T>(operation: string, run: () => Promise<T>, options?: HostEnvironmentBoundaryOptions): Promise<T>;

package/dist/sdk/environment/host-environment-errors.js

@@ -0,0 +1,124 @@
+/**
+ * @module sdk/host-environment-errors
+ *
+ * Classifies host filesystem/resource failures at SDK boundaries without
+ * leaking local paths or swallowing genuine implementation defects.
+ */
+
+!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]="41fec0f3-5cc8-5007-a896-f8d8b83ae4f5")}catch(e){}}();
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+const HOST_ENVIRONMENT_FAULTS = new Map([
+    [
+        "EACCES",
+        {
+            summary: "was denied filesystem permission",
+            recovery: "Grant the required filesystem access, then retry.",
+            category: "permission",
+        },
+    ],
+    [
+        "EDQUOT",
+        {
+            summary: "exceeded the filesystem quota",
+            recovery: "Raise or reclaim the filesystem quota, then retry.",
+            category: "capacity",
+        },
+    ],
+    [
+        "EMFILE",
+        {
+            summary: "exhausted the process file-descriptor limit",
+            recovery: "Close unused file handles or raise the process limit, then retry.",
+            category: "resource",
+        },
+    ],
+    [
+        "ENFILE",
+        {
+            summary: "exhausted the host file-descriptor limit",
+            recovery: "Free host file descriptors or raise the host limit, then retry.",
+            category: "resource",
+        },
+    ],
+    [
+        "ENOMEM",
+        {
+            summary: "ran out of available memory",
+            recovery: "Free memory or reduce concurrent work, then retry.",
+            category: "resource",
+        },
+    ],
+    [
+        "ENOSPC",
+        {
+            summary: "ran out of storage space",
+            recovery: "Free storage on the filesystem holding the project, then retry.",
+            category: "capacity",
+        },
+    ],
+    [
+        "EPERM",
+        {
+            summary: "was denied by the host permission policy",
+            recovery: "Grant the required filesystem permission, then retry.",
+            category: "permission",
+        },
+    ],
+    [
+        "EROFS",
+        {
+            summary: "targeted a read-only filesystem",
+            recovery: "Use a writable project filesystem or remount it read-write, then retry.",
+            category: "permission",
+        },
+    ],
+]);
+const OPERATION_PATTERN = /^[a-z][a-z0-9_]{0,63}$/u;
+const HOST_ENVIRONMENT_FAULT_CODES = {
+    capacity: { code: "host_environment_capacity_fault" },
+    permission: { code: "host_environment_permission_fault" },
+    resource: { code: "host_environment_resource_fault" },
+};
+/** Return a declared host errno only when it represents recoverable environment state. */
+export function classifyHostEnvironmentFault(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return null;
+    const code = error.code;
+    return typeof code === "string" && HOST_ENVIRONMENT_FAULTS.has(code)
+        ? code
+        : null;
+}
+/** Translate one known host fault into a stable path-redacted SDK refusal. */
+export function translateHostEnvironmentFault(error, operation, options = {}) {
+    const errno = classifyHostEnvironmentFault(error);
+    if (errno === null)
+        return null;
+    if (!OPERATION_PATTERN.test(operation)) {
+        throw new PmCliError("Host environment operation labels must be bounded identifiers.", EXIT_CODE.USAGE, { code: "host_environment_operation_invalid", field: "operation" });
+    }
+    const fault = HOST_ENVIRONMENT_FAULTS.get(errno);
+    return new PmCliError(`Host filesystem operation ${operation} ${fault.summary}.`, EXIT_CODE.GENERIC_FAILURE, {
+        code: options.codes?.[fault.category] ??
+            HOST_ENVIRONMENT_FAULT_CODES[fault.category].code,
+        reason: errno,
+        required: fault.recovery,
+        why: options.why ??
+            "The operating system refused a required project filesystem operation.",
+        nextSteps: [fault.recovery, ...(options.nextSteps ?? [])],
+        ...(options.suggestedRetry
+            ? { recovery: { suggested_retry: options.suggestedRetry } }
+            : {}),
+    });
+}
+/** Run one SDK filesystem stage and translate only declared host faults. */
+export async function withHostEnvironmentBoundary(operation, run, options = {}) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        throw translateHostEnvironmentFault(error, operation, options) ?? error;
+    }
+}
+//# sourceMappingURL=host-environment-errors.js.map
+//# debugId=41fec0f3-5cc8-5007-a896-f8d8b83ae4f5

package/dist/sdk/environment/project-runtime-compatibility.d.ts

@@ -0,0 +1,65 @@
+import { PmCliError } from "../../core/shared/errors.js";
+export { PmCliError };
+/** One discovered project pin that can prove the active executable is stale. */
+export interface ProjectRuntimeVersionPin {
+    /** Exact or minimum date-version extracted from the project declaration. */
+    version: string;
+    /** Redaction-safe origin of the pin. */
+    source: "package.json" | "installed-package" | "package-lock.json" | "pnpm-lock.yaml" | "yarn.lock";
+}
+/** Structured result returned by the read-only compatibility probe. */
+export interface ProjectRuntimeCompatibilityResult {
+    /** Whether the invocation can write with the active runtime. */
+    compatible: boolean;
+    /** Active executable package version. */
+    executing_version: string;
+    /** Highest project pin discovered without exposing local paths. */
+    project_version?: string;
+    /** Origin of the highest project pin. */
+    source?: ProjectRuntimeVersionPin["source"];
+    /** Canonical command selected from the invocation. */
+    command?: string;
+    /** Whether the selected invocation can mutate project state. */
+    mutating: boolean;
+    /** Whether the active executable is older than the strongest project pin. */
+    stale?: boolean;
+    /** Non-blocking diagnostic attached to stale read-only invocations. */
+    warning?: ProjectRuntimeCompatibilityWarning;
+    /** Whether the explicit one-invocation recovery override was accepted. */
+    override_applied: boolean;
+}
+/** Structured, package-manager-neutral warning returned for a stale read. */
+export interface ProjectRuntimeCompatibilityWarning {
+    /** Stable warning code for filtering and automation. */
+    code: "project_runtime_stale_read";
+    /** Active executable package version. */
+    executing_version: string;
+    /** Strongest newer project version pin. */
+    project_version: string;
+    /** Redaction-safe origin of the project pin. */
+    source: ProjectRuntimeVersionPin["source"];
+    /** Concise explanation of the mismatch. */
+    message: string;
+    /** Package-manager-neutral recovery actions. */
+    next_steps: string[];
+}
+/** Compare pm date versions without accepting arbitrary semver-like prose. */
+export declare function comparePmDateVersions(left: string, right: string): number | null;
+/** Discover declared, installed, and lock-resolved versions without network I/O. */
+export declare function discoverProjectRuntimeVersionPins(projectRoot: string): ProjectRuntimeVersionPin[];
+/** Classify mutation-capable invocations while preserving explicit read modes. */
+export declare function isProjectMutatingInvocation(argv: readonly string[]): boolean;
+/** Inspect whether one invocation is compatible with the project's newest pin. */
+export declare function inspectProjectRuntimeCompatibility(options: {
+    executingVersion: string;
+    projectRoot: string;
+    argv: readonly string[];
+    allowStale?: boolean;
+}): ProjectRuntimeCompatibilityResult;
+/** Refuse stale mutations with a stable SDK error and package-neutral recovery. */
+export declare function assertProjectRuntimeCompatibility(options: {
+    executingVersion: string;
+    projectRoot: string;
+    argv: readonly string[];
+    allowStale?: boolean;
+}): ProjectRuntimeCompatibilityResult;