@unbrained/pm-cli 2026.6.13 → 2026.6.17

package/dist/core/io/body-file.d.ts

@@ -0,0 +1,14 @@
+/**
+ * GH-214: shared resolver for the `--body-file <path>` input convenience on
+ * `pm create` and `pm update`. It loads a long markdown body from a file so
+ * agents do not have to escape multi-paragraph content (code blocks, tables)
+ * into a single inline `--body` string or issue a second `pm append` call.
+ *
+ * This is a CLI-only input alias that maps onto the existing `body` field, so
+ * it deliberately does NOT flow through the MCP/contract field surface (a file
+ * path is meaningless over MCP, mirroring `pm history --diff`). The file read is
+ * injectable so the pure resolution logic stays fully unit-coverable without
+ * touching disk.
+ */
+export type BodyFileReader = (path: string) => Promise<string>;
+export declare function resolveBodyFileContent(bodyFile: string, inlineBody: string | undefined, readFileImpl?: BodyFileReader): Promise<string>;

package/dist/core/io/body-file.js

@@ -0,0 +1,47 @@
+
+!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]="0f24c814-7ca3-557a-90fa-187e399521e9")}catch(e){}}();
+import { readFile } from "node:fs/promises";
+import { EXIT_CODE } from "../shared/constants.js";
+import { PmCliError } from "../shared/errors.js";
+const defaultBodyFileReader = (path) => readFile(path, "utf8");
+export async function resolveBodyFileContent(bodyFile, inlineBody, readFileImpl = defaultBodyFileReader) {
+    // Mutual exclusion: --body and --body-file both define the body, so accepting
+    // both silently would hide which one wins. Fail with an actionable message.
+    if (inlineBody !== undefined) {
+        throw new PmCliError("--body and --body-file are mutually exclusive; provide the body inline with --body or from a file with --body-file, not both.", EXIT_CODE.USAGE, {
+            code: "body_file_conflicts_with_body",
+            required: "Choose exactly one body source.",
+            why: "Both --body and --body-file set the item body; allowing both would make the effective body ambiguous.",
+            nextSteps: ["Re-run with only --body <text> or only --body-file <path>."],
+        });
+    }
+    const path = bodyFile.trim();
+    if (path.length === 0) {
+        throw new PmCliError("--body-file requires a file path.", EXIT_CODE.USAGE, {
+            code: "body_file_missing_path",
+            required: "Pass a readable file path: --body-file <path>.",
+            why: "An empty --body-file value has no file to read the body from.",
+        });
+    }
+    try {
+        return await readFileImpl(path);
+    }
+    catch (error) {
+        // Preserve the underlying errno (ENOENT/EACCES/EISDIR/...) so the failure
+        // is debuggable, and tailor the directory case (a real footgun: pointing
+        // --body-file at a folder) to an exact message instead of a generic one.
+        const errno = error?.code;
+        const isDirectory = errno === "EISDIR";
+        const detail = errno ? ` (${errno})` : "";
+        throw new PmCliError(isDirectory
+            ? `--body-file "${path}" is a directory, not a file. Point it at a readable file.`
+            : `--body-file could not read "${path}"${detail}. Check that the file exists and is readable.`, EXIT_CODE.NOT_FOUND, {
+            code: "body_file_unreadable",
+            required: "Point --body-file at an existing, readable file.",
+            why: `The body content is loaded from the file at the supplied path, so an unreadable path cannot produce a body${errno ? ` (underlying error: ${errno})` : ""}.`,
+            nextSteps: [`Verify the path: ls -l "${path}"`, "Or pass the body inline with --body <text>."],
+        });
+    }
+}
+//# sourceMappingURL=body-file.js.map
+//# debugId=0f24c814-7ca3-557a-90fa-187e399521e9

package/dist/core/io/body-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"body-file.js","sources":["core/io/body-file.ts"],"sourceRoot":"/","sourcesContent":["import { readFile } from \"node:fs/promises\";\n\nimport { EXIT_CODE } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\n\n/**\n * GH-214: shared resolver for the `--body-file <path>` input convenience on\n * `pm create` and `pm update`. It loads a long markdown body from a file so\n * agents do not have to escape multi-paragraph content (code blocks, tables)\n * into a single inline `--body` string or issue a second `pm append` call.\n *\n * This is a CLI-only input alias that maps onto the existing `body` field, so\n * it deliberately does NOT flow through the MCP/contract field surface (a file\n * path is meaningless over MCP, mirroring `pm history --diff`). The file read is\n * injectable so the pure resolution logic stays fully unit-coverable without\n * touching disk.\n */\nexport type BodyFileReader = (path: string) => Promise<string>;\n\nconst defaultBodyFileReader: BodyFileReader = (path) => readFile(path, \"utf8\");\n\nexport async function resolveBodyFileContent(\n  bodyFile: string,\n  inlineBody: string | undefined,\n  readFileImpl: BodyFileReader = defaultBodyFileReader,\n): Promise<string> {\n  // Mutual exclusion: --body and --body-file both define the body, so accepting\n  // both silently would hide which one wins. Fail with an actionable message.\n  if (inlineBody !== undefined) {\n    throw new PmCliError(\n      \"--body and --body-file are mutually exclusive; provide the body inline with --body or from a file with --body-file, not both.\",\n      EXIT_CODE.USAGE,\n      {\n        code: \"body_file_conflicts_with_body\",\n        required: \"Choose exactly one body source.\",\n        why: \"Both --body and --body-file set the item body; allowing both would make the effective body ambiguous.\",\n        nextSteps: [\"Re-run with only --body <text> or only --body-file <path>.\"],\n      },\n    );\n  }\n  const path = bodyFile.trim();\n  if (path.length === 0) {\n    throw new PmCliError(\"--body-file requires a file path.\", EXIT_CODE.USAGE, {\n      code: \"body_file_missing_path\",\n      required: \"Pass a readable file path: --body-file <path>.\",\n      why: \"An empty --body-file value has no file to read the body from.\",\n    });\n  }\n  try {\n    return await readFileImpl(path);\n  } catch (error: unknown) {\n    // Preserve the underlying errno (ENOENT/EACCES/EISDIR/...) so the failure\n    // is debuggable, and tailor the directory case (a real footgun: pointing\n    // --body-file at a folder) to an exact message instead of a generic one.\n    const errno = (error as NodeJS.ErrnoException | undefined)?.code;\n    const isDirectory = errno === \"EISDIR\";\n    const detail = errno ? ` (${errno})` : \"\";\n    throw new PmCliError(\n      isDirectory\n        ? `--body-file \"${path}\" is a directory, not a file. Point it at a readable file.`\n        : `--body-file could not read \"${path}\"${detail}. Check that the file exists and is readable.`,\n      EXIT_CODE.NOT_FOUND,\n      {\n        code: \"body_file_unreadable\",\n        required: \"Point --body-file at an existing, readable file.\",\n        why: `The body content is loaded from the file at the supplied path, so an unreadable path cannot produce a body${errno ? ` (underlying error: ${errno})` : \"\"}.`,\n        nextSteps: [`Verify the path: ls -l \"${path}\"`, \"Or pass the body inline with --body <text>.\"],\n      },\n    );\n  }\n}\n"],"names":[],"mappings":";;AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAgBjD,MAAM,qBAAqB,GAAmB,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAE/E,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,QAAgB,EAChB,UAA8B,EAC9B,eAA+B,qBAAqB;IAEpD,8EAA8E;IAC9E,4EAA4E;IAC5E,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,UAAU,CAClB,+HAA+H,EAC/H,SAAS,CAAC,KAAK,EACf;YACE,IAAI,EAAE,+BAA+B;YACrC,QAAQ,EAAE,iCAAiC;YAC3C,GAAG,EAAE,uGAAuG;YAC5G,SAAS,EAAE,CAAC,4DAA4D,CAAC;SAC1E,CACF,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,UAAU,CAAC,mCAAmC,EAAE,SAAS,CAAC,KAAK,EAAE;YACzE,IAAI,EAAE,wBAAwB;YAC9B,QAAQ,EAAE,gDAAgD;YAC1D,GAAG,EAAE,+DAA+D;SACrE,CAAC,CAAC;IACL,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,0EAA0E;QAC1E,yEAAyE;QACzE,yEAAyE;QACzE,MAAM,KAAK,GAAI,KAA2C,EAAE,IAAI,CAAC;QACjE,MAAM,WAAW,GAAG,KAAK,KAAK,QAAQ,CAAC;QACvC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,UAAU,CAClB,WAAW;YACT,CAAC,CAAC,gBAAgB,IAAI,4DAA4D;YAClF,CAAC,CAAC,+BAA+B,IAAI,IAAI,MAAM,+CAA+C,EAChG,SAAS,CAAC,SAAS,EACnB;YACE,IAAI,EAAE,sBAAsB;YAC5B,QAAQ,EAAE,kDAAkD;YAC5D,GAAG,EAAE,6GAA6G,KAAK,CAAC,CAAC,CAAC,uBAAuB,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG;YACjK,SAAS,EAAE,CAAC,2BAA2B,IAAI,GAAG,EAAE,6CAA6C,CAAC;SAC/F,CACF,CAAC;IACJ,CAAC;AACH,CAAC","debugId":"0f24c814-7ca3-557a-90fa-187e399521e9"}

package/dist/core/item/item-format.d.ts

@@ -1,11 +1,38 @@
-import type { ItemDocument, ItemMetadata, RuntimeSchemaSettings } from "../../types/index.js";
+import type { ItemDocument, ItemMetadata, RuntimeSchemaSettings, ItemTestRunSummary, LinkedTest, PlanDecision, PlanDiscovery, PlanStep, PlanStepDoc, PlanStepFile, PlanStepLink, PlanValidationCheck } from "../../types/index.js";
 import type { ItemFormat } from "../../types/index.js";
+import { type RuntimeFieldRegistry, type RuntimeStatusRegistry } from "../schema/runtime-schema.js";
+declare function firstNonZeroComparison(comparisons: readonly number[]): number;
+interface RuntimeSchemaValidationContext {
+    statusRegistry?: RuntimeStatusRegistry;
+    fieldRegistry?: RuntimeFieldRegistry;
+    unknownFieldPolicy: "allow" | "warn" | "reject";
+    extensionFieldNames: ReadonlySet<string>;
+    onWarning?: (warning: string) => void;
+}
 export interface ItemDocumentFormatOptions {
     format?: ItemFormat;
     schema?: RuntimeSchemaSettings;
     extensionFieldNames?: readonly string[];
     onWarning?: (warning: string) => void;
 }
+declare function runtimeFieldRequiredForType(definition: RuntimeFieldRegistry["definitions"][number], typeName: string): boolean;
+declare function buildKnownFrontMatterKeys(runtimeContext: RuntimeSchemaValidationContext): Set<string>;
+declare function normalizeTestRunSummaries(values: ItemTestRunSummary[] | undefined): ItemTestRunSummary[] | undefined;
+declare function sortTests(values: LinkedTest[] | undefined): LinkedTest[] | undefined;
+declare function normalizePlanStepLinks(value: unknown): PlanStepLink[] | undefined;
+declare function normalizePlanStepFiles(value: unknown): PlanStepFile[] | undefined;
+declare function normalizePlanStepTests(value: unknown): {
+    command?: string;
+    path?: string;
+    note?: string;
+}[] | undefined;
+declare function normalizePlanStepDocs(value: unknown): PlanStepDoc[] | undefined;
+declare function normalizePlanSteps(value: unknown): PlanStep[] | undefined;
+declare function normalizePlanDecisions(value: unknown): PlanDecision[] | undefined;
+declare function normalizePlanDiscoveries(value: unknown): PlanDiscovery[] | undefined;
+declare function normalizePlanValidation(value: unknown): PlanValidationCheck[] | undefined;
+declare function normalizeTypeOptions(values: Record<string, string> | undefined): Record<string, string> | undefined;
+declare function normalizeBody(body: string): string;
 export declare function normalizeFrontMatter(frontMatter: ItemMetadata, options?: Pick<ItemDocumentFormatOptions, "schema" | "extensionFieldNames" | "onWarning">): ItemMetadata;
 export declare function splitFrontMatter(content: string): {
     frontMatter: string;
@@ -14,3 +41,21 @@ export declare function splitFrontMatter(content: string): {
 export declare function parseItemDocument(content: string, options?: ItemDocumentFormatOptions): ItemDocument;
 export declare function serializeItemDocument(document: ItemDocument, options?: ItemDocumentFormatOptions): string;
 export declare function canonicalDocument(document: ItemDocument, options?: Pick<ItemDocumentFormatOptions, "schema" | "extensionFieldNames" | "onWarning">): ItemDocument;
+export declare const _testOnlyItemFormat: {
+    buildKnownFrontMatterKeys: typeof buildKnownFrontMatterKeys;
+    firstNonZeroComparison: typeof firstNonZeroComparison;
+    normalizeBody: typeof normalizeBody;
+    normalizePlanDecisions: typeof normalizePlanDecisions;
+    normalizePlanDiscoveries: typeof normalizePlanDiscoveries;
+    normalizePlanStepDocs: typeof normalizePlanStepDocs;
+    normalizePlanStepFiles: typeof normalizePlanStepFiles;
+    normalizePlanStepLinks: typeof normalizePlanStepLinks;
+    normalizePlanSteps: typeof normalizePlanSteps;
+    normalizePlanStepTests: typeof normalizePlanStepTests;
+    normalizePlanValidation: typeof normalizePlanValidation;
+    normalizeTestRunSummaries: typeof normalizeTestRunSummaries;
+    normalizeTypeOptions: typeof normalizeTypeOptions;
+    runtimeFieldRequiredForType: typeof runtimeFieldRequiredForType;
+    sortTests: typeof sortTests;
+};
+export {};

package/dist/core/item/item-format.js

@@ -1,5 +1,5 @@
 
-!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]="ba14fa53-be28-55e9-92fb-d00e33a98480")}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]="5f2983a2-ef36-52b1-892b-f6adaec87de3")}catch(e){}}();
 import { encode as encodeToon } from "@toon-format/toon";
 import { CONFIDENCE_TEXT_VALUES, ISSUE_SEVERITY_VALUES, RECURRENCE_FREQUENCY_VALUES, RECURRENCE_WEEKDAY_VALUES, STATUS_VALUES, weekdayOrderIndex, } from "../../types/index.js";
 import { coerceRuntimeFieldValue } from "../schema/runtime-field-values.js";
@@ -15,6 +15,14 @@ const LINKED_TEST_PM_CONTEXT_MODE_VALUES = new Set(["schema", "tracker", "auto"]
 function normalizePathValue(value) {
     return value.replaceAll("\\", "/");
 }
+function firstNonZeroComparison(comparisons) {
+    for (const comparison of comparisons) {
+        if (comparison !== 0) {
+            return comparison;
+        }
+    }
+    return 0;
+}
 const REQUIRED_STRING_FIELDS = [
     "id",
     "title",
@@ -241,7 +249,7 @@ function assertValidFrontMatter(frontMatter, runtimeContext) {
                 record[definition.metadata_key] = coerceRuntimeFieldValue(definition, fieldValue, `metadata field "${definition.metadata_key}"`);
             }
             catch (error) {
-                validationError(error instanceof Error ? error.message.replace(/^Invalid\s+/u, "") : `invalid ${definition.metadata_key} value`);
+                validationError(String(error?.message).replace(/^Invalid\s+/u, ""));
             }
         }
     }
@@ -445,15 +453,11 @@ function normalizeTestRunSummaries(values) {
         };
     })
         .filter((value) => value.run_id.length > 0 && value.started_at.length > 0 && value.finished_at.length > 0 && value.recorded_at.length > 0)
-        .sort((a, b) => {
-        const byRecorded = compareTimestampStrings(a.recorded_at, b.recorded_at);
-        if (byRecorded !== 0)
-            return byRecorded;
-        const byRunId = a.run_id.localeCompare(b.run_id);
-        if (byRunId !== 0)
-            return byRunId;
-        return a.kind.localeCompare(b.kind);
-    });
+        .sort((a, b) => firstNonZeroComparison([
+        compareTimestampStrings(a.recorded_at, b.recorded_at),
+        a.run_id.localeCompare(b.run_id),
+        a.kind.localeCompare(b.kind),
+    ]));
     return normalized.length > 0 ? normalized : undefined;
 }
 function sortTests(values) {
@@ -515,54 +519,24 @@ function sortTests(values) {
             : undefined,
         note: value.note?.trim() || undefined,
     }))
-        .sort((a, b) => {
-        const byScope = a.scope.localeCompare(b.scope);
-        if (byScope !== 0)
-            return byScope;
-        const byPath = (a.path ?? "").localeCompare(b.path ?? "");
-        if (byPath !== 0)
-            return byPath;
-        const byCommand = (a.command ?? "").localeCompare(b.command ?? "");
-        if (byCommand !== 0)
-            return byCommand;
-        const byTimeout = (a.timeout_seconds ?? 0) - (b.timeout_seconds ?? 0);
-        if (byTimeout !== 0)
-            return byTimeout;
-        const byPmContext = (a.pm_context_mode ?? "").localeCompare(b.pm_context_mode ?? "");
-        if (byPmContext !== 0)
-            return byPmContext;
-        const bySharedHostSafe = Number(Boolean(a.shared_host_safe)) - Number(Boolean(b.shared_host_safe));
-        if (bySharedHostSafe !== 0)
-            return bySharedHostSafe;
-        const byEnvClear = JSON.stringify(a.env_clear ?? []).localeCompare(JSON.stringify(b.env_clear ?? []));
-        if (byEnvClear !== 0)
-            return byEnvClear;
-        const byEnvSet = JSON.stringify(a.env_set ?? {}).localeCompare(JSON.stringify(b.env_set ?? {}));
-        if (byEnvSet !== 0)
-            return byEnvSet;
-        const byStdoutContains = JSON.stringify(a.assert_stdout_contains ?? []).localeCompare(JSON.stringify(b.assert_stdout_contains ?? []));
-        if (byStdoutContains !== 0)
-            return byStdoutContains;
-        const byStdoutRegex = JSON.stringify(a.assert_stdout_regex ?? []).localeCompare(JSON.stringify(b.assert_stdout_regex ?? []));
-        if (byStdoutRegex !== 0)
-            return byStdoutRegex;
-        const byStderrContains = JSON.stringify(a.assert_stderr_contains ?? []).localeCompare(JSON.stringify(b.assert_stderr_contains ?? []));
-        if (byStderrContains !== 0)
-            return byStderrContains;
-        const byStderrRegex = JSON.stringify(a.assert_stderr_regex ?? []).localeCompare(JSON.stringify(b.assert_stderr_regex ?? []));
-        if (byStderrRegex !== 0)
-            return byStderrRegex;
-        const byStdoutMinLines = (a.assert_stdout_min_lines ?? 0) - (b.assert_stdout_min_lines ?? 0);
-        if (byStdoutMinLines !== 0)
-            return byStdoutMinLines;
-        const byJsonFieldEquals = JSON.stringify(a.assert_json_field_equals ?? {}).localeCompare(JSON.stringify(b.assert_json_field_equals ?? {}));
-        if (byJsonFieldEquals !== 0)
-            return byJsonFieldEquals;
-        const byJsonFieldGte = JSON.stringify(a.assert_json_field_gte ?? {}).localeCompare(JSON.stringify(b.assert_json_field_gte ?? {}));
-        if (byJsonFieldGte !== 0)
-            return byJsonFieldGte;
-        return (a.note ?? "").localeCompare(b.note ?? "");
-    });
+        .sort((a, b) => firstNonZeroComparison([
+        a.scope.localeCompare(b.scope),
+        (a.path ?? "").localeCompare(b.path ?? ""),
+        (a.command ?? "").localeCompare(b.command ?? ""),
+        (a.timeout_seconds ?? 0) - (b.timeout_seconds ?? 0),
+        (a.pm_context_mode ?? "").localeCompare(b.pm_context_mode ?? ""),
+        Number(Boolean(a.shared_host_safe)) - Number(Boolean(b.shared_host_safe)),
+        JSON.stringify(a.env_clear ?? []).localeCompare(JSON.stringify(b.env_clear ?? [])),
+        JSON.stringify(a.env_set ?? {}).localeCompare(JSON.stringify(b.env_set ?? {})),
+        JSON.stringify(a.assert_stdout_contains ?? []).localeCompare(JSON.stringify(b.assert_stdout_contains ?? [])),
+        JSON.stringify(a.assert_stdout_regex ?? []).localeCompare(JSON.stringify(b.assert_stdout_regex ?? [])),
+        JSON.stringify(a.assert_stderr_contains ?? []).localeCompare(JSON.stringify(b.assert_stderr_contains ?? [])),
+        JSON.stringify(a.assert_stderr_regex ?? []).localeCompare(JSON.stringify(b.assert_stderr_regex ?? [])),
+        (a.assert_stdout_min_lines ?? 0) - (b.assert_stdout_min_lines ?? 0),
+        JSON.stringify(a.assert_json_field_equals ?? {}).localeCompare(JSON.stringify(b.assert_json_field_equals ?? {})),
+        JSON.stringify(a.assert_json_field_gte ?? {}).localeCompare(JSON.stringify(b.assert_json_field_gte ?? {})),
+        (a.note ?? "").localeCompare(b.note ?? ""),
+    ]));
 }
 function sortDocs(values) {
     if (!values || values.length === 0)
@@ -1137,5 +1111,22 @@ export function canonicalDocument(document, options = {}) {
         body: normalizeBody(document.body ?? ""),
     };
 }
+export const _testOnlyItemFormat = {
+    buildKnownFrontMatterKeys,
+    firstNonZeroComparison,
+    normalizeBody,
+    normalizePlanDecisions,
+    normalizePlanDiscoveries,
+    normalizePlanStepDocs,
+    normalizePlanStepFiles,
+    normalizePlanStepLinks,
+    normalizePlanSteps,
+    normalizePlanStepTests,
+    normalizePlanValidation,
+    normalizeTestRunSummaries,
+    normalizeTypeOptions,
+    runtimeFieldRequiredForType,
+    sortTests,
+};
 //# sourceMappingURL=item-format.js.map
-//# debugId=ba14fa53-be28-55e9-92fb-d00e33a98480
+//# debugId=5f2983a2-ef36-52b1-892b-f6adaec87de3