@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/staging-alias/commands/set.mjs

@@ -0,0 +1,188 @@
+// set.mjs — `pa staging-alias set --site <hostname> --branch <branch>`
+//
+// Wires `staging.<hostname>` to the latest preview version of the source
+// Worker (which Workers Builds populated when the branch was pushed).
+//
+// Steps:
+//   1. Resolve the site entry + load CF creds for the right account.
+//   2. Drill: GET /accounts/{id} and assert `result.name` matches
+//      `expectedAccountName`. ABORT if it doesn't.
+//   3. List versions on the source worker, pick the newest (or the one
+//      pinned by --version, when provided). Per-branch tagging is not
+//      surfaced by CF's API today; the contract is "operator just pushed
+//      the named branch, so the latest version is theirs". The CLI
+//      surfaces the picked version's metadata so the operator can verify.
+//   4. Compute the workers.dev preview hostname for that version.
+//   5. Resolve the zone id for `<site>` (we use the site's apex zone —
+//      `staging.<apex>` is on the same zone).
+//   6. Upload the router worker (`<source>-staging`) with STAGING_TARGET
+//      bound to the preview hostname. Compat date pinned by the helper.
+//   7. Bind `staging.<hostname>` to the router worker as a Custom Domain
+//      (idempotent — no-op if already correct).
+//   8. Print the final URL.
+//
+// On any step failure after the upload, the command rolls back by
+// removing the binding it created in step 7 (if step 7 succeeded). The
+// router-worker upload itself is left in place because the failure mode
+// it's most often associated with is the Custom-Domain binding, which is
+// the destructive surface — a stranded router worker with no domain bound
+// is harmless. The next `set` call will overwrite it cleanly.
+
+import { resolveSite, stagingHostname } from '../sites.mjs';
+import { loadCloudflareCreds } from '../../gsc/cloudflare.mjs';
+import {
+  verifyAccount,
+  resolveAccountSubdomain,
+  resolveZoneId,
+  listWorkerVersions,
+  previewHostname,
+  workerScriptExists,
+  uploadRouterWorker,
+  bindWorkerCustomDomain,
+  unbindWorkerCustomDomain,
+} from '../cloudflare.mjs';
+
+export function parseFlags(args) {
+  const out = { site: null, branch: null, version: null, yes: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--site') out.site = args[++i];
+    else if (a.startsWith('--site=')) out.site = a.slice('--site='.length);
+    else if (a === '--branch') out.branch = args[++i];
+    else if (a.startsWith('--branch=')) out.branch = a.slice('--branch='.length);
+    else if (a === '--version') out.version = args[++i];
+    else if (a.startsWith('--version=')) out.version = a.slice('--version='.length);
+    else if (a === '--yes' || a === '-y') out.yes = true;
+    else {
+      throw Object.assign(new Error(`unexpected argument: ${a}`), { exitCode: 1 });
+    }
+  }
+  if (!out.site) throw Object.assign(new Error('--site is required'), { exitCode: 1 });
+  if (!out.branch && !out.version) {
+    throw Object.assign(new Error('one of --branch or --version is required'), { exitCode: 1 });
+  }
+  return out;
+}
+
+export async function runSet(args, overrides = {}) {
+  let flags;
+  try { flags = parseFlags(args); } catch (e) {
+    process.stderr.write(`[staging-alias set] ${e.message}\n`);
+    return e.exitCode || 1;
+  }
+
+  const out = overrides.stdout || process.stdout;
+  const log = (msg) => out.write(`[staging-alias set] ${msg}\n`);
+
+  let site;
+  try { site = resolveSite(flags.site); } catch (e) {
+    process.stderr.write(`[staging-alias set] ${e.message}\n`);
+    return e.exitCode || 1;
+  }
+  const staging = stagingHostname(site);
+
+  // ── Step 1+2: credentials + safety drill. ──
+  let creds;
+  try {
+    creds = await loadCloudflareCreds({ ...overrides, account: site.accountKey });
+  } catch (e) {
+    process.stderr.write(`[staging-alias set] vault: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+  log(`using vault keys for account "${site.accountKey}"`);
+
+  let verified;
+  try {
+    verified = await verifyAccount(creds, site.expectedAccountName, overrides.fetchImpl);
+  } catch (e) {
+    process.stderr.write(`[staging-alias set] account drill FAILED: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+  log(`account verified: "${verified.name}" (${verified.id})`);
+
+  // ── Step 3: pick version. ──
+  let versionId;
+  let versionMeta;
+  if (flags.version) {
+    versionId = flags.version;
+    log(`using --version ${versionId} (no version-listing fetch)`);
+  } else {
+    let versions;
+    try {
+      versions = await listWorkerVersions(creds, site.sourceWorker, overrides.fetchImpl);
+    } catch (e) {
+      process.stderr.write(`[staging-alias set] listVersions: ${e.message}\n`);
+      return e.exitCode || 2;
+    }
+    if (versions.length === 0) {
+      process.stderr.write(
+        `[staging-alias set] worker "${site.sourceWorker}" has no versions yet. ` +
+        `Push branch "${flags.branch}" to trigger Workers Builds first.\n`,
+      );
+      return 1;
+    }
+    versionMeta = versions[0];
+    versionId = versionMeta.id;
+    log(`branch "${flags.branch}" -> latest version ${versionId} (number=${versionMeta.number}, created=${versionMeta?.metadata?.created_on})`);
+    log('note: CF does not tag versions with branch; verify the version matches your branch push.');
+  }
+
+  // ── Step 4: compute preview hostname. ──
+  let subdomain;
+  try {
+    subdomain = await resolveAccountSubdomain(creds, overrides.fetchImpl);
+  } catch (e) {
+    process.stderr.write(`[staging-alias set] subdomain: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+  const targetHost = previewHostname(versionId, site.sourceWorker, subdomain);
+  log(`router target: https://${targetHost}/`);
+
+  // ── Step 5: zone id. ──
+  let zone;
+  try {
+    zone = await resolveZoneId(creds, site.zoneName, overrides.fetchImpl);
+  } catch (e) {
+    process.stderr.write(`[staging-alias set] resolveZone: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+  log(`zone: ${zone.zoneName} (${zone.zoneId})`);
+
+  // ── Step 6: upload router worker. ──
+  try {
+    await uploadRouterWorker(creds, site.routerWorker, targetHost, overrides.fetchImpl);
+    log(`router worker "${site.routerWorker}" uploaded with STAGING_TARGET=${targetHost}`);
+  } catch (e) {
+    process.stderr.write(`[staging-alias set] uploadRouterWorker: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+
+  // ── Step 7: bind Custom Domain. ──
+  let bindResult;
+  try {
+    bindResult = await bindWorkerCustomDomain(
+      creds, staging, site.routerWorker, zone.zoneId, overrides.fetchImpl,
+    );
+    log(`Custom Domain ${staging} -> ${site.routerWorker}: ${bindResult.action}`);
+  } catch (e) {
+    // No previous step depends on the binding existing — nothing to roll back.
+    process.stderr.write(`[staging-alias set] bindCustomDomain: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+
+  // ── Step 8: print URL. ──
+  const url = `https://${staging}/`;
+  out.write(JSON.stringify({
+    site: site.hostname,
+    staging,
+    branch: flags.branch || null,
+    versionId,
+    targetHost,
+    routerWorker: site.routerWorker,
+    customDomainAction: bindResult.action,
+    url,
+  }, null, 2) + '\n');
+  log(`done. ${url} now serves the chosen preview version.`);
+  log('TLS cert provisioning can take up to ~60s on first bind.');
+  return 0;
+}

package/dist/engineering-pa-cli/src/staging-alias/commands/status.mjs

@@ -0,0 +1,113 @@
+// status.mjs — `pa staging-alias status --site <hostname>`
+//
+// Read-only probe of the current staging-alias state for one site.
+// Reports:
+//   - Whether the router worker exists.
+//   - The router's STAGING_TARGET (the workers.dev preview URL).
+//   - Whether `staging.<hostname>` is bound to the router as a Custom Domain.
+//   - The custom-domain TLS cert id (CF doesn't expose cert state via this
+//     endpoint, so we surface presence as a proxy — fuller TLS introspection
+//     would need /accounts/{id}/access/certificates lookups, deferred).
+//
+// Does NOT run the account drill — status is read-only. It does verify
+// the account name and surfaces a warning if it doesn't match the
+// expected value, so the operator notices vault-key drift.
+
+import { resolveSite, stagingHostname } from '../sites.mjs';
+import { loadCloudflareCreds } from '../../gsc/cloudflare.mjs';
+import {
+  cfFetch,
+  readRouterTarget,
+  findWorkerDomain,
+  workerScriptExists,
+} from '../cloudflare.mjs';
+
+export function parseFlags(args) {
+  const out = { site: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--site') out.site = args[++i];
+    else if (a.startsWith('--site=')) out.site = a.slice('--site='.length);
+    else {
+      throw Object.assign(new Error(`unexpected argument: ${a}`), { exitCode: 1 });
+    }
+  }
+  if (!out.site) throw Object.assign(new Error('--site is required'), { exitCode: 1 });
+  return out;
+}
+
+/**
+ * Build a structured status report for a single site. Pure-ish (depends on
+ * CF API via injected creds/fetchImpl).
+ */
+export async function buildStatus(site, creds, fetchImpl) {
+  const staging = stagingHostname(site);
+
+  // Account-name probe (best-effort).
+  let accountName = null;
+  let accountWarning = null;
+  try {
+    const body = await cfFetch(creds.token, `/accounts/${creds.accountId}`, {}, fetchImpl);
+    accountName = body && body.result && body.result.name;
+    if (accountName && accountName !== site.expectedAccountName) {
+      accountWarning = `account name "${accountName}" does not match expected "${site.expectedAccountName}"`;
+    }
+  } catch (e) {
+    accountWarning = `account probe failed: ${e.message}`;
+  }
+
+  const routerExists = await workerScriptExists(creds, site.routerWorker, fetchImpl);
+  const target = routerExists
+    ? await readRouterTarget(creds, site.routerWorker, fetchImpl)
+    : null;
+  const binding = await findWorkerDomain(creds, staging, fetchImpl);
+
+  return {
+    site: site.hostname,
+    staging,
+    accountKey: site.accountKey,
+    accountName,
+    accountWarning,
+    routerWorker: site.routerWorker,
+    routerExists,
+    routerTarget: target,
+    customDomain: binding
+      ? { hostname: binding.hostname, service: binding.service, id: binding.id, certId: binding.cert_id || null }
+      : null,
+    url: binding ? `https://${binding.hostname}/` : null,
+  };
+}
+
+export async function runStatus(args, overrides = {}) {
+  let flags;
+  try { flags = parseFlags(args); } catch (e) {
+    process.stderr.write(`[staging-alias status] ${e.message}\n`);
+    return e.exitCode || 1;
+  }
+
+  let site;
+  try { site = resolveSite(flags.site); } catch (e) {
+    process.stderr.write(`[staging-alias status] ${e.message}\n`);
+    return e.exitCode || 1;
+  }
+
+  let creds;
+  try {
+    creds = await loadCloudflareCreds({ ...overrides, account: site.accountKey });
+  } catch (e) {
+    process.stderr.write(`[staging-alias status] vault: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+
+  let report;
+  try {
+    report = await buildStatus(site, creds, overrides.fetchImpl);
+  } catch (e) {
+    process.stderr.write(`[staging-alias status] ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+
+  const out = overrides.stdout || process.stdout;
+  out.write(JSON.stringify(report, null, 2) + '\n');
+  return report.accountWarning ? 2 : 0;
+}

package/dist/engineering-pa-cli/src/staging-alias/commands/unset.mjs

@@ -0,0 +1,95 @@
+// unset.mjs — `pa staging-alias unset --site <hostname>`
+//
+// Removes `staging.<hostname>` cleanly:
+//   1. Resolve site + creds + drill.
+//   2. Unbind Custom Domain `staging.<hostname>` (idempotent).
+//   3. Delete the router worker script (idempotent).
+//
+// We leave the apex DNS / production custom domains untouched — see the
+// boundaries note in the brief.
+
+import { resolveSite, stagingHostname } from '../sites.mjs';
+import { loadCloudflareCreds } from '../../gsc/cloudflare.mjs';
+import {
+  verifyAccount,
+  unbindWorkerCustomDomain,
+  deleteWorkerScript,
+} from '../cloudflare.mjs';
+
+export function parseFlags(args) {
+  const out = { site: null, keepWorker: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--site') out.site = args[++i];
+    else if (a.startsWith('--site=')) out.site = a.slice('--site='.length);
+    else if (a === '--keep-worker') out.keepWorker = true;
+    else {
+      throw Object.assign(new Error(`unexpected argument: ${a}`), { exitCode: 1 });
+    }
+  }
+  if (!out.site) throw Object.assign(new Error('--site is required'), { exitCode: 1 });
+  return out;
+}
+
+export async function runUnset(args, overrides = {}) {
+  let flags;
+  try { flags = parseFlags(args); } catch (e) {
+    process.stderr.write(`[staging-alias unset] ${e.message}\n`);
+    return e.exitCode || 1;
+  }
+
+  const out = overrides.stdout || process.stdout;
+  const log = (msg) => out.write(`[staging-alias unset] ${msg}\n`);
+
+  let site;
+  try { site = resolveSite(flags.site); } catch (e) {
+    process.stderr.write(`[staging-alias unset] ${e.message}\n`);
+    return e.exitCode || 1;
+  }
+  const staging = stagingHostname(site);
+
+  let creds;
+  try {
+    creds = await loadCloudflareCreds({ ...overrides, account: site.accountKey });
+  } catch (e) {
+    process.stderr.write(`[staging-alias unset] vault: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+
+  let verified;
+  try {
+    verified = await verifyAccount(creds, site.expectedAccountName, overrides.fetchImpl);
+  } catch (e) {
+    process.stderr.write(`[staging-alias unset] account drill FAILED: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+  log(`account verified: "${verified.name}" (${verified.id})`);
+
+  let unbindResult;
+  try {
+    unbindResult = await unbindWorkerCustomDomain(creds, staging, overrides.fetchImpl);
+    log(`unbind ${staging}: ${unbindResult.action}`);
+  } catch (e) {
+    process.stderr.write(`[staging-alias unset] unbind: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+
+  let deleteResult = { action: 'skipped' };
+  if (!flags.keepWorker) {
+    try {
+      deleteResult = await deleteWorkerScript(creds, site.routerWorker, overrides.fetchImpl);
+      log(`delete worker "${site.routerWorker}": ${deleteResult.action}`);
+    } catch (e) {
+      process.stderr.write(`[staging-alias unset] deleteWorker: ${e.message}\n`);
+      return e.exitCode || 2;
+    }
+  }
+
+  out.write(JSON.stringify({
+    site: site.hostname,
+    staging,
+    customDomainAction: unbindResult.action,
+    workerAction: deleteResult.action,
+  }, null, 2) + '\n');
+  return 0;
+}

package/dist/engineering-pa-cli/src/staging-alias/sites.mjs

@@ -0,0 +1,105 @@
+// sites.mjs — Data-driven registry of operator-managed Cloudflare-Workers sites.
+//
+// Each entry binds a public hostname to:
+//   - the source Worker name (the one whose preview deployments we want to
+//     surface at staging.<hostname>),
+//   - the CF account whose vault keys hold the API credentials,
+//   - the expected CF account display name (used for the safety drill: the
+//     CLI reads /accounts/{account_id} before any write and aborts unless
+//     `result.name` matches `expectedAccountName`),
+//   - the router-worker name (derived by convention as `<source>-staging`).
+//
+// Adding a fourth site is one entry. The lookup is intentionally a flat
+// object rather than a search over `operator/knowledge/systems/web-properties/`
+// — the CLI lives in the platform package and must not depend on the
+// operator-repo layout (per `feedback_role_definition_genericity.md`).
+//
+// `accountKey` is the vault-key suffix (lowercase form passed to
+// `loadCloudflareCreds({ account })`). The CF helper upper-cases it
+// internally to build `CLOUDFLARE_PAGES_API_KEY_<SUFFIX>` + matching
+// account-id key.
+
+/** @typedef {{
+ *   hostname: string,
+ *   sourceWorker: string,
+ *   routerWorker: string,
+ *   accountKey: string,
+ *   expectedAccountName: string,
+ *   zoneName: string,
+ *   notes?: string,
+ * }} SiteEntry */
+
+/** @type {Record<string, SiteEntry>} */
+export const SITES = Object.freeze({
+  'stravica.ai': {
+    hostname: 'stravica.ai',
+    sourceWorker: 'stravica-ai',
+    routerWorker: 'stravica-ai-staging',
+    accountKey: 'stravica',
+    expectedAccountName: "Barry@stravica.ai's Account",
+    zoneName: 'stravica.ai',
+    notes: 'Stravica-dedicated CF account (ab9a9e66...d848).',
+  },
+  'cliveelliott.net': {
+    hostname: 'cliveelliott.net',
+    sourceWorker: 'cliveelliott',
+    routerWorker: 'cliveelliott-staging',
+    accountKey: 'clive',
+    expectedAccountName: "Thefootonline@outlook.com's Account",
+    zoneName: 'cliveelliott.net',
+    notes: 'Clive-shared CF account (4c07d09f...5a76), pending transfer to Clive.',
+  },
+  'besafetraining.co.uk': {
+    hostname: 'besafetraining.co.uk',
+    sourceWorker: 'besafetraining',
+    routerWorker: 'besafetraining-staging',
+    accountKey: 'clive',
+    expectedAccountName: "Thefootonline@outlook.com's Account",
+    zoneName: 'besafetraining.co.uk',
+    notes: 'Clive-shared CF account (4c07d09f...5a76), pending transfer to Clive.',
+  },
+});
+
+/**
+ * Look up a registered site by hostname (apex only — passing
+ * `staging.stravica.ai` is rejected because the CLI itself owns the
+ * `staging.` prefix).
+ *
+ * @param {string} hostname
+ * @returns {SiteEntry}
+ * @throws {Error} with exitCode=1 when not found.
+ */
+export function resolveSite(hostname) {
+  const raw = String(hostname || '').trim().toLowerCase();
+  if (!raw) {
+    throw Object.assign(new Error('--site: hostname is required'), { exitCode: 1 });
+  }
+  if (raw.startsWith('staging.')) {
+    throw Object.assign(
+      new Error(
+        `--site "${raw}" looks like a staging hostname. Pass the apex (e.g. ` +
+        `--site ${raw.slice('staging.'.length)}).`,
+      ),
+      { exitCode: 1 },
+    );
+  }
+  const entry = SITES[raw];
+  if (!entry) {
+    const known = Object.keys(SITES).join(', ');
+    throw Object.assign(
+      new Error(`--site "${raw}" is not registered. Known sites: ${known}`),
+      { exitCode: 1 },
+    );
+  }
+  return entry;
+}
+
+/** Iteration helper for the `list` verb. */
+export function allSites() {
+  return Object.values(SITES);
+}
+
+/** The staging hostname for a site (always `staging.<apex>`). */
+export function stagingHostname(site) {
+  return `staging.${site.hostname}`;
+}

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

@@ -0,0 +1,151 @@
+// estate-sync — CLI.
+//
+// Arg parsing (node:util.parseArgs, strict:true), verb routing,
+// exit-code translation per §5–§6 of the tooling standard.
+//
+// Bin name: `estate-sync`. `sync` is kept as a back-compat alias — same
+// entry point, same behaviour; both bins import this module unchanged.
+//
+// In v2 the operator repo no longer contains `core/tools/`. This tool is
+// installed as part of the @stravica-ai/engineering-pa-cli package and writes
+// its lock + audit log under `<repoRoot>/.cache/estate-sync/` (gitignored
+// per the tooling standard §16). (Renamed from `.cache/sync/` alongside
+// the dave-sync -> estate-sync rewrite; the old directory, if present from
+// a prior install, is simply orphaned — no data loss, nothing git-tracked.)
+
+import { appendFile, mkdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { runSync } from './run.mjs';
+import { defaultRunner } from './runner.mjs';
+
+const USAGE = `estate-sync — single-writer-per-host git sync for ESTATE-NATIVE content.
+
+(Also invocable as \`sync\` — kept as a back-compat alias for the pre-rename
+bin name; identical behaviour.)
+
+Usage:
+  estate-sync run                Run a real sync pass (lock, stage, pull --rebase, commit, push)
+  estate-sync run --dry-run      Print what would happen without modifying state
+  estate-sync -h, --help         Show this help
+
+Exit codes:
+  0  ok (including healthy no-ops)
+  1  usage error
+  2  logical / operational failure (rebase conflict, push rejected after retry)
+  3  transport / IO failure (git command itself errored)
+
+Behaviour summary:
+  - Acquires a PID lock at <repoRoot>/.cache/estate-sync/.lock (stale-after 10 minutes).
+  - If working tree is clean and no commits ahead of origin, exits 0
+    (status: noop-nothing-to-do).
+  - Otherwise: computes a registry-scoped commit scope (when
+    <repoRoot>/operator/registry/{devices.json,repos.json} exist — every
+    entitled mount's \`to\` subtree + .vault/** are excluded; everything
+    else dirty is staged via explicit pathspecs, NEVER a bare
+    \`git add -A\`). No registry present -> unscoped \`git add -A\`, loudly
+    flagged in both the run's output and the commit body. Then
+    \`git fetch && git pull --rebase && git commit && git push\`. One
+    push-retry on rejection.
+  - Audit-logs every non-dry-run exit to <repoRoot>/.cache/estate-sync/logs/runs.jsonl.
+
+Source of truth for behaviour: @stravica-ai/engineering-pa-cli/docs/estate-sync.md
+`;
+
+async function defaultRepoRoot() {
+  const envRoot = process.env.DAVE_REPO_ROOT || process.env.PA_REPO_ROOT;
+  if (envRoot) return resolve(envRoot);
+  // .git-walk from cwd
+  let d = process.cwd();
+  while (d && d !== dirname(d)) {
+    if (existsSync(join(d, '.git'))) return d;
+    d = dirname(d);
+  }
+  return null;
+}
+
+async function writeBootstrapAudit({ err, exitCode, stderr }) {
+  try {
+    const repoRoot = await defaultRepoRoot();
+    if (!repoRoot) {
+      stderr.write('[estate-sync] warning: no repo root resolved; skipping bootstrap audit\n');
+      return;
+    }
+    const logDir = join(repoRoot, '.cache/estate-sync/logs');
+    const runsLog = join(logDir, 'runs.jsonl');
+    await mkdir(logDir, { recursive: true });
+    const record = {
+      ts: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+      status: 'fail-cli-bootstrap',
+      exitCode,
+      durationSec: 0,
+      reason: `cli bootstrap failure: ${err?.message || err}`,
+    };
+    await appendFile(runsLog, JSON.stringify(record) + '\n');
+  } catch (auditErr) {
+    stderr.write(`[estate-sync] warning: failed to append bootstrap audit record: ${auditErr.message}\n`);
+  }
+}
+
+export async function main(
+  argv,
+  { stderr = process.stderr, exit = process.exit, audit = writeBootstrapAudit } = {},
+) {
+  try {
+    return await route(argv);
+  } catch (err) {
+    const code = err?.syncExitCode ?? 2;
+    stderr.write(`[estate-sync] ${err.message || err}\n`);
+    await audit({ err, exitCode: code, stderr });
+    exit(code);
+  }
+}
+
+async function route(argv) {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    process.stdout.write(USAGE);
+    process.exit(0);
+  }
+
+  const verb = argv[0];
+  const rest = argv.slice(1);
+
+  if (verb === 'run') {
+    const { values } = parseArgs({
+      args: rest,
+      options: {
+        'dry-run': { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      strict: true,
+    });
+    if (values.help) {
+      process.stdout.write(USAGE);
+      process.exit(0);
+    }
+    const repoRoot = await defaultRepoRoot();
+    if (!repoRoot) {
+      process.stderr.write('[estate-sync] could not find repo root (no .git ancestor; set DAVE_REPO_ROOT)\n');
+      process.exit(2);
+    }
+    const logDir = join(repoRoot, '.cache/estate-sync/logs');
+    await mkdir(logDir, { recursive: true });
+    const runsLog = join(logDir, 'runs.jsonl');
+    const lockPath = join(repoRoot, '.cache/estate-sync/.lock');
+    const code = await runSync({
+      repoRoot,
+      logDir,
+      runsLog,
+      lockPath,
+      dryRun: values['dry-run'],
+      runner: defaultRunner,
+    });
+    process.exit(code ?? 0);
+  }
+
+  process.stderr.write(`[estate-sync] unknown command: ${verb}\n`);
+  process.stderr.write(USAGE);
+  process.exit(1);
+}