@unbrained/pm-cli 2026.5.18 → 2026.5.27

package/dist/cli/commands/learnings.js

@@ -1,124 +1,25 @@
 
-!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]="639c3678-d362-5aaa-ad2e-b3f2138d3ef7")}catch(e){}}();
-import { pathExists } from "../../core/fs/fs-utils.js";
-import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
-import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
-import { EXIT_CODE } from "../../core/shared/constants.js";
-import { PmCliError } from "../../core/shared/errors.js";
-import { nowIso } from "../../core/shared/time.js";
-import { createStdinTokenResolver, parseCsvKv } from "../../core/item/parse.js";
-import { locateItem, mutateItem, readLocatedItem } from "../../core/store/item-store.js";
-import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
-import { readSettings } from "../../core/store/settings.js";
-import { parseLimit } from "../shared-parsers.js";
-function resolveAuthor(candidate, fallback) {
-    const resolved = candidate ?? process.env.PM_AUTHOR ?? fallback;
-    const trimmed = resolved.trim();
-    return trimmed || "unknown";
-}
-function limitLearnings(values, limit) {
-    if (limit === undefined)
-        return values;
-    if (limit === 0)
-        return [];
-    return values.slice(Math.max(0, values.length - limit));
-}
-function parseLearningTextInput(raw) {
-    const trimmed = raw.trim();
-    if (!trimmed) {
-        return "";
-    }
-    const looksStructured = /^(?:[-*+]\s*)?text\s*[:=]/im.test(trimmed) || trimmed.startsWith("```");
-    if (!looksStructured) {
-        return trimmed;
-    }
-    try {
-        const kv = parseCsvKv(trimmed, "--add");
-        const keys = Object.keys(kv).map((key) => key.trim().toLowerCase());
-        if (keys.some((key) => key !== "text")) {
-            return trimmed;
-        }
-        const text = kv.text?.trim();
-        return text || trimmed;
-    }
-    catch {
-        return trimmed;
-    }
-}
+!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]="34fecc22-cb1c-5cf6-b68d-8a89f6d07692")}catch(e){}}();
+import { createStdinTokenResolver } from "../../core/item/parse.js";
+import { parseAnnotationTextInput, runAnnotationCommand } from "./annotation-command.js";
 export async function runLearnings(id, options, global) {
     const stdinResolver = createStdinTokenResolver();
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
-    const settings = await readSettings(pmRoot);
-    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
-    const limit = parseLimit(options.limit);
-    if (options.add === undefined) {
-        const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
-        if (!located) {
-            throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);
-        }
-        const loaded = await readLocatedItem(located, { schema: settings.schema });
-        const learnings = limitLearnings(loaded.document.metadata.learnings ?? [], limit);
-        return {
-            id: located.id,
-            learnings,
-            count: learnings.length,
-        };
-    }
-    const author = resolveAuthor(options.author, settings.author_default);
-    const addInput = await stdinResolver.resolveValue(options.add, "--add");
-    const text = parseLearningTextInput(addInput ?? "");
-    if (!text) {
-        throw new PmCliError("--add text cannot be empty", EXIT_CODE.USAGE);
-    }
-    let result;
-    try {
-        result = await mutateItem({
-            pmRoot,
-            settings,
-            id,
-            op: "learning_add",
-            author,
-            message: options.message,
-            force: options.force,
-            bypassAssigneeConflict: Boolean(options.allowAuditLearning || options.allowAuditComment),
-            mutate(document) {
-                const learnings = document.metadata.learnings ?? [];
-                learnings.push({
-                    created_at: nowIso(),
-                    author,
-                    text,
-                });
-                document.metadata.learnings = learnings;
-                return { changedFields: ["learnings"] };
-            },
-        });
-    }
-    catch (error) {
-        if (error instanceof PmCliError &&
-            error.exitCode === EXIT_CODE.CONFLICT &&
-            error.message.includes("is assigned to") &&
-            error.message.includes("Use --force to override")) {
-            throw new PmCliError(error.message, error.exitCode, {
-                code: "ownership_conflict",
-                required: "For append-only learning audits on another owner's item, prefer --allow-audit-learning (legacy alias: --allow-audit-comment) before considering --force.",
-                examples: ['pm learnings pm-a1b2 --add "audit learning" --author "reviewer" --allow-audit-learning'],
-                nextSteps: [
-                    "Retry with --allow-audit-learning (or legacy --allow-audit-comment) for append-only learning audits that do not mutate item metadata beyond learnings.",
-                    "Use --force only when an ownership override is explicitly approved.",
-                ],
-            });
-        }
-        throw error;
-    }
-    const learnings = limitLearnings(result.item.learnings, limit);
-    return {
-        id: result.item.id,
-        learnings,
-        count: learnings.length,
-    };
+    const addInput = options.add === undefined ? undefined : await stdinResolver.resolveValue(options.add, "--add");
+    return runAnnotationCommand(id, options, global, {
+        input: options.add === undefined ? { mode: "list" } : { mode: "add", value: addInput ?? "", emptyFlag: "--add" },
+        collectionKey: "learnings",
+        op: "learning_add",
+        parseText: (raw) => parseAnnotationTextInput(raw),
+        allowAuditBypass: Boolean(options.allowAuditLearning || options.allowAuditComment),
+        conflictGuidance: {
+            required: "For append-only learning audits on another owner's item, prefer --allow-audit-learning (legacy alias: --allow-audit-comment) before considering --force.",
+            examples: ['pm learnings pm-a1b2 --add "audit learning" --author "reviewer" --allow-audit-learning'],
+            nextSteps: [
+                "Retry with --allow-audit-learning (or legacy --allow-audit-comment) for append-only learning audits that do not mutate item metadata beyond learnings.",
+                "Use --force only when an ownership override is explicitly approved.",
+            ],
+        },
+    });
 }
 //# sourceMappingURL=learnings.js.map
-//# debugId=639c3678-d362-5aaa-ad2e-b3f2138d3ef7
+//# debugId=34fecc22-cb1c-5cf6-b68d-8a89f6d07692

package/dist/cli/commands/learnings.js.map

@@ -1 +1 @@
-{"version":3,"file":"learnings.js","sources":["cli/commands/learnings.ts"],"sourceRoot":"/","sourcesContent":["import { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { getActiveExtensionRegistrations } from \"../../core/extensions/index.js\";\nimport { resolveItemTypeRegistry } from \"../../core/item/type-registry.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 { nowIso } from \"../../core/shared/time.js\";\nimport { createStdinTokenResolver, parseCsvKv } from \"../../core/item/parse.js\";\nimport { locateItem, mutateItem, readLocatedItem } from \"../../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport { parseLimit } from \"../shared-parsers.js\";\nimport type { LogNote } from \"../../types/index.js\";\n\nexport interface LearningsCommandOptions {\n  add?: string;\n  limit?: string;\n  author?: string;\n  message?: string;\n  allowAuditLearning?: boolean;\n  allowAuditComment?: boolean;\n  force?: boolean;\n}\n\nexport interface LearningsResult {\n  id: string;\n  learnings: LogNote[];\n  count: number;\n}\n\nfunction resolveAuthor(candidate: string | undefined, fallback: string): string {\n  const resolved = candidate ?? process.env.PM_AUTHOR ?? fallback;\n  const trimmed = resolved.trim();\n  return trimmed || \"unknown\";\n}\n\nfunction limitLearnings(values: LogNote[], limit: number | undefined): LogNote[] {\n  if (limit === undefined) return values;\n  if (limit === 0) return [];\n  return values.slice(Math.max(0, values.length - limit));\n}\n\nfunction parseLearningTextInput(raw: string): string {\n  const trimmed = raw.trim();\n  if (!trimmed) {\n    return \"\";\n  }\n  const looksStructured = /^(?:[-*+]\\s*)?text\\s*[:=]/im.test(trimmed) || trimmed.startsWith(\"```\");\n  if (!looksStructured) {\n    return trimmed;\n  }\n  try {\n    const kv = parseCsvKv(trimmed, \"--add\");\n    const keys = Object.keys(kv).map((key) => key.trim().toLowerCase());\n    if (keys.some((key) => key !== \"text\")) {\n      return trimmed;\n    }\n    const text = kv.text?.trim();\n    return text || trimmed;\n  } catch {\n    return trimmed;\n  }\n}\n\nexport async function runLearnings(\n  id: string,\n  options: LearningsCommandOptions,\n  global: GlobalOptions,\n): Promise<LearningsResult> {\n  const stdinResolver = createStdinTokenResolver();\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);\n  }\n  const settings = await readSettings(pmRoot);\n  const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());\n  const limit = parseLimit(options.limit);\n\n  if (options.add === undefined) {\n    const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);\n    if (!located) {\n      throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);\n    }\n    const loaded = await readLocatedItem(located, { schema: settings.schema });\n    const learnings = limitLearnings(loaded.document.metadata.learnings ?? [], limit);\n    return {\n      id: located.id,\n      learnings,\n      count: learnings.length,\n    };\n  }\n\n  const author = resolveAuthor(options.author, settings.author_default);\n  const addInput = await stdinResolver.resolveValue(options.add, \"--add\");\n  const text = parseLearningTextInput(addInput ?? \"\");\n  if (!text) {\n    throw new PmCliError(\"--add text cannot be empty\", EXIT_CODE.USAGE);\n  }\n\n  let result: Awaited<ReturnType<typeof mutateItem>>;\n  try {\n    result = await mutateItem({\n      pmRoot,\n      settings,\n      id,\n      op: \"learning_add\",\n      author,\n      message: options.message,\n      force: options.force,\n      bypassAssigneeConflict: Boolean(options.allowAuditLearning || options.allowAuditComment),\n      mutate(document) {\n        const learnings = document.metadata.learnings ?? [];\n        learnings.push({\n          created_at: nowIso(),\n          author,\n          text,\n        });\n        document.metadata.learnings = learnings;\n        return { changedFields: [\"learnings\"] };\n      },\n    });\n  } catch (error: unknown) {\n    if (\n      error instanceof PmCliError &&\n      error.exitCode === EXIT_CODE.CONFLICT &&\n      error.message.includes(\"is assigned to\") &&\n      error.message.includes(\"Use --force to override\")\n    ) {\n      throw new PmCliError(error.message, error.exitCode, {\n        code: \"ownership_conflict\",\n        required:\n          \"For append-only learning audits on another owner's item, prefer --allow-audit-learning (legacy alias: --allow-audit-comment) before considering --force.\",\n        examples: ['pm learnings pm-a1b2 --add \"audit learning\" --author \"reviewer\" --allow-audit-learning'],\n        nextSteps: [\n          \"Retry with --allow-audit-learning (or legacy --allow-audit-comment) for append-only learning audits that do not mutate item metadata beyond learnings.\",\n          \"Use --force only when an ownership override is explicitly approved.\",\n        ],\n      });\n    }\n    throw error;\n  }\n\n  const learnings = limitLearnings(result.item.learnings as LogNote[], limit);\n  return {\n    id: result.item.id,\n    learnings,\n    count: learnings.length,\n  };\n}\n"],"names":[],"mappings":"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","debugId":"639c3678-d362-5aaa-ad2e-b3f2138d3ef7"}
+{"version":3,"file":"learnings.js","sources":["cli/commands/learnings.ts"],"sourceRoot":"/","sourcesContent":["import type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { createStdinTokenResolver } from \"../../core/item/parse.js\";\nimport type { LogNote } from \"../../types/index.js\";\nimport { parseAnnotationTextInput, runAnnotationCommand } from \"./annotation-command.js\";\n\nexport interface LearningsCommandOptions {\n  add?: string;\n  limit?: string;\n  author?: string;\n  message?: string;\n  allowAuditLearning?: boolean;\n  allowAuditComment?: boolean;\n  force?: boolean;\n}\n\nexport interface LearningsResult {\n  id: string;\n  learnings: LogNote[];\n  count: number;\n}\n\nexport async function runLearnings(\n  id: string,\n  options: LearningsCommandOptions,\n  global: GlobalOptions,\n): Promise<LearningsResult> {\n  const stdinResolver = createStdinTokenResolver();\n  const addInput = options.add === undefined ? undefined : await stdinResolver.resolveValue(options.add, \"--add\");\n\n  return runAnnotationCommand<\"learnings\", LogNote>(id, options, global, {\n    input: options.add === undefined ? { mode: \"list\" } : { mode: \"add\", value: addInput ?? \"\", emptyFlag: \"--add\" },\n    collectionKey: \"learnings\",\n    op: \"learning_add\",\n    parseText: (raw) => parseAnnotationTextInput(raw),\n    allowAuditBypass: Boolean(options.allowAuditLearning || options.allowAuditComment),\n    conflictGuidance: {\n      required:\n        \"For append-only learning audits on another owner's item, prefer --allow-audit-learning (legacy alias: --allow-audit-comment) before considering --force.\",\n      examples: ['pm learnings pm-a1b2 --add \"audit learning\" --author \"reviewer\" --allow-audit-learning'],\n      nextSteps: [\n        \"Retry with --allow-audit-learning (or legacy --allow-audit-comment) for append-only learning audits that do not mutate item metadata beyond learnings.\",\n        \"Use --force only when an ownership override is explicitly approved.\",\n      ],\n    },\n  });\n}\n"],"names":[],"mappings":";;AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,OAAO,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAkBzF,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,EAAU,EACV,OAAgC,EAChC,MAAqB;IAErB,MAAM,aAAa,GAAG,wBAAwB,EAAE,CAAC;IACjD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,aAAa,CAAC,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAEhH,OAAO,oBAAoB,CAAuB,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE;QACrE,KAAK,EAAE,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,IAAI,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;QAChH,aAAa,EAAE,WAAW;QAC1B,EAAE,EAAE,cAAc;QAClB,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,wBAAwB,CAAC,GAAG,CAAC;QACjD,gBAAgB,EAAE,OAAO,CAAC,OAAO,CAAC,kBAAkB,IAAI,OAAO,CAAC,iBAAiB,CAAC;QAClF,gBAAgB,EAAE;YAChB,QAAQ,EACN,0JAA0J;YAC5J,QAAQ,EAAE,CAAC,wFAAwF,CAAC;YACpG,SAAS,EAAE;gBACT,wJAAwJ;gBACxJ,qEAAqE;aACtE;SACF;KACF,CAAC,CAAC;AACL,CAAC","debugId":"34fecc22-cb1c-5cf6-b68d-8a89f6d07692"}

package/dist/cli/commands/legacy-none-tokens.d.ts

@@ -0,0 +1,3 @@
+export declare function isLegacyNoneToken(value: string | undefined): boolean;
+export declare function assertNoLegacyNoneToken(value: string | undefined, flag: string, replacementHint?: string): void;
+export declare function assertNoLegacyNoneTokens(values: string[] | undefined, flag: string, replacementHint?: string): void;

package/dist/cli/commands/legacy-none-tokens.js

@@ -0,0 +1,39 @@
+
+!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]="4e8ab87c-f133-56a8-bf3e-e0f371b72197")}catch(e){}}();
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+/**
+ * Shared legacy "none"/"null" sentinel handling for the create and update
+ * commands. These tokens used to mean "clear this field"; they are now
+ * rejected in favour of explicit --unset / --clear-* flags.
+ *
+ * Extracted verbatim from create.ts and update.ts (pm-why9) — behaviour and
+ * error strings are identical to the previous per-command copies.
+ */
+const LEGACY_NONE_TOKENS = new Set(["none", "null"]);
+export function isLegacyNoneToken(value) {
+    if (value === undefined) {
+        return false;
+    }
+    return LEGACY_NONE_TOKENS.has(value.trim().toLowerCase());
+}
+export function assertNoLegacyNoneToken(value, flag, replacementHint) {
+    if (!isLegacyNoneToken(value)) {
+        return;
+    }
+    const suffix = replacementHint ? ` ${replacementHint}` : "";
+    throw new PmCliError(`${flag} no longer accepts "none" or "null".${suffix}`.trim(), EXIT_CODE.USAGE);
+}
+export function assertNoLegacyNoneTokens(values, flag, replacementHint) {
+    if (!values || values.length === 0) {
+        return;
+    }
+    const hasLegacyToken = values.some((value) => isLegacyNoneToken(value));
+    if (!hasLegacyToken) {
+        return;
+    }
+    const suffix = replacementHint ? ` ${replacementHint}` : "";
+    throw new PmCliError(`${flag} no longer accepts "none" or "null".${suffix}`.trim(), EXIT_CODE.USAGE);
+}
+//# sourceMappingURL=legacy-none-tokens.js.map
+//# debugId=4e8ab87c-f133-56a8-bf3e-e0f371b72197

package/dist/cli/commands/legacy-none-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-none-tokens.js","sources":["cli/commands/legacy-none-tokens.ts"],"sourceRoot":"/","sourcesContent":["import { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\n\n/**\n * Shared legacy \"none\"/\"null\" sentinel handling for the create and update\n * commands. These tokens used to mean \"clear this field\"; they are now\n * rejected in favour of explicit --unset / --clear-* flags.\n *\n * Extracted verbatim from create.ts and update.ts (pm-why9) — behaviour and\n * error strings are identical to the previous per-command copies.\n */\nconst LEGACY_NONE_TOKENS = new Set([\"none\", \"null\"]);\n\nexport function isLegacyNoneToken(value: string | undefined): boolean {\n  if (value === undefined) {\n    return false;\n  }\n  return LEGACY_NONE_TOKENS.has(value.trim().toLowerCase());\n}\n\nexport function assertNoLegacyNoneToken(value: string | undefined, flag: string, replacementHint?: string): void {\n  if (!isLegacyNoneToken(value)) {\n    return;\n  }\n  const suffix = replacementHint ? ` ${replacementHint}` : \"\";\n  throw new PmCliError(`${flag} no longer accepts \"none\" or \"null\".${suffix}`.trim(), EXIT_CODE.USAGE);\n}\n\nexport function assertNoLegacyNoneTokens(values: string[] | undefined, flag: string, replacementHint?: string): void {\n  if (!values || values.length === 0) {\n    return;\n  }\n  const hasLegacyToken = values.some((value) => isLegacyNoneToken(value));\n  if (!hasLegacyToken) {\n    return;\n  }\n  const suffix = replacementHint ? ` ${replacementHint}` : \"\";\n  throw new PmCliError(`${flag} no longer accepts \"none\" or \"null\".${suffix}`.trim(), EXIT_CODE.USAGE);\n}\n"],"names":[],"mappings":";;AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEzD;;;;;;;GAOG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAErD,MAAM,UAAU,iBAAiB,CAAC,KAAyB;IACzD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,KAAyB,EAAE,IAAY,EAAE,eAAwB;IACvG,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO;IACT,CAAC;IACD,MAAM,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,IAAI,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5D,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,uCAAuC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;AACvG,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,MAA4B,EAAE,IAAY,EAAE,eAAwB;IAC3G,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,OAAO;IACT,CAAC;IACD,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,OAAO;IACT,CAAC;IACD,MAAM,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,IAAI,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5D,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,uCAAuC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;AACvG,CAAC","debugId":"4e8ab87c-f133-56a8-bf3e-e0f371b72197"}

package/dist/cli/commands/linked-artifacts.d.ts

@@ -0,0 +1,96 @@
+import type { GlobalOptions } from "../../core/shared/command-types.js";
+import type { LinkScope } from "../../types/index.js";
+export type LinkedArtifact = {
+    path: string;
+    scope: LinkScope;
+    note?: string;
+};
+export interface LinkedArtifactCommandOptions {
+    add?: string[];
+    addGlob?: string[];
+    remove?: string[];
+    migrate?: string[];
+    list?: boolean;
+    appendStable?: boolean;
+    validatePaths?: boolean;
+    audit?: boolean;
+    author?: string;
+    message?: string;
+    force?: boolean;
+}
+export interface PathMigration {
+    from: string;
+    to: string;
+}
+export interface AddGlobEntry {
+    pattern: string;
+    scope: LinkScope;
+    note?: string;
+}
+export interface LinkedPathValidation {
+    checked: number;
+    existing_files: string[];
+    missing_paths: string[];
+    non_file_paths: string[];
+}
+export interface LinkedPathAuditEntry {
+    path: string;
+    linked_by_count: number;
+    linked_item_ids: string[];
+}
+export interface LinkedArtifactResult {
+    id: string;
+    changed: boolean;
+    count: number;
+    migrations_applied?: number;
+    validation?: LinkedPathValidation;
+    audit?: LinkedPathAuditEntry[];
+    artifacts: LinkedArtifact[];
+}
+/**
+ * Configuration that adapts the shared linked-artifact command core to a
+ * specific resource kind (files or docs) while preserving every behavioral
+ * detail of the original twin implementations.
+ */
+export interface LinkedArtifactKindConfig {
+    /** Metadata key under which the artifacts are stored (e.g. "files" | "docs"). */
+    metadataKey: "files" | "docs";
+    /** Mutation op recorded in history (e.g. "files_add" | "docs_add"). */
+    op: "files_add" | "docs_add";
+    /** Noun used in the "bare <noun> path" --add usage error (e.g. "file" | "doc"). */
+    bareNoun: "file" | "doc";
+    /**
+     * Whether this kind honors the append-stable option. files supports it;
+     * docs always sorts and must never expose append-stable behavior.
+     */
+    supportsAppendStable: boolean;
+}
+export declare function ensureScope(raw: string | undefined): LinkScope;
+export declare function looksLikeStructuredPathEntry(raw: string): boolean;
+export declare function parseAddEntries(raw: string[] | undefined, bareNoun: "file" | "doc"): LinkedArtifact[];
+export declare function parseAddGlobEntries(raw: string[] | undefined): AddGlobEntry[];
+export declare function parseRemoveEntries(raw: string[] | undefined): string[];
+export declare function parseMigrateEntries(raw: string[] | undefined): PathMigration[];
+export declare function applyPathMigrations(artifactPath: string, migrations: PathMigration[]): string;
+export declare function normalizeLinkedPath(value: string): string;
+export declare function expandAddGlobEntries(entries: AddGlobEntry[]): Promise<LinkedArtifact[]>;
+export declare function artifactKey(value: Pick<LinkedArtifact, "path" | "scope">): string;
+export declare function sortLinkedArtifacts(artifacts: LinkedArtifact[]): LinkedArtifact[];
+export declare function dedupeLinkedArtifacts(artifacts: LinkedArtifact[]): LinkedArtifact[];
+export declare function validateLinkedPaths(paths: string[]): Promise<LinkedPathValidation>;
+export declare function buildLinkedPathAudit(paths: string[], allItems: Array<{
+    id: string;
+    artifacts?: LinkedArtifact[];
+}>): LinkedPathAuditEntry[];
+/**
+ * Shared linked-artifact list/mutate command core used by runFiles and runDocs.
+ * The kind config selects metadata key, op, bare-path noun, and whether
+ * append-stable ordering is honored, preserving each twin's exact semantics.
+ */
+export declare function runLinkedArtifacts(id: string, options: LinkedArtifactCommandOptions, global: GlobalOptions, config: LinkedArtifactKindConfig): Promise<LinkedArtifactResult>;
+/**
+ * Re-key the generic `artifacts` field to the resource-specific name (files/docs)
+ * while preserving the original key order and presence so kind-specific result
+ * shapes (and their deterministic JSON key ordering) stay byte-identical.
+ */
+export declare function renameArtifactsResultKey(result: LinkedArtifactResult, key: "files" | "docs"): Record<string, unknown>;

package/dist/cli/commands/linked-artifacts.js

@@ -0,0 +1,335 @@
+
+!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]="352e67e3-0c41-5c04-8d2d-3395c6216303")}catch(e){}}();
+import fs from "node:fs/promises";
+import path from "node:path";
+import fg from "fast-glob";
+import { pathExists } from "../../core/fs/fs-utils.js";
+import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
+import { createStdinTokenResolver, parseCsvKv } from "../../core/item/parse.js";
+import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { listAllFrontMatter, locateItem, mutateItem, readLocatedItem } from "../../core/store/item-store.js";
+import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
+import { readSettings } from "../../core/store/settings.js";
+import { SCOPE_VALUES } from "../../types/index.js";
+import { resolveAuthor } from "../../core/shared/author.js";
+export function ensureScope(raw) {
+    const value = (raw ?? "project");
+    if (!SCOPE_VALUES.includes(value)) {
+        throw new PmCliError(`Invalid scope "${raw}". Valid scopes: ${SCOPE_VALUES.join(", ")} (default: project).`, EXIT_CODE.USAGE);
+    }
+    return value;
+}
+export function looksLikeStructuredPathEntry(raw) {
+    if (raw.startsWith("```") || raw.includes("\n")) {
+        return true;
+    }
+    return /^(?:[-*+]\s+)?(?:path|scope|note)\s*[:=]/i.test(raw);
+}
+export function parseAddEntries(raw, bareNoun) {
+    if (!raw)
+        return [];
+    return raw.map((entry) => {
+        const trimmed = entry.trim();
+        const kv = looksLikeStructuredPathEntry(trimmed) ? parseCsvKv(entry, "--add") : { path: trimmed };
+        if (!kv.path) {
+            throw new PmCliError(`--add requires path=<value> or a bare ${bareNoun} path`, EXIT_CODE.USAGE);
+        }
+        return {
+            path: kv.path,
+            scope: ensureScope(kv.scope),
+            note: kv.note?.trim() || undefined,
+        };
+    });
+}
+export function parseAddGlobEntries(raw) {
+    if (!raw)
+        return [];
+    return raw.map((entry) => {
+        const trimmed = entry.trim();
+        if (!trimmed) {
+            throw new PmCliError("--add-glob requires a glob pattern value", EXIT_CODE.USAGE);
+        }
+        if (trimmed.includes("=") || /^(?:[-*+]\s+)?(?:pattern|glob|path)\s*[:=]/i.test(trimmed) || trimmed.startsWith("```")) {
+            const kv = parseCsvKv(trimmed, "--add-glob");
+            const pattern = kv.pattern?.trim() || kv.glob?.trim() || kv.path?.trim();
+            if (!pattern) {
+                throw new PmCliError("--add-glob key/value form requires pattern=<glob>", EXIT_CODE.USAGE);
+            }
+            return {
+                pattern,
+                scope: ensureScope(kv.scope),
+                note: kv.note?.trim() || undefined,
+            };
+        }
+        return {
+            pattern: trimmed,
+            scope: "project",
+        };
+    });
+}
+export function parseRemoveEntries(raw) {
+    if (!raw)
+        return [];
+    return raw.map((entry) => {
+        const trimmed = entry.trim();
+        if (!trimmed) {
+            throw new PmCliError("--remove requires a path value", EXIT_CODE.USAGE);
+        }
+        if (trimmed.includes("=") || /^(?:[-*+]\s+)?path\s*[:=]/i.test(trimmed) || trimmed.startsWith("```")) {
+            const kv = parseCsvKv(trimmed, "--remove");
+            if (!kv.path) {
+                throw new PmCliError("--remove key/value form requires path=<value>", EXIT_CODE.USAGE);
+            }
+            return kv.path;
+        }
+        return trimmed;
+    });
+}
+export function parseMigrateEntries(raw) {
+    if (!raw)
+        return [];
+    return raw.map((entry) => {
+        const kv = parseCsvKv(entry, "--migrate");
+        const from = kv.from?.trim();
+        const to = kv.to?.trim();
+        if (!from || !to) {
+            throw new PmCliError("--migrate requires from=<value> and to=<value>", EXIT_CODE.USAGE);
+        }
+        return { from, to };
+    });
+}
+export function applyPathMigrations(artifactPath, migrations) {
+    let next = artifactPath;
+    for (const migration of migrations) {
+        if (next.startsWith(migration.from)) {
+            next = `${migration.to}${next.slice(migration.from.length)}`;
+        }
+    }
+    return next;
+}
+export function normalizeLinkedPath(value) {
+    return value.split(path.sep).join("/");
+}
+export async function expandAddGlobEntries(entries) {
+    const expanded = [];
+    for (const entry of entries) {
+        const absolutePattern = path.isAbsolute(entry.pattern);
+        const matches = await fg(entry.pattern, {
+            cwd: process.cwd(),
+            absolute: absolutePattern,
+            onlyFiles: true,
+            dot: true,
+            unique: true,
+            followSymbolicLinks: true,
+        });
+        const sortedMatches = [...new Set(matches.map((match) => normalizeLinkedPath(path.normalize(match))))].sort((left, right) => left.localeCompare(right));
+        for (const matchedPath of sortedMatches) {
+            expanded.push({
+                path: matchedPath,
+                scope: entry.scope,
+                note: entry.note,
+            });
+        }
+    }
+    return expanded;
+}
+export function artifactKey(value) {
+    return `${value.path}::${value.scope}`;
+}
+export function sortLinkedArtifacts(artifacts) {
+    return [...artifacts].sort((left, right) => {
+        const byPath = left.path.localeCompare(right.path);
+        if (byPath !== 0)
+            return byPath;
+        return left.scope.localeCompare(right.scope);
+    });
+}
+export function dedupeLinkedArtifacts(artifacts) {
+    return [...new Map(artifacts.map((entry) => [artifactKey(entry), entry])).values()].map((entry) => ({
+        ...entry,
+        note: entry.note?.trim() || undefined,
+    }));
+}
+export async function validateLinkedPaths(paths) {
+    const uniquePaths = [...new Set(paths)].sort((left, right) => left.localeCompare(right));
+    const existingFiles = [];
+    const missingPaths = [];
+    const nonFilePaths = [];
+    for (const relativePath of uniquePaths) {
+        const resolvedPath = path.isAbsolute(relativePath) ? relativePath : path.resolve(process.cwd(), relativePath);
+        try {
+            const stats = await fs.stat(resolvedPath);
+            if (stats.isFile()) {
+                existingFiles.push(relativePath);
+            }
+            else {
+                nonFilePaths.push(relativePath);
+            }
+        }
+        catch (error) {
+            if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+                missingPaths.push(relativePath);
+                continue;
+            }
+            nonFilePaths.push(relativePath);
+        }
+    }
+    return {
+        checked: uniquePaths.length,
+        existing_files: existingFiles,
+        missing_paths: missingPaths,
+        non_file_paths: nonFilePaths,
+    };
+}
+export function buildLinkedPathAudit(paths, allItems) {
+    const index = new Map();
+    for (const item of allItems) {
+        for (const linkedArtifact of item.artifacts ?? []) {
+            const seen = index.get(linkedArtifact.path) ?? new Set();
+            seen.add(item.id);
+            index.set(linkedArtifact.path, seen);
+        }
+    }
+    return [...new Set(paths)]
+        .sort((left, right) => left.localeCompare(right))
+        .map((linkedPath) => {
+        const linkedIds = [...(index.get(linkedPath) ?? new Set())].sort((left, right) => left.localeCompare(right));
+        return {
+            path: linkedPath,
+            linked_by_count: linkedIds.length,
+            linked_item_ids: linkedIds,
+        };
+    });
+}
+/**
+ * Shared linked-artifact list/mutate command core used by runFiles and runDocs.
+ * The kind config selects metadata key, op, bare-path noun, and whether
+ * append-stable ordering is honored, preserving each twin's exact semantics.
+ */
+export async function runLinkedArtifacts(id, options, global, config) {
+    const { metadataKey } = config;
+    const stdinResolver = createStdinTokenResolver();
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+    const settings = await readSettings(pmRoot);
+    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
+    const resolvedAdds = await stdinResolver.resolveList(options.add, "--add");
+    const resolvedAddGlobs = await stdinResolver.resolveList(options.addGlob, "--add-glob");
+    const resolvedRemoves = await stdinResolver.resolveList(options.remove, "--remove");
+    const resolvedMigrations = await stdinResolver.resolveList(options.migrate, "--migrate");
+    const parsedAdds = parseAddEntries(resolvedAdds, config.bareNoun);
+    const addGlobs = parseAddGlobEntries(resolvedAddGlobs);
+    const expandedGlobAdds = await expandAddGlobEntries(addGlobs);
+    const adds = [...parsedAdds, ...expandedGlobAdds];
+    const removes = parseRemoveEntries(resolvedRemoves);
+    const migrations = parseMigrateEntries(resolvedMigrations);
+    const shouldMutate = adds.length > 0 || removes.length > 0 || migrations.length > 0;
+    const collectAuditItems = async () => (await listAllFrontMatter(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema)).map((entry) => ({
+        id: entry.id,
+        artifacts: entry[metadataKey],
+    }));
+    if (!shouldMutate) {
+        const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
+        if (!located) {
+            throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);
+        }
+        const loaded = await readLocatedItem(located, { schema: settings.schema });
+        const artifacts = loaded.document.metadata[metadataKey] ?? [];
+        return {
+            id: located.id,
+            artifacts,
+            changed: false,
+            count: artifacts.length,
+            validation: options.validatePaths ? await validateLinkedPaths(artifacts.map((entry) => entry.path)) : undefined,
+            audit: options.audit ? buildLinkedPathAudit(artifacts.map((entry) => entry.path), await collectAuditItems()) : undefined,
+        };
+    }
+    const author = resolveAuthor(options.author, settings.author_default);
+    const result = await mutateItem({
+        pmRoot,
+        settings,
+        id,
+        op: config.op,
+        author,
+        message: options.message,
+        force: options.force,
+        mutate(document) {
+            const metadata = document.metadata;
+            const next = [...(metadata[metadataKey] ?? [])];
+            let migrationCount = 0;
+            if (migrations.length > 0) {
+                for (let index = 0; index < next.length; index += 1) {
+                    const migratedPath = applyPathMigrations(next[index].path, migrations);
+                    if (migratedPath !== next[index].path) {
+                        next[index] = { ...next[index], path: migratedPath };
+                        migrationCount += 1;
+                    }
+                }
+            }
+            const migratedAdds = adds.map((entry) => {
+                const migratedPath = applyPathMigrations(entry.path, migrations);
+                if (migratedPath !== entry.path) {
+                    migrationCount += 1;
+                }
+                return {
+                    ...entry,
+                    path: migratedPath,
+                };
+            });
+            const migratedRemoves = removes.map((entry) => applyPathMigrations(entry, migrations));
+            for (const add of migratedAdds) {
+                const exists = next.some((entry) => entry.path === add.path && entry.scope === add.scope);
+                if (!exists) {
+                    next.push(add);
+                }
+            }
+            if (migratedRemoves.length > 0) {
+                for (let i = next.length - 1; i >= 0; i -= 1) {
+                    if (migratedRemoves.includes(next[i].path)) {
+                        next.splice(i, 1);
+                    }
+                }
+            }
+            const deduped = dedupeLinkedArtifacts(next);
+            const normalized = config.supportsAppendStable && options.appendStable ? deduped : sortLinkedArtifacts(deduped);
+            if (normalized.length > 0) {
+                metadata[metadataKey] = normalized;
+            }
+            else {
+                delete metadata[metadataKey];
+            }
+            return { changedFields: [metadataKey], warnings: migrationCount > 0 ? [`path_migrations_applied:${migrationCount}`] : [] };
+        },
+    });
+    const artifacts = result.item[metadataKey] ?? [];
+    const migrationWarning = result.warnings.find((warning) => warning.startsWith("path_migrations_applied:"));
+    const migrationCount = migrationWarning ? Number(migrationWarning.slice("path_migrations_applied:".length)) : 0;
+    const allItems = options.audit ? await collectAuditItems() : [];
+    return {
+        id: result.item.id,
+        artifacts,
+        changed: true,
+        count: artifacts.length,
+        migrations_applied: migrationCount > 0 ? migrationCount : undefined,
+        validation: options.validatePaths ? await validateLinkedPaths(artifacts.map((entry) => entry.path)) : undefined,
+        audit: options.audit ? buildLinkedPathAudit(artifacts.map((entry) => entry.path), allItems) : undefined,
+    };
+}
+/**
+ * Re-key the generic `artifacts` field to the resource-specific name (files/docs)
+ * while preserving the original key order and presence so kind-specific result
+ * shapes (and their deterministic JSON key ordering) stay byte-identical.
+ */
+export function renameArtifactsResultKey(result, key) {
+    const out = {};
+    for (const [field, value] of Object.entries(result)) {
+        out[field === "artifacts" ? key : field] = value;
+    }
+    return out;
+}
+//# sourceMappingURL=linked-artifacts.js.map
+//# debugId=352e67e3-0c41-5c04-8d2d-3395c6216303