@tenonhq/dovetail-core 0.0.104 → 0.0.106

package/dist/commander.js

@@ -12,6 +12,7 @@ const schemaCommand_1 = require("./schemaCommand");
 const claudeCommand_1 = require("./claudeCommand");
 const createRecordCommand_1 = require("./createRecordCommand");
 const deleteRecordCommand_1 = require("./deleteRecordCommand");
+const reconcileCommand_1 = require("./reconcileCommand");
 const migrateCommand_1 = require("./migrateCommand");
 const clickupCommands_1 = require("./clickupCommands");
 const loginCommand_1 = require("./loginCommand");
@@ -386,6 +387,39 @@ async function initCommands() {
         else if (args.subcommand === "snapshots") {
             await (0, schemaCommand_1.schemaSnapshotsCommand)(args);
         }
+    })
+        .command("reconcile", "Make your personal instance match the checked-out branch (diff/report by default; --apply to apply CREATE + UPDATE + DELETE)", (cmdArgs) => {
+        cmdArgs.options({
+            ...sharedOptions,
+            scope: {
+                alias: "s",
+                type: "string",
+                describe: "Single scope (default: all scopes from dove.config.js)",
+            },
+            schema: {
+                type: "boolean",
+                default: true,
+                describe: "Include schema drift (report-only). --no-schema to skip. Requires a `dove schema pull --snapshot`.",
+            },
+            "write-baseline": {
+                type: "boolean",
+                default: false,
+                describe: "Establish the per-instance baseline (merge-base) from current live state. Run once before --apply.",
+            },
+            apply: {
+                type: "boolean",
+                default: false,
+                describe: "Apply records branch -> instance: CREATE + UPDATE + tracked DELETE. Refuses on drift unless --force.",
+            },
+            force: {
+                type: "boolean",
+                default: false,
+                describe: "With --apply: discard instance drift (edits to tracked records since baseline). Never deletes the dev's own local records.",
+            },
+        });
+        return cmdArgs;
+    }, async (args) => {
+        await (0, reconcileCommand_1.reconcileCommand)(args);
     })
         .command("init-claude", "Install Dovetail Claude Code skills to .claude/commands/", (cmdArgs) => {
         cmdArgs.options({

package/dist/reconcile/applyPlan.js

@@ -0,0 +1,60 @@
+"use strict";
+// Pure decision layer for the reconcile apply phase: given a classified diff,
+// the dirty set, and the flags, decide whether to refuse and exactly which
+// changes are eligible to apply. No I/O — the command layer executes the plan.
+//
+// Safety model (the git-checkout analogy):
+//   - No baseline            -> refuse. You must establish the merge-base first
+//                              (`dove reconcile --write-baseline`); without it
+//                              there is no way to tell the dev's edits from the
+//                              branch's, so an apply could clobber local work.
+//   - Drift, no --force      -> refuse. Tracked records changed on the instance
+//                              since baseline; refresh to keep them or --force.
+//   - Clean, or --force      -> apply.
+//
+// What applies:
+//   - CREATE  every branch-only record (created on the instance with the
+//             branch's own sys_id — the server honors it via setNewGuidValue).
+//   - UPDATE  every diff update (branch content overwrites the instance).
+//   - DELETE  only "tracked" instance-only records (the branch deleted them).
+//             "local-new" / "no-baseline" records are the dev's own creations —
+//             NEVER deleted, not even with --force (force discards edits to the
+//             branch's records, it does not reap records the branch never owned).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildApplyPlan = buildApplyPlan;
+function buildApplyPlan(options) {
+    const { diff, dirty, hasBaseline, force } = options;
+    const deletes = [];
+    const skippedDeletes = [];
+    for (const change of diff.deletes) {
+        if (change.deleteDisposition === "tracked") {
+            deletes.push(change);
+        }
+        else {
+            skippedDeletes.push(change);
+        }
+    }
+    let refuse = false;
+    let refuseReason = "";
+    if (!hasBaseline) {
+        refuse = true;
+        refuseReason =
+            "no baseline for this instance — establish the merge-base first with " +
+                "`dove reconcile --write-baseline`, then re-run apply.";
+    }
+    else if (dirty.length > 0 && !force) {
+        refuse = true;
+        refuseReason =
+            dirty.length +
+                " record(s) changed on the instance since baseline. Keep them with " +
+                "`dove refresh`, or discard them with --force.";
+    }
+    return {
+        refuse,
+        refuseReason,
+        creates: diff.creates.slice(),
+        updates: diff.updates.slice(),
+        deletes,
+        skippedDeletes,
+    };
+}

package/dist/reconcile/baseline.js

@@ -0,0 +1,126 @@
+"use strict";
+// The reconcile baseline — the "merge-base / index" in the git analogy. It
+// records the {sys_id -> sys_updated_on} the instance was known to hold at the
+// last reconcile (or refresh), namespaced by instance host. It MUST live
+// outside the git tree: after a `git checkout`, the on-disk
+// `metaData._lastUpdatedOn` is the *committer's* refresh time, not this
+// developer's instance state, so the branch files cannot answer "did the dev
+// change the instance since we last synced?". The baseline can.
+//
+// Phase 1 only READS the baseline (to disambiguate deletes and surface drift).
+// `writeBaseline` / `baselineFromLive` are the apply-phase write path and the
+// pure dirty-check is shared by both.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASELINE_FILENAME = void 0;
+exports.baselinePath = baselinePath;
+exports.readBaseline = readBaseline;
+exports.writeBaseline = writeBaseline;
+exports.baselineFromLive = baselineFromLive;
+exports.baselineSysIds = baselineSysIds;
+exports.computeDirty = computeDirty;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+exports.BASELINE_FILENAME = ".dove-reconcile-baseline.json";
+function baselinePath(rootDir) {
+    return path_1.default.join(rootDir, exports.BASELINE_FILENAME);
+}
+function isStringRecordMap(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    for (const key of Object.keys(value)) {
+        if (typeof value[key] !== "string") {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Read the baseline for `instance`. Returns null when the file is absent,
+ * unparseable, malformed, or was captured against a different instance (a
+ * mismatched baseline is useless and must not silently disambiguate the wrong
+ * instance's records). All failure modes degrade to "no baseline", never throw.
+ */
+function readBaseline(rootDir, instance) {
+    const filePath = baselinePath(rootDir);
+    let raw;
+    try {
+        if (!fs_1.default.existsSync(filePath)) {
+            return null;
+        }
+        raw = fs_1.default.readFileSync(filePath, "utf8");
+    }
+    catch (e) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return null;
+    }
+    const candidate = parsed;
+    if (candidate.version !== 1 || !isStringRecordMap(candidate.records)) {
+        return null;
+    }
+    if (instance && candidate.instance && candidate.instance !== instance) {
+        return null;
+    }
+    return {
+        version: 1,
+        instance: candidate.instance || instance,
+        records: candidate.records,
+    };
+}
+function writeBaseline(rootDir, baseline) {
+    fs_1.default.writeFileSync(baselinePath(rootDir), JSON.stringify(baseline, null, 2) + "\n", "utf8");
+}
+/** Build a fresh baseline snapshot from the current live record set. */
+function baselineFromLive(instance, live) {
+    const records = {};
+    for (const record of live) {
+        records[record.sys_id] = record.updatedOn || "";
+    }
+    return { version: 1, instance, records };
+}
+function baselineSysIds(baseline) {
+    if (!baseline) {
+        return null;
+    }
+    return new Set(Object.keys(baseline.records));
+}
+/**
+ * The dev's own uncommitted instance work: records present in the baseline
+ * whose live `sys_updated_on` has moved since. This is the refuse-if-dirty
+ * signal — Phase 1 reports it, Phase 2 blocks apply on it (unless `--force`).
+ * Pure. With no baseline there is nothing to compare against, so it returns [].
+ */
+function computeDirty(options) {
+    const { baseline, live } = options;
+    if (!baseline) {
+        return [];
+    }
+    const dirty = [];
+    for (const record of live) {
+        const baselineStamp = baseline.records[record.sys_id];
+        if (baselineStamp !== undefined &&
+            baselineStamp !== "" &&
+            record.updatedOn !== "" &&
+            record.updatedOn !== baselineStamp) {
+            dirty.push({
+                sys_id: record.sys_id,
+                table: record.table,
+                name: record.name,
+                reason: "changed-since-baseline",
+            });
+        }
+    }
+    return dirty;
+}

package/dist/reconcile/fields.js

@@ -0,0 +1,28 @@
+"use strict";
+// Field-comparison rules for reconcile. A record's on-disk representation is a
+// directory of per-field files plus a `metaData.json` snapshot. metaData is
+// Dovetail bookkeeping — it carries `_lastUpdatedOn`, a host-stripped
+// `_record_link`, and a full field dump, and it is re-stamped on every touch —
+// so including it in a content comparison would make every record read as
+// modified. Excluding it leaves the genuine, content-bearing field files
+// (script.js, etc.), which is exactly what `dove refresh` writes verbatim from
+// the instance. Comparing those raw is therefore consistent with the Phase 1
+// acceptance test: "a reconcile dry-run matches a hand-diff of two refresh
+// snapshots."
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fieldKey = fieldKey;
+exports.isComparableField = isComparableField;
+/** Stable "<field>.<type>" key used on both the branch and live sides. */
+function fieldKey(file) {
+    return file.name + "." + file.type;
+}
+/**
+ * True when a record file is a content-bearing field that should participate in
+ * the diff. Excludes the `metaData.json` bookkeeping file.
+ */
+function isComparableField(file) {
+    if (file.name === "metaData" && file.type === "json") {
+        return false;
+    }
+    return true;
+}

package/dist/reconcile/gitignore.js

@@ -0,0 +1,68 @@
+"use strict";
+// Ensure the per-instance baseline is gitignored in the consumer project. The
+// baseline is per-developer, per-instance local state (the "merge-base/index")
+// and must never be committed. The compute step is pure and unit-tested; the
+// wrapper does the file I/O and never throws (a gitignore it cannot write is a
+// warning, not a failed reconcile).
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasGitignoreEntry = hasGitignoreEntry;
+exports.ensureEntryContent = ensureEntryContent;
+exports.ensureGitignored = ensureGitignored;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function lines(content) {
+    return content.split(/\r?\n/);
+}
+/**
+ * Returns whether `entry` is already an active (non-comment) line in the
+ * gitignore content. Trailing whitespace and blank lines are ignored.
+ */
+function hasGitignoreEntry(content, entry) {
+    const target = entry.trim();
+    for (const line of lines(content)) {
+        const trimmed = line.trim();
+        if (trimmed === target) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Pure: compute the gitignore content that includes `entry`. Appends a tidy
+ * block (with a trailing newline) when missing; returns unchanged when present.
+ * `content` is null when the file does not yet exist.
+ */
+function ensureEntryContent(content, entry) {
+    if (content !== null && hasGitignoreEntry(content, entry)) {
+        return { changed: false, content };
+    }
+    const base = content === null ? "" : content;
+    const needsNewline = base.length > 0 && !base.endsWith("\n");
+    const next = base + (needsNewline ? "\n" : "") + entry + "\n";
+    return { changed: true, content: next };
+}
+function ensureGitignored(rootDir, entry) {
+    const filePath = path_1.default.join(rootDir, ".gitignore");
+    let existing = null;
+    try {
+        if (fs_1.default.existsSync(filePath)) {
+            existing = fs_1.default.readFileSync(filePath, "utf8");
+        }
+    }
+    catch (e) {
+        existing = null;
+    }
+    const update = ensureEntryContent(existing, entry);
+    if (update.changed) {
+        try {
+            fs_1.default.writeFileSync(filePath, update.content, "utf8");
+        }
+        catch (e) {
+            return { changed: false, content: existing || "" };
+        }
+    }
+    return update;
+}

package/dist/reconcile/multiPass.js

@@ -0,0 +1,55 @@
+"use strict";
+// FK-safe record operations without building a dependency graph. ServiceNow
+// refuses to delete a record another still references, and refuses to create a
+// record before the parent it references exists. Both orderings fall out of the
+// same loop: attempt every pending record, keep whatever succeeded, retry the
+// failures next pass, stop when a full pass makes no progress (a genuine,
+// non-ordering failure — e.g. ACL) and report the stragglers.
+//   - DELETE: a parent blocked by a still-present child succeeds once the child
+//     is gone (children before parents).
+//   - CREATE: a child blocked by a missing parent succeeds once the parent
+//     exists (parents before children).
+//
+// Pure control flow: the operation is injected, so the loop is unit-tested with
+// a fake executor that encodes a dependency ("B cannot proceed until A has").
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMultiPassOps = runMultiPassOps;
+async function runMultiPassOps(changes, attempt) {
+    const succeeded = [];
+    let pending = changes.slice();
+    let lastError = new Map();
+    while (pending.length > 0) {
+        const stillPending = [];
+        let progressed = false;
+        lastError = new Map();
+        for (const change of pending) {
+            let result;
+            try {
+                result = await attempt(change);
+            }
+            catch (e) {
+                result = { ok: false, error: e instanceof Error ? e.message : String(e) };
+            }
+            if (result.ok) {
+                succeeded.push({ change, ok: true });
+                progressed = true;
+            }
+            else {
+                stillPending.push(change);
+                lastError.set(change.sys_id, result.error || "operation failed");
+            }
+        }
+        pending = stillPending;
+        if (!progressed) {
+            // A full pass changed nothing — the remaining failures are not ordering
+            // problems. Report them and stop.
+            break;
+        }
+    }
+    const failures = pending.map((change) => ({
+        change,
+        ok: false,
+        error: lastError.get(change.sys_id) || "operation failed",
+    }));
+    return succeeded.concat(failures);
+}

package/dist/reconcile/recordDiff.js

@@ -0,0 +1,103 @@
+"use strict";
+// The pure record-diff engine: classify every tracked record into create /
+// update / delete / unchanged by joining the branch and live sides on sys_id.
+// No I/O — callers supply already-normalized ReconcileRecord[] (see
+// recordSource.ts for the on-disk + instance adapters). Fully unit-testable.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffRecords = diffRecords;
+function indexBySysId(records) {
+    const map = new Map();
+    for (const record of records) {
+        map.set(record.sys_id, record);
+    }
+    return map;
+}
+function toChange(kind, record, fieldDeltas) {
+    return {
+        kind,
+        table: record.table,
+        scope: record.scope,
+        sys_id: record.sys_id,
+        name: record.name,
+        fieldDeltas,
+    };
+}
+// Compare two sides of the same record. Emits one FieldDelta per field that is
+// added, removed, or changed; identical fields produce nothing.
+function computeFieldDeltas(branch, live) {
+    const keys = new Set();
+    for (const key of Object.keys(branch.fields)) {
+        keys.add(key);
+    }
+    for (const key of Object.keys(live.fields)) {
+        keys.add(key);
+    }
+    const deltas = [];
+    for (const key of Array.from(keys).sort()) {
+        const onBranch = Object.prototype.hasOwnProperty.call(branch.fields, key);
+        const onLive = Object.prototype.hasOwnProperty.call(live.fields, key);
+        const changed = onBranch && onLive && branch.fields[key] !== live.fields[key];
+        if (!onBranch || !onLive || changed) {
+            deltas.push({ field: key, onBranch, onLive, changed });
+        }
+    }
+    return deltas;
+}
+function byTableThenName(a, b) {
+    if (a.table !== b.table) {
+        return a.table < b.table ? -1 : 1;
+    }
+    if (a.name !== b.name) {
+        return a.name < b.name ? -1 : 1;
+    }
+    return a.sys_id < b.sys_id ? -1 : a.sys_id > b.sys_id ? 1 : 0;
+}
+function diffRecords(options) {
+    const { branch, live } = options;
+    const branchIndex = indexBySysId(branch);
+    const liveIndex = indexBySysId(live);
+    const hasBaseline = options.baselineSysIds !== null;
+    const baseline = options.baselineSysIds || new Set();
+    const creates = [];
+    const updates = [];
+    const deletes = [];
+    let unchangedCount = 0;
+    // CREATE + UPDATE/unchanged — walk the branch side.
+    for (const branchRecord of branch) {
+        const liveRecord = liveIndex.get(branchRecord.sys_id);
+        if (!liveRecord) {
+            creates.push(toChange("create", branchRecord, []));
+            continue;
+        }
+        const deltas = computeFieldDeltas(branchRecord, liveRecord);
+        if (deltas.length === 0) {
+            unchangedCount++;
+        }
+        else {
+            updates.push(toChange("update", branchRecord, deltas));
+        }
+    }
+    // DELETE — live records the branch no longer carries.
+    for (const liveRecord of live) {
+        if (branchIndex.has(liveRecord.sys_id)) {
+            continue;
+        }
+        let disposition;
+        if (!hasBaseline) {
+            disposition = "no-baseline";
+        }
+        else if (baseline.has(liveRecord.sys_id)) {
+            disposition = "tracked";
+        }
+        else {
+            disposition = "local-new";
+        }
+        const change = toChange("delete", liveRecord, []);
+        change.deleteDisposition = disposition;
+        deletes.push(change);
+    }
+    creates.sort(byTableThenName);
+    updates.sort(byTableThenName);
+    deletes.sort(byTableThenName);
+    return { creates, updates, deletes, unchangedCount };
+}