npm - @unbrained/pm-cli - Versions diffs - 2026.7.16 → 2026.7.18 - Mend

@unbrained/pm-cli 2026.7.16 → 2026.7.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (620) hide show

package/dist/sdk/test/parsers.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"parsers.js","sources":["sdk/test/parsers.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/test/parsers\n *\n * Implements the pm linked test parsers command surface and its agent-facing runtime behavior.\n */\nimport { parseOptionalNumber } from \"../../core/item/parse.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { splitCommaList } from \"../../core/shared/split-comma-list.js\";\nimport { STRUCTURED_LINKED_TEST_KEYS } from \"./entry.js\";\nimport { SCOPE_VALUES } from \"../../types/index.js\";\nimport type { LinkedTest, LinkScope } from \"../../types/index.js\";\n\n/**\n * Shared linked-test field parsers used by the `create` and `test` commands.\n *\n * Extracted verbatim from create.ts and test.ts (pm-why9). The two copies were\n * byte-identical apart from their empty-input guard: create called these with\n * raw (untrimmed) values and used `if (!normalized)`; test called them with\n * pre-`.trim()`-ed values and used `if (!raw || raw.trim().length === 0)`.\n *\n * Both reduce to the same observable behaviour when the guard is the plain\n * falsy check used here: create's call sites still pass untrimmed values\n * (behaviour preserved exactly), and test's call sites pre-trim so a\n * whitespace-only value collapses to \"\" and is rejected by `!raw` exactly as\n * before. Error strings and parsing semantics are identical to both originals.\n */\n\nexport const LINKED_TEST_PROTECTED_ENV_KEYS = new Set([\n \"PM_PATH\",\n \"PM_GLOBAL_PATH\",\n \"FORCE_COLOR\",\n]);\n/** Public contract for linked test env name pattern, shared by SDK and presentation-layer consumers. */\nexport const LINKED_TEST_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;\n/** Supported values accepted by the linked test pm context mode contract. */\nexport const LINKED_TEST_PM_CONTEXT_MODE_VALUES = [\n \"schema\",\n \"tracker\",\n \"auto\",\n] as const;\n/** Restricts linked test pm context mode values accepted by command, SDK, and storage contracts. */\nexport type LinkedTestPmContextMode =\n (typeof LINKED_TEST_PM_CONTEXT_MODE_VALUES)[number];\n\n/** Implements parse linked test env set for the public runtime surface of this module. */\nexport function parseLinkedTestEnvSet(\n raw: string | undefined,\n optionName: string,\n): Record<string, string> | undefined {\n if (!raw) {\n return undefined;\n }\n const assignments = raw\n .split(/[;\\n]/)\n .map((entry) => entry.trim())\n .filter((entry) => entry.length > 0);\n if (assignments.length === 0) {\n throw new PmCliError(\n `${optionName} env_set must include at least one KEY=VALUE assignment`,\n EXIT_CODE.USAGE,\n );\n }\n const envSet: Record<string, string> = Object.create(null);\n for (const assignment of assignments) {\n const separatorIndex = assignment.indexOf(\"=\");\n if (separatorIndex <= 0) {\n throw new PmCliError(\n `${optionName} env_set entries must use KEY=VALUE and be separated by semicolons. Example: env_set=PORT=0;PLAYWRIGHT_BASE_URL=http://127.0.0.1:4173`,\n EXIT_CODE.USAGE,\n );\n }\n const key = assignment.slice(0, separatorIndex).trim();\n const value = assignment.slice(separatorIndex + 1);\n if (!LINKED_TEST_ENV_NAME_PATTERN.test(key)) {\n throw new PmCliError(\n `${optionName} env_set key \"${key}\" is invalid`,\n EXIT_CODE.USAGE,\n );\n }\n if (LINKED_TEST_PROTECTED_ENV_KEYS.has(key.toUpperCase())) {\n throw new PmCliError(\n `${optionName} env_set key \"${key}\" is reserved for sandbox safety`,\n EXIT_CODE.USAGE,\n );\n }\n envSet[key] = value;\n }\n /* c8 ignore start -- envSet always has >=1 key here (assignments is non-empty and each adds one); the undefined branch is defensive. */\n return Object.keys(envSet).length > 0 ? envSet : undefined;\n /* c8 ignore stop */\n}\n\n/** Implements parse linked test env clear for the public runtime surface of this module. */\nexport function parseLinkedTestEnvClear(\n raw: string | undefined,\n optionName: string,\n): string[] | undefined {\n if (!raw) {\n return undefined;\n }\n const keys = splitCommaList(raw, { separators: /[;,\\n]/ });\n if (keys.length === 0) {\n throw new PmCliError(\n `${optionName} env_clear must include at least one environment variable name`,\n EXIT_CODE.USAGE,\n );\n }\n for (const key of keys) {\n if (!LINKED_TEST_ENV_NAME_PATTERN.test(key)) {\n throw new PmCliError(\n `${optionName} env_clear key \"${key}\" is invalid`,\n EXIT_CODE.USAGE,\n );\n }\n if (LINKED_TEST_PROTECTED_ENV_KEYS.has(key.toUpperCase())) {\n throw new PmCliError(\n `${optionName} env_clear key \"${key}\" is reserved for sandbox safety`,\n EXIT_CODE.USAGE,\n );\n }\n }\n return keys;\n}\n\n/** Implements parse linked test boolean for the public runtime surface of this module. */\nexport function parseLinkedTestBoolean(\n raw: string | undefined,\n optionName: string,\n fieldLabel: string,\n): boolean | undefined {\n if (!raw) {\n return undefined;\n }\n const value = raw.trim().toLowerCase();\n if (value === \"true\" || value === \"1\" || value === \"yes\") {\n return true;\n }\n if (value === \"false\" || value === \"0\" || value === \"no\") {\n return false;\n }\n throw new PmCliError(\n `${optionName} ${fieldLabel} must be one of true|false|1|0|yes|no`,\n EXIT_CODE.USAGE,\n );\n}\n\n/** Implements parse linked test context mode for the public runtime surface of this module. */\nexport function parseLinkedTestContextMode(\n raw: string | undefined,\n optionName: string,\n): LinkedTest[\"pm_context_mode\"] | undefined {\n if (!raw) {\n return undefined;\n }\n const value = raw.trim().toLowerCase();\n if (\n (LINKED_TEST_PM_CONTEXT_MODE_VALUES as readonly string[]).includes(value)\n ) {\n return value as LinkedTest[\"pm_context_mode\"];\n }\n throw new PmCliError(\n `${optionName} pm_context_mode must be one of: ${LINKED_TEST_PM_CONTEXT_MODE_VALUES.join(\", \")}`,\n EXIT_CODE.USAGE,\n );\n}\n\n/** Implements parse linked test string list for the public runtime surface of this module. */\nexport function parseLinkedTestStringList(\n raw: string | undefined,\n): string[] | undefined {\n if (!raw) {\n return undefined;\n }\n const values = splitCommaList(raw, { separators: /[;\\n]/ });\n return values.length > 0 ? values : undefined;\n}\n\n/** Implements parse linked test regex list for the public runtime surface of this module. */\nexport function parseLinkedTestRegexList(\n raw: string | undefined,\n optionName: string,\n fieldLabel: string,\n): string[] | undefined {\n const values = parseLinkedTestStringList(raw);\n if (!values || values.length === 0) {\n return undefined;\n }\n for (const pattern of values) {\n try {\n // Validate regex syntax early so malformed assertions fail at parse time.\n // User-provided, per-item patterns only run during local CLI validation.\n new RegExp(pattern, \"m\");\n } catch (error: unknown) {\n throw new PmCliError(\n /* c8 ignore next -- RegExp only throws SyntaxError (an Error); String(error) fallback is defensive. */\n `${optionName} ${fieldLabel} includes invalid regex \"${pattern}\": ${error instanceof Error ? error.message : String(error)}`,\n EXIT_CODE.USAGE,\n );\n }\n }\n return values;\n}\n\n/** Implements parse linked test min lines for the public runtime surface of this module. */\nexport function parseLinkedTestMinLines(\n raw: string | undefined,\n optionName: string,\n): number | undefined {\n if (!raw) {\n return undefined;\n }\n const parsed = parseOptionalNumber(raw, \"assert_stdout_min_lines\");\n if (!Number.isInteger(parsed) || parsed < 0) {\n throw new PmCliError(\n `${optionName} assert_stdout_min_lines must be an integer >= 0`,\n EXIT_CODE.USAGE,\n );\n }\n return parsed;\n}\n\n/** Implements parse linked test assertion equals map for the public runtime surface of this module. */\nexport function parseLinkedTestAssertionEqualsMap(\n raw: string | undefined,\n optionName: string,\n): Record<string, string> | undefined {\n if (!raw) {\n return undefined;\n }\n const assignments = raw\n .split(/[;\\n]/)\n .map((entry) => entry.trim())\n .filter((entry) => entry.length > 0);\n if (assignments.length === 0) {\n throw new PmCliError(\n `${optionName} assert_json_field_equals must include at least one path=value assignment`,\n EXIT_CODE.USAGE,\n );\n }\n const values: Record<string, string> = Object.create(null);\n for (const assignment of assignments) {\n const separatorIndex = assignment.indexOf(\"=\");\n if (separatorIndex <= 0) {\n throw new PmCliError(\n `${optionName} assert_json_field_equals entries must use path=value and be separated by semicolons`,\n EXIT_CODE.USAGE,\n );\n }\n const key = assignment.slice(0, separatorIndex).trim();\n const value = assignment.slice(separatorIndex + 1).trim();\n if (key.length === 0 || value.length === 0) {\n throw new PmCliError(\n `${optionName} assert_json_field_equals entries must include non-empty path and value`,\n EXIT_CODE.USAGE,\n );\n }\n values[key] = value;\n }\n /* c8 ignore start -- values always has >=1 key here (assignments is non-empty and each adds one); the undefined branch is defensive. */\n return Object.keys(values).length > 0 ? values : undefined;\n /* c8 ignore stop */\n}\n\n/** Implements parse linked test assertion gte map for the public runtime surface of this module. */\nexport function parseLinkedTestAssertionGteMap(\n raw: string | undefined,\n optionName: string,\n): Record<string, number> | undefined {\n if (!raw) {\n return undefined;\n }\n const assignments = raw\n .split(/[;\\n]/)\n .map((entry) => entry.trim())\n .filter((entry) => entry.length > 0);\n if (assignments.length === 0) {\n throw new PmCliError(\n `${optionName} assert_json_field_gte must include at least one path=value assignment`,\n EXIT_CODE.USAGE,\n );\n }\n const values: Record<string, number> = Object.create(null);\n for (const assignment of assignments) {\n const separatorIndex = assignment.indexOf(\"=\");\n if (separatorIndex <= 0) {\n throw new PmCliError(\n `${optionName} assert_json_field_gte entries must use path=value and be separated by semicolons`,\n EXIT_CODE.USAGE,\n );\n }\n const key = assignment.slice(0, separatorIndex).trim();\n const valueRaw = assignment.slice(separatorIndex + 1).trim();\n if (key.length === 0 || valueRaw.length === 0) {\n throw new PmCliError(\n `${optionName} assert_json_field_gte entries must include non-empty path and value`,\n EXIT_CODE.USAGE,\n );\n }\n const value = Number(valueRaw);\n if (!Number.isFinite(value)) {\n throw new PmCliError(\n `${optionName} assert_json_field_gte value for \"${key}\" must be numeric`,\n EXIT_CODE.USAGE,\n );\n }\n values[key] = value;\n }\n /* c8 ignore start -- values always has >=1 key here (assignments is non-empty and each adds one); the undefined branch is defensive. */\n return Object.keys(values).length > 0 ? values : undefined;\n /* c8 ignore stop */\n}\n\n/**\n * Strict JSON linked-test entry parsing for `pm test --add-json` (pm-vcr2).\n *\n * Accepts a JSON object or array of objects whose keys match the structured\n * linked-test fields. Unlike `--add` CSV parsing, command strings are stored\n * verbatim: commas, nested quotes, `--` separators, and shell variables like\n * `$tmp` survive byte-identically.\n */\n\nconst LINKED_TEST_JSON_KEY_SET = new Set<string>(STRUCTURED_LINKED_TEST_KEYS);\n\ntype JsonRecord = Record<string, unknown>;\n\nfunction isPlainObject(value: unknown): value is JsonRecord {\n return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction normalizeJsonEntryKeys(\n entry: JsonRecord,\n fail: (message: string) => PmCliError,\n): JsonRecord {\n const normalized: JsonRecord = {};\n const unknownKeys: string[] = [];\n for (const [key, value] of Object.entries(entry)) {\n const normalizedKey = key.toLowerCase();\n if (!LINKED_TEST_JSON_KEY_SET.has(normalizedKey)) {\n unknownKeys.push(key);\n continue;\n }\n if (Object.hasOwn(normalized, normalizedKey)) {\n throw fail(\n `provides key \"${key}\" more than once after case normalization`,\n );\n }\n normalized[normalizedKey] = value;\n }\n if (unknownKeys.length > 0) {\n throw fail(\n `does not recognize key${unknownKeys.length > 1 ? \"s\" : \"\"} ${unknownKeys.map((key) => `\"${key}\"`).join(\", \")}. Allowed keys: ${STRUCTURED_LINKED_TEST_KEYS.join(\", \")}.`,\n );\n }\n return normalized;\n}\n\nfunction readJsonEntryString(\n entry: JsonRecord,\n key: string,\n fail: (message: string) => PmCliError,\n): string | undefined {\n if (!Object.hasOwn(entry, key)) {\n return undefined;\n }\n const value = entry[key];\n if (value === undefined) {\n return undefined;\n }\n if (typeof value !== \"string\") {\n throw fail(`field \"${key}\" must be a JSON string`);\n }\n return value;\n}\n\nfunction readJsonEntryStringList(\n entry: JsonRecord,\n key: string,\n fail: (message: string) => PmCliError,\n): string[] | undefined {\n if (!Object.hasOwn(entry, key)) {\n return undefined;\n }\n const value = entry[key];\n if (value === undefined) {\n return undefined;\n }\n const list = typeof value === \"string\" ? [value] : value;\n if (!Array.isArray(list) || list.some((item) => typeof item !== \"string\")) {\n throw fail(`field \"${key}\" must be a string or an array of strings`);\n }\n const values = (list as string[]).filter((item) => item.length > 0);\n return values.length > 0 ? values : undefined;\n}\n\nfunction readJsonEntryRegexList(\n entry: JsonRecord,\n key: string,\n fail: (message: string) => PmCliError,\n): string[] | undefined {\n const values = readJsonEntryStringList(entry, key, fail);\n if (!values) {\n return undefined;\n }\n for (const pattern of values) {\n try {\n new RegExp(pattern, \"m\");\n } catch (error: unknown) {\n throw fail(\n /* c8 ignore next -- RegExp only throws SyntaxError (an Error); String(error) fallback is defensive. */\n `field \"${key}\" includes invalid regex \"${pattern}\": ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n return values;\n}\n\nfunction readJsonEntryNumber(\n value: unknown,\n key: string,\n fail: (message: string) => PmCliError,\n): number {\n const parsed =\n typeof value === \"number\"\n ? value\n : typeof value === \"string\" && value.trim().length > 0\n ? Number(value.trim())\n : Number.NaN;\n if (typeof value === \"boolean\" || !Number.isFinite(parsed)) {\n throw fail(`field \"${key}\" must be a finite number (or numeric string)`);\n }\n return parsed;\n}\n\nfunction readJsonEntryTimeoutSeconds(\n entry: JsonRecord,\n fail: (message: string) => PmCliError,\n): number | undefined {\n const timeoutSecondsRaw = entry.timeout_seconds;\n const timeoutAliasRaw = entry.timeout;\n if (timeoutSecondsRaw === undefined && timeoutAliasRaw === undefined) {\n return undefined;\n }\n const timeoutSeconds =\n timeoutSecondsRaw === undefined\n ? undefined\n : readJsonEntryNumber(timeoutSecondsRaw, \"timeout_seconds\", fail);\n const timeoutAlias =\n timeoutAliasRaw === undefined\n ? undefined\n : readJsonEntryNumber(timeoutAliasRaw, \"timeout\", fail);\n if (\n timeoutSeconds !== undefined &&\n timeoutAlias !== undefined &&\n timeoutSeconds !== timeoutAlias\n ) {\n throw fail(\"timeout and timeout_seconds must match when both are provided\");\n }\n const timeout = timeoutSeconds ?? (timeoutAlias as number);\n if (!Number.isInteger(timeout) || timeout <= 0) {\n throw fail(\"timeout_seconds must be a positive integer\");\n }\n return timeout;\n}\n\nfunction readJsonEntryScope(\n entry: JsonRecord,\n fail: (message: string) => PmCliError,\n): LinkScope {\n const value = readJsonEntryString(entry, \"scope\", fail);\n if (value === undefined) {\n return \"project\";\n }\n if (!(SCOPE_VALUES as readonly string[]).includes(value)) {\n throw fail(`field \"scope\" must be one of: ${SCOPE_VALUES.join(\", \")}`);\n }\n return value as LinkScope;\n}\n\nfunction readJsonEntryEnvSet(\n entry: JsonRecord,\n fail: (message: string) => PmCliError,\n): Record<string, string> | undefined {\n if (!Object.hasOwn(entry, \"env_set\")) {\n return undefined;\n }\n const value = entry.env_set;\n if (value === undefined) {\n return undefined;\n }\n if (!isPlainObject(value)) {\n throw fail(\n 'field \"env_set\" must be a JSON object mapping environment names to string values',\n );\n }\n const envSet: Record<string, string> = Object.create(null);\n for (const [key, entryValue] of Object.entries(value)) {\n if (typeof entryValue !== \"string\") {\n throw fail(`field \"env_set\" value for \"${key}\" must be a string`);\n }\n if (!LINKED_TEST_ENV_NAME_PATTERN.test(key)) {\n throw fail(`field \"env_set\" key \"${key}\" is invalid`);\n }\n if (LINKED_TEST_PROTECTED_ENV_KEYS.has(key.toUpperCase())) {\n throw fail(`field \"env_set\" key \"${key}\" is reserved for sandbox safety`);\n }\n envSet[key] = entryValue;\n }\n return Object.keys(envSet).length > 0 ? envSet : undefined;\n}\n\nfunction readJsonEntryEnvClear(\n entry: JsonRecord,\n fail: (message: string) => PmCliError,\n): string[] | undefined {\n const keys = readJsonEntryStringList(entry, \"env_clear\", fail);\n if (!keys) {\n return undefined;\n }\n for (const key of keys) {\n if (!LINKED_TEST_ENV_NAME_PATTERN.test(key)) {\n throw fail(`field \"env_clear\" key \"${key}\" is invalid`);\n }\n if (LINKED_TEST_PROTECTED_ENV_KEYS.has(key.toUpperCase())) {\n throw fail(\n `field \"env_clear\" key \"${key}\" is reserved for sandbox safety`,\n );\n }\n }\n return keys;\n}\n\nfunction readJsonEntryBoolean(\n entry: JsonRecord,\n key: string,\n fail: (message: string) => PmCliError,\n): boolean | undefined {\n if (!Object.hasOwn(entry, key)) {\n return undefined;\n }\n const value = entry[key];\n if (value === undefined) {\n return undefined;\n }\n if (typeof value !== \"boolean\") {\n throw fail(`field \"${key}\" must be a JSON boolean (true or false)`);\n }\n return value;\n}\n\nfunction readJsonEntryMinLines(\n entry: JsonRecord,\n fail: (message: string) => PmCliError,\n): number | undefined {\n if (!Object.hasOwn(entry, \"assert_stdout_min_lines\")) {\n return undefined;\n }\n const value = entry.assert_stdout_min_lines;\n if (value === undefined) {\n return undefined;\n }\n const parsed = readJsonEntryNumber(value, \"assert_stdout_min_lines\", fail);\n if (!Number.isInteger(parsed) || parsed < 0) {\n throw fail('field \"assert_stdout_min_lines\" must be an integer >= 0');\n }\n return parsed;\n}\n\nfunction readJsonEntryEqualsMap(\n entry: JsonRecord,\n fail: (message: string) => PmCliError,\n): Record<string, string> | undefined {\n if (!Object.hasOwn(entry, \"assert_json_field_equals\")) {\n return undefined;\n }\n const value = entry.assert_json_field_equals;\n if (value === undefined) {\n return undefined;\n }\n if (!isPlainObject(value)) {\n throw fail(\n 'field \"assert_json_field_equals\" must be a JSON object mapping field paths to expected values',\n );\n }\n const values: Record<string, string> = Object.create(null);\n for (const [key, entryValue] of Object.entries(value)) {\n if (key.trim().length === 0) {\n throw fail(\n 'field \"assert_json_field_equals\" keys must be non-empty field paths',\n );\n }\n if (\n typeof entryValue !== \"string\" &&\n typeof entryValue !== \"number\" &&\n typeof entryValue !== \"boolean\"\n ) {\n throw fail(\n `field \"assert_json_field_equals\" value for \"${key}\" must be a string, number, or boolean`,\n );\n }\n values[key] = String(entryValue);\n }\n return Object.keys(values).length > 0 ? values : undefined;\n}\n\nfunction readJsonEntryGteMap(\n entry: JsonRecord,\n fail: (message: string) => PmCliError,\n): Record<string, number> | undefined {\n if (!Object.hasOwn(entry, \"assert_json_field_gte\")) {\n return undefined;\n }\n const value = entry.assert_json_field_gte;\n if (value === undefined) {\n return undefined;\n }\n if (!isPlainObject(value)) {\n throw fail(\n 'field \"assert_json_field_gte\" must be a JSON object mapping field paths to numeric minimums',\n );\n }\n const values: Record<string, number> = Object.create(null);\n for (const [key, entryValue] of Object.entries(value)) {\n if (key.trim().length === 0) {\n throw fail(\n 'field \"assert_json_field_gte\" keys must be non-empty field paths',\n );\n }\n values[key] = readJsonEntryNumber(\n entryValue,\n `assert_json_field_gte.${key}`,\n fail,\n );\n }\n return Object.keys(values).length > 0 ? values : undefined;\n}\n\nfunction parseLinkedTestJsonEntry(\n rawEntry: unknown,\n label: string,\n optionName: string,\n): LinkedTest {\n const fail = (message: string): PmCliError =>\n new PmCliError(`${optionName} ${label} ${message}`, EXIT_CODE.USAGE);\n if (!isPlainObject(rawEntry)) {\n throw fail(\n `must be a JSON object with linked-test fields. Allowed keys: ${STRUCTURED_LINKED_TEST_KEYS.join(\", \")}.`,\n );\n }\n const entry = normalizeJsonEntryKeys(rawEntry, fail);\n const commandValue = readJsonEntryString(entry, \"command\", fail);\n const cmdAlias = readJsonEntryString(entry, \"cmd\", fail);\n if (\n commandValue !== undefined &&\n cmdAlias !== undefined &&\n commandValue !== cmdAlias\n ) {\n throw fail(\"command and cmd must match when both are provided\");\n }\n const command = commandValue ?? cmdAlias;\n if (command === undefined || command.trim().length === 0) {\n throw fail('requires a non-empty \"command\" string');\n }\n const pathValue = readJsonEntryString(entry, \"path\", fail);\n const pmContextModeValue = readJsonEntryString(\n entry,\n \"pm_context_mode\",\n fail,\n );\n if (\n pmContextModeValue !== undefined &&\n !(LINKED_TEST_PM_CONTEXT_MODE_VALUES as readonly string[]).includes(\n pmContextModeValue,\n )\n ) {\n throw fail(\n `field \"pm_context_mode\" must be one of: ${LINKED_TEST_PM_CONTEXT_MODE_VALUES.join(\", \")}`,\n );\n }\n const noteValue = readJsonEntryString(entry, \"note\", fail);\n return {\n command,\n path:\n pathValue !== undefined && pathValue.length > 0 ? pathValue : undefined,\n scope: readJsonEntryScope(entry, fail),\n timeout_seconds: readJsonEntryTimeoutSeconds(entry, fail),\n pm_context_mode: pmContextModeValue as LinkedTest[\"pm_context_mode\"],\n env_set: readJsonEntryEnvSet(entry, fail),\n env_clear: readJsonEntryEnvClear(entry, fail),\n shared_host_safe: readJsonEntryBoolean(entry, \"shared_host_safe\", fail),\n assert_stdout_contains: readJsonEntryStringList(\n entry,\n \"assert_stdout_contains\",\n fail,\n ),\n assert_stdout_regex: readJsonEntryRegexList(\n entry,\n \"assert_stdout_regex\",\n fail,\n ),\n assert_stderr_contains: readJsonEntryStringList(\n entry,\n \"assert_stderr_contains\",\n fail,\n ),\n assert_stderr_regex: readJsonEntryRegexList(\n entry,\n \"assert_stderr_regex\",\n fail,\n ),\n assert_stdout_min_lines: readJsonEntryMinLines(entry, fail),\n assert_json_field_equals: readJsonEntryEqualsMap(entry, fail),\n assert_json_field_gte: readJsonEntryGteMap(entry, fail),\n note:\n noteValue !== undefined && noteValue.trim().length > 0\n ? noteValue.trim()\n : undefined,\n };\n}\n\n/** Implements parse linked test json entries for the public runtime surface of this module. */\nexport function parseLinkedTestJsonEntries(\n raw: string,\n optionName: string,\n): LinkedTest[] {\n const trimmed = raw.trim();\n if (trimmed.length === 0) {\n throw new PmCliError(\n `${optionName} requires a JSON object or array of objects describing linked-test entries`,\n EXIT_CODE.USAGE,\n );\n }\n let parsed: unknown;\n try {\n parsed = JSON.parse(trimmed) as unknown;\n } catch (error: unknown) {\n throw new PmCliError(\n /* c8 ignore next -- JSON.parse only throws SyntaxError (an Error); String(error) fallback is defensive. */\n `${optionName} value is not valid JSON: ${error instanceof Error ? error.message : String(error)}. Provide a JSON object or array of objects, e.g. '{\"command\":\"node scripts/check.js --flag value, with commas\",\"timeout_seconds\":120}'.`,\n EXIT_CODE.USAGE,\n );\n }\n const entries = Array.isArray(parsed) ? parsed : [parsed];\n if (entries.length === 0) {\n throw new PmCliError(\n `${optionName} array must include at least one linked-test entry object`,\n EXIT_CODE.USAGE,\n );\n }\n return entries.map((entry, index) =>\n parseLinkedTestJsonEntry(\n entry,\n entries.length > 1 ? `entry ${index + 1}` : \"entry\",\n optionName,\n ),\n );\n}\n\n/** Public contract for test only linked test parsers, shared by SDK and presentation-layer consumers. */\nexport const _testOnlyLinkedTestParsers = {\n parseLinkedTestJsonEntry,\n};\n"],"names":[],"mappings":"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","debugId":"070a3dbc-d028-5ce9-a1ed-41010c72d9ab"}

package/dist/sdk/test/runs.d.ts ADDED Viewed

@@ -0,0 +1,92 @@
+import type { GlobalOptions } from "../../core/shared/command-types.js";
+import { type BackgroundLogStream, type BackgroundTestRunKind, type BackgroundTestRunStatus } from "../../core/test/background-runs.js";
+/** Documents the start background run command options payload exchanged by command, SDK, and package integrations. */
+export interface StartBackgroundRunCommandOptions {
+    /** Value that configures or reports kind for this contract. */
+    kind: BackgroundTestRunKind;
+    /** Value that configures or reports command args for this contract. */
+    commandArgs: string[];
+    /** Value that configures or reports target id for this contract. */
+    targetId?: string;
+    /** Value that configures or reports status filter for this contract. */
+    statusFilter?: string;
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Value that configures or reports no extensions for this contract. */
+    noExtensions?: boolean;
+}
+/** Documents the start background run result payload exchanged by command, SDK, and package integrations. */
+export interface StartBackgroundRunResult {
+    /** Value that configures or reports started for this contract. */
+    started: boolean;
+    /** Value that configures or reports duplicate of for this contract. */
+    duplicate_of?: string;
+    /** Value that configures or reports run for this contract. */
+    run: unknown;
+}
+/** Implements run start background run for the public runtime surface of this module. */
+export declare function runStartBackgroundRun(options: StartBackgroundRunCommandOptions, global: GlobalOptions): Promise<StartBackgroundRunResult>;
+/** Documents the test runs list command options payload exchanged by command, SDK, and package integrations. */
+export interface TestRunsListCommandOptions {
+    /** Lifecycle state reported for status. */
+    status?: string;
+    /** Value that configures or reports limit for this contract. */
+    limit?: string;
+}
+/** Implements run test runs list for the public runtime surface of this module. */
+export declare function runTestRunsList(options: TestRunsListCommandOptions, global: GlobalOptions): Promise<{
+    runs: unknown[];
+    count: number;
+    filters: {
+        status?: BackgroundTestRunStatus;
+        limit?: number;
+    };
+}>;
+/** Implements run test runs status for the public runtime surface of this module. */
+export declare function runTestRunsStatus(runId: string, global: GlobalOptions): Promise<{
+    run: unknown;
+    health: unknown;
+}>;
+/** Documents the test runs logs command options payload exchanged by command, SDK, and package integrations. */
+export interface TestRunsLogsCommandOptions {
+    /** Value that configures or reports stream for this contract. */
+    stream?: string;
+    /** Value that configures or reports tail for this contract. */
+    tail?: string;
+}
+/** Implements run test runs logs for the public runtime surface of this module. */
+export declare function runTestRunsLogs(runId: string, options: TestRunsLogsCommandOptions, global: GlobalOptions): Promise<{
+    run: unknown;
+    stream: BackgroundLogStream;
+    tail: number;
+    stdout: string[];
+    stderr: string[];
+}>;
+/** Documents the test runs stop command options payload exchanged by command, SDK, and package integrations. */
+export interface TestRunsStopCommandOptions {
+    /** Value that configures or reports force for this contract. */
+    force?: boolean;
+}
+/** Implements run test runs stop for the public runtime surface of this module. */
+export declare function runTestRunsStop(runId: string, options: TestRunsStopCommandOptions, global: GlobalOptions): Promise<{
+    run: unknown;
+    signal_sent: "SIGTERM" | "SIGKILL" | "none";
+}>;
+/** Documents the test runs resume command options payload exchanged by command, SDK, and package integrations. */
+export interface TestRunsResumeCommandOptions {
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Value that configures or reports no extensions for this contract. */
+    noExtensions?: boolean;
+}
+/** Implements run test runs resume for the public runtime surface of this module. */
+export declare function runTestRunsResume(runId: string, options: TestRunsResumeCommandOptions, global: GlobalOptions): Promise<{
+    resumed_from: string;
+    run: unknown;
+}>;
+/** Implements run test runs worker for the public runtime surface of this module. */
+export declare function runTestRunsWorker(runId: string, global: GlobalOptions): Promise<{
+    id: string;
+    status: BackgroundTestRunStatus;
+    exit_code?: number;
+}>;

package/dist/sdk/test/runs.js ADDED Viewed

@@ -0,0 +1,195 @@
+/**
+ * @module sdk/test/runs
+ *
+ * Implements the pm test runs 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]="2c42bfb9-c598-5a6e-bfff-0c073bb44205")}catch(e){}}();
+import os from "node:os";
+import { pathExists } from "../../core/fs/fs-utils.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { getBackgroundTestRunStatus, listBackgroundTestRuns, readBackgroundTestRunLogs, resumeBackgroundTestRun, runBackgroundTestRunWorker, spawnBackgroundTestRunWorker, startBackgroundTestRun, stopBackgroundTestRun, } from "../../core/test/background-runs.js";
+import { getSettingsPath, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
+import { readSettings } from "../../core/store/settings.js";
+import { parseLimit } from "../../core/shared/numeric-parsers.js";
+const BACKGROUND_STATUS_VALUES = [
+    "queued",
+    "running",
+    "passed",
+    "failed",
+    "stopped",
+    "canceled",
+];
+const BACKGROUND_STREAM_VALUES = [
+    "stdout",
+    "stderr",
+    "both",
+];
+function normalizeStatus(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (BACKGROUND_STATUS_VALUES.includes(normalized)) {
+        return normalized;
+    }
+    throw new PmCliError(`Invalid --status value "${value}"`, EXIT_CODE.USAGE);
+}
+function normalizeStream(value) {
+    if (value === undefined || value.trim().length === 0) {
+        return "stderr";
+    }
+    const normalized = value.trim().toLowerCase();
+    if (BACKGROUND_STREAM_VALUES.includes(normalized)) {
+        return normalized;
+    }
+    throw new PmCliError(`Invalid --stream value "${value}"`, EXIT_CODE.USAGE);
+}
+function resolveWhoamiFallback() {
+    try {
+        const username = os.userInfo().username.trim();
+        if (username.length > 0) {
+            return username;
+        }
+    }
+    catch {
+        // Fall back to environment-derived attribution.
+    }
+    return undefined;
+}
+function resolveRequestedBy(author, fallback) {
+    const candidates = [
+        author,
+        process.env.PM_AUTHOR,
+        fallback,
+        process.env.USER,
+        process.env.LOGNAME,
+        process.env.USERNAME,
+        resolveWhoamiFallback(),
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate !== "string") {
+            continue;
+        }
+        const trimmed = candidate.trim();
+        if (trimmed.length > 0) {
+            return trimmed;
+        }
+    }
+    return "unknown";
+}
+async function ensureInitialized(pmRoot) {
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+}
+/** Implements run start background run for the public runtime surface of this module. */
+export async function runStartBackgroundRun(options, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    const globalPmRoot = resolveGlobalPmRoot(process.cwd());
+    await ensureInitialized(pmRoot);
+    const settings = await readSettings(pmRoot);
+    const requestedBy = resolveRequestedBy(options.author, settings.author_default);
+    const started = await startBackgroundTestRun({
+        pmRoot,
+        globalPmRoot,
+        kind: options.kind,
+        commandArgs: options.commandArgs,
+        requestedBy,
+        targetId: options.targetId,
+        statusFilter: options.statusFilter,
+    });
+    if (!started.started) {
+        return {
+            started: false,
+            duplicate_of: started.duplicate_of,
+            run: started.run,
+        };
+    }
+    const spawned = await spawnBackgroundTestRunWorker({
+        pmRoot,
+        runId: started.run.id,
+        noExtensions: options.noExtensions === true,
+    });
+    return {
+        started: true,
+        run: spawned,
+    };
+}
+/** Implements run test runs list for the public runtime surface of this module. */
+export async function runTestRunsList(options, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    await ensureInitialized(pmRoot);
+    const status = normalizeStatus(options.status);
+    const limit = parseLimit(options.limit, "limit");
+    const runs = await listBackgroundTestRuns(pmRoot, { status, limit });
+    return {
+        runs,
+        count: runs.length,
+        filters: {
+            status,
+            limit,
+        },
+    };
+}
+/** Implements run test runs status for the public runtime surface of this module. */
+export async function runTestRunsStatus(runId, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    await ensureInitialized(pmRoot);
+    const status = await getBackgroundTestRunStatus(pmRoot, runId);
+    return {
+        run: status.run,
+        health: status.health,
+    };
+}
+/** Implements run test runs logs for the public runtime surface of this module. */
+export async function runTestRunsLogs(runId, options, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    await ensureInitialized(pmRoot);
+    const stream = normalizeStream(options.stream);
+    const tail = parseLimit(options.tail, "tail");
+    const logs = await readBackgroundTestRunLogs(pmRoot, runId, stream, tail);
+    return {
+        run: logs.run,
+        stream: logs.stream,
+        tail: logs.tail,
+        stdout: logs.stdout,
+        stderr: logs.stderr,
+    };
+}
+/** Implements run test runs stop for the public runtime surface of this module. */
+export async function runTestRunsStop(runId, options, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    await ensureInitialized(pmRoot);
+    const stopped = await stopBackgroundTestRun(pmRoot, runId, options.force === true);
+    return {
+        run: stopped.run,
+        signal_sent: stopped.signal_sent,
+    };
+}
+/** Implements run test runs resume for the public runtime surface of this module. */
+export async function runTestRunsResume(runId, options, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    await ensureInitialized(pmRoot);
+    const settings = await readSettings(pmRoot);
+    const requestedBy = resolveRequestedBy(options.author, settings.author_default);
+    const resumed = await resumeBackgroundTestRun(pmRoot, runId, requestedBy, options.noExtensions === true);
+    return {
+        resumed_from: runId,
+        run: resumed,
+    };
+}
+/** Implements run test runs worker for the public runtime surface of this module. */
+export async function runTestRunsWorker(runId, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    await ensureInitialized(pmRoot);
+    const finished = await runBackgroundTestRunWorker(pmRoot, runId, global.noExtensions === true);
+    return {
+        id: finished.id,
+        status: finished.status,
+        exit_code: finished.exit_code,
+    };
+}
+//# sourceMappingURL=runs.js.map
+//# debugId=2c42bfb9-c598-5a6e-bfff-0c073bb44205

package/dist/sdk/test/runs.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"runs.js","sources":["sdk/test/runs.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/test/runs\n *\n * Implements the pm test runs command surface and its agent-facing runtime behavior.\n */\nimport os from \"node:os\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport {\n type BackgroundLogStream,\n type BackgroundTestRunKind,\n type BackgroundTestRunStatus,\n getBackgroundTestRunStatus,\n listBackgroundTestRuns,\n readBackgroundTestRunLogs,\n resumeBackgroundTestRun,\n runBackgroundTestRunWorker,\n spawnBackgroundTestRunWorker,\n startBackgroundTestRun,\n stopBackgroundTestRun,\n} from \"../../core/test/background-runs.js\";\nimport {\n getSettingsPath,\n resolveGlobalPmRoot,\n resolvePmRoot,\n} from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport { parseLimit } from \"../../core/shared/numeric-parsers.js\";\n\nconst BACKGROUND_STATUS_VALUES: readonly BackgroundTestRunStatus[] = [\n \"queued\",\n \"running\",\n \"passed\",\n \"failed\",\n \"stopped\",\n \"canceled\",\n];\nconst BACKGROUND_STREAM_VALUES: readonly BackgroundLogStream[] = [\n \"stdout\",\n \"stderr\",\n \"both\",\n];\n\nfunction normalizeStatus(\n value: string | undefined,\n): BackgroundTestRunStatus | undefined {\n if (value === undefined) {\n return undefined;\n }\n const normalized = value.trim().toLowerCase();\n if ((BACKGROUND_STATUS_VALUES as readonly string[]).includes(normalized)) {\n return normalized as BackgroundTestRunStatus;\n }\n throw new PmCliError(`Invalid --status value \"${value}\"`, EXIT_CODE.USAGE);\n}\n\nfunction normalizeStream(value: string | undefined): BackgroundLogStream {\n if (value === undefined || value.trim().length === 0) {\n return \"stderr\";\n }\n const normalized = value.trim().toLowerCase();\n if ((BACKGROUND_STREAM_VALUES as readonly string[]).includes(normalized)) {\n return normalized as BackgroundLogStream;\n }\n throw new PmCliError(`Invalid --stream value \"${value}\"`, EXIT_CODE.USAGE);\n}\n\nfunction resolveWhoamiFallback(): string | undefined {\n try {\n const username = os.userInfo().username.trim();\n if (username.length > 0) {\n return username;\n }\n } catch {\n // Fall back to environment-derived attribution.\n }\n return undefined;\n}\n\nfunction resolveRequestedBy(\n author: string | undefined,\n fallback: string,\n): string {\n const candidates = [\n author,\n process.env.PM_AUTHOR,\n fallback,\n process.env.USER,\n process.env.LOGNAME,\n process.env.USERNAME,\n resolveWhoamiFallback(),\n ];\n for (const candidate of candidates) {\n if (typeof candidate !== \"string\") {\n continue;\n }\n const trimmed = candidate.trim();\n if (trimmed.length > 0) {\n return trimmed;\n }\n }\n return \"unknown\";\n}\n\nasync function ensureInitialized(pmRoot: string): Promise<void> {\n if (!(await pathExists(getSettingsPath(pmRoot)))) {\n throw new PmCliError(\n `Tracker is not initialized at ${pmRoot}. Run pm init first.`,\n EXIT_CODE.NOT_FOUND,\n );\n }\n}\n\n/** Documents the start background run command options payload exchanged by command, SDK, and package integrations. */\nexport interface StartBackgroundRunCommandOptions {\n /** Value that configures or reports kind for this contract. */\n kind: BackgroundTestRunKind;\n /** Value that configures or reports command args for this contract. */\n commandArgs: string[];\n /** Value that configures or reports target id for this contract. */\n targetId?: string;\n /** Value that configures or reports status filter for this contract. */\n statusFilter?: string;\n /** Value that configures or reports author for this contract. */\n author?: string;\n /** Value that configures or reports no extensions for this contract. */\n noExtensions?: boolean;\n}\n\n/** Documents the start background run result payload exchanged by command, SDK, and package integrations. */\nexport interface StartBackgroundRunResult {\n /** Value that configures or reports started for this contract. */\n started: boolean;\n /** Value that configures or reports duplicate of for this contract. */\n duplicate_of?: string;\n /** Value that configures or reports run for this contract. */\n run: unknown;\n}\n\n/** Implements run start background run for the public runtime surface of this module. */\nexport async function runStartBackgroundRun(\n options: StartBackgroundRunCommandOptions,\n global: GlobalOptions,\n): Promise<StartBackgroundRunResult> {\n const pmRoot = resolvePmRoot(process.cwd(), global.path);\n const globalPmRoot = resolveGlobalPmRoot(process.cwd());\n await ensureInitialized(pmRoot);\n const settings = await readSettings(pmRoot);\n const requestedBy = resolveRequestedBy(\n options.author,\n settings.author_default,\n );\n const started = await startBackgroundTestRun({\n pmRoot,\n globalPmRoot,\n kind: options.kind,\n commandArgs: options.commandArgs,\n requestedBy,\n targetId: options.targetId,\n statusFilter: options.statusFilter,\n });\n if (!started.started) {\n return {\n started: false,\n duplicate_of: started.duplicate_of,\n run: started.run,\n };\n }\n const spawned = await spawnBackgroundTestRunWorker({\n pmRoot,\n runId: started.run.id,\n noExtensions: options.noExtensions === true,\n });\n return {\n started: true,\n run: spawned,\n };\n}\n\n/** Documents the test runs list command options payload exchanged by command, SDK, and package integrations. */\nexport interface TestRunsListCommandOptions {\n /** Lifecycle state reported for status. */\n status?: string;\n /** Value that configures or reports limit for this contract. */\n limit?: string;\n}\n\n/** Implements run test runs list for the public runtime surface of this module. */\nexport async function runTestRunsList(\n options: TestRunsListCommandOptions,\n global: GlobalOptions,\n): Promise<{\n runs: unknown[];\n count: number;\n filters: {\n status?: BackgroundTestRunStatus;\n limit?: number;\n };\n}> {\n const pmRoot = resolvePmRoot(process.cwd(), global.path);\n await ensureInitialized(pmRoot);\n const status = normalizeStatus(options.status);\n const limit = parseLimit(options.limit, \"limit\");\n const runs = await listBackgroundTestRuns(pmRoot, { status, limit });\n return {\n runs,\n count: runs.length,\n filters: {\n status,\n limit,\n },\n };\n}\n\n/** Implements run test runs status for the public runtime surface of this module. */\nexport async function runTestRunsStatus(\n runId: string,\n global: GlobalOptions,\n): Promise<{\n run: unknown;\n health: unknown;\n}> {\n const pmRoot = resolvePmRoot(process.cwd(), global.path);\n await ensureInitialized(pmRoot);\n const status = await getBackgroundTestRunStatus(pmRoot, runId);\n return {\n run: status.run,\n health: status.health,\n };\n}\n\n/** Documents the test runs logs command options payload exchanged by command, SDK, and package integrations. */\nexport interface TestRunsLogsCommandOptions {\n /** Value that configures or reports stream for this contract. */\n stream?: string;\n /** Value that configures or reports tail for this contract. */\n tail?: string;\n}\n\n/** Implements run test runs logs for the public runtime surface of this module. */\nexport async function runTestRunsLogs(\n runId: string,\n options: TestRunsLogsCommandOptions,\n global: GlobalOptions,\n): Promise<{\n run: unknown;\n stream: BackgroundLogStream;\n tail: number;\n stdout: string[];\n stderr: string[];\n}> {\n const pmRoot = resolvePmRoot(process.cwd(), global.path);\n await ensureInitialized(pmRoot);\n const stream = normalizeStream(options.stream);\n const tail = parseLimit(options.tail, \"tail\");\n const logs = await readBackgroundTestRunLogs(pmRoot, runId, stream, tail);\n return {\n run: logs.run,\n stream: logs.stream,\n tail: logs.tail,\n stdout: logs.stdout,\n stderr: logs.stderr,\n };\n}\n\n/** Documents the test runs stop command options payload exchanged by command, SDK, and package integrations. */\nexport interface TestRunsStopCommandOptions {\n /** Value that configures or reports force for this contract. */\n force?: boolean;\n}\n\n/** Implements run test runs stop for the public runtime surface of this module. */\nexport async function runTestRunsStop(\n runId: string,\n options: TestRunsStopCommandOptions,\n global: GlobalOptions,\n): Promise<{\n run: unknown;\n signal_sent: \"SIGTERM\" | \"SIGKILL\" | \"none\";\n}> {\n const pmRoot = resolvePmRoot(process.cwd(), global.path);\n await ensureInitialized(pmRoot);\n const stopped = await stopBackgroundTestRun(\n pmRoot,\n runId,\n options.force === true,\n );\n return {\n run: stopped.run,\n signal_sent: stopped.signal_sent,\n };\n}\n\n/** Documents the test runs resume command options payload exchanged by command, SDK, and package integrations. */\nexport interface TestRunsResumeCommandOptions {\n /** Value that configures or reports author for this contract. */\n author?: string;\n /** Value that configures or reports no extensions for this contract. */\n noExtensions?: boolean;\n}\n\n/** Implements run test runs resume for the public runtime surface of this module. */\nexport async function runTestRunsResume(\n runId: string,\n options: TestRunsResumeCommandOptions,\n global: GlobalOptions,\n): Promise<{\n resumed_from: string;\n run: unknown;\n}> {\n const pmRoot = resolvePmRoot(process.cwd(), global.path);\n await ensureInitialized(pmRoot);\n const settings = await readSettings(pmRoot);\n const requestedBy = resolveRequestedBy(\n options.author,\n settings.author_default,\n );\n const resumed = await resumeBackgroundTestRun(\n pmRoot,\n runId,\n requestedBy,\n options.noExtensions === true,\n );\n return {\n resumed_from: runId,\n run: resumed,\n };\n}\n\n/** Implements run test runs worker for the public runtime surface of this module. */\nexport async function runTestRunsWorker(\n runId: string,\n global: GlobalOptions,\n): Promise<{\n id: string;\n status: BackgroundTestRunStatus;\n exit_code?: number;\n}> {\n const pmRoot = resolvePmRoot(process.cwd(), global.path);\n await ensureInitialized(pmRoot);\n const finished = await runBackgroundTestRunWorker(\n pmRoot,\n runId,\n global.noExtensions === true,\n );\n return {\n id: finished.id,\n status: finished.status,\n exit_code: finished.exit_code,\n };\n}\n"],"names":[],"mappings":"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","debugId":"2c42bfb9-c598-5a6e-bfff-0c073bb44205"}

package/docs/AGENT_GUIDE.md CHANGED Viewed

@@ -137,6 +137,7 @@ pm release <item-id>
 | Agent plan read | `pm plan show <plan-id> --depth brief` (or `--fields id,title,steps_summary`) |
 | Materialize plan steps | `pm plan materialize <plan-id> --steps plan-step-002 --materialize-type Task` |
 | Dependencies | `pm deps <id> --format tree` |
+| Graph queries | `pm graph successors <id> --limit 20` (also `ancestors`, `paths`, `impact`, `analyze`, `audit`, `communities`, `redundancy`, `dominators`, `plan`) |
 | Bulk update by id allowlist | `pm update-many --ids pm-a,pm-b --priority 1 --dry-run` (preview, then drop `--dry-run`) |
 | Audited bulk close (sprint closeout) | `pm close-many --filter-sprint <s> --reason "<text>" --dry-run` (full `pm close` semantics per item; `--rollback <id>` to undo) |
 | Local docs routing | `pm install guide-shell --project`, then `pm guide <topic>` |

package/docs/COMMANDS.md CHANGED Viewed

@@ -548,12 +548,30 @@ pm files <id> --add-glob "src/cli/**/*.ts"
 pm docs <id> --add path=docs/COMMANDS.md,note="public command docs"
 pm docs <id> --add docs/COMMANDS.md --note "public command docs"
 pm deps <id> --format tree
+pm deps <id> --format context --direction both --kind blocked_by,parent --token-budget 800
 ```
-Linked files and docs keep reviews reproducible. `deps` is read-only and projects item relationships. The standalone `--note <text>` flag annotates every link added by `--add`/`--add-glob` in the same invocation (a per-entry embedded `note=` wins); `--note` without an add is a usage error.
+Linked files and docs keep reviews reproducible. `deps` is read-only and projects item relationships. `--format context` returns one bounded, explainable relationship packet: a counts-first summary, per-node `role`/`via`/`reasons`, root evidence pointers, enumerated `missing_references` with active-versus-legacy classification, `meta.completeness`, and cursor continuation; `--direction`, repeatable or comma-separated `--kind`, `--max-depth`, `--node-limit`, `--edge-limit`, `--token-budget`, and `--cursor` control the traversal (see [Relationship Graph](RELATIONSHIP_GRAPH.md)). `--edge-limit` caps both returned graph edges and enumerated `missing_references`; `missing_reference_count` retains the total when rows are omitted. The standalone `--note <text>` flag annotates every link added by `--add`/`--add-glob` in the same invocation (a per-entry embedded `note=` wins); `--note` without an add is a usage error.
 Structured key/value forms reject unrecognized keys with an `Allowed keys: …` error (matching `test --add`), so a typoed key (`lable=` instead of `label=`) fails fast instead of being silently dropped: `--add`/`--file`/`--doc` accept `path,scope,note`; `--add-glob` accepts `pattern,glob,path,scope,note`; `--remove` accepts `path`; `--migrate` accepts `from,to`; `--dep` accepts `id,kind,type,author,created_at` (plus `source_kind` on update); `--reminder` accepts `at,date,text,title`; `--event` accepts `start,date,end,duration,title,description,location,timezone,all_day` and the `recur_*` recurrence keys. Bare values (`--add src/cli/main.ts`) skip key validation.
+## Graph Queries
+```bash
+pm graph ancestors <id> --max-depth 3
+pm graph successors <id> --kind blocked_by --limit 20
+pm graph paths <id> <target> --direction outgoing --max-paths 5
+pm graph impact <id> --direction incoming --summary
+pm graph analyze --limit 10
+pm graph audit --sample 5 --exempt-isolate pm-root
+pm graph communities --kind blocked_by --limit 5
+pm graph redundancy --max-depth 6 --limit 20
+pm graph dominators <id> --direction outgoing --limit 10
+pm graph plan --sample 5 --limit 20
+```
+`graph` is read-only and answers workspace-wide relationship questions through the public SDK graph toolkit. `ancestors`/`descendants` walk registered hierarchy kinds, `predecessors`/`successors` walk order-bearing kinds, `paths` enumerates bounded simple paths between two items with per-edge kinds, and `impact` reports the bounded blast radius with an explaining path per affected item. `analyze` returns workspace execution analytics (topological layers, prerequisite frontier, critical path, genuine ordering cycles) plus knowledge-graph structure (components, orphans, hubs), and `audit` runs the policy-aware governance audit with counts-first findings, severities, and bounded evidence samples. Audit severity gates on lifecycle: ordering cycles and duplicated edge spellings confined to closed/canceled items downgrade to informational `legacy_ordering_cycle`/`legacy_duplicate_edge` findings (history debt, never repaired ad hoc), while `ordering_cycle` errors and `duplicate_edge` findings are reserved for subjects touching at least one active item; `duplicate_edge` reports parallel same-family spellings — including reciprocal inverse pairs such as `A blocked_by B` plus `B blocks A` — that transitive-reduction redundancy deliberately cannot see. `communities` clusters the undirected structure with deterministic label propagation (reporting `iterations` and `converged`), `redundancy` finds stored edges implied by a longer path of the same semantic family (`blocked_by`/`blocks` and hierarchy spellings witness each other, each row carrying its witness path), and `dominators` reports the structural bottlenecks of one item's reachable subgraph — nodes every path from the root must pass through, ranked by how much work they gate (`dominated_count`). `plan` derives a dry-run remediation plan from the audit plus the redundancy scan: exact `remove`/`retype`/`supersede`/`waive`/`investigate` proposals with per-step policy code, evidence, rationale, and confidence — nothing is ever applied automatically and no proposal invents an edge. Every envelope is counts-first with explicit `truncated`, `cost` (visited nodes, inspected edges), and `cache` (workspace fingerprint plus assembly/result hit-or-miss) metadata; repeated identical queries in long-lived hosts such as the MCP server are answered from a fingerprint-keyed snapshot cache that invalidates on any relationship-relevant item change. `--summary` suppresses row collections entirely. `--kind` accepts registered relationship kinds (repeatable or comma-separated) and fails fast on unknown values (`redundancy` additionally requires directed ordering or hierarchy kinds); `--after` resumes hierarchy/ordering walks after a previously returned node id (see [Relationship Graph](RELATIONSHIP_GRAPH.md)).
 ## Linked Tests
 ```bash

package/docs/RELATIONSHIP_GRAPH.md CHANGED Viewed

@@ -67,15 +67,22 @@ Every analytics result identifies its algorithm and edge family. Exact algorithm
 ## Bounded agent context
-`buildRelationshipContext` joins caller-owned compact node details with the graph kernel in one request. The packet includes the root, shortest-distance related nodes, semantic selection reasons (`prerequisite`, `dependent`, `ancestor`, `descendant`, `provenance`, or bounded reachability), root evidence pointers, included edges, explicit work counts, token accounting, omitted counts, and an opaque continuation cursor.
+`buildRelationshipContext` joins caller-owned compact node details with the graph kernel in one request. The packet opens with a counts-first `summary` (root identity and status, root-incident edge counts per semantic family, discovered/returned/omitted node and edge counts, evidence count, and a continuation marker) followed by the root, shortest-distance related nodes, included edges, root evidence pointers, and the cost envelope.
+Every returned node is explainable: `role` names its semantic family (`prerequisite`, `dependent`, `ancestor`, `descendant`, `provenance`, or `related`), `via` names the node through which bounded traversal first discovered it, and `reasons` lists the direct classifications for depth-1 nodes or a `"<role> via <node> (depth N)"` chain explanation for deeper nodes. When a node matches several families, `role` picks the deterministic priority order `prerequisite > dependent > ancestor > descendant > provenance > related`.
+`meta.completeness` reports result quality: the exact in-memory kernel emits `complete` or `truncated`, and the contract reserves `sampled`, `approximate`, `stale_index`, and `redacted` for index-backed or policy-filtered providers so consumers can branch on one field.
 Node, edge, depth, kind, direction, and token bounds are independent. The cursor fingerprint covers semantic filters and traversal shape, so it is rejected when reused for a different root or query. Output remains a plain object suitable for TOON, JSON, JSONL, MCP, or a custom UI; adapters own rendering and do not reimplement traversal.
-The native adapter is `pm deps <id> --format context`. It is also available through `PmClient.deps`, `runAction({ action: "deps" })`, and the MCP `pm_deps` tool. `--max-depth`, `--node-limit`, `--edge-limit`, `--token-budget`, and `--cursor` map directly to the public SDK context options; `--summary` keeps only counts. Tree and graph formats remain compatible.
+The native adapter is `pm deps <id> --format context`. It is also available through `PmClient.deps`, `runAction({ action: "deps" })`, and the MCP `pm_deps` tool. `--max-depth`, `--node-limit`, `--edge-limit`, `--token-budget`, `--cursor`, `--direction`, and repeatable or comma-separated `--kind` map directly to the public SDK context options; `--summary` keeps only counts. Unknown `--kind` values fail fast with the registered-kind list instead of silently matching nothing. Tree and graph formats remain compatible.
+The context result also enumerates broken references instead of reporting a bare count: `missing_count` counts missing nodes reachable within the same bounded traversal that produced the packet (so it agrees with tree/graph semantics for equal traversal parameters and is documented by `missing_scope: "traversal"`), and `missing_references` lists each dangling declaration inside the packet with its declaring holder, dangling target, kind, source surface, and `legacy_terminal` classification so agents can separate repairable typos on active items from ignorable historical debt. `--edge-limit` caps both returned graph edges and enumerated missing-reference rows; `missing_reference_count` preserves the untruncated declaration total. The root's linked files, tests, docs, and annotation counts are promoted into `evidence` as bounded pointers.
 ```bash
 pm deps pm-example --format context --max-depth 3 \
-  --node-limit 20 --edge-limit 40 --token-budget 800
+  --node-limit 20 --edge-limit 40 --token-budget 800 \
+  --direction both --kind blocked_by,parent
 ```
 ```ts
@@ -102,6 +109,95 @@ const packet = buildRelationshipContext(
 );
 ```
+## Semantic traversal and governance
+The `@unbrained/pm-cli/sdk` barrel exports registry-aware traversal primitives
+for domain packages that need more than generic adjacency:
+- `hierarchyAncestors` and `hierarchyDescendants` follow only hierarchy kinds
+  and honor each kind's declared parent endpoint.
+- `orderingPredecessors` and `orderingSuccessors` follow only order-bearing
+  kinds and honor declared precedence, so inverse spellings agree.
+- `enumerateRelationshipPaths` returns bounded simple paths with edge evidence,
+  cost metadata, cancellation, direction/kind filters, and explicit truncation.
+All semantic walks are breadth-first and deterministic. `limit`, `maxDepth`,
+and `after` provide bounded continuation for hierarchy and ordering walks;
+path enumeration separately bounds returned paths and expanded partial paths.
+Unknown kinds and cursors fail fast instead of silently degrading context.
+`assembleWorkspaceRelationshipGraph` is the shared normalization seam for
+dependency-shaped workspaces. It folds parent links, the legacy scalar
+`blocked_by`, and structured dependency edges into one graph, materializes
+missing endpoints as explainable placeholder nodes, and returns active versus
+terminal dangling-reference partitions. Domain adapters pass their
+`RelationshipKindRegistry` as the optional third argument so custom VCS,
+company, or package-defined edges survive assembly with their registered
+semantics. `auditWorkspaceRelationshipGraph`
+consumes that assembly and emits counts-first findings for active/terminal
+missing references, retired sentinels, ordering cycles, stale lifecycle blocks,
+and sparse or isolated active nodes. Findings include stable codes, severity,
+bounded deterministic samples, truncation, policy text, and safe remediation;
+the audit never invents an edge. Explicit isolate exemptions suppress policy
+findings without changing structural coverage metrics.
+```ts
+import {
+  assembleWorkspaceRelationshipGraph,
+  auditWorkspaceRelationshipGraph,
+  orderingPredecessors,
+} from "@unbrained/pm-cli/sdk";
+const assembly = assembleWorkspaceRelationshipGraph(items, isTerminalStatus);
+const prerequisites = orderingPredecessors(assembly.graph, "deploy", {
+  limit: 20,
+  maxDepth: 4,
+});
+const governance = auditWorkspaceRelationshipGraph(assembly, {
+  isTerminal: isTerminalStatus,
+  exemptIsolates: ["company-root"],
+  maxSampleSize: 25,
+});
+```
+The three layers are intentionally separate: assembly owns storage-shape
+normalization, traversal owns semantic graph algorithms, and governance owns
+policy findings. A VCS, company operating model, digital twin, or other
+non-project domain can replace the assembly adapter while reusing the same
+registry, traversal, event, context, and audit contracts.
+The native workspace adapter is `pm graph <subcommand>`, also available as
+`PmClient.graph`, `runAction({ action: "graph" })`, and the MCP `pm_graph`
+tool. `ancestors`/`descendants`/`predecessors`/`successors` expose the
+semantic walks, `paths` exposes bounded simple-path enumeration, `impact`
+exposes reverse-reachability blast radius from `analyzeGraphImpact`,
+`analyze` combines `analyzeRelationshipExecution` and `analyzeKnowledgeGraph`
+into one counts-first workspace projection, and `audit` runs
+`auditWorkspaceRelationshipGraph` with `--sample` and `--exempt-isolate`
+policy controls. `communities` exposes `detectRelationshipCommunities`
+(deterministic asynchronous label propagation with lexicographic
+tie-breaking), `redundancy` exposes `findRedundantRelationshipEdges`
+(transitive-reduction scan over ordering and hierarchy families in semantic
+orientation, each finding carrying a bounded witness path), and `dominators`
+exposes `computeRelationshipDominators` (Cooper–Harvey–Kennedy immediate
+dominators over the root's reachable subgraph, ranking structural
+bottlenecks by gated work), and `plan` exposes `planRelationshipRemediation`
+(dry-run remediation proposals derived from audit findings and witnessed
+redundancy rows, each carrying an exact operation, policy code, evidence,
+rationale, and confidence — never auto-applied). The audit gates finding
+severity on lifecycle: contradictions confined to terminal items report as
+informational `legacy_ordering_cycle`/`legacy_duplicate_edge` history debt,
+while `ordering_cycle` errors and `duplicate_edge` findings require at least
+one active subject; `duplicate_edge` covers parallel same-family spellings,
+reciprocal inverse pairs included, which transitive-reduction redundancy
+deliberately skips. All subcommands resolve the workspace assembly through
+the shared fingerprint-keyed graph cache (`WorkspaceGraphCache`): the
+fingerprint digests every relationship-relevant item field, so unchanged
+workspaces in long-lived hosts reuse the assembled graph and memoized query
+results, and every envelope reports `cache` hit/miss observability next to
+its explicit `truncated` and `cost` metadata. Ids resolve
+case-insensitively; `--summary` returns envelopes without row collections.
 ## Compatibility and migration
 Aliases normalize at registry boundaries; stored values are not silently rewritten. Imports must carry or select a compatible registry version. Federation merges definitions before edges and rejects identifier or alias collisions. Rollback removes the custom definition and its derived index only after application-owned edges have been exported or superseded; immutable history is retained.