@unbrained/pm-cli 2026.6.23 → 2026.6.30

package/dist/core/extensions/version-compat.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @module core/extensions/version-compat
+ *
+ * Single source of truth for extension-manifest version-bound compatibility.
+ *
+ * An extension manifest may declare an inclusive `pm_min_version` lower bound and
+ * an inclusive `pm_max_version` upper bound. At load time the
+ * {@link ../extensions/loader.js | loader} compares them against the running pm
+ * CLI version and skips (or warns about) an extension that falls outside the
+ * supported window. The comparison and the per-bound status semantics live here
+ * so the runtime loader and the author-time SDK helper
+ * (`checkExtensionManifestCompatibility`) share one implementation and can never
+ * drift — the same "agrees with the loader by construction" guarantee the
+ * declarative authoring helpers (`describeExtensionBlueprint`,
+ * `deriveExtensionCapabilities`) already provide.
+ *
+ * The functions here are pure: they take an already-resolved current version
+ * (the loader resolves it from `package.json`; the SDK caller supplies a target
+ * version) and return structured outcomes. Warning-string formatting and
+ * version resolution stay with the loader; finding/message presentation stays
+ * with the SDK.
+ */
+import type { PmMaxVersionExceededMode } from "./extension-types.js";
+/** The two inclusive manifest version bounds pm evaluates at load time. */
+export type PmVersionBoundKind = "pm_min_version" | "pm_max_version";
+/**
+ * The outcome of evaluating a single manifest version bound against a pm version.
+ *
+ * - `absent`: the bound is not declared — nothing to enforce.
+ * - `ok`: the bound is declared and satisfied by the current version.
+ * - `invalid`: the declared bound is malformed (unparseable, or a range prefix on
+ *   `pm_max_version`); the loader treats the extension as incompatible and skips it.
+ * - `unchecked`: the bound is well-formed but cannot be compared against the
+ *   current version (the current version is unknown or not comparable); the
+ *   extension still loads, with an advisory warning.
+ * - `unmet`: the current version is older than the inclusive `pm_min_version`
+ *   lower bound; the loader skips the extension (only emitted for `pm_min_version`).
+ * - `exceeded`: the current version is newer than the inclusive `pm_max_version`
+ *   upper bound and the exceeded mode is `block`; the loader skips the extension
+ *   (only emitted for `pm_max_version`).
+ * - `exceeded_warn`: the current version is newer than `pm_max_version` but the
+ *   exceeded mode is `warn`, so the extension loads with an advisory warning
+ *   (only emitted for `pm_max_version`).
+ */
+export type PmVersionBoundStatus = "absent" | "ok" | "invalid" | "unchecked" | "unmet" | "exceeded" | "exceeded_warn";
+/**
+ * The structured result of evaluating one manifest version bound, consumed by the
+ * loader (to format its `extension_pm_*_version_*` warning strings) and the SDK
+ * (to build author-time compatibility findings).
+ */
+export interface PmVersionBoundEvaluation {
+    /** Which bound this evaluation describes. */
+    kind: PmVersionBoundKind;
+    /** The classified outcome of comparing the bound against the current version. */
+    status: PmVersionBoundStatus;
+    /** Whether the bound permits the extension to load (`false` only for `invalid`/`unmet`/`exceeded`). */
+    allowed: boolean;
+    /** The declared bound value, verbatim; the empty string when the bound is absent. */
+    required: string;
+    /** The current version compared against, or `null` when it could not be resolved. */
+    current: string | null;
+}
+/**
+ * Parse a comparable release string into numeric segments, or `null` when it is
+ * not an interpretable dotted-numeric version.
+ *
+ * Leniently strips a leading inclusive-minimum `>=` and an optional `v` prefix
+ * (so `engines.pm`-style `">=2026.5.31"` and `"v1.2.3"` both parse), then drops
+ * any build/pre-release suffix and keeps the leading dotted-numeric release.
+ */
+export declare function parseComparableVersion(value: string): number[] | null;
+/**
+ * Compare two comparable version strings segment by segment.
+ *
+ * Returns `1` when `currentVersion` is greater, `-1` when it is smaller, `0` when
+ * equal, and `null` when either side is not an interpretable version (so callers
+ * can classify the comparison as `unchecked`). Missing trailing segments are
+ * treated as `0`, so `1.2` and `1.2.0` compare equal.
+ */
+export declare function compareComparableVersions(currentVersion: string, otherVersion: string): number | null;
+/**
+ * Evaluate a manifest `pm_min_version` inclusive lower bound against the current
+ * pm version.
+ *
+ * An omitted bound is `absent`; a blank, non-string, or unparseable bound is
+ * `invalid`; an unknown or incomparable current version is `unchecked`; a current
+ * version below the bound is `unmet`; otherwise the bound is satisfied (`ok`).
+ * `currentVersion` is `null` when the loader could not resolve the running CLI
+ * version.
+ */
+export declare function evaluatePmMinVersionBound(required: unknown, currentVersion: string | null): PmVersionBoundEvaluation;
+/**
+ * Evaluate a manifest `pm_max_version` inclusive upper bound against the current
+ * pm version.
+ *
+ * An omitted bound is `absent`. A blank or non-string bound is `invalid`. The
+ * upper bound must be an exact version: a range prefix (`<`/`>`/`=`/`~`/`^`) is
+ * rejected as `invalid`, because
+ * {@link parseComparableVersion} leniently strips a leading `>=` for
+ * `engines.pm` min-version compatibility and would otherwise turn a range-like
+ * `">=2026.6.1"` into an inclusive max and wrongly block newer CLIs. An
+ * unparseable bound is `invalid`; an unknown or incomparable current version is
+ * `unchecked`; a current version above the bound is `exceeded` (or
+ * `exceeded_warn` when `exceededMode` is `warn`, so the extension still loads
+ * during a controlled upgrade window); otherwise the bound is satisfied (`ok`).
+ */
+export declare function evaluatePmMaxVersionBound(required: unknown, currentVersion: string | null, exceededMode: PmMaxVersionExceededMode): PmVersionBoundEvaluation;

package/dist/core/extensions/version-compat.js

@@ -0,0 +1,130 @@
+
+!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]="9675b93b-da90-574d-a6cf-ea7448b40600")}catch(e){}}();
+function formatVersionBoundValue(value) {
+    return typeof value === "string" ? value : String(value);
+}
+/**
+ * Parse a comparable release string into numeric segments, or `null` when it is
+ * not an interpretable dotted-numeric version.
+ *
+ * Leniently strips a leading inclusive-minimum `>=` and an optional `v` prefix
+ * (so `engines.pm`-style `">=2026.5.31"` and `"v1.2.3"` both parse), then drops
+ * any build/pre-release suffix and keeps the leading dotted-numeric release.
+ */
+export function parseComparableVersion(value) {
+    const normalized = value.trim().replace(/^>=\s*/, "").replace(/^v/i, "");
+    const release = normalized.split(/[+-]/, 1)[0];
+    if (!/^\d+(?:[.-]\d+)*$/.test(release)) {
+        return null;
+    }
+    return release.split(/[.-]/).map((part) => Number(part));
+}
+/**
+ * Compare two comparable version strings segment by segment.
+ *
+ * Returns `1` when `currentVersion` is greater, `-1` when it is smaller, `0` when
+ * equal, and `null` when either side is not an interpretable version (so callers
+ * can classify the comparison as `unchecked`). Missing trailing segments are
+ * treated as `0`, so `1.2` and `1.2.0` compare equal.
+ */
+export function compareComparableVersions(currentVersion, otherVersion) {
+    const currentParts = parseComparableVersion(currentVersion);
+    const otherParts = parseComparableVersion(otherVersion);
+    if (!currentParts || !otherParts) {
+        return null;
+    }
+    const width = Math.max(currentParts.length, otherParts.length);
+    for (let index = 0; index < width; index += 1) {
+        const current = currentParts[index] ?? 0;
+        const other = otherParts[index] ?? 0;
+        if (current > other) {
+            return 1;
+        }
+        if (current < other) {
+            return -1;
+        }
+    }
+    return 0;
+}
+/**
+ * Evaluate a manifest `pm_min_version` inclusive lower bound against the current
+ * pm version.
+ *
+ * An omitted bound is `absent`; a blank, non-string, or unparseable bound is
+ * `invalid`; an unknown or incomparable current version is `unchecked`; a current
+ * version below the bound is `unmet`; otherwise the bound is satisfied (`ok`).
+ * `currentVersion` is `null` when the loader could not resolve the running CLI
+ * version.
+ */
+export function evaluatePmMinVersionBound(required, currentVersion) {
+    if (required === undefined || required === null) {
+        return { kind: "pm_min_version", status: "absent", allowed: true, required: "", current: currentVersion };
+    }
+    const declared = formatVersionBoundValue(required);
+    if (typeof required !== "string" || declared.trim().length === 0) {
+        return { kind: "pm_min_version", status: "invalid", allowed: false, required: declared, current: currentVersion };
+    }
+    if (!parseComparableVersion(declared)) {
+        return { kind: "pm_min_version", status: "invalid", allowed: false, required: declared, current: currentVersion };
+    }
+    if (currentVersion === null) {
+        return { kind: "pm_min_version", status: "unchecked", allowed: true, required: declared, current: null };
+    }
+    const comparison = compareComparableVersions(currentVersion, declared);
+    if (comparison === null) {
+        return { kind: "pm_min_version", status: "unchecked", allowed: true, required: declared, current: currentVersion };
+    }
+    if (comparison < 0) {
+        return { kind: "pm_min_version", status: "unmet", allowed: false, required: declared, current: currentVersion };
+    }
+    return { kind: "pm_min_version", status: "ok", allowed: true, required: declared, current: currentVersion };
+}
+/**
+ * Evaluate a manifest `pm_max_version` inclusive upper bound against the current
+ * pm version.
+ *
+ * An omitted bound is `absent`. A blank or non-string bound is `invalid`. The
+ * upper bound must be an exact version: a range prefix (`<`/`>`/`=`/`~`/`^`) is
+ * rejected as `invalid`, because
+ * {@link parseComparableVersion} leniently strips a leading `>=` for
+ * `engines.pm` min-version compatibility and would otherwise turn a range-like
+ * `">=2026.6.1"` into an inclusive max and wrongly block newer CLIs. An
+ * unparseable bound is `invalid`; an unknown or incomparable current version is
+ * `unchecked`; a current version above the bound is `exceeded` (or
+ * `exceeded_warn` when `exceededMode` is `warn`, so the extension still loads
+ * during a controlled upgrade window); otherwise the bound is satisfied (`ok`).
+ */
+export function evaluatePmMaxVersionBound(required, currentVersion, exceededMode) {
+    if (required === undefined || required === null) {
+        return { kind: "pm_max_version", status: "absent", allowed: true, required: "", current: currentVersion };
+    }
+    const declared = formatVersionBoundValue(required);
+    if (typeof required !== "string" || declared.trim().length === 0) {
+        return { kind: "pm_max_version", status: "invalid", allowed: false, required: declared, current: currentVersion };
+    }
+    if (/^[<>=~^]/.test(declared.trim()) || !parseComparableVersion(declared)) {
+        return { kind: "pm_max_version", status: "invalid", allowed: false, required: declared, current: currentVersion };
+    }
+    if (currentVersion === null) {
+        return { kind: "pm_max_version", status: "unchecked", allowed: true, required: declared, current: null };
+    }
+    const comparison = compareComparableVersions(currentVersion, declared);
+    if (comparison === null) {
+        return { kind: "pm_max_version", status: "unchecked", allowed: true, required: declared, current: currentVersion };
+    }
+    if (comparison > 0) {
+        if (exceededMode === "warn") {
+            return {
+                kind: "pm_max_version",
+                status: "exceeded_warn",
+                allowed: true,
+                required: declared,
+                current: currentVersion,
+            };
+        }
+        return { kind: "pm_max_version", status: "exceeded", allowed: false, required: declared, current: currentVersion };
+    }
+    return { kind: "pm_max_version", status: "ok", allowed: true, required: declared, current: currentVersion };
+}
+//# sourceMappingURL=version-compat.js.map
+//# debugId=9675b93b-da90-574d-a6cf-ea7448b40600

package/dist/core/extensions/version-compat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-compat.js","sources":["core/extensions/version-compat.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/extensions/version-compat\n *\n * Single source of truth for extension-manifest version-bound compatibility.\n *\n * An extension manifest may declare an inclusive `pm_min_version` lower bound and\n * an inclusive `pm_max_version` upper bound. At load time the\n * {@link ../extensions/loader.js | loader} compares them against the running pm\n * CLI version and skips (or warns about) an extension that falls outside the\n * supported window. The comparison and the per-bound status semantics live here\n * so the runtime loader and the author-time SDK helper\n * (`checkExtensionManifestCompatibility`) share one implementation and can never\n * drift — the same \"agrees with the loader by construction\" guarantee the\n * declarative authoring helpers (`describeExtensionBlueprint`,\n * `deriveExtensionCapabilities`) already provide.\n *\n * The functions here are pure: they take an already-resolved current version\n * (the loader resolves it from `package.json`; the SDK caller supplies a target\n * version) and return structured outcomes. Warning-string formatting and\n * version resolution stay with the loader; finding/message presentation stays\n * with the SDK.\n */\nimport type { PmMaxVersionExceededMode } from \"./extension-types.js\";\n\n/** The two inclusive manifest version bounds pm evaluates at load time. */\nexport type PmVersionBoundKind = \"pm_min_version\" | \"pm_max_version\";\n\n/**\n * The outcome of evaluating a single manifest version bound against a pm version.\n *\n * - `absent`: the bound is not declared — nothing to enforce.\n * - `ok`: the bound is declared and satisfied by the current version.\n * - `invalid`: the declared bound is malformed (unparseable, or a range prefix on\n *   `pm_max_version`); the loader treats the extension as incompatible and skips it.\n * - `unchecked`: the bound is well-formed but cannot be compared against the\n *   current version (the current version is unknown or not comparable); the\n *   extension still loads, with an advisory warning.\n * - `unmet`: the current version is older than the inclusive `pm_min_version`\n *   lower bound; the loader skips the extension (only emitted for `pm_min_version`).\n * - `exceeded`: the current version is newer than the inclusive `pm_max_version`\n *   upper bound and the exceeded mode is `block`; the loader skips the extension\n *   (only emitted for `pm_max_version`).\n * - `exceeded_warn`: the current version is newer than `pm_max_version` but the\n *   exceeded mode is `warn`, so the extension loads with an advisory warning\n *   (only emitted for `pm_max_version`).\n */\nexport type PmVersionBoundStatus =\n  | \"absent\"\n  | \"ok\"\n  | \"invalid\"\n  | \"unchecked\"\n  | \"unmet\"\n  | \"exceeded\"\n  | \"exceeded_warn\";\n\n/**\n * The structured result of evaluating one manifest version bound, consumed by the\n * loader (to format its `extension_pm_*_version_*` warning strings) and the SDK\n * (to build author-time compatibility findings).\n */\nexport interface PmVersionBoundEvaluation {\n  /** Which bound this evaluation describes. */\n  kind: PmVersionBoundKind;\n  /** The classified outcome of comparing the bound against the current version. */\n  status: PmVersionBoundStatus;\n  /** Whether the bound permits the extension to load (`false` only for `invalid`/`unmet`/`exceeded`). */\n  allowed: boolean;\n  /** The declared bound value, verbatim; the empty string when the bound is absent. */\n  required: string;\n  /** The current version compared against, or `null` when it could not be resolved. */\n  current: string | null;\n}\n\nfunction formatVersionBoundValue(value: unknown): string {\n  return typeof value === \"string\" ? value : String(value);\n}\n\n/**\n * Parse a comparable release string into numeric segments, or `null` when it is\n * not an interpretable dotted-numeric version.\n *\n * Leniently strips a leading inclusive-minimum `>=` and an optional `v` prefix\n * (so `engines.pm`-style `\">=2026.5.31\"` and `\"v1.2.3\"` both parse), then drops\n * any build/pre-release suffix and keeps the leading dotted-numeric release.\n */\nexport function parseComparableVersion(value: string): number[] | null {\n  const normalized = value.trim().replace(/^>=\\s*/, \"\").replace(/^v/i, \"\");\n  const release = normalized.split(/[+-]/, 1)[0];\n  if (!/^\\d+(?:[.-]\\d+)*$/.test(release)) {\n    return null;\n  }\n  return release.split(/[.-]/).map((part) => Number(part));\n}\n\n/**\n * Compare two comparable version strings segment by segment.\n *\n * Returns `1` when `currentVersion` is greater, `-1` when it is smaller, `0` when\n * equal, and `null` when either side is not an interpretable version (so callers\n * can classify the comparison as `unchecked`). Missing trailing segments are\n * treated as `0`, so `1.2` and `1.2.0` compare equal.\n */\nexport function compareComparableVersions(currentVersion: string, otherVersion: string): number | null {\n  const currentParts = parseComparableVersion(currentVersion);\n  const otherParts = parseComparableVersion(otherVersion);\n  if (!currentParts || !otherParts) {\n    return null;\n  }\n  const width = Math.max(currentParts.length, otherParts.length);\n  for (let index = 0; index < width; index += 1) {\n    const current = currentParts[index] ?? 0;\n    const other = otherParts[index] ?? 0;\n    if (current > other) {\n      return 1;\n    }\n    if (current < other) {\n      return -1;\n    }\n  }\n  return 0;\n}\n\n/**\n * Evaluate a manifest `pm_min_version` inclusive lower bound against the current\n * pm version.\n *\n * An omitted bound is `absent`; a blank, non-string, or unparseable bound is\n * `invalid`; an unknown or incomparable current version is `unchecked`; a current\n * version below the bound is `unmet`; otherwise the bound is satisfied (`ok`).\n * `currentVersion` is `null` when the loader could not resolve the running CLI\n * version.\n */\nexport function evaluatePmMinVersionBound(\n  required: unknown,\n  currentVersion: string | null,\n): PmVersionBoundEvaluation {\n  if (required === undefined || required === null) {\n    return { kind: \"pm_min_version\", status: \"absent\", allowed: true, required: \"\", current: currentVersion };\n  }\n  const declared = formatVersionBoundValue(required);\n  if (typeof required !== \"string\" || declared.trim().length === 0) {\n    return { kind: \"pm_min_version\", status: \"invalid\", allowed: false, required: declared, current: currentVersion };\n  }\n  if (!parseComparableVersion(declared)) {\n    return { kind: \"pm_min_version\", status: \"invalid\", allowed: false, required: declared, current: currentVersion };\n  }\n  if (currentVersion === null) {\n    return { kind: \"pm_min_version\", status: \"unchecked\", allowed: true, required: declared, current: null };\n  }\n  const comparison = compareComparableVersions(currentVersion, declared);\n  if (comparison === null) {\n    return { kind: \"pm_min_version\", status: \"unchecked\", allowed: true, required: declared, current: currentVersion };\n  }\n  if (comparison < 0) {\n    return { kind: \"pm_min_version\", status: \"unmet\", allowed: false, required: declared, current: currentVersion };\n  }\n  return { kind: \"pm_min_version\", status: \"ok\", allowed: true, required: declared, current: currentVersion };\n}\n\n/**\n * Evaluate a manifest `pm_max_version` inclusive upper bound against the current\n * pm version.\n *\n * An omitted bound is `absent`. A blank or non-string bound is `invalid`. The\n * upper bound must be an exact version: a range prefix (`<`/`>`/`=`/`~`/`^`) is\n * rejected as `invalid`, because\n * {@link parseComparableVersion} leniently strips a leading `>=` for\n * `engines.pm` min-version compatibility and would otherwise turn a range-like\n * `\">=2026.6.1\"` into an inclusive max and wrongly block newer CLIs. An\n * unparseable bound is `invalid`; an unknown or incomparable current version is\n * `unchecked`; a current version above the bound is `exceeded` (or\n * `exceeded_warn` when `exceededMode` is `warn`, so the extension still loads\n * during a controlled upgrade window); otherwise the bound is satisfied (`ok`).\n */\nexport function evaluatePmMaxVersionBound(\n  required: unknown,\n  currentVersion: string | null,\n  exceededMode: PmMaxVersionExceededMode,\n): PmVersionBoundEvaluation {\n  if (required === undefined || required === null) {\n    return { kind: \"pm_max_version\", status: \"absent\", allowed: true, required: \"\", current: currentVersion };\n  }\n  const declared = formatVersionBoundValue(required);\n  if (typeof required !== \"string\" || declared.trim().length === 0) {\n    return { kind: \"pm_max_version\", status: \"invalid\", allowed: false, required: declared, current: currentVersion };\n  }\n  if (/^[<>=~^]/.test(declared.trim()) || !parseComparableVersion(declared)) {\n    return { kind: \"pm_max_version\", status: \"invalid\", allowed: false, required: declared, current: currentVersion };\n  }\n  if (currentVersion === null) {\n    return { kind: \"pm_max_version\", status: \"unchecked\", allowed: true, required: declared, current: null };\n  }\n  const comparison = compareComparableVersions(currentVersion, declared);\n  if (comparison === null) {\n    return { kind: \"pm_max_version\", status: \"unchecked\", allowed: true, required: declared, current: currentVersion };\n  }\n  if (comparison > 0) {\n    if (exceededMode === \"warn\") {\n      return {\n        kind: \"pm_max_version\",\n        status: \"exceeded_warn\",\n        allowed: true,\n        required: declared,\n        current: currentVersion,\n      };\n    }\n    return { kind: \"pm_max_version\", status: \"exceeded\", allowed: false, required: declared, current: currentVersion };\n  }\n  return { kind: \"pm_max_version\", status: \"ok\", allowed: true, required: declared, current: currentVersion };\n}\n"],"names":[],"mappings":"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","debugId":"9675b93b-da90-574d-a6cf-ea7448b40600"}

package/dist/core/fs/fs-utils.js

@@ -4,10 +4,11 @@
  * Provides filesystem helpers for Fs Utils.
  */
 
-!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]="4ddafbee-315f-5aa0-b08f-d4d7a82cfe8d")}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]="4ba3885b-85fc-5941-bf52-6c70b2bb5c2a")}catch(e){}}();
 import * as fs from "node:fs/promises";
 import path from "node:path";
 import crypto from "node:crypto";
+const WINDOWS_RENAME_RETRY_DELAYS_MS = [10, 25, 50, 100];
 /**
  * Implements ensure dir for the public runtime surface of this module.
  */
@@ -52,6 +53,30 @@ export async function writeFileAtomic(targetPath, contents) {
         await fs.rename(tempPath, targetPath);
     }
     catch (error) {
+        if (process.platform === "win32" &&
+            (isErrno(error, "EPERM") || isErrno(error, "EBUSY"))) {
+            let lastError = error;
+            for (const delayMs of WINDOWS_RENAME_RETRY_DELAYS_MS) {
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+                try {
+                    await fs.rename(tempPath, targetPath);
+                    return;
+                }
+                catch (retryError) {
+                    lastError = retryError;
+                    if (!isErrno(retryError, "EPERM") && !isErrno(retryError, "EBUSY")) {
+                        break;
+                    }
+                }
+            }
+            try {
+                await fs.unlink(tempPath);
+            }
+            catch {
+                // Best-effort cleanup only.
+            }
+            throw lastError;
+        }
         if (isErrno(error, "EXDEV")) {
             try {
                 await fs.copyFile(tempPath, targetPath);
@@ -122,4 +147,4 @@ function isErrno(error, code) {
     return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 //# sourceMappingURL=fs-utils.js.map
-//# debugId=4ddafbee-315f-5aa0-b08f-d4d7a82cfe8d
+//# debugId=4ba3885b-85fc-5941-bf52-6c70b2bb5c2a

package/dist/core/fs/fs-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"fs-utils.js","sources":["core/fs/fs-utils.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/fs/fs-utils\n *\n * Provides filesystem helpers for Fs Utils.\n */\nimport * as fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport crypto from \"node:crypto\";\n\n/**\n * Implements ensure dir for the public runtime surface of this module.\n */\nexport async function ensureDir(dirPath: string): Promise<void> {\n  await fs.mkdir(dirPath, { recursive: true });\n}\n\n/**\n * Implements path exists for the public runtime surface of this module.\n */\nexport async function pathExists(targetPath: string): Promise<boolean> {\n  try {\n    await fs.access(targetPath);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Implements read file if exists for the public runtime surface of this module.\n */\nexport async function readFileIfExists(targetPath: string): Promise<string | null> {\n  try {\n    return await fs.readFile(targetPath, \"utf8\");\n  } catch (error: unknown) {\n    if (isErrno(error, \"ENOENT\")) {\n      return null;\n    }\n    throw error;\n  }\n}\n\n/**\n * Implements write file atomic for the public runtime surface of this module.\n */\nexport async function writeFileAtomic(targetPath: string, contents: string): Promise<void> {\n  const dirPath = path.dirname(targetPath);\n  await ensureDir(dirPath);\n  const tempPath = path.join(\n    dirPath,\n    `.${path.basename(targetPath)}.${process.pid}.${Date.now()}.${crypto.randomBytes(4).toString(\"hex\")}.tmp`,\n  );\n  await fs.writeFile(tempPath, contents, \"utf8\");\n  try {\n    await fs.rename(tempPath, targetPath);\n  } catch (error: unknown) {\n    if (isErrno(error, \"EXDEV\")) {\n      try {\n        await fs.copyFile(tempPath, targetPath);\n      } finally {\n        try {\n          await fs.unlink(tempPath);\n        } catch {\n          // Best-effort cleanup only.\n        }\n      }\n      return;\n    }\n    try {\n      await fs.unlink(tempPath);\n    } catch {\n      // Best-effort cleanup only.\n    }\n    throw error;\n  }\n}\n\n/**\n * Append a single newline-terminated line to a file, opened with `O_APPEND`.\n *\n * Concurrency contract: `O_APPEND` makes the seek-to-EOF that precedes each\n * `write(2)` atomic, so independent appenders never overwrite each other's\n * bytes. For the common case the whole `${line}\\n` buffer is handed to the\n * kernel in one `write(2)`, which mainstream filesystems (ext4/xfs/apfs) commit\n * atomically under the inode lock — concurrent multi-process appends of small\n * records (e.g. the telemetry and OTLP-span queues) therefore stay\n * line-coherent without an external lock.\n *\n * The guarantee weakens only for a single record large enough that the OS\n * splits it across multiple `write(2)` calls (multi-KiB lines), where another\n * process's append could interleave between fragments. History JSONL — the only\n * caller that can produce large lines — is always written while the per-item\n * store lock is held (see core/store/item-store.ts), so those appends are\n * serialized regardless. Callers writing large records concurrently from\n * multiple processes must hold an equivalent lock.\n */\nexport async function appendLineAtomic(targetPath: string, line: string): Promise<void> {\n  const dirPath = path.dirname(targetPath);\n  await ensureDir(dirPath);\n  const handle = await fs.open(targetPath, \"a\");\n  try {\n    await handle.writeFile(`${line}\\n`, \"utf8\");\n  } finally {\n    await handle.close();\n  }\n}\n\n/**\n * Implements remove file if exists for the public runtime surface of this module.\n */\nexport async function removeFileIfExists(targetPath: string): Promise<void> {\n  try {\n    await fs.unlink(targetPath);\n  } catch (error: unknown) {\n    if (!isErrno(error, \"ENOENT\")) {\n      throw error;\n    }\n  }\n}\n\nfunction isErrno(error: unknown, code: string): boolean {\n  return typeof error === \"object\" && error !== null && \"code\" in error && (error as { code?: string }).code === code;\n}\n"],"names":[],"mappings":"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","debugId":"4ddafbee-315f-5aa0-b08f-d4d7a82cfe8d"}
+{"version":3,"file":"fs-utils.js","sources":["core/fs/fs-utils.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/fs/fs-utils\n *\n * Provides filesystem helpers for Fs Utils.\n */\nimport * as fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport crypto from \"node:crypto\";\n\nconst WINDOWS_RENAME_RETRY_DELAYS_MS = [10, 25, 50, 100];\n\n/**\n * Implements ensure dir for the public runtime surface of this module.\n */\nexport async function ensureDir(dirPath: string): Promise<void> {\n  await fs.mkdir(dirPath, { recursive: true });\n}\n\n/**\n * Implements path exists for the public runtime surface of this module.\n */\nexport async function pathExists(targetPath: string): Promise<boolean> {\n  try {\n    await fs.access(targetPath);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Implements read file if exists for the public runtime surface of this module.\n */\nexport async function readFileIfExists(targetPath: string): Promise<string | null> {\n  try {\n    return await fs.readFile(targetPath, \"utf8\");\n  } catch (error: unknown) {\n    if (isErrno(error, \"ENOENT\")) {\n      return null;\n    }\n    throw error;\n  }\n}\n\n/**\n * Implements write file atomic for the public runtime surface of this module.\n */\nexport async function writeFileAtomic(targetPath: string, contents: string): Promise<void> {\n  const dirPath = path.dirname(targetPath);\n  await ensureDir(dirPath);\n  const tempPath = path.join(\n    dirPath,\n    `.${path.basename(targetPath)}.${process.pid}.${Date.now()}.${crypto.randomBytes(4).toString(\"hex\")}.tmp`,\n  );\n  await fs.writeFile(tempPath, contents, \"utf8\");\n  try {\n    await fs.rename(tempPath, targetPath);\n  } catch (error: unknown) {\n    if (\n      process.platform === \"win32\" &&\n      (isErrno(error, \"EPERM\") || isErrno(error, \"EBUSY\"))\n    ) {\n      let lastError = error;\n      for (const delayMs of WINDOWS_RENAME_RETRY_DELAYS_MS) {\n        await new Promise<void>((resolve) => setTimeout(resolve, delayMs));\n        try {\n          await fs.rename(tempPath, targetPath);\n          return;\n        } catch (retryError: unknown) {\n          lastError = retryError;\n          if (!isErrno(retryError, \"EPERM\") && !isErrno(retryError, \"EBUSY\")) {\n            break;\n          }\n        }\n      }\n      try {\n        await fs.unlink(tempPath);\n      } catch {\n        // Best-effort cleanup only.\n      }\n      throw lastError;\n    }\n    if (isErrno(error, \"EXDEV\")) {\n      try {\n        await fs.copyFile(tempPath, targetPath);\n      } finally {\n        try {\n          await fs.unlink(tempPath);\n        } catch {\n          // Best-effort cleanup only.\n        }\n      }\n      return;\n    }\n    try {\n      await fs.unlink(tempPath);\n    } catch {\n      // Best-effort cleanup only.\n    }\n    throw error;\n  }\n}\n\n/**\n * Append a single newline-terminated line to a file, opened with `O_APPEND`.\n *\n * Concurrency contract: `O_APPEND` makes the seek-to-EOF that precedes each\n * `write(2)` atomic, so independent appenders never overwrite each other's\n * bytes. For the common case the whole `${line}\\n` buffer is handed to the\n * kernel in one `write(2)`, which mainstream filesystems (ext4/xfs/apfs) commit\n * atomically under the inode lock — concurrent multi-process appends of small\n * records (e.g. the telemetry and OTLP-span queues) therefore stay\n * line-coherent without an external lock.\n *\n * The guarantee weakens only for a single record large enough that the OS\n * splits it across multiple `write(2)` calls (multi-KiB lines), where another\n * process's append could interleave between fragments. History JSONL — the only\n * caller that can produce large lines — is always written while the per-item\n * store lock is held (see core/store/item-store.ts), so those appends are\n * serialized regardless. Callers writing large records concurrently from\n * multiple processes must hold an equivalent lock.\n */\nexport async function appendLineAtomic(targetPath: string, line: string): Promise<void> {\n  const dirPath = path.dirname(targetPath);\n  await ensureDir(dirPath);\n  const handle = await fs.open(targetPath, \"a\");\n  try {\n    await handle.writeFile(`${line}\\n`, \"utf8\");\n  } finally {\n    await handle.close();\n  }\n}\n\n/**\n * Implements remove file if exists for the public runtime surface of this module.\n */\nexport async function removeFileIfExists(targetPath: string): Promise<void> {\n  try {\n    await fs.unlink(targetPath);\n  } catch (error: unknown) {\n    if (!isErrno(error, \"ENOENT\")) {\n      throw error;\n    }\n  }\n}\n\nfunction isErrno(error: unknown, code: string): boolean {\n  return typeof error === \"object\" && error !== null && \"code\" in error && (error as { code?: string }).code === code;\n}\n"],"names":[],"mappings":"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","debugId":"4ba3885b-85fc-5941-bf52-6c70b2bb5c2a"}

package/dist/core/item/actionability.d.ts

@@ -0,0 +1,57 @@
+import type { RuntimeStatusRegistry } from "../schema/runtime-schema.js";
+import type { ItemFrontMatter, ItemStatus } from "../../types/index.js";
+/**
+ * Collects the blocker item ids declared by an item: the legacy scalar
+ * `blocked_by` field plus every `blocked_by` dependency edge. Ids are trimmed,
+ * de-duplicated, and returned in stable lexicographic order. This is the single
+ * source of truth for "what must close before this item can proceed", shared by
+ * `pm next` readiness classification and the close-time auto-unblock sweep.
+ */
+export declare function collectBlockedByIds(item: Pick<ItemFrontMatter, "blocked_by" | "dependencies">): string[];
+/** A blocker reference resolved against the corpus and annotated with its state. */
+export interface ResolvedBlocker {
+    id: string;
+    title: string | null;
+    status: ItemStatus | null;
+    /** True when the blocker no longer gates work: its id is unknown or terminal. */
+    resolved: boolean;
+}
+/**
+ * Resolves an item's declared blockers against a corpus index, annotating each
+ * with the blocker's title/status and whether it still gates work. A blocker is
+ * treated as resolved when its id is unknown (a dangling reference cannot be
+ * waited on) or the referenced item is terminal — mirroring the close-time
+ * auto-unblock rule, which only clears a dependent once its blocker is terminal.
+ */
+export declare function resolveItemBlockers(item: Pick<ItemFrontMatter, "blocked_by" | "dependencies">, itemsById: Map<string, ItemFrontMatter>, statusRegistry: RuntimeStatusRegistry): ResolvedBlocker[];
+/** A classified actionable item plus the context an agent needs to act on it. */
+export interface ActionableEntry {
+    item: ItemFrontMatter;
+    /** Blockers that still gate the item (resolved blockers are filtered out). */
+    open_blockers: ResolvedBlocker[];
+    /** Ids of non-terminal items whose `blocked_by` points at this item. */
+    unblocks: string[];
+}
+/** Result of partitioning a candidate set into ready vs blocked leaf work. */
+export interface ActionabilityReport {
+    /** Active leaves with no open blockers — ready to work on now. */
+    ready: ActionableEntry[];
+    /** Active leaves with at least one open blocker — waiting to become ready. */
+    blocked: ActionableEntry[];
+    /** Active candidates considered before the leaf/blocker split. */
+    active_count: number;
+    /** Active candidates skipped because they still have open descendants. */
+    container_count: number;
+}
+/**
+ * Partitions a candidate set into ready vs blocked leaf work using the corpus to
+ * resolve blockers, descendants, and downstream dependents.
+ *
+ * An item qualifies when its status is active. Containers — items with at least
+ * one non-terminal descendant — are excluded from both lists because the real
+ * work is the leaf beneath them. A leaf with no open blockers is READY; a leaf
+ * with one or more open blockers is BLOCKED, annotated with the unresolved
+ * blockers and the non-terminal items it would unblock. Returned lists preserve
+ * the candidate order so the caller can apply its own ranking.
+ */
+export declare function computeActionabilityReport(candidates: ItemFrontMatter[], corpus: ItemFrontMatter[], statusRegistry: RuntimeStatusRegistry): ActionabilityReport;

package/dist/core/item/actionability.js

@@ -0,0 +1,178 @@
+/**
+ * @module core/item/actionability
+ *
+ * Pure, dependency-aware actionability model shared by the `pm next` command and
+ * the close-time auto-unblock sweep. It answers "what is ready to work on now?"
+ * without any I/O: given a candidate set and the surrounding corpus it partitions
+ * work into READY items (active, leaf, no open blockers) and BLOCKED items (active
+ * leaf waiting on at least one open blocker). Keeping the logic here — rather than
+ * inside a CLI command — makes it trivially testable and reusable, and gives the
+ * `blocked_by` resolution a single source of truth.
+ */
+
+!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]="b38f538c-6772-5336-bea4-8c72447c236f")}catch(e){}}();
+import { isTerminalStatus, normalizeStatusForRegistry } from "./status.js";
+/** Dependency kind that marks "this item is blocked by the referenced item". */
+const BLOCKED_BY_DEPENDENCY_KIND = "blocked_by";
+/**
+ * Normalizes an item id / parent reference / blocker id to its canonical
+ * comparison key (trimmed, lowercased). pm ids are canonically lowercase, but
+ * resolving case-insensitively — as {@link collectSubtreeIds} does — keeps a
+ * hand-edited mixed-case reference from being silently treated as missing.
+ */
+function normalizeItemId(id) {
+    return id.trim().toLowerCase();
+}
+/**
+ * Collects the blocker item ids declared by an item: the legacy scalar
+ * `blocked_by` field plus every `blocked_by` dependency edge. Ids are trimmed,
+ * de-duplicated, and returned in stable lexicographic order. This is the single
+ * source of truth for "what must close before this item can proceed", shared by
+ * `pm next` readiness classification and the close-time auto-unblock sweep.
+ */
+export function collectBlockedByIds(item) {
+    const ids = new Set();
+    const scalar = typeof item.blocked_by === "string" ? item.blocked_by.trim() : "";
+    if (scalar.length > 0) {
+        ids.add(scalar);
+    }
+    for (const dependency of item.dependencies ?? []) {
+        if (dependency.kind === BLOCKED_BY_DEPENDENCY_KIND &&
+            typeof dependency.id === "string" &&
+            dependency.id.trim().length > 0) {
+            ids.add(dependency.id.trim());
+        }
+    }
+    return [...ids].sort((left, right) => left.localeCompare(right));
+}
+/**
+ * Resolves an item's declared blockers against a corpus index, annotating each
+ * with the blocker's title/status and whether it still gates work. A blocker is
+ * treated as resolved when its id is unknown (a dangling reference cannot be
+ * waited on) or the referenced item is terminal — mirroring the close-time
+ * auto-unblock rule, which only clears a dependent once its blocker is terminal.
+ */
+export function resolveItemBlockers(item, itemsById, statusRegistry) {
+    return collectBlockedByIds(item).map((id) => {
+        const blocker = itemsById.get(normalizeItemId(id));
+        if (!blocker) {
+            return { id, title: null, status: null, resolved: true };
+        }
+        return {
+            id,
+            title: blocker.title,
+            status: blocker.status,
+            resolved: isTerminalStatus(blocker.status, statusRegistry),
+        };
+    });
+}
+/**
+ * Resolves the registry's active status set, falling back to just the canonical
+ * open status when a custom schema declares none — the same safety net `pm
+ * context` applies so the report never misclassifies every item as inactive.
+ */
+function resolveActiveStatusSet(statusRegistry) {
+    /* c8 ignore start -- fallback applies only to custom schemas that intentionally define zero active statuses */
+    return statusRegistry.active_statuses.size > 0 ? statusRegistry.active_statuses : new Set([statusRegistry.open_status]);
+    /* c8 ignore stop */
+}
+/**
+ * Returns whether an item has any non-terminal descendant by walking the
+ * parent→children index depth-first, short-circuiting on the first one found.
+ * Such an item is a container (its real work lives in its children), so `pm next`
+ * skips it and recommends a leaf instead. Cycle-safe via a visited set.
+ */
+function hasOpenDescendant(rootId, childrenByParent, statusRegistry) {
+    const stack = [normalizeItemId(rootId)];
+    const visited = new Set();
+    while (stack.length > 0) {
+        const current = stack.pop();
+        /* c8 ignore start -- defensive cycle-guard: unreachable for active roots (an open child returns before any node is revisited, and single-parent graphs cannot form a root-reachable cycle excluding the root), retained for safety */
+        if (visited.has(current))
+            continue;
+        /* c8 ignore stop */
+        visited.add(current);
+        for (const child of childrenByParent.get(current) ?? []) {
+            if (!isTerminalStatus(child.status, statusRegistry)) {
+                return true;
+            }
+            stack.push(normalizeItemId(child.id));
+        }
+    }
+    return false;
+}
+/**
+ * Indexes the corpus into a by-id map, a parent→children map, and a reverse
+ * blocker map (blocker id → ids of items it blocks). Built once per report so
+ * blocker resolution, descendant counting, and downstream "unblocks" lookups
+ * share the same passes over the corpus.
+ */
+function indexCorpus(corpus) {
+    const itemsById = new Map();
+    const childrenByParent = new Map();
+    const blockedByReverse = new Map();
+    for (const item of corpus) {
+        // Index keys are normalized (lowercased) for case-insensitive resolution;
+        // stored values keep the item's original-case id for display.
+        itemsById.set(normalizeItemId(item.id), item);
+        const parent = typeof item.parent === "string" ? item.parent.trim() : "";
+        if (parent.length > 0) {
+            const parentKey = normalizeItemId(parent);
+            const siblings = childrenByParent.get(parentKey) ?? [];
+            siblings.push(item);
+            childrenByParent.set(parentKey, siblings);
+        }
+        for (const blockerId of collectBlockedByIds(item)) {
+            const blockerKey = normalizeItemId(blockerId);
+            const dependents = blockedByReverse.get(blockerKey) ?? [];
+            dependents.push(item.id);
+            blockedByReverse.set(blockerKey, dependents);
+        }
+    }
+    return { itemsById, childrenByParent, blockedByReverse };
+}
+/**
+ * Partitions a candidate set into ready vs blocked leaf work using the corpus to
+ * resolve blockers, descendants, and downstream dependents.
+ *
+ * An item qualifies when its status is active. Containers — items with at least
+ * one non-terminal descendant — are excluded from both lists because the real
+ * work is the leaf beneath them. A leaf with no open blockers is READY; a leaf
+ * with one or more open blockers is BLOCKED, annotated with the unresolved
+ * blockers and the non-terminal items it would unblock. Returned lists preserve
+ * the candidate order so the caller can apply its own ranking.
+ */
+export function computeActionabilityReport(candidates, corpus, statusRegistry) {
+    const { itemsById, childrenByParent, blockedByReverse } = indexCorpus(corpus);
+    const activeStatuses = resolveActiveStatusSet(statusRegistry);
+    // Ids of corpus items still in flight, used to keep only the non-terminal
+    // dependents in each item's downstream "unblocks" list.
+    const nonTerminalIds = new Set(corpus.filter((entry) => !isTerminalStatus(entry.status, statusRegistry)).map((entry) => normalizeItemId(entry.id)));
+    const ready = [];
+    const blocked = [];
+    let activeCount = 0;
+    let containerCount = 0;
+    for (const item of candidates) {
+        if (!activeStatuses.has(normalizeStatusForRegistry(item.status, statusRegistry)))
+            continue;
+        activeCount += 1;
+        if (hasOpenDescendant(item.id, childrenByParent, statusRegistry)) {
+            containerCount += 1;
+            continue;
+        }
+        const openBlockers = resolveItemBlockers(item, itemsById, statusRegistry).filter((blocker) => !blocker.resolved);
+        const unblocks = (blockedByReverse.get(normalizeItemId(item.id)) ?? [])
+            .filter((dependentId) => nonTerminalIds.has(normalizeItemId(dependentId)))
+            .sort((left, right) => left.localeCompare(right));
+        const entry = { item, open_blockers: openBlockers, unblocks };
+        if (openBlockers.length === 0) {
+            ready.push(entry);
+        }
+        else {
+            blocked.push(entry);
+        }
+    }
+    return { ready, blocked, active_count: activeCount, container_count: containerCount };
+}
+//# sourceMappingURL=actionability.js.map
+//# debugId=b38f538c-6772-5336-bea4-8c72447c236f

package/dist/core/item/actionability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actionability.js","sources":["core/item/actionability.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/item/actionability\n *\n * Pure, dependency-aware actionability model shared by the `pm next` command and\n * the close-time auto-unblock sweep. It answers \"what is ready to work on now?\"\n * without any I/O: given a candidate set and the surrounding corpus it partitions\n * work into READY items (active, leaf, no open blockers) and BLOCKED items (active\n * leaf waiting on at least one open blocker). Keeping the logic here — rather than\n * inside a CLI command — makes it trivially testable and reusable, and gives the\n * `blocked_by` resolution a single source of truth.\n */\nimport { isTerminalStatus, normalizeStatusForRegistry } from \"./status.js\";\nimport type { RuntimeStatusRegistry } from \"../schema/runtime-schema.js\";\nimport type { ItemFrontMatter, ItemStatus } from \"../../types/index.js\";\n\n/** Dependency kind that marks \"this item is blocked by the referenced item\". */\nconst BLOCKED_BY_DEPENDENCY_KIND = \"blocked_by\";\n\n/**\n * Normalizes an item id / parent reference / blocker id to its canonical\n * comparison key (trimmed, lowercased). pm ids are canonically lowercase, but\n * resolving case-insensitively — as {@link collectSubtreeIds} does — keeps a\n * hand-edited mixed-case reference from being silently treated as missing.\n */\nfunction normalizeItemId(id: string): string {\n  return id.trim().toLowerCase();\n}\n\n/**\n * Collects the blocker item ids declared by an item: the legacy scalar\n * `blocked_by` field plus every `blocked_by` dependency edge. Ids are trimmed,\n * de-duplicated, and returned in stable lexicographic order. This is the single\n * source of truth for \"what must close before this item can proceed\", shared by\n * `pm next` readiness classification and the close-time auto-unblock sweep.\n */\nexport function collectBlockedByIds(item: Pick<ItemFrontMatter, \"blocked_by\" | \"dependencies\">): string[] {\n  const ids = new Set<string>();\n  const scalar = typeof item.blocked_by === \"string\" ? item.blocked_by.trim() : \"\";\n  if (scalar.length > 0) {\n    ids.add(scalar);\n  }\n  for (const dependency of item.dependencies ?? []) {\n    if (\n      dependency.kind === BLOCKED_BY_DEPENDENCY_KIND &&\n      typeof dependency.id === \"string\" &&\n      dependency.id.trim().length > 0\n    ) {\n      ids.add(dependency.id.trim());\n    }\n  }\n  return [...ids].sort((left, right) => left.localeCompare(right));\n}\n\n/** A blocker reference resolved against the corpus and annotated with its state. */\nexport interface ResolvedBlocker {\n  id: string;\n  title: string | null;\n  status: ItemStatus | null;\n  /** True when the blocker no longer gates work: its id is unknown or terminal. */\n  resolved: boolean;\n}\n\n/**\n * Resolves an item's declared blockers against a corpus index, annotating each\n * with the blocker's title/status and whether it still gates work. A blocker is\n * treated as resolved when its id is unknown (a dangling reference cannot be\n * waited on) or the referenced item is terminal — mirroring the close-time\n * auto-unblock rule, which only clears a dependent once its blocker is terminal.\n */\nexport function resolveItemBlockers(\n  item: Pick<ItemFrontMatter, \"blocked_by\" | \"dependencies\">,\n  itemsById: Map<string, ItemFrontMatter>,\n  statusRegistry: RuntimeStatusRegistry,\n): ResolvedBlocker[] {\n  return collectBlockedByIds(item).map((id) => {\n    const blocker = itemsById.get(normalizeItemId(id));\n    if (!blocker) {\n      return { id, title: null, status: null, resolved: true };\n    }\n    return {\n      id,\n      title: blocker.title,\n      status: blocker.status,\n      resolved: isTerminalStatus(blocker.status, statusRegistry),\n    };\n  });\n}\n\n/** A classified actionable item plus the context an agent needs to act on it. */\nexport interface ActionableEntry {\n  item: ItemFrontMatter;\n  /** Blockers that still gate the item (resolved blockers are filtered out). */\n  open_blockers: ResolvedBlocker[];\n  /** Ids of non-terminal items whose `blocked_by` points at this item. */\n  unblocks: string[];\n}\n\n/** Result of partitioning a candidate set into ready vs blocked leaf work. */\nexport interface ActionabilityReport {\n  /** Active leaves with no open blockers — ready to work on now. */\n  ready: ActionableEntry[];\n  /** Active leaves with at least one open blocker — waiting to become ready. */\n  blocked: ActionableEntry[];\n  /** Active candidates considered before the leaf/blocker split. */\n  active_count: number;\n  /** Active candidates skipped because they still have open descendants. */\n  container_count: number;\n}\n\n/**\n * Resolves the registry's active status set, falling back to just the canonical\n * open status when a custom schema declares none — the same safety net `pm\n * context` applies so the report never misclassifies every item as inactive.\n */\nfunction resolveActiveStatusSet(statusRegistry: RuntimeStatusRegistry): Set<string> {\n  /* c8 ignore start -- fallback applies only to custom schemas that intentionally define zero active statuses */\n  return statusRegistry.active_statuses.size > 0 ? statusRegistry.active_statuses : new Set<string>([statusRegistry.open_status]);\n  /* c8 ignore stop */\n}\n\n/**\n * Returns whether an item has any non-terminal descendant by walking the\n * parent→children index depth-first, short-circuiting on the first one found.\n * Such an item is a container (its real work lives in its children), so `pm next`\n * skips it and recommends a leaf instead. Cycle-safe via a visited set.\n */\nfunction hasOpenDescendant(\n  rootId: string,\n  childrenByParent: Map<string, ItemFrontMatter[]>,\n  statusRegistry: RuntimeStatusRegistry,\n): boolean {\n  const stack = [normalizeItemId(rootId)];\n  const visited = new Set<string>();\n  while (stack.length > 0) {\n    const current = stack.pop() as string;\n    /* c8 ignore start -- defensive cycle-guard: unreachable for active roots (an open child returns before any node is revisited, and single-parent graphs cannot form a root-reachable cycle excluding the root), retained for safety */\n    if (visited.has(current)) continue;\n    /* c8 ignore stop */\n    visited.add(current);\n    for (const child of childrenByParent.get(current) ?? []) {\n      if (!isTerminalStatus(child.status, statusRegistry)) {\n        return true;\n      }\n      stack.push(normalizeItemId(child.id));\n    }\n  }\n  return false;\n}\n\n/**\n * Indexes the corpus into a by-id map, a parent→children map, and a reverse\n * blocker map (blocker id → ids of items it blocks). Built once per report so\n * blocker resolution, descendant counting, and downstream \"unblocks\" lookups\n * share the same passes over the corpus.\n */\nfunction indexCorpus(corpus: ItemFrontMatter[]): {\n  itemsById: Map<string, ItemFrontMatter>;\n  childrenByParent: Map<string, ItemFrontMatter[]>;\n  blockedByReverse: Map<string, string[]>;\n} {\n  const itemsById = new Map<string, ItemFrontMatter>();\n  const childrenByParent = new Map<string, ItemFrontMatter[]>();\n  const blockedByReverse = new Map<string, string[]>();\n  for (const item of corpus) {\n    // Index keys are normalized (lowercased) for case-insensitive resolution;\n    // stored values keep the item's original-case id for display.\n    itemsById.set(normalizeItemId(item.id), item);\n    const parent = typeof item.parent === \"string\" ? item.parent.trim() : \"\";\n    if (parent.length > 0) {\n      const parentKey = normalizeItemId(parent);\n      const siblings = childrenByParent.get(parentKey) ?? [];\n      siblings.push(item);\n      childrenByParent.set(parentKey, siblings);\n    }\n    for (const blockerId of collectBlockedByIds(item)) {\n      const blockerKey = normalizeItemId(blockerId);\n      const dependents = blockedByReverse.get(blockerKey) ?? [];\n      dependents.push(item.id);\n      blockedByReverse.set(blockerKey, dependents);\n    }\n  }\n  return { itemsById, childrenByParent, blockedByReverse };\n}\n\n/**\n * Partitions a candidate set into ready vs blocked leaf work using the corpus to\n * resolve blockers, descendants, and downstream dependents.\n *\n * An item qualifies when its status is active. Containers — items with at least\n * one non-terminal descendant — are excluded from both lists because the real\n * work is the leaf beneath them. A leaf with no open blockers is READY; a leaf\n * with one or more open blockers is BLOCKED, annotated with the unresolved\n * blockers and the non-terminal items it would unblock. Returned lists preserve\n * the candidate order so the caller can apply its own ranking.\n */\nexport function computeActionabilityReport(\n  candidates: ItemFrontMatter[],\n  corpus: ItemFrontMatter[],\n  statusRegistry: RuntimeStatusRegistry,\n): ActionabilityReport {\n  const { itemsById, childrenByParent, blockedByReverse } = indexCorpus(corpus);\n  const activeStatuses = resolveActiveStatusSet(statusRegistry);\n  // Ids of corpus items still in flight, used to keep only the non-terminal\n  // dependents in each item's downstream \"unblocks\" list.\n  const nonTerminalIds = new Set(\n    corpus.filter((entry) => !isTerminalStatus(entry.status, statusRegistry)).map((entry) => normalizeItemId(entry.id)),\n  );\n  const ready: ActionableEntry[] = [];\n  const blocked: ActionableEntry[] = [];\n  let activeCount = 0;\n  let containerCount = 0;\n  for (const item of candidates) {\n    if (!activeStatuses.has(normalizeStatusForRegistry(item.status, statusRegistry))) continue;\n    activeCount += 1;\n    if (hasOpenDescendant(item.id, childrenByParent, statusRegistry)) {\n      containerCount += 1;\n      continue;\n    }\n    const openBlockers = resolveItemBlockers(item, itemsById, statusRegistry).filter((blocker) => !blocker.resolved);\n    const unblocks = (blockedByReverse.get(normalizeItemId(item.id)) ?? [])\n      .filter((dependentId) => nonTerminalIds.has(normalizeItemId(dependentId)))\n      .sort((left, right) => left.localeCompare(right));\n    const entry: ActionableEntry = { item, open_blockers: openBlockers, unblocks };\n    if (openBlockers.length === 0) {\n      ready.push(entry);\n    } else {\n      blocked.push(entry);\n    }\n  }\n  return { ready, blocked, active_count: activeCount, container_count: containerCount };\n}\n"],"names":[],"mappings":"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","debugId":"b38f538c-6772-5336-bea4-8c72447c236f"}