@unbrained/pm-cli 2026.7.19 → 2026.7.20

package/dist/sdk/merge/driver.js

@@ -0,0 +1,166 @@
+/**
+ * @module sdk/merge/driver
+ *
+ * File-level git merge driver runner for tracker artifacts. Git invokes the
+ * driver with the base (%O), ours (%A), and theirs (%B) temporary files; the
+ * driver writes the merged content back to the ours path and reports whether
+ * unresolvable conflicts remain. Conflicted artifacts are still written as
+ * parseable documents (resolved toward the preferred side) so a conflicted
+ * merge never corrupts tracker storage the way raw conflict markers do.
+ */
+
+!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]="dcd2575e-24f4-58db-b4ab-d64277c71d7c")}catch(e){}}();
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
+import { collectRegisteredItemFieldNames } from "../../core/extensions/item-fields.js";
+import { pathExists } from "../../core/fs/fs-utils.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { nowIso } from "../../core/shared/time.js";
+import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
+import { readSettings } from "../../core/store/settings.js";
+import { mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, } from "./three-way.js";
+/** Supported values accepted by the merge driver artifact contract across CLI, SDK, and MCP surfaces. */
+export const MERGE_DRIVER_ARTIFACT_VALUES = [
+    "item",
+    "history",
+    "relationship",
+    "json",
+];
+function resolveArtifact(value) {
+    const normalized = value.trim().toLowerCase();
+    if (MERGE_DRIVER_ARTIFACT_VALUES.includes(normalized)) {
+        return normalized;
+    }
+    throw new PmCliError(`Unknown merge artifact "${value}". Supported values: ${MERGE_DRIVER_ARTIFACT_VALUES.join(", ")}.`, EXIT_CODE.USAGE);
+}
+function resolvePreferredSide(value) {
+    if (value === undefined) {
+        return "ours";
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "ours" || normalized === "theirs") {
+        return normalized;
+    }
+    throw new PmCliError(`Unknown --prefer value "${value}". Supported values: ours, theirs.`, EXIT_CODE.USAGE);
+}
+async function readSideFile(filePath, label) {
+    try {
+        return await readFile(filePath, "utf8");
+    }
+    catch {
+        throw new PmCliError(`Cannot read merge ${label} file at ${filePath}.`, EXIT_CODE.NOT_FOUND);
+    }
+}
+/**
+ * Load the workspace settings when a tracker is initialized at the resolved pm
+ * root, or fall back to format defaults when the driver runs outside a tracker
+ * (git can invoke merge drivers before `pm init`, e.g. while rebasing the
+ * commit that introduces the tracker).
+ */
+async function loadOptionalSettings(global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        return null;
+    }
+    return readSettings(pmRoot);
+}
+function itemFormatForPath(filePath, settings) {
+    if (filePath.endsWith(".md")) {
+        return "json_markdown";
+    }
+    if (filePath.endsWith(".toon")) {
+        return "toon";
+    }
+    return settings?.item_format ?? "toon";
+}
+/**
+ * Execute one git merge-driver invocation for a tracker artifact. Reads the
+ * three per-side versions, applies the artifact's field-aware merge semantics,
+ * writes the merged content (parseable even when conflicted) to the output
+ * path, and reports remaining conflicts so the CLI can exit non-zero and let
+ * git mark the path unmerged.
+ */
+export async function runMergeDriver(options, global) {
+    const artifact = resolveArtifact(options.artifact);
+    const preferred = resolvePreferredSide(options.prefer);
+    const outputPath = path.resolve(options.outputPath ?? options.oursPath);
+    const [baseRaw, oursRaw, theirsRaw] = await Promise.all([
+        readSideFile(options.basePath, "base"),
+        readSideFile(options.oursPath, "ours"),
+        readSideFile(options.theirsPath, "theirs"),
+    ]);
+    let merged;
+    const conflicts = [];
+    const result = {};
+    if (artifact === "history") {
+        const historyMerge = mergeHistoryStreams(baseRaw, oursRaw, theirsRaw);
+        merged = historyMerge.merged;
+        result.history = {
+            strategy: historyMerge.strategy,
+            common_entries: historyMerge.common_entries,
+            entries_from_ours: historyMerge.entries_from_ours,
+            entries_from_theirs: historyMerge.entries_from_theirs,
+            entries_total: historyMerge.entries_total,
+            reanchored: historyMerge.reanchored,
+        };
+    }
+    else if (artifact === "relationship") {
+        const relationshipMerge = mergeRelationshipEventStreams(baseRaw, oursRaw, theirsRaw);
+        merged = relationshipMerge.merged;
+        result.relationship = {
+            strategy: relationshipMerge.strategy,
+            common_entries: relationshipMerge.common_entries,
+            entries_from_ours: relationshipMerge.entries_from_ours,
+            entries_from_theirs: relationshipMerge.entries_from_theirs,
+            entries_total: relationshipMerge.entries_total,
+            reanchored: relationshipMerge.reanchored,
+        };
+    }
+    else if (artifact === "item") {
+        const settings = await loadOptionalSettings(global);
+        const itemMerge = mergeItemDocuments(baseRaw, oursRaw, theirsRaw, {
+            format: itemFormatForPath(options.itemPath ?? outputPath, settings),
+            schema: settings?.schema,
+            extensionFieldNames: collectRegisteredItemFieldNames(getActiveExtensionRegistrations()),
+            preferred,
+        });
+        merged = itemMerge.merged;
+        conflicts.push(...itemMerge.conflict_fields);
+        result.item = {
+            fields_from_theirs: itemMerge.fields_from_theirs,
+            union_fields: itemMerge.union_fields,
+        };
+    }
+    else {
+        const jsonMerge = mergeJsonDocuments(baseRaw, oursRaw, theirsRaw, {
+            preferred,
+        });
+        merged = jsonMerge.merged;
+        conflicts.push(...jsonMerge.conflict_paths);
+        result.json = {
+            paths_from_theirs: jsonMerge.paths_from_theirs,
+        };
+    }
+    await writeFile(outputPath, merged, "utf8");
+    const guidance = [];
+    if (conflicts.length > 0) {
+        guidance.push(`Both branches changed ${conflicts.join(", ")}; the ${preferred} value was kept. Review the merged file, re-apply the losing change if needed, then "git add" it.`);
+    }
+    if (artifact === "history" && result.history?.reanchored) {
+        guidance.push('The merged history chain was re-anchored. Run "pm validate --check-history-drift" and "pm history-repair --all" after the merge to reconcile item state with merged history.');
+    }
+    return {
+        ok: conflicts.length === 0,
+        artifact,
+        output_path: outputPath,
+        preferred,
+        conflicts,
+        ...result,
+        guidance,
+        generated_at: nowIso(),
+    };
+}
+//# sourceMappingURL=driver.js.map
+//# debugId=dcd2575e-24f4-58db-b4ab-d64277c71d7c

package/dist/sdk/merge/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sources":["sdk/merge/driver.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/merge/driver\n *\n * File-level git merge driver runner for tracker artifacts. Git invokes the\n * driver with the base (%O), ours (%A), and theirs (%B) temporary files; the\n * driver writes the merged content back to the ours path and reports whether\n * unresolvable conflicts remain. Conflicted artifacts are still written as\n * parseable documents (resolved toward the preferred side) so a conflicted\n * merge never corrupts tracker storage the way raw conflict markers do.\n */\nimport { readFile, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { getActiveExtensionRegistrations } from \"../../core/extensions/index.js\";\nimport { collectRegisteredItemFieldNames } from \"../../core/extensions/item-fields.js\";\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 { nowIso } from \"../../core/shared/time.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport type { ItemFormat, PmSettings } from \"../../types/index.js\";\nimport {\n  mergeHistoryStreams,\n  mergeItemDocuments,\n  mergeJsonDocuments,\n  mergeRelationshipEventStreams,\n  type MergePreferredSide,\n} from \"./three-way.js\";\n\n/** Supported values accepted by the merge driver artifact contract across CLI, SDK, and MCP surfaces. */\nexport const MERGE_DRIVER_ARTIFACT_VALUES = [\n  \"item\",\n  \"history\",\n  \"relationship\",\n  \"json\",\n] as const;\n/** Restricts merge driver artifact values accepted by command, SDK, and storage contracts. */\nexport type MergeDriverArtifact = (typeof MERGE_DRIVER_ARTIFACT_VALUES)[number];\n\n/** Documents the merge driver options payload exchanged by command, SDK, and package integrations. */\nexport interface MergeDriverOptions {\n  /** Artifact class being merged: item document, history JSONL stream, relationship event JSONL store, or key-level JSON config. */\n  artifact: string;\n  /** Path to the common-ancestor version (git %O). */\n  basePath: string;\n  /** Path to the current-branch version (git %A); also the default output path per the git merge-driver protocol. */\n  oursPath: string;\n  /** Path to the other-branch version (git %B). */\n  theirsPath: string;\n  /** Optional explicit output path overriding the git default of writing to the ours path. */\n  outputPath?: string;\n  /** Original repository-relative item path supplied by Git as `%P`, used to detect item format when temporary side paths lack extensions. */\n  itemPath?: string;\n  /** Side that wins unresolvable conflicts (default \"ours\"). */\n  prefer?: string;\n}\n\n/** Documents the merge driver result payload exchanged by command, SDK, and package integrations. */\nexport interface MergeDriverResult {\n  /** Whether the merge completed without unresolvable conflicts. */\n  ok: boolean;\n  /** Artifact class that was merged. */\n  artifact: MergeDriverArtifact;\n  /** Path the merged content was written to. */\n  output_path: string;\n  /** Side unresolvable conflicts were resolved toward. */\n  preferred: MergePreferredSide;\n  /** Unresolvable conflict labels: metadata field names (item), dotted key paths (json). Empty for history merges. */\n  conflicts: string[];\n  /** History-merge strategy and entry accounting; present only for the history artifact. */\n  history?: {\n    strategy: string;\n    common_entries: number;\n    entries_from_ours: number;\n    entries_from_theirs: number;\n    entries_total: number;\n    reanchored: boolean;\n  };\n  /** Relationship-event-merge strategy and accounting; present only for the relationship artifact. */\n  relationship?: {\n    strategy: string;\n    common_entries: number;\n    entries_from_ours: number;\n    entries_from_theirs: number;\n    entries_total: number;\n    reanchored: boolean;\n  };\n  /** Item-merge field accounting; present only for the item artifact. */\n  item?: {\n    fields_from_theirs: string[];\n    union_fields: string[];\n  };\n  /** JSON-merge key accounting; present only for the json artifact. */\n  json?: {\n    paths_from_theirs: string[];\n  };\n  /** Guidance for resolving remaining conflicts or verifying the merged workspace. */\n  guidance: string[];\n  /** ISO 8601 timestamp recording when generated occurred. */\n  generated_at: string;\n}\n\nfunction resolveArtifact(value: string): MergeDriverArtifact {\n  const normalized = value.trim().toLowerCase();\n  if (\n    (MERGE_DRIVER_ARTIFACT_VALUES as readonly string[]).includes(normalized)\n  ) {\n    return normalized as MergeDriverArtifact;\n  }\n  throw new PmCliError(\n    `Unknown merge artifact \"${value}\". Supported values: ${MERGE_DRIVER_ARTIFACT_VALUES.join(\", \")}.`,\n    EXIT_CODE.USAGE,\n  );\n}\n\nfunction resolvePreferredSide(value: string | undefined): MergePreferredSide {\n  if (value === undefined) {\n    return \"ours\";\n  }\n  const normalized = value.trim().toLowerCase();\n  if (normalized === \"ours\" || normalized === \"theirs\") {\n    return normalized;\n  }\n  throw new PmCliError(\n    `Unknown --prefer value \"${value}\". Supported values: ours, theirs.`,\n    EXIT_CODE.USAGE,\n  );\n}\n\nasync function readSideFile(filePath: string, label: string): Promise<string> {\n  try {\n    return await readFile(filePath, \"utf8\");\n  } catch {\n    throw new PmCliError(\n      `Cannot read merge ${label} file at ${filePath}.`,\n      EXIT_CODE.NOT_FOUND,\n    );\n  }\n}\n\n/**\n * Load the workspace settings when a tracker is initialized at the resolved pm\n * root, or fall back to format defaults when the driver runs outside a tracker\n * (git can invoke merge drivers before `pm init`, e.g. while rebasing the\n * commit that introduces the tracker).\n */\nasync function loadOptionalSettings(\n  global: GlobalOptions,\n): Promise<PmSettings | null> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    return null;\n  }\n  return readSettings(pmRoot);\n}\n\nfunction itemFormatForPath(\n  filePath: string,\n  settings: PmSettings | null,\n): ItemFormat {\n  if (filePath.endsWith(\".md\")) {\n    return \"json_markdown\";\n  }\n  if (filePath.endsWith(\".toon\")) {\n    return \"toon\";\n  }\n  return settings?.item_format ?? \"toon\";\n}\n\n/**\n * Execute one git merge-driver invocation for a tracker artifact. Reads the\n * three per-side versions, applies the artifact's field-aware merge semantics,\n * writes the merged content (parseable even when conflicted) to the output\n * path, and reports remaining conflicts so the CLI can exit non-zero and let\n * git mark the path unmerged.\n */\nexport async function runMergeDriver(\n  options: MergeDriverOptions,\n  global: GlobalOptions,\n): Promise<MergeDriverResult> {\n  const artifact = resolveArtifact(options.artifact);\n  const preferred = resolvePreferredSide(options.prefer);\n  const outputPath = path.resolve(options.outputPath ?? options.oursPath);\n  const [baseRaw, oursRaw, theirsRaw] = await Promise.all([\n    readSideFile(options.basePath, \"base\"),\n    readSideFile(options.oursPath, \"ours\"),\n    readSideFile(options.theirsPath, \"theirs\"),\n  ]);\n\n  let merged: string;\n  const conflicts: string[] = [];\n  const result: Partial<MergeDriverResult> = {};\n  if (artifact === \"history\") {\n    const historyMerge = mergeHistoryStreams(baseRaw, oursRaw, theirsRaw);\n    merged = historyMerge.merged;\n    result.history = {\n      strategy: historyMerge.strategy,\n      common_entries: historyMerge.common_entries,\n      entries_from_ours: historyMerge.entries_from_ours,\n      entries_from_theirs: historyMerge.entries_from_theirs,\n      entries_total: historyMerge.entries_total,\n      reanchored: historyMerge.reanchored,\n    };\n  } else if (artifact === \"relationship\") {\n    const relationshipMerge = mergeRelationshipEventStreams(\n      baseRaw,\n      oursRaw,\n      theirsRaw,\n    );\n    merged = relationshipMerge.merged;\n    result.relationship = {\n      strategy: relationshipMerge.strategy,\n      common_entries: relationshipMerge.common_entries,\n      entries_from_ours: relationshipMerge.entries_from_ours,\n      entries_from_theirs: relationshipMerge.entries_from_theirs,\n      entries_total: relationshipMerge.entries_total,\n      reanchored: relationshipMerge.reanchored,\n    };\n  } else if (artifact === \"item\") {\n    const settings = await loadOptionalSettings(global);\n    const itemMerge = mergeItemDocuments(baseRaw, oursRaw, theirsRaw, {\n      format: itemFormatForPath(options.itemPath ?? outputPath, settings),\n      schema: settings?.schema,\n      extensionFieldNames: collectRegisteredItemFieldNames(\n        getActiveExtensionRegistrations(),\n      ),\n      preferred,\n    });\n    merged = itemMerge.merged;\n    conflicts.push(...itemMerge.conflict_fields);\n    result.item = {\n      fields_from_theirs: itemMerge.fields_from_theirs,\n      union_fields: itemMerge.union_fields,\n    };\n  } else {\n    const jsonMerge = mergeJsonDocuments(baseRaw, oursRaw, theirsRaw, {\n      preferred,\n    });\n    merged = jsonMerge.merged;\n    conflicts.push(...jsonMerge.conflict_paths);\n    result.json = {\n      paths_from_theirs: jsonMerge.paths_from_theirs,\n    };\n  }\n\n  await writeFile(outputPath, merged, \"utf8\");\n  const guidance: string[] = [];\n  if (conflicts.length > 0) {\n    guidance.push(\n      `Both branches changed ${conflicts.join(\", \")}; the ${preferred} value was kept. Review the merged file, re-apply the losing change if needed, then \"git add\" it.`,\n    );\n  }\n  if (artifact === \"history\" && result.history?.reanchored) {\n    guidance.push(\n      'The merged history chain was re-anchored. Run \"pm validate --check-history-drift\" and \"pm history-repair --all\" after the merge to reconcile item state with merged history.',\n    );\n  }\n  return {\n    ok: conflicts.length === 0,\n    artifact,\n    output_path: outputPath,\n    preferred,\n    conflicts,\n    ...result,\n    guidance,\n    generated_at: nowIso(),\n  };\n}\n"],"names":[],"mappings":"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","debugId":"dcd2575e-24f4-58db-b4ab-d64277c71d7c"}

package/dist/sdk/merge/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @module sdk/merge
+ *
+ * Public SDK surface for multi-branch tracker merge semantics: field-aware
+ * three-way merge primitives, the git merge-driver runner, and the repository
+ * merge-configuration installer. The CLI `pm merge` command is a shim over
+ * this module so packages and hosts can reuse the same merge behavior.
+ */
+export { ITEM_LATEST_TIMESTAMP_FIELDS, ITEM_UNION_COLLECTION_FIELDS, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, type HistoryMergeResult, type HistoryMergeStrategy, type ItemDocumentMergeResult, type JsonDocumentMergeResult, type MergePreferredSide, type RelationshipStreamMergeResult, } from "./three-way.js";
+export { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, type MergeDriverArtifact, type MergeDriverOptions, type MergeDriverResult, } from "./driver.js";
+export { auditMergeAttributeFence, buildMergeAttributePatterns, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, refreshMergeAttributeFenceIfInstalled, runMergeInstall, type MergeFenceAuditResult, type MergeFenceRefreshOutcome, type MergeInstallOptions, type MergeInstallResult, } from "./install.js";

package/dist/sdk/merge/index.js

@@ -0,0 +1,15 @@
+/**
+ * @module sdk/merge
+ *
+ * Public SDK surface for multi-branch tracker merge semantics: field-aware
+ * three-way merge primitives, the git merge-driver runner, and the repository
+ * merge-configuration installer. The CLI `pm merge` command is a shim over
+ * this module so packages and hosts can reuse the same merge 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]="f3029f43-e4c7-5551-bc13-6c2206239bbd")}catch(e){}}();
+export { ITEM_LATEST_TIMESTAMP_FIELDS, ITEM_UNION_COLLECTION_FIELDS, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, } from "./three-way.js";
+export { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, } from "./driver.js";
+export { auditMergeAttributeFence, buildMergeAttributePatterns, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, refreshMergeAttributeFenceIfInstalled, runMergeInstall, } from "./install.js";
+//# sourceMappingURL=index.js.map
+//# debugId=f3029f43-e4c7-5551-bc13-6c2206239bbd

package/dist/sdk/merge/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["sdk/merge/index.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/merge\n *\n * Public SDK surface for multi-branch tracker merge semantics: field-aware\n * three-way merge primitives, the git merge-driver runner, and the repository\n * merge-configuration installer. The CLI `pm merge` command is a shim over\n * this module so packages and hosts can reuse the same merge behavior.\n */\nexport {\n  ITEM_LATEST_TIMESTAMP_FIELDS,\n  ITEM_UNION_COLLECTION_FIELDS,\n  mergeHistoryStreams,\n  mergeItemDocuments,\n  mergeJsonDocuments,\n  mergeRelationshipEventStreams,\n  type HistoryMergeResult,\n  type HistoryMergeStrategy,\n  type ItemDocumentMergeResult,\n  type JsonDocumentMergeResult,\n  type MergePreferredSide,\n  type RelationshipStreamMergeResult,\n} from \"./three-way.js\";\nexport {\n  MERGE_DRIVER_ARTIFACT_VALUES,\n  runMergeDriver,\n  type MergeDriverArtifact,\n  type MergeDriverOptions,\n  type MergeDriverResult,\n} from \"./driver.js\";\nexport {\n  auditMergeAttributeFence,\n  buildMergeAttributePatterns,\n  PM_GITATTRIBUTES_END,\n  PM_GITATTRIBUTES_START,\n  refreshMergeAttributeFenceIfInstalled,\n  runMergeInstall,\n  type MergeFenceAuditResult,\n  type MergeFenceRefreshOutcome,\n  type MergeInstallOptions,\n  type MergeInstallResult,\n} from \"./install.js\";\n"],"names":[],"mappings":"AAAA;;;;;;;GAOG;;;AACH,OAAO,EACL,4BAA4B,EAC5B,4BAA4B,EAC5B,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,6BAA6B,GAO9B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,4BAA4B,EAC5B,cAAc,GAIf,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,oBAAoB,EACpB,sBAAsB,EACtB,qCAAqC,EACrC,eAAe,GAKhB,MAAM,cAAc,CAAC","debugId":"f3029f43-e4c7-5551-bc13-6c2206239bbd"}

package/dist/sdk/merge/install.d.ts

@@ -0,0 +1,90 @@
+import type { GlobalOptions } from "../../core/shared/command-types.js";
+/** Opening marker for the pm-owned merge-driver `.gitattributes` block. */
+export declare const PM_GITATTRIBUTES_START = "# pm-cli:merge-drivers:start";
+/** Closing marker for the pm-owned merge-driver `.gitattributes` block. */
+export declare const PM_GITATTRIBUTES_END = "# pm-cli:merge-drivers:end";
+/** Documents the merge install options payload exchanged by command, SDK, and package integrations. */
+export interface MergeInstallOptions {
+    /** Preview the `.gitattributes` and `git config` changes without writing anything. */
+    dryRun?: boolean;
+}
+/** Documents the merge install result payload exchanged by command, SDK, and package integrations. */
+export interface MergeInstallResult {
+    /** Whether the installation completed (or, for dry runs, would complete) without errors. */
+    ok: boolean;
+    /** Whether this run was a preview only. */
+    dry_run: boolean;
+    /** Repository root the merge configuration was installed into. */
+    workspace_root: string;
+    /** `.gitattributes` reconciliation outcome. */
+    gitattributes: {
+        path: string;
+        changed: boolean;
+        patterns: string[];
+    };
+    /** Local `git config` merge-driver definitions applied (or previewed). */
+    git_config: Array<{
+        key: string;
+        value: string;
+    }>;
+    /** Guidance for completing the multi-branch workflow setup. */
+    guidance: string[];
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/**
+ * Build the complete fenced `.gitattributes` pattern list for a tracker rooted
+ * at `trackerRelativeRoot` (git-root-relative POSIX path, empty when the
+ * tracker root IS the git root). This is the single coverage contract shared
+ * by `pm merge install` (which writes the fence) and the validate
+ * merge-fence-drift detection (which compares the committed fence against the
+ * active schema's type folders), so schema-added custom types can never
+ * silently diverge from the installed fence without a warning.
+ */
+export declare function buildMergeAttributePatterns(trackerRelativeRoot: string, typeFolders: string[]): string[];
+/** Result of comparing the committed merge-fence block against the coverage the active schema requires. */
+export interface MergeFenceAuditResult {
+    /** Audit outcome: no fence installed (nothing to audit), fence matches, or fence drifted from the active schema/type folders. */
+    status: "not_installed" | "ok" | "drift";
+    /** `.gitattributes` file containing the fence, when one was found. */
+    path?: string;
+    /** Expected attribute lines absent from the committed fence (for example a schema-added type folder). */
+    missing_patterns: string[];
+    /** Committed fence lines no longer produced by the coverage contract (for example a removed type folder). */
+    stale_patterns: string[];
+}
+/**
+ * Audit the committed `.gitattributes` merge fence against the coverage the
+ * active schema requires, without touching git configuration. The fence file
+ * is discovered by walking up from the tracker root (bounded), so the audit
+ * stays filesystem-only and safe to run inside `pm validate`. A `drift`
+ * result means items of some type folder (or a tracker JSONL store) would
+ * merge under git's default text driver despite the fence being installed.
+ */
+export declare function auditMergeAttributeFence(pmRoot: string, typeFolders: string[]): Promise<MergeFenceAuditResult>;
+/** Outcome of an automatic merge-fence refresh attempted after a schema type mutation. */
+export interface MergeFenceRefreshOutcome {
+    /** What happened: the fence was rewritten, already matched, was never installed (actionable hint), or there is no git repository to configure. */
+    status: "refreshed" | "unchanged" | "not_installed" | "no_git";
+    /** `.gitattributes` path examined, when a git repository was found. */
+    path?: string;
+}
+/**
+ * Refresh the fenced `.gitattributes` merge-driver block after a schema type
+ * mutation, but only when `pm merge install` already ran (the fence markers
+ * are present). Without this, custom item types registered after install
+ * would write items into folders with no merge attribute — silently
+ * reintroducing the whole-file conflict class for exactly those items. Repos
+ * that never installed the fence get a `not_installed` outcome so callers can
+ * surface an actionable hint instead of mutating git configuration nobody
+ * asked for.
+ */
+export declare function refreshMergeAttributeFenceIfInstalled(pmRoot: string): Promise<MergeFenceRefreshOutcome>;
+/**
+ * Install (or preview) the repository merge configuration for tracker data:
+ * writes the fenced merge-driver block into `.gitattributes` (committed and
+ * shared with every branch) and defines the `merge.pm-*.driver` entries in the
+ * repository-local git config (per-clone, so every collaborator runs this once
+ * per checkout). Requires an initialized tracker and a git repository.
+ */
+export declare function runMergeInstall(options: MergeInstallOptions, global: GlobalOptions): Promise<MergeInstallResult>;

package/dist/sdk/merge/install.js

@@ -0,0 +1,318 @@
+/**
+ * @module sdk/merge/install
+ *
+ * Installs the tracker's git merge configuration into a repository: a fenced
+ * `.gitattributes` block mapping every mergeable tracker artifact class to a
+ * pm merge driver, plus the local `git config` driver definitions that make
+ * those attributes effective. Idempotent and re-runnable; schema type
+ * mutations refresh the fenced block automatically once it is installed.
+ */
+
+!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]="86f1b43a-3b30-5791-ba03-fc362dfe5585")}catch(e){}}();
+import { readFile, writeFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
+import { pathExists } from "../../core/fs/fs-utils.js";
+import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
+import { acquireLock } from "../../core/lock/lock.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { nowIso } from "../../core/shared/time.js";
+import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
+import { readSettings, resolveGovernanceKnobs, } from "../../core/store/settings.js";
+import { isPathOutsideRoot } from "../workspace.js";
+const execFileAsync = promisify(execFile);
+/** Opening marker for the pm-owned merge-driver `.gitattributes` block. */
+export const PM_GITATTRIBUTES_START = "# pm-cli:merge-drivers:start";
+/** Closing marker for the pm-owned merge-driver `.gitattributes` block. */
+export const PM_GITATTRIBUTES_END = "# pm-cli:merge-drivers:end";
+const MERGE_FENCE_LOCK_ID = "merge-fence";
+const MERGE_DRIVER_DEFINITIONS = [
+    {
+        key: "pm-item-toon",
+        name: "pm field-aware TOON item document merge",
+        artifact: "item",
+        itemPath: "item.toon",
+    },
+    {
+        key: "pm-item-markdown",
+        name: "pm field-aware JSON-markdown item document merge",
+        artifact: "item",
+        itemPath: "item.md",
+    },
+    {
+        key: "pm-history",
+        name: "pm append-only history stream merge",
+        artifact: "history",
+        itemPath: undefined,
+    },
+    {
+        key: "pm-relationship",
+        name: "pm append-only relationship event store merge",
+        artifact: "relationship",
+        itemPath: undefined,
+    },
+    {
+        key: "pm-json",
+        name: "pm key-level JSON config merge",
+        artifact: "json",
+        itemPath: undefined,
+    },
+];
+async function resolveGitWorkspaceRoot(cwd) {
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8", windowsHide: true, timeout: 10_000 });
+        return stdout.trim();
+    }
+    catch {
+        throw new PmCliError("pm merge install requires a git repository (merge drivers are git configuration).", EXIT_CODE.USAGE);
+    }
+}
+function toPosixRelative(fromPath, toPath) {
+    return path.relative(fromPath, toPath).replaceAll("\\", "/");
+}
+/** Encode one Git attributes pattern with C-style quoting so whitespace, backslashes, and quotation marks remain part of the repository path instead of being parsed as attribute separators. */
+function quoteGitAttributePattern(value) {
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+/**
+ * Build the complete fenced `.gitattributes` pattern list for a tracker rooted
+ * at `trackerRelativeRoot` (git-root-relative POSIX path, empty when the
+ * tracker root IS the git root). This is the single coverage contract shared
+ * by `pm merge install` (which writes the fence) and the validate
+ * merge-fence-drift detection (which compares the committed fence against the
+ * active schema's type folders), so schema-added custom types can never
+ * silently diverge from the installed fence without a warning.
+ */
+export function buildMergeAttributePatterns(trackerRelativeRoot, typeFolders) {
+    const prefix = trackerRelativeRoot.length > 0 ? `${trackerRelativeRoot}/` : "";
+    const patterns = [];
+    for (const folder of typeFolders) {
+        patterns.push(`${quoteGitAttributePattern(`${prefix}${folder}/*.toon`)} merge=pm-item-toon`);
+        patterns.push(`${quoteGitAttributePattern(`${prefix}${folder}/*.md`)} merge=pm-item-markdown`);
+    }
+    // RelationshipEventStore deliberately accepts a caller-chosen relativePath
+    // anywhere below the tracker root. Cover all tracker JSONL first, then let
+    // the more-specific history rule below override it. This keeps custom event
+    // stores protected without guessing package-owned paths.
+    patterns.push(`${quoteGitAttributePattern(`${prefix}**/*.jsonl`)} merge=pm-relationship`);
+    patterns.push(`${quoteGitAttributePattern(`${prefix}history/*.jsonl`)} merge=pm-history`);
+    patterns.push(`${quoteGitAttributePattern(`${prefix}settings.json`)} merge=pm-json`);
+    patterns.push(`${quoteGitAttributePattern(`${prefix}schema/*.json`)} merge=pm-json`);
+    return patterns;
+}
+async function reconcileGitattributesBlock(workspaceRoot, patterns, dryRun) {
+    const gitattributesPath = path.join(workspaceRoot, ".gitattributes");
+    let current = "";
+    try {
+        current = await readFile(gitattributesPath, "utf8");
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+            throw error;
+        }
+    }
+    const block = [
+        PM_GITATTRIBUTES_START,
+        ...patterns,
+        PM_GITATTRIBUTES_END,
+    ].join("\n");
+    const start = current.indexOf(PM_GITATTRIBUTES_START);
+    const end = current.indexOf(PM_GITATTRIBUTES_END);
+    const withoutManagedBlock = start >= 0 && end > start
+        ? `${current.slice(0, start)}${current.slice(end + PM_GITATTRIBUTES_END.length)}`
+        : current
+            .replace(PM_GITATTRIBUTES_START, "")
+            .replace(PM_GITATTRIBUTES_END, "");
+    const prefix = withoutManagedBlock.trimEnd();
+    const next = `${prefix.length > 0 ? `${prefix}\n\n` : ""}${block}\n`;
+    if (next === current) {
+        return { path: gitattributesPath, changed: false };
+    }
+    if (!dryRun) {
+        await writeFile(gitattributesPath, next, "utf8");
+    }
+    return { path: gitattributesPath, changed: true };
+}
+/**
+ * Audit the committed `.gitattributes` merge fence against the coverage the
+ * active schema requires, without touching git configuration. The fence file
+ * is discovered by walking up from the tracker root (bounded), so the audit
+ * stays filesystem-only and safe to run inside `pm validate`. A `drift`
+ * result means items of some type folder (or a tracker JSONL store) would
+ * merge under git's default text driver despite the fence being installed.
+ */
+export async function auditMergeAttributeFence(pmRoot, typeFolders) {
+    const resolvedRoot = path.resolve(pmRoot);
+    let fenceDirectory = null;
+    let fenceContent = "";
+    let directory = resolvedRoot;
+    for (let depth = 0; depth < 8; depth += 1) {
+        const candidate = path.join(directory, ".gitattributes");
+        try {
+            const raw = await readFile(candidate, "utf8");
+            if (raw.includes(PM_GITATTRIBUTES_START)) {
+                fenceDirectory = directory;
+                fenceContent = raw;
+                break;
+            }
+        }
+        catch {
+            // No .gitattributes at this level; keep walking up.
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory) {
+            break;
+        }
+        directory = parent;
+    }
+    if (fenceDirectory === null) {
+        return { status: "not_installed", missing_patterns: [], stale_patterns: [] };
+    }
+    const fencePath = path.join(fenceDirectory, ".gitattributes");
+    const start = fenceContent.indexOf(PM_GITATTRIBUTES_START);
+    const end = fenceContent.indexOf(PM_GITATTRIBUTES_END);
+    const committed = end > start
+        ? fenceContent
+            .slice(start + PM_GITATTRIBUTES_START.length, end)
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+        : [];
+    const expected = buildMergeAttributePatterns(toPosixRelative(fenceDirectory, resolvedRoot), typeFolders);
+    const committedSet = new Set(committed);
+    const expectedSet = new Set(expected);
+    const missing = expected.filter((line) => !committedSet.has(line));
+    const stale = committed.filter((line) => !expectedSet.has(line));
+    return {
+        status: missing.length > 0 || stale.length > 0 ? "drift" : "ok",
+        path: fencePath,
+        missing_patterns: missing,
+        stale_patterns: stale,
+    };
+}
+/**
+ * Refresh the fenced `.gitattributes` merge-driver block after a schema type
+ * mutation, but only when `pm merge install` already ran (the fence markers
+ * are present). Without this, custom item types registered after install
+ * would write items into folders with no merge attribute — silently
+ * reintroducing the whole-file conflict class for exactly those items. Repos
+ * that never installed the fence get a `not_installed` outcome so callers can
+ * surface an actionable hint instead of mutating git configuration nobody
+ * asked for.
+ */
+export async function refreshMergeAttributeFenceIfInstalled(pmRoot) {
+    let workspaceRoot;
+    try {
+        workspaceRoot = await resolveGitWorkspaceRoot(path.resolve(pmRoot));
+    }
+    catch {
+        return { status: "no_git" };
+    }
+    const trackerRelativeRoot = toPosixRelative(workspaceRoot, path.resolve(pmRoot));
+    const lockSettings = await readSettings(pmRoot);
+    const owner = (process.env.PM_AUTHOR ?? lockSettings.author_default).trim();
+    const releaseLock = await acquireLock(pmRoot, MERGE_FENCE_LOCK_ID, lockSettings.locks.ttl_seconds, owner.length > 0 ? owner : "unknown", false, resolveGovernanceKnobs(lockSettings).force_required_for_stale_lock, lockSettings.locks.wait_ms);
+    try {
+        const gitattributesPath = path.join(workspaceRoot, ".gitattributes");
+        let current;
+        try {
+            current = await readFile(gitattributesPath, "utf8");
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                "code" in error &&
+                error.code === "ENOENT") {
+                return { status: "not_installed", path: gitattributesPath };
+            }
+            throw error;
+        }
+        if (!current.includes(PM_GITATTRIBUTES_START)) {
+            return { status: "not_installed", path: gitattributesPath };
+        }
+        // Re-read after acquiring the dedicated fence lock so every concurrent
+        // refresher computes from the latest committed type registry.
+        const settings = await readSettings(pmRoot);
+        const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
+        const typeFolders = [
+            ...new Set(Object.values(typeRegistry.type_to_folder)),
+        ].sort((left, right) => left.localeCompare(right));
+        const outcome = await reconcileGitattributesBlock(workspaceRoot, buildMergeAttributePatterns(trackerRelativeRoot, typeFolders), false);
+        return {
+            status: outcome.changed ? "refreshed" : "unchanged",
+            path: outcome.path,
+        };
+    }
+    finally {
+        await releaseLock();
+    }
+}
+/**
+ * Install (or preview) the repository merge configuration for tracker data:
+ * writes the fenced merge-driver block into `.gitattributes` (committed and
+ * shared with every branch) and defines the `merge.pm-*.driver` entries in the
+ * repository-local git config (per-clone, so every collaborator runs this once
+ * per checkout). Requires an initialized tracker and a git repository.
+ */
+export async function runMergeInstall(options, global) {
+    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 dryRun = options.dryRun === true;
+    const workspaceRoot = await resolveGitWorkspaceRoot(process.cwd());
+    const trackerRelativeRoot = toPosixRelative(workspaceRoot, path.resolve(pmRoot));
+    if (isPathOutsideRoot(trackerRelativeRoot)) {
+        throw new PmCliError(`Tracker root ${pmRoot} is outside the git repository ${workspaceRoot}; there is nothing to configure for this repository.`, EXIT_CODE.USAGE);
+    }
+    const settings = await readSettings(pmRoot);
+    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
+    const typeFolders = [
+        ...new Set(Object.values(typeRegistry.type_to_folder)),
+    ].sort((left, right) => left.localeCompare(right));
+    const patterns = buildMergeAttributePatterns(trackerRelativeRoot, typeFolders);
+    const gitattributes = await reconcileGitattributesBlock(workspaceRoot, patterns, dryRun);
+    const gitConfigEntries = [];
+    for (const definition of MERGE_DRIVER_DEFINITIONS) {
+        gitConfigEntries.push({
+            key: `merge.${definition.key}.name`,
+            value: definition.name,
+        });
+        gitConfigEntries.push({
+            key: `merge.${definition.key}.driver`,
+            value: `pm merge driver ${definition.artifact} "%O" "%A" "%B"${definition.itemPath === undefined ? "" : ` --item-path ${definition.itemPath}`}`,
+        });
+    }
+    if (!dryRun) {
+        for (const entry of gitConfigEntries) {
+            await execFileAsync("git", ["config", entry.key, entry.value], {
+                cwd: workspaceRoot,
+                encoding: "utf8",
+                windowsHide: true,
+                timeout: 10_000,
+            });
+        }
+    }
+    return {
+        ok: true,
+        dry_run: dryRun,
+        workspace_root: workspaceRoot,
+        gitattributes: {
+            path: gitattributes.path,
+            changed: gitattributes.changed,
+            patterns,
+        },
+        git_config: gitConfigEntries,
+        guidance: [
+            "Commit .gitattributes so every branch and collaborator shares the merge mapping.",
+            'git config is per-clone: each collaborator (and each fresh worktree/clone) runs "pm merge install" once.',
+            'After merging branches, run "pm validate" and, if history drift is reported, "pm history-repair --all" to reconcile item state with merged history.',
+            "Custom item types registered later refresh this fence automatically (pm schema add-type/remove-type); rerun pm merge install only after out-of-band type-folder edits.",
+        ],
+        generated_at: nowIso(),
+    };
+}
+//# sourceMappingURL=install.js.map
+//# debugId=86f1b43a-3b30-5791-ba03-fc362dfe5585