amalgm 0.1.158 → 0.1.159

package/runtime/scripts/amalgm-mcp/tools/shared-live-smoke.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Live smoke for the shared realtime rail (Wave 3) against RUNNING runtimes.
+ *
+ * The CI tiers in local-live-runbook.md (unit / loopback / full-route e2e)
+ * all run against sandboxed engines. This tool is the fourth tier: it drives
+ * the real installed runtime on this machine, through the real local
+ * gateway, onto the real cloud rail. Nothing is stubbed.
+ *
+ * Commands:
+ *   status                 shared replicas + runtime health for this machine
+ *   send   [--path <doc>]  append a marker line to a shared doc through the
+ *                          normal doc path, then wait for the official cloud
+ *                          ack (applied_version advance + sync_status synced)
+ *   watch  --for <text>    wait until <text> arrives IN THE FILE on disk —
+ *                          i.e. a remote machine's edit crossed the rail and
+ *                          materialized here
+ *
+ * Cross-machine proof = `send` on machine A, `watch --for <its marker>` on
+ * machine B, then the reverse. Run from a checkout (node
+ * runtime/scripts/amalgm-mcp/tools/shared-live-smoke.js …) or from an
+ * installed runtime package (same relative path under the install dir).
+ *
+ * Options: --user <email> (default: sole entry under ~/amalgm/users),
+ * --branch <label> (default: main), --timeout <seconds> (default: 90).
+ * Exit code 0 on proof, 1 on failure/timeout — usable from scripts.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function fail(msg) {
+  console.error(`FAIL: ${msg}`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      args[a.slice(2)] = argv[i + 1];
+      i++;
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+function expandHome(p) {
+  if (!p) return p;
+  return p.startsWith('~') ? path.join(os.homedir(), p.slice(1)) : p;
+}
+
+function resolveUser(args) {
+  if (args.user) return args.user;
+  const usersDir = path.join(os.homedir(), 'amalgm', 'users');
+  const entries = fs.readdirSync(usersDir).filter((e) => e.includes('@'));
+  if (entries.length === 1) return entries[0];
+  fail(`multiple users under ${usersDir} — pass --user <email> (found: ${entries.join(', ')})`);
+}
+
+function loadRuntime(user, branch) {
+  const base = path.join(os.homedir(), 'amalgm', 'users', user);
+  const runtimeDir = path.join(base, 'runtimes', branch);
+  const statePath = path.join(runtimeDir, 'runtime-state.json');
+  if (!fs.existsSync(statePath)) {
+    fail(`no runtime state at ${statePath} — is the ${branch} runtime installed for ${user}?`);
+  }
+  const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+  const token = JSON.parse(fs.readFileSync(path.join(runtimeDir, 'runtime-token.json'), 'utf8')).token;
+  const dbPath = path.join(base, 'amalgm.db');
+  return { base, gatewayUrl: state.gateway_url, version: state.version, token, dbPath };
+}
+
+function openDb(dbPath) {
+  const Database = require('better-sqlite3');
+  return new Database(dbPath, { readonly: true, fileMustExist: true });
+}
+
+function readReplicas(db) {
+  return db
+    .prepare(
+      `SELECT resource_id, local_path, applied_version, snapshot_version,
+              sync_status, last_error, updated_at
+         FROM shared_resource_replicas ORDER BY updated_at DESC`
+    )
+    .all();
+}
+
+function replicaFor(db, docPath) {
+  return db
+    .prepare(`SELECT * FROM shared_resource_replicas WHERE local_path = ?`)
+    .get(docPath);
+}
+
+async function api(rt, route, body) {
+  const res = await fetch(`${rt.gatewayUrl}${route}`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      'x-amalgm-runtime-token': rt.token,
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await res.text();
+  if (!res.ok) fail(`${route} → HTTP ${res.status}: ${text.slice(0, 300)}`);
+  return JSON.parse(text);
+}
+
+async function checkHealth(rt) {
+  let res;
+  try {
+    res = await fetch(`${rt.gatewayUrl}/healthz`, { signal: AbortSignal.timeout(5000) });
+  } catch (err) {
+    fail(`runtime unreachable at ${rt.gatewayUrl} (${err.cause?.code || err.message}) — is it running?`);
+  }
+  if (!res.ok) fail(`healthz → HTTP ${res.status}`);
+  return res.json();
+}
+
+function pickDocPath(args, db) {
+  if (args.path) return path.resolve(expandHome(args.path));
+  const rows = readReplicas(db);
+  if (rows.length === 1) return rows[0].local_path;
+  if (rows.length === 0) fail('no shared replicas on this machine — share a doc first, or pass --path');
+  fail(`multiple shared replicas — pass --path. Known:\n  ${rows.map((r) => r.local_path).join('\n  ')}`);
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function cmdStatus(rt) {
+  const health = await checkHealth(rt);
+  console.log(`runtime ${health.runtime_label} v${rt.version} at ${rt.gatewayUrl} — ${health.status}`);
+  const db = openDb(rt.dbPath);
+  const rows = readReplicas(db);
+  if (rows.length === 0) {
+    console.log('no shared replicas.');
+    return;
+  }
+  for (const r of rows) {
+    console.log(
+      `  ${r.resource_id}  v${r.applied_version} (snapshot v${r.snapshot_version})  ${r.sync_status}` +
+        `${r.last_error ? `  ERROR: ${r.last_error}` : ''}\n    ${r.local_path}  (updated ${r.updated_at})`
+    );
+  }
+}
+
+async function cmdSend(rt, args, timeoutMs) {
+  const Y = require('yjs');
+  await checkHealth(rt);
+  const db = openDb(rt.dbPath);
+  const docPath = pickDocPath(args, db);
+  const before = replicaFor(db, docPath);
+  if (!before) fail(`${docPath} is not a shared replica on this machine`);
+  if (before.sync_status !== 'synced') {
+    console.log(`note: replica starts in '${before.sync_status}' (v${before.applied_version})`);
+  }
+
+  const marker = `[smoke ${new Date().toISOString()} host=${os.hostname()} n=${Math.random().toString(36).slice(2, 8)}]`;
+  const opened = await api(rt, '/state/docs/open', { path: docPath });
+  const doc = new Y.Doc();
+  Y.applyUpdate(doc, Buffer.from(opened.state, 'base64'));
+  const beforeVector = Y.encodeStateVector(doc);
+  const text = doc.getText('content');
+  doc.transact(() => text.insert(text.length, `\n${marker}\n`));
+  const update = Buffer.from(Y.encodeStateAsUpdate(doc, beforeVector)).toString('base64');
+  await api(rt, '/state/docs/update', { path: docPath, updates: [update] });
+  console.log(`sent marker through doc path: ${marker}`);
+  console.log(`waiting for cloud ack (baseline v${before.applied_version})…`);
+
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const row = replicaFor(db, docPath);
+    if (row.sync_status === 'rejected' || row.sync_status === 'conflicted') {
+      fail(`replica entered '${row.sync_status}': ${row.last_error || '(no error recorded)'}`);
+    }
+    if (row.applied_version > before.applied_version && row.sync_status === 'synced') {
+      const materialized = fs.readFileSync(docPath, 'utf8').includes(marker);
+      console.log(
+        `PASS: official v${before.applied_version} → v${row.applied_version} in ${Date.now() - start}ms; ` +
+          `file materialized: ${materialized ? 'yes' : 'pending write-back'}`
+      );
+      console.log(`cross-machine check: on the other machine run\n  … watch --for "${marker}"`);
+      return;
+    }
+    await sleep(400);
+  }
+  fail(`no cloud ack within ${timeoutMs / 1000}s — edit is journaled locally (nothing lost); check tunnel/gateway per local-live-runbook.md`);
+}
+
+async function cmdWatch(rt, args, timeoutMs) {
+  if (!args.for) fail('watch requires --for <text>');
+  const db = openDb(rt.dbPath);
+  const docPath = pickDocPath(args, db);
+  const start = Date.now();
+  console.log(`watching ${docPath} for: ${args.for}`);
+  while (Date.now() - start < timeoutMs) {
+    if (fs.existsSync(docPath) && fs.readFileSync(docPath, 'utf8').includes(args.for)) {
+      const row = replicaFor(db, docPath);
+      console.log(`PASS: marker arrived in the file after ${Date.now() - start}ms (replica v${row?.applied_version}, ${row?.sync_status})`);
+      return;
+    }
+    await sleep(400);
+  }
+  fail(`marker did not arrive within ${timeoutMs / 1000}s`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cmd = args._[0];
+  if (!['status', 'send', 'watch'].includes(cmd)) {
+    console.error('usage: shared-live-smoke.js <status|send|watch> [--path <doc>] [--for <text>] [--user <email>] [--branch <label>] [--timeout <seconds>]');
+    process.exit(1);
+  }
+  const rt = loadRuntime(resolveUser(args), args.branch || 'main');
+  const timeoutMs = (Number(args.timeout) || 90) * 1000;
+  if (cmd === 'status') await cmdStatus(rt);
+  if (cmd === 'send') await cmdSend(rt, args, timeoutMs);
+  if (cmd === 'watch') await cmdWatch(rt, args, timeoutMs);
+}
+
+main().catch((err) => fail(err.stack || String(err)));

package/runtime/scripts/amalgm-mcp/workspace/card.js

@@ -0,0 +1,199 @@
+'use strict';
+
+/**
+ * Repo cards: one small, typed statement of a worktree's exact state.
+ *
+ * A card carries identifiers and counts, never file contents — a
+ * 4,000-file checkout is one card change. Cards are observations; nothing
+ * in the system acts on one, and observing never writes to a repo. The
+ * contract is docs/workspace-sync.md.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  classifyDirectory,
+  headAndDirty,
+  headOid,
+  listWorktrees,
+  operationState,
+  originUrl,
+  rootCommit,
+} = require('./git');
+const { cacheRootCommit, machineId, replicaForGitDir } = require('./identity');
+
+const CARD_CONTRACT = 'repo-card@2';
+
+// A transportable identity needs a dotted host: bare names resolve through
+// this machine's own config (ssh aliases, LAN names) and identify nothing
+// anywhere else.
+const HOST = String.raw`([\w-]+(?:\.[\w-]+)+)`;
+const URL_REMOTE = new RegExp(`^(?:ssh|git|https?)://(?:[^@/]+@)?${HOST}(?::\\d+)?/(.+)$`, 'i');
+const SCP_REMOTE = new RegExp(`^(?:[\\w.-]+@)?${HOST}:(.+)$`);
+
+/**
+ * The transportable identity of a remote, or null when it has none.
+ *
+ * Every clone spelling of one hosted repo folds onto one https URL:
+ * scp-like (git@host:owner/repo.git), ssh:// with a port, https:// with
+ * credentials — lowercased host, no userinfo, no port, no query, no
+ * fragment, no .git. Credentials and tokens embedded anywhere in a URL
+ * must never ride a card off this machine, and machine-local remotes
+ * (file://, bare paths, ssh aliases) are null: a name that only resolves
+ * on this machine identifies nothing on any other.
+ */
+function remoteIdentity(url) {
+  const trimmed = url.trim();
+  const match = trimmed.match(URL_REMOTE) || trimmed.match(SCP_REMOTE);
+  if (!match) return null;
+  const repoPath = match[2]
+    .replace(/[?#].*$/, '')
+    .replace(/^\/+/, '')
+    .replace(/\/+$/, '')
+    .replace(/\.git$/, '');
+  return repoPath ? `https://${match[1].toLowerCase()}/${repoPath}` : null;
+}
+
+function cardKind(classified) {
+  if (classified.superproject) return 'submodule';
+  return classified.linked ? 'linked-worktree' : 'primary';
+}
+
+async function observeWorktree(classified) {
+  const worktreeRoot = classified.toplevel;
+  const gitDir = await fs.promises.realpath(classified.gitDir);
+  const replica = replicaForGitDir(gitDir);
+  const [{ head, dirty }, operation, remote] = await Promise.all([
+    headAndDirty(worktreeRoot),
+    operationState(worktreeRoot),
+    originUrl(worktreeRoot),
+  ]);
+  let anchor = replica.rootCommit;
+  if (!anchor && head.oid) {
+    anchor = await rootCommit(worktreeRoot);
+    cacheRootCommit(gitDir, anchor);
+  }
+
+  return {
+    card: CARD_CONTRACT,
+    machine: machineId(),
+    replica: replica.replicaId,
+    path: worktreeRoot,
+    gitDir,
+    repo: {
+      remote: remote === null ? null : remoteIdentity(remote),
+      rootCommit: anchor,
+    },
+    kind: cardKind(classified),
+    head,
+    dirty,
+    operation,
+    observedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Build the repo-card@2 for one worktree. `dirPath` may be any directory
+ * inside the worktree; the card is always for the worktree root. Throws
+ * on anything that is not a worktree — discovery filters first.
+ *
+ * Observation is not atomic — git can move between the underlying reads —
+ * so HEAD is probed again afterwards and the card rebuilt once if it
+ * moved. A repo still in motion after that simply cards again on the next
+ * doorbell; every card is a true observation of some moment.
+ */
+async function buildRepoCard(dirPath) {
+  const classified = await classifyDirectory(dirPath);
+  if (classified.kind !== 'worktree') {
+    throw new Error(`cannot card ${classified.path}: ${classified.kind}`);
+  }
+  const observed = await observeWorktree(classified);
+  if (observed.head.oid === await headOid(classified.toplevel)) return observed;
+  return observeWorktree(classified);
+}
+
+/**
+ * The card's identity-relevant content. Two observations of an untouched
+ * repo produce the same fingerprint; any real change produces a new one.
+ * The store bumps a card's generation exactly when the fingerprint moves.
+ */
+function cardFingerprint(card) {
+  const { observedAt, ...content } = card;
+  return JSON.stringify(content);
+}
+
+async function isDirectory(candidate) {
+  const stats = await fs.promises.stat(candidate);
+  return stats.isDirectory();
+}
+
+/**
+ * Resolve a tracked folder to the worktrees it means, using git itself:
+ *
+ * - a folder inside a repo means that repo,
+ * - a plain folder means the repos sitting one level down (a folder of
+ *   projects; hidden entries are not code folders),
+ * - and every discovered repo brings all of its linked worktrees along,
+ *   wherever on disk they live — same repo, same tracking.
+ *
+ * Returns { worktrees, skipped } — worktree roots to card, and what was
+ * looked at but not carded, each with its reason: 'bare', 'not-a-repo',
+ * 'prunable' (registered but gone from disk), or 'broken-worktree'
+ * (present on disk but no longer answering as a repo, e.g. after its
+ * main repo moved).
+ * Discovery never descends into a repo looking for submodules; an
+ * explicitly tracked submodule path cards like any other worktree.
+ */
+async function discoverWorktrees(rootPath) {
+  const classified = await classifyDirectory(rootPath);
+  const skipped = [];
+  const repos = new Map(); // commonDir → one worktree root; two doors into one repo expand once
+
+  if (classified.kind === 'worktree') {
+    repos.set(classified.commonDir, classified.toplevel);
+  } else if (classified.kind === 'bare') {
+    skipped.push({ path: classified.path, reason: 'bare' });
+  } else {
+    const entries = await fs.promises.readdir(classified.path);
+    const children = entries
+      .filter((entry) => !entry.startsWith('.'))
+      .map((entry) => path.join(classified.path, entry));
+    for (const child of children) {
+      if (!(await isDirectory(child))) continue;
+      const childClassified = await classifyDirectory(child);
+      if (childClassified.kind === 'worktree') {
+        if (!repos.has(childClassified.commonDir)) repos.set(childClassified.commonDir, childClassified.toplevel);
+      } else {
+        skipped.push({ path: childClassified.path, reason: childClassified.kind });
+      }
+    }
+  }
+
+  const worktrees = new Set();
+  for (const repoRoot of repos.values()) {
+    for (const worktree of await listWorktrees(repoRoot)) {
+      if (worktree.prunable) {
+        skipped.push({ path: worktree.path, reason: 'prunable' });
+        continue;
+      }
+      // Being listed is not enough — after a repo moves, a registered
+      // worktree can survive on disk with a dangling pointer. Card only
+      // what answers to git as a worktree.
+      const answered = await classifyDirectory(worktree.path);
+      if (answered.kind === 'worktree') {
+        worktrees.add(answered.toplevel);
+      } else {
+        skipped.push({ path: worktree.path, reason: 'broken-worktree' });
+      }
+    }
+  }
+  return { worktrees: [...worktrees].sort(), skipped };
+}
+
+module.exports = {
+  CARD_CONTRACT,
+  buildRepoCard,
+  cardFingerprint,
+  discoverWorktrees,
+  remoteIdentity,
+};