@unbrained/pm-cli 2026.7.19 → 2026.7.20

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

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

package/dist/sdk/merge/three-way.d.ts

@@ -0,0 +1,126 @@
+import { type ItemDocumentFormatOptions } from "../../core/item/item-format.js";
+/** Restricts which side of a three-way merge wins an unresolvable conflict. */
+export type MergePreferredSide = "ours" | "theirs";
+/** Restricts the strategy labels reported by the history stream merge. */
+export type HistoryMergeStrategy = "identical" | "fast_forward_ours" | "fast_forward_theirs" | "union_reanchor";
+/** Documents the history stream merge result payload exchanged by command, SDK, and package integrations. */
+export interface HistoryMergeResult {
+    /** Merged JSONL content ready to be written as the resolved history stream. */
+    merged: string;
+    /** Strategy the merge used: identical inputs, one-sided fast-forward, or a deterministic union with a re-anchored hash chain. */
+    strategy: HistoryMergeStrategy;
+    /** Number of entries shared by both sides before their streams diverged. */
+    common_entries: number;
+    /** Number of divergent entries contributed by the ours side. */
+    entries_from_ours: number;
+    /** Number of divergent entries contributed by the theirs side. */
+    entries_from_theirs: number;
+    /** Total entries in the merged stream. */
+    entries_total: number;
+    /** Whether the merged chain required hash re-anchoring (true for every union merge). */
+    reanchored: boolean;
+}
+/**
+ * Deterministically merge two diverged versions of one append-only history
+ * JSONL stream. Identical streams and one-sided fast-forwards keep the winning
+ * side byte-for-byte; genuinely diverged streams are merged as the shared
+ * prefix plus both suffixes ordered by timestamp (ours-first on ties), then
+ * hash re-anchored so the resulting chain verifies again. No side's events are
+ * ever discarded: content divergence is preserved for the post-merge
+ * reconciliation pass (`pm validate` + `pm history-repair`) instead of being
+ * silently resolved by last-writer-wins.
+ */
+export declare function mergeHistoryStreams(baseRaw: string, oursRaw: string, theirsRaw: string): HistoryMergeResult;
+/** Documents the relationship event stream merge result payload exchanged by command, SDK, and package integrations. */
+export interface RelationshipStreamMergeResult {
+    /** Merged JSONL content with consecutively renumbered `sequence` values, ready to be written as the resolved event store. */
+    merged: string;
+    /** Strategy the merge used: identical inputs, one-sided fast-forward, or a deterministic union with renumbered sequences. */
+    strategy: HistoryMergeStrategy;
+    /** Number of events shared by both sides before their streams diverged. */
+    common_entries: number;
+    /** Number of divergent events contributed by the ours side. */
+    entries_from_ours: number;
+    /** Number of divergent events contributed by the theirs side. */
+    entries_from_theirs: number;
+    /** Total events in the merged stream. */
+    entries_total: number;
+    /** Whether merged events required sequence renumbering (true for every union merge). */
+    reanchored: boolean;
+}
+/**
+ * Deterministically merge two diverged versions of one append-only
+ * relationship event JSONL store. The store's loader enforces strictly
+ * consecutive one-based `sequence` values, so a plain text union of two
+ * diverged streams is always unreadable; this merge keeps the shared prefix,
+ * unions both divergent suffixes by `eventId` (ordered by event timestamp,
+ * ours-first on ties), and renumbers every merged sequence consecutively so
+ * the resulting stream loads again. No side's events are ever discarded.
+ */
+export declare function mergeRelationshipEventStreams(baseRaw: string, oursRaw: string, theirsRaw: string): RelationshipStreamMergeResult;
+/**
+ * Item metadata collections merged by element-identity set semantics instead
+ * of whole-field three-way comparison: concurrent commutative appends from two
+ * branches (notes on A, tags on B, a test run on each) must merge cleanly.
+ * Element identity is the stable serialization of the normalized element, so
+ * an element edited on one side counts as remove-old + add-new and both sides'
+ * contributions survive. Plan collections are deliberately excluded: plan
+ * steps carry cross-element ordering invariants that set-union would corrupt,
+ * so they stay under scalar three-way semantics with explicit conflicts.
+ */
+export declare const ITEM_UNION_COLLECTION_FIELDS: readonly ["tags", "dependencies", "comments", "notes", "learnings", "files", "tests", "test_runs", "docs", "reminders", "events"];
+/** Item metadata fields resolved by deterministic latest-timestamp-wins instead of three-way conflict, so disjoint-field edits never conflict on the shared freshness scalar every mutation rewrites. */
+export declare const ITEM_LATEST_TIMESTAMP_FIELDS: readonly ["updated_at"];
+/** Documents the item document merge result payload exchanged by command, SDK, and package integrations. */
+export interface ItemDocumentMergeResult {
+    /** Serialized merged item document (always parseable; count headers recomputed by canonical serialization). */
+    merged: string;
+    /** Metadata fields (plus `body`) where both sides changed to different values; resolved toward the preferred side. */
+    conflict_fields: string[];
+    /** Fields taken from the theirs side by clean three-way resolution. */
+    fields_from_theirs: string[];
+    /** Collection fields that merged by element-identity union. */
+    union_fields: string[];
+    /** Which side unresolvable conflicts were resolved toward. */
+    preferred: MergePreferredSide;
+}
+/**
+ * Field-aware three-way merge of one tracker item document. Commutative
+ * collections (notes, tags, tests, ...) union by element identity so
+ * concurrent appends never conflict; `updated_at` resolves to the latest
+ * timestamp so disjoint-field edits never collide on the shared freshness
+ * scalar; every other metadata field and the body use classic three-way
+ * resolution. Unresolvable both-sides-changed conflicts are resolved toward
+ * the preferred side but reported in `conflict_fields`, and the merged output
+ * is always canonically serialized — count-prefixed TOON array headers are
+ * recomputed, so the hand-resolution corruption class (stale `notes[N]`
+ * headers) cannot be produced by this merge.
+ */
+export declare function mergeItemDocuments(baseRaw: string, oursRaw: string, theirsRaw: string, options?: ItemDocumentFormatOptions & {
+    /** Side that wins unresolvable conflicts (default "ours"). */
+    preferred?: MergePreferredSide;
+}): ItemDocumentMergeResult;
+/** Documents the JSON document merge result payload exchanged by command, SDK, and package integrations. */
+export interface JsonDocumentMergeResult {
+    /** Serialized merged JSON document (two-space indent, trailing newline — the tracker's canonical config style). */
+    merged: string;
+    /** Dotted key paths where both sides changed to different values; resolved toward the preferred side. */
+    conflict_paths: string[];
+    /** Dotted key paths taken from the theirs side by clean three-way resolution. */
+    paths_from_theirs: string[];
+    /** Which side unresolvable conflicts were resolved toward. */
+    preferred: MergePreferredSide;
+}
+/**
+ * Key-level three-way merge for the tracker's single-file JSON configuration
+ * artifacts (`settings.json`, `schema/*.json`). Nested objects merge
+ * recursively per key so two branches editing disjoint settings never
+ * conflict; both-sides-changed leaf values resolve toward the preferred side
+ * and are reported in `conflict_paths`. The output is always valid JSON, so a
+ * merged configuration can never regress into the silent-defaults fallback
+ * that raw conflict markers cause.
+ */
+export declare function mergeJsonDocuments(baseRaw: string, oursRaw: string, theirsRaw: string, options?: {
+    /** Side that wins unresolvable conflicts (default "ours"). */
+    preferred?: MergePreferredSide;
+}): JsonDocumentMergeResult;