@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/sync/git.mjs

@@ -0,0 +1,149 @@
+// sync — git operations.
+//
+// Thin wrappers around the specific git invocations sync performs. Every
+// function delegates spawning to the runner chokepoint — nothing here
+// touches the outside world directly.
+//
+// The set is intentionally minimal: status, branch, ahead/behind, fetch,
+// pull --rebase, rebase --abort, add -A, commit, push. Sync is the SOLE
+// git writer on a host running HQ crons; if we ever need a new git
+// operation here, it should be considered carefully — a wider surface
+// invites the kind of race this tool exists to eliminate.
+
+// `--untracked-files=all` is load-bearing, not cosmetic: plain
+// `git status --porcelain` collapses a WHOLLY untracked directory to a
+// single ancestor line (e.g. `?? agents/` when nothing under `agents/`
+// is tracked), rather than listing each untracked file individually.
+// registry-scope.mjs's exclusion check is a `startsWith` match against
+// mount `to` prefixes (e.g. `agents/dave/`) — a collapsed `agents/` line
+// does not start with `agents/dave/`, so it survives the exclusion
+// filter and everything under it (mount-owned content included) gets
+// staged. This only bites when the mount target has no tracked anchor
+// file anywhere in its ancestry (fresh onboarding, no prior commits
+// under that subtree) — exactly the case a brand-new mount hits. `=all`
+// makes git enumerate every untracked file individually, so each path
+// is checked against the exclusion prefixes on its own merits.
+export async function statusPorcelain(runner, { cwd }) {
+  return runner.spawn('git', ['status', '--porcelain', '--untracked-files=all'], { cwd });
+}
+
+export async function currentBranch(runner, { cwd }) {
+  const r = await runner.spawn('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd });
+  return r.stdout.trim();
+}
+
+// Are we ahead of / behind the upstream tracking branch?
+//
+// Returns { ahead, behind }. Either may be NaN if upstream is missing —
+// callers treat NaN ahead as "0 ahead" (nothing to push) and NaN behind as
+// "no upstream tracking, do not pull".
+export async function aheadBehind(runner, { cwd }) {
+  const r = await runner.spawn(
+    'git',
+    ['rev-list', '--left-right', '--count', 'HEAD...@{u}'],
+    { cwd },
+  );
+  if (r.code !== 0) {
+    return { ahead: NaN, behind: NaN };
+  }
+  const parts = r.stdout.trim().split(/\s+/);
+  const ahead = Number.parseInt(parts[0], 10);
+  const behind = Number.parseInt(parts[1], 10);
+  return { ahead, behind };
+}
+
+export async function fetchOrigin(runner, { cwd }) {
+  return runner.spawn('git', ['fetch', 'origin'], { cwd });
+}
+
+export async function pullRebase(runner, { cwd, branch }) {
+  return runner.spawn('git', ['pull', '--rebase', '--quiet', 'origin', branch], { cwd });
+}
+
+export async function rebaseAbort(runner, { cwd }) {
+  return runner.spawn('git', ['rebase', '--abort'], { cwd });
+}
+
+export async function addAll(runner, { cwd }) {
+  return runner.spawn('git', ['add', '-A'], { cwd });
+}
+
+export async function hasStagedChanges(runner, { cwd }) {
+  const r = await runner.spawn('git', ['diff', '--cached', '--quiet'], { cwd });
+  return r.code !== 0;
+}
+
+// Commit with a title + optional multi-paragraph body. Passes message
+// through argv (-m / -m) — runner spawns with shell:false so embedded
+// quotes / newlines are safe without further escaping.
+export async function commit(runner, { cwd, title, body }) {
+  const args = ['commit', '-m', title];
+  if (body && body.length > 0) {
+    args.push('-m', body);
+  }
+  return runner.spawn('git', args, { cwd });
+}
+
+export async function push(runner, { cwd }) {
+  return runner.spawn('git', ['push'], { cwd });
+}
+
+// Parse `git status --porcelain` output for paths currently in conflict.
+// Git marks unmerged entries with an XY code from a fixed set (see
+// git-status(1) `Short Format` — "Unmerged entries have the following
+// second column"): DD, AU, UD, UA, DU, AA, UU. Anything else is a normal
+// modification (M ), untracked (??), etc.
+export async function listConflictedPaths(runner, { cwd }) {
+  const r = await runner.spawn('git', ['status', '--porcelain'], { cwd });
+  if (r.code !== 0) {
+    return { code: r.code, stderr: r.stderr, paths: [] };
+  }
+  const paths = [];
+  for (const line of r.stdout.split('\n')) {
+    // Porcelain v1 line: `XY <path>` where XY is exactly two chars
+    // followed by a space. Renamed entries use `XY <old> -> <new>` — the
+    // conflict codes below never apply to renames, so we treat the tail
+    // as the path verbatim.
+    if (line.length < 4) continue;
+    const xy = line.slice(0, 2);
+    if (xy === 'DD' || xy === 'AU' || xy === 'UD' || xy === 'UA'
+        || xy === 'DU' || xy === 'AA' || xy === 'UU') {
+      paths.push(line.slice(3));
+    }
+  }
+  return { code: 0, stderr: '', paths };
+}
+
+// Take upstream's version of `paths` during a rebase.
+//
+// GOTCHA — rebase inverts --ours / --theirs vs merge. During a rebase,
+// `--ours` refers to the branch we are rebasing ONTO (upstream, i.e.
+// origin's version) and `--theirs` refers to the branch that holds the
+// commit being replayed (our local work). This is the opposite of merge,
+// where `--ours` is the current branch. Since we want to keep origin's
+// version and drop our fresh regeneration, we pass `--ours`. See the
+// note in git-checkout(1): "Note that during git rebase and git pull
+// --rebase, ours and theirs may appear swapped."
+export async function checkoutOursDuringRebase(runner, { cwd, paths }) {
+  if (paths.length === 0) return { code: 0, stdout: '', stderr: '' };
+  return runner.spawn('git', ['checkout', '--ours', '--', ...paths], { cwd });
+}
+
+// Stage specific paths after conflict resolution. Uses `git add --` to
+// stop any leading `-`-prefixed path being treated as a flag.
+export async function addPaths(runner, { cwd, paths }) {
+  if (paths.length === 0) return { code: 0, stdout: '', stderr: '' };
+  return runner.spawn('git', ['add', '--', ...paths], { cwd });
+}
+
+// Continue an in-progress rebase after conflict resolution. `git rebase
+// --continue` may want to open $EDITOR to confirm the message of the
+// replayed commit; forcing GIT_EDITOR=true (the `true` binary, exit 0)
+// makes it accept the existing message unmodified and continue.
+export async function rebaseContinue(runner, { cwd }) {
+  return runner.spawn(
+    'git',
+    ['rebase', '--continue'],
+    { cwd, env: { ...process.env, GIT_EDITOR: 'true' } },
+  );
+}

package/dist/engineering-pa-cli/src/sync/lock.mjs

@@ -0,0 +1,30 @@
+// sync — process lock.
+//
+// Two sync runs on the same host MUST NOT overlap. A second instance
+// trying to push while the first is mid-commit would just hit the same
+// remote-rejected → rebase-retry path; on a slow host it could land in a
+// loop. Cheaper to short-circuit at start.
+//
+// Implementation: delegates to the shared core lock utility
+// (`@stravica-ai/engineering-pa-core` → `acquireLock`, see
+// packages/core/docs/lock.md) with sync's own staleness window: 10
+// minutes. The core default (2 hours) is sized for long agent sweeps;
+// sync runs are seconds long on a 30-minute cron tick, so a 10-minute
+// window is a safe, much faster self-heal for a wedged run. On stale,
+// the lock is stolen; on contention with a live PID the caller exits `0`
+// with status `noop-locked` — the next tick will retry.
+//
+// `acquire` keeps the historical sync signature and return shape
+// ({ acquired, reason } | { acquired, record, release }); tests inject
+// `now()`, `isProcessAlive`, and a fake fs exactly as before.
+
+// Subpath import (not the bare package) — the engineering-pa dist bundle
+// rewrites cross-package import strings to relative paths, and a bare
+// package import would rewrite to a directory path ESM cannot resolve.
+import { acquireLock } from '../../../engineering-pa-core/src/lock/lock.mjs';
+
+const STALE_AFTER_MS = 10 * 60 * 1000; // 10 minutes
+
+export async function acquire(lockPath, options = {}) {
+  return acquireLock(lockPath, { staleAfterMs: STALE_AFTER_MS, ...options });
+}

package/dist/engineering-pa-cli/src/sync/regenerated-artifacts.mjs

@@ -0,0 +1,114 @@
+// sync — regenerated-artifacts allowlist for auto-conflict-resolution.
+//
+// The problem this solves: on a multi-host HQ deploy, distillation runs
+// on more than one host and regenerates the same knowledge-artifact files
+// (`.graph.json`, `domains.json`, `profile.md`, auto-classified system
+// pages, …). The output is byte-different across hosts (timestamps,
+// map-key ordering, whitespace) but semantically equivalent — every host
+// gets the same information, just written slightly differently. When two
+// hosts push their regenerations within the same cron window, sync's
+// `pull --rebase` conflicts on those files, exits `fail-rebase`, and
+// wedges the cron until a human `git reset --hard origin/main`s the loser.
+//
+// Fix: when a rebase conflicts AND every conflicted path is in the
+// allowlist below, sync takes origin's version, continues the rebase, and
+// pushes. The regeneration we discarded will land in origin naturally on
+// the next distill cycle — that cycle will fold in whatever staging
+// observations we contributed AND whatever the other host contributed.
+// Nothing is lost.
+//
+// Conflicts on any path outside the allowlist still fail-rebase exit 2 —
+// real conflicts must surface for a human to resolve.
+//
+// Extension: repos can add project-specific regenerable paths via a
+// `.sync-config.json` at the repo root:
+//   { "regeneratedArtifacts": ["path/to/generated/**"] }
+// Entries are additive to the built-in defaults; unknown fields are
+// ignored so future config additions do not need this module updated.
+
+import { readFile } from 'node:fs/promises';
+import { join, matchesGlob } from 'node:path';
+
+// Files/globs that distillation regenerates each cycle. Any rebase
+// conflict on these paths is a byte-race between two hosts' regenerations
+// and can safely be auto-resolved by taking origin's version. Paths are
+// relative to the repo root. Globs use POSIX-style `*` (single segment)
+// and `**` (any number of segments) as understood by `path.matchesGlob`
+// (stable in Node ≥ 22.5).
+export const DEFAULT_REGENERATED_ARTIFACTS = Object.freeze([
+  'operator/knowledge/.graph.json',
+  'operator/knowledge/.backlinks.json',
+  'operator/knowledge/domains.json',
+  'operator/profile/profile.md',
+  'operator/profile/operator.json',
+  'operator/knowledge/systems/web-properties/*.md',
+]);
+
+const CONFIG_FILENAME = '.sync-config.json';
+
+// Load the effective allowlist: defaults ∪ any operator-supplied globs
+// from `<repoRoot>/.sync-config.json`. Failure modes are non-fatal:
+//   - no file           → defaults only, source = 'defaults'
+//   - unreadable file   → defaults only, source = 'defaults', warning set
+//   - malformed JSON    → defaults only, source = 'defaults', warning set
+//   - malformed field   → defaults only, source = 'defaults' (silently
+//                          drops non-string entries; array must be array)
+// Callers should log the returned `warning` (if any) so a broken config
+// is visible without wedging the cron.
+export async function loadRegeneratedArtifacts({ repoRoot, fs = { readFile } } = {}) {
+  const defaults = [...DEFAULT_REGENERATED_ARTIFACTS];
+  const result = {
+    patterns: defaults,
+    source: 'defaults',
+    configPath: null,
+    added: 0,
+    warning: null,
+  };
+  if (!repoRoot) return result;
+  const configPath = join(repoRoot, CONFIG_FILENAME);
+  result.configPath = configPath;
+  let raw;
+  try {
+    raw = await fs.readFile(configPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return result;
+    result.warning = `read failed: ${err.message}`;
+    return result;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    result.warning = `parse failed: ${err.message}`;
+    return result;
+  }
+  const extra = Array.isArray(parsed?.regeneratedArtifacts)
+    ? parsed.regeneratedArtifacts.filter((p) => typeof p === 'string' && p.length > 0)
+    : [];
+  if (extra.length === 0) return result;
+  return {
+    ...result,
+    patterns: [...defaults, ...extra],
+    source: 'defaults+config',
+    added: extra.length,
+  };
+}
+
+// Does `relPath` (repo-root-relative, forward slashes) match any pattern?
+export function isAllowedPath(relPath, patterns) {
+  for (const pat of patterns) {
+    if (matchesGlob(relPath, pat)) return true;
+  }
+  return false;
+}
+
+// Split `paths` by the allowlist. Preserves input order in each bucket.
+export function classifyConflicts(paths, patterns) {
+  const allowed = [];
+  const disallowed = [];
+  for (const p of paths) {
+    if (isAllowedPath(p, patterns)) allowed.push(p);
+    else disallowed.push(p);
+  }
+  return { allowed, disallowed };
+}

package/dist/engineering-pa-cli/src/sync/registry-scope.mjs

@@ -0,0 +1,260 @@
+// estate-sync — registry-scoped commit set.
+//
+// Replaces the blind `git add -A` with a computed COMMIT SCOPE: when
+// `<repoRoot>/operator/registry/{devices.json,repos.json}` exist, this
+// module resolves the current device (same hostname short-name algorithm
+// as `operator/extensions/tools/library-sync/run.mjs`'s resolveDeviceId),
+// derives every mount `to` subtree for repos this device is entitled to,
+// and returns that set as the EXCLUSION list. `.vault/**` is excluded
+// unconditionally regardless of registry state.
+//
+// Per the library-sync-solidification architecture decision (D1/D2): the
+// in-scope (committable) set is everything NOT under any mount `to` path.
+// This is deliberately simpler than library-sync's own down-path owner-
+// exclusion (which carves out THIS device's own upPath-owned mount) —
+// estate-sync excludes ALL mount `to` subtrees unconditionally, including
+// the device's own agent tree, because D2 moves `agents/*` run-state
+// wholly onto the library pipeline; estate-sync (the git layer) must never
+// be a second writer for any mount-owned path, owned-by-this-device or not.
+//
+// Degrade-gracefully-never-crash: any registry read/parse/resolve failure
+// (missing files, malformed JSON, unknown device) falls back to
+// `registryPresent: false` with a warning explaining why — the caller
+// (run.mjs) then falls back to the pre-rewrite unscoped `git add -A`
+// behaviour with a loud warning, never a silent unscoped commit and never
+// a crashed sync run.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { hostname as osHostname } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Resolve which device id to run as, matching os.hostname() against each
+ * device's `host` field (exact, then prefix-before-first-dot) or against
+ * the device id itself. Mirrors
+ * `operator/extensions/tools/library-sync/run.mjs`'s resolveDeviceId
+ * exactly, so the two tools never disagree about "which device am I".
+ *
+ * @param {object} devicesDoc
+ * @param {string} currentHostname
+ * @returns {string|null}
+ */
+export function resolveDeviceId(devicesDoc, currentHostname) {
+  const shortCurrent = currentHostname.split('.')[0];
+  const devices = (devicesDoc && devicesDoc.devices) || {};
+  for (const [id, device] of Object.entries(devices)) {
+    if (device.host === currentHostname) return id;
+    if (id === currentHostname || id === shortCurrent) return id;
+  }
+  for (const [id, device] of Object.entries(devices)) {
+    if (typeof device.host === 'string' && device.host.split('.')[0] === shortCurrent) return id;
+  }
+  return null;
+}
+
+/**
+ * Resolve the repos a device is entitled to, paired with their mount
+ * definitions. Never throws — an entitlement referencing a repo id absent
+ * from repos.json is skipped with a warning (registry drift, not a reason
+ * to crash a 30-minute cron).
+ *
+ * @param {object} registry - { devices, repos } parsed JSON docs
+ * @param {string} deviceId
+ * @returns {{ entitled: { repoId: string, repo: object }[], warnings: string[] }}
+ */
+export function resolveEntitlements(registry, deviceId) {
+  const warnings = [];
+  const device = registry.devices?.devices?.[deviceId];
+  if (!device) {
+    warnings.push(`device "${deviceId}" not found in devices.json`);
+    return { entitled: [], warnings };
+  }
+  const repoIds = device.entitlements?.repos;
+  if (!Array.isArray(repoIds)) {
+    warnings.push(`device "${deviceId}" has no entitlements.repos array`);
+    return { entitled: [], warnings };
+  }
+  const entitled = [];
+  for (const repoId of repoIds) {
+    const repo = registry.repos?.repos?.[repoId];
+    if (!repo) {
+      warnings.push(`device "${deviceId}" entitles repo "${repoId}" not present in repos.json`);
+      continue;
+    }
+    entitled.push({ repoId, repo });
+  }
+  return { entitled, warnings };
+}
+
+/** Normalise a mount `to` path to a POSIX-style directory prefix ending in "/". */
+function normalizeDir(to) {
+  let p = String(to).split('\\').join('/');
+  if (p.startsWith('./')) p = p.slice(2);
+  if (!p.endsWith('/')) p += '/';
+  return p;
+}
+
+/**
+ * Derive the exclusion set: every entitled repo's mount `to` subtree,
+ * unconditionally (D1/D2 — no ownership carve-out; see module doc), plus
+ * `.vault/**` unconditionally. Sorted, deduped.
+ *
+ * @param {{ repoId: string, repo: object }[]} entitled
+ * @returns {string[]} POSIX-relative directory prefixes, each ending in "/"
+ */
+export function computeExcludeDirs(entitled) {
+  const dirs = new Set();
+  for (const { repo } of entitled) {
+    const mounts = Array.isArray(repo.mounts) ? repo.mounts : [];
+    for (const mount of mounts) {
+      if (mount && typeof mount.to === 'string' && mount.to.length > 0) {
+        dirs.add(normalizeDir(mount.to));
+      }
+    }
+  }
+  dirs.add('.vault/');
+  return [...dirs].sort();
+}
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+/**
+ * Compute the full commit-scope decision for this device/repo, degrading
+ * gracefully at every failure point (see module doc).
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot
+ * @param {() => string} [opts.hostnameFn] - injectable for tests
+ * @returns {{
+ *   registryPresent: boolean,
+ *   deviceId?: string,
+ *   excludeDirs: string[],
+ *   warnings: string[],
+ * }}
+ */
+export function computeCommitScope({ repoRoot, hostnameFn = osHostname }) {
+  const devicesPath = join(repoRoot, 'operator/registry/devices.json');
+  const reposPath = join(repoRoot, 'operator/registry/repos.json');
+
+  if (!existsSync(devicesPath) || !existsSync(reposPath)) {
+    return { registryPresent: false, excludeDirs: [], warnings: [] };
+  }
+
+  let devicesDoc;
+  let reposDoc;
+  try {
+    devicesDoc = readJson(devicesPath);
+    reposDoc = readJson(reposPath);
+  } catch (err) {
+    return {
+      registryPresent: false,
+      excludeDirs: [],
+      warnings: [`registry present but unreadable (${err.message}) — falling back to unscoped`],
+    };
+  }
+
+  const deviceId = resolveDeviceId(devicesDoc, hostnameFn());
+  if (!deviceId) {
+    return {
+      registryPresent: false,
+      excludeDirs: [],
+      warnings: [`could not resolve a device id from hostname "${hostnameFn()}" against ${devicesPath} — falling back to unscoped`],
+    };
+  }
+
+  const { entitled, warnings } = resolveEntitlements({ devices: devicesDoc, repos: reposDoc }, deviceId);
+  const excludeDirs = computeExcludeDirs(entitled);
+
+  return { registryPresent: true, deviceId, excludeDirs, warnings };
+}
+
+/**
+ * Parse `git status --porcelain` output into a flat list of paths. Rename
+ * entries (`R  old -> new`) contribute BOTH paths — `git add -- <path>`
+ * correctly stages a deletion when given an explicit path that no longer
+ * exists on disk (git >= 2.0), so staging both sides of a rename is
+ * sufficient without needing `-A` semantics.
+ *
+ * Shares the same C-style-quoting limitation as `listConflictedPaths` in
+ * git.mjs (paths with unusual characters are not unquoted) — acceptable,
+ * matches existing precedent in this module.
+ *
+ * @param {string} porcelainOutput
+ * @returns {string[]}
+ */
+export function parsePorcelainPaths(porcelainOutput) {
+  const out = [];
+  for (const rawLine of porcelainOutput.split('\n')) {
+    if (rawLine.length < 4) continue;
+    const rest = rawLine.slice(3);
+    const arrowIdx = rest.indexOf(' -> ');
+    if (arrowIdx !== -1) {
+      out.push(rest.slice(0, arrowIdx));
+      out.push(rest.slice(arrowIdx + 4));
+    } else {
+      out.push(rest);
+    }
+  }
+  return out;
+}
+
+/** Is `path` under one of `excludeDirs` (each ending in "/")? */
+export function isExcluded(path, excludeDirs) {
+  return excludeDirs.some((dir) => path === dir.slice(0, -1) || path.startsWith(dir));
+}
+
+/**
+ * Filter porcelain output down to the in-scope (committable) paths —
+ * everything NOT under an excluded subtree. Dedupes (a path can appear
+ * twice from a rename pair sharing a prefix) while preserving first-seen
+ * order.
+ *
+ * @param {string} porcelainOutput
+ * @param {string[]} excludeDirs
+ * @returns {{ inScope: string[], excludedCount: number }}
+ */
+export function filterInScopePaths(porcelainOutput, excludeDirs) {
+  const allPaths = parsePorcelainPaths(porcelainOutput);
+  const seen = new Set();
+  const inScope = [];
+  let excludedCount = 0;
+  for (const p of allPaths) {
+    if (isExcluded(p, excludeDirs)) {
+      excludedCount += 1;
+      continue;
+    }
+    if (!seen.has(p)) {
+      seen.add(p);
+      inScope.push(p);
+    }
+  }
+  return { inScope, excludedCount };
+}
+
+/**
+ * Render the scope-decision section for the commit body (requirement:
+ * "report the scope decision in the commit body — counts: staged N paths,
+ * excluded M subtrees by rule").
+ *
+ * @param {object} scope - result of computeCommitScope
+ * @param {object} counts
+ * @param {number} counts.staged
+ * @param {number} counts.excludedPaths - dirty paths that were excluded
+ * @returns {string}
+ */
+export function renderScopeSection(scope, { staged, excludedPaths }) {
+  if (!scope.registryPresent) {
+    return 'estate-sync: no registry found, unscoped commit';
+  }
+  const lines = [
+    `estate-sync scope: registry-scoped (device=${scope.deviceId})`,
+    `  staged: ${staged} path(s)`,
+    `  excluded: ${scope.excludeDirs.length} subtree(s) by rule (${excludedPaths} dirty path(s) matched) — ${scope.excludeDirs.join(', ')}`,
+  ];
+  if (scope.warnings.length > 0) {
+    lines.push(`  warnings: ${scope.warnings.join('; ')}`);
+  }
+  return lines.join('\n');
+}