@quolu/lattice 0.1.0 → 0.12.2

package/src/bounded-seam.mjs

@@ -0,0 +1,144 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import {
+  exactRecord, isTodoDigest, isTodoIdentifier, isTodoRef, todoSelfDigest,
+} from './todo-contracts.mjs';
+
+const GIT_OID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u;
+
+function sortedUniqueRefs(value, { nonempty = false } = {}) {
+  return Array.isArray(value) && (!nonempty || value.length > 0) && value.every(isTodoRef)
+    && value.every((entry, index) => index === 0 || value[index - 1] < entry);
+}
+
+export function validateBoundedSeamCandidate(value) {
+  try {
+    return exactRecord(value, [
+      'schema', 'candidate_id', 'base_sha', 'manifest_digest', 'finding_digest',
+      'todo_refs', 'anchor', 'allowed_paths', 'required_paths', 'verification_policy',
+      'candidate_digest',
+    ]) && value.schema === 'lattice.bounded_seam_candidate.v1'
+      && isTodoIdentifier(value.candidate_id) && GIT_OID.test(value.base_sha)
+      && isTodoDigest(value.manifest_digest) && isTodoDigest(value.finding_digest)
+      && Array.isArray(value.todo_refs) && value.todo_refs.length >= 2
+      && value.todo_refs.every((entry) => exactRecord(entry, ['plan_key', 'task_id'])
+        && isTodoIdentifier(entry.plan_key) && isTodoIdentifier(entry.task_id))
+      && value.todo_refs.every((entry, index) => index === 0
+        || `${value.todo_refs[index - 1].plan_key}\0${value.todo_refs[index - 1].task_id}`
+          < `${entry.plan_key}\0${entry.task_id}`)
+      && exactRecord(value.anchor, ['path', 'symbol', 'start_line', 'end_line'])
+      && isTodoRef(value.anchor.path) && isTodoIdentifier(value.anchor.symbol)
+      && Number.isSafeInteger(value.anchor.start_line) && value.anchor.start_line >= 1
+      && Number.isSafeInteger(value.anchor.end_line) && value.anchor.end_line >= value.anchor.start_line
+      && sortedUniqueRefs(value.allowed_paths, { nonempty: true })
+      && sortedUniqueRefs(value.required_paths, { nonempty: true })
+      && value.required_paths.every((entry) => value.allowed_paths.includes(entry))
+      && value.allowed_paths.includes(value.anchor.path)
+      && exactRecord(value.verification_policy, [
+        'focused_test_ids', 'require_behavior_equivalence', 'require_fresh_sensor',
+        'require_overlap_reduction',
+      ]) && Array.isArray(value.verification_policy.focused_test_ids)
+      && value.verification_policy.focused_test_ids.length > 0
+      && value.verification_policy.focused_test_ids.every(isTodoIdentifier)
+      && value.verification_policy.focused_test_ids.every((entry, index) => index === 0
+        || value.verification_policy.focused_test_ids[index - 1] < entry)
+      && value.verification_policy.require_behavior_equivalence === true
+      && value.verification_policy.require_fresh_sensor === true
+      && value.verification_policy.require_overlap_reduction === true
+      && isTodoDigest(value.candidate_digest)
+      && value.candidate_digest === todoSelfDigest(value, 'candidate_digest');
+  } catch { return false; }
+}
+
+function run(command, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+    const stdout = []; const stderr = [];
+    child.stdout.on('data', (chunk) => stdout.push(chunk));
+    child.stderr.on('data', (chunk) => stderr.push(chunk));
+    child.once('error', reject);
+    child.once('close', (code, signal) => {
+      if (code === 0 && signal === null) resolve(Buffer.concat(stdout));
+      else reject(new Error(`${command} failed (${signal ?? code}): ${Buffer.concat(stderr).toString('utf8').trim()}`));
+    });
+  });
+}
+
+async function fingerprint(repoRoot) {
+  const [head, status, refs] = await Promise.all([
+    run('git', ['rev-parse', 'HEAD'], repoRoot),
+    run('git', ['status', '--porcelain=v1', '--untracked-files=all'], repoRoot),
+    run('git', ['for-each-ref', '--format=%(refname) %(objectname)'], repoRoot),
+  ]);
+  return Buffer.concat([head, status, refs]).toString('hex');
+}
+
+async function changedPaths(worktreePath) {
+  const bytes = await run('git', ['status', '--porcelain=v1', '-z', '--untracked-files=all'], worktreePath);
+  const fields = bytes.toString('utf8').split('\0').filter(Boolean);
+  const paths = [];
+  for (let index = 0; index < fields.length; index += 1) {
+    const field = fields[index];
+    const status = field.slice(0, 2);
+    paths.push(field.slice(3));
+    if (status.includes('R') || status.includes('C')) paths.push(fields[++index]);
+  }
+  return [...new Set(paths)].sort();
+}
+
+function outcome(candidate, decision, reason, changed, verification, cleanupOk) {
+  const result = { schema: 'lattice.bounded_seam_outcome.v1', candidate_id: candidate.candidate_id,
+    candidate_digest: candidate.candidate_digest, decision, reason, changed_paths: changed,
+    verification, cleanup_ok: cleanupOk, outcome_digest: '' };
+  result.outcome_digest = todoSelfDigest(result, 'outcome_digest');
+  return result;
+}
+
+export async function runBoundedSeamCandidate({ repoRoot, candidate, transform, verify }) {
+  if (!validateBoundedSeamCandidate(candidate)) throw new TypeError('bounded seam candidate invalid');
+  if (typeof repoRoot !== 'string' || typeof transform !== 'function' || typeof verify !== 'function') {
+    throw new TypeError('bounded seam runner options invalid');
+  }
+  const before = await fingerprint(repoRoot);
+  const head = (await run('git', ['rev-parse', 'HEAD'], repoRoot)).toString('utf8').trim();
+  if (head !== candidate.base_sha) return outcome(candidate, 'rejected', 'stale_base', [], null, true);
+  const worktreeRoot = await mkdtemp(path.join(tmpdir(), 'lattice-bounded-seam-'));
+  const worktreePath = path.join(worktreeRoot, 'tree');
+  let changed = [];
+  let result;
+  let cleanupOk = false;
+  try {
+    await run('git', ['worktree', 'add', '--detach', worktreePath, candidate.base_sha], repoRoot);
+    try { await transform({ worktreePath, candidate: structuredClone(candidate) }); }
+    catch { result = outcome(candidate, 'rejected', 'transform_failed', [], null, false); }
+    if (result === undefined) changed = await changedPaths(worktreePath);
+    if (result === undefined && (changed.some((entry) => !candidate.allowed_paths.includes(entry))
+      || candidate.required_paths.some((entry) => !changed.includes(entry)))) {
+      result = outcome(candidate, 'rejected', 'scope_drift', changed, null, false);
+    } else if (result === undefined) {
+      let verification;
+      try { verification = await verify({ worktreePath, candidate: structuredClone(candidate), changed_paths: changed }); }
+      catch { verification = null; }
+      const valid = exactRecord(verification, [
+        'behavior_equivalent', 'focused_tests_passed', 'sensor_fresh', 'overlap_reduced',
+        'evidence_digest',
+      ]) && verification.behavior_equivalent === true && verification.focused_tests_passed === true
+        && verification.sensor_fresh === true && verification.overlap_reduced === true
+        && isTodoDigest(verification.evidence_digest);
+      result = outcome(candidate, valid ? 'accepted' : 'rejected',
+        valid ? 'all_gates_passed' : 'verification_failed', changed, verification, false);
+    }
+  } finally {
+    try {
+      await run('git', ['worktree', 'remove', '--force', worktreePath], repoRoot);
+      await rm(worktreeRoot, { recursive: true, force: true });
+      cleanupOk = true;
+    } catch { cleanupOk = false; }
+  }
+  const after = await fingerprint(repoRoot);
+  if (before !== after) throw new TypeError('bounded seam runner modified canonical repository');
+  return outcome(candidate, result.decision, result.reason, changed, result.verification, cleanupOk);
+}

package/src/bridge-cli.mjs

@@ -0,0 +1,227 @@
+import { isIP } from 'node:net';
+import * as clack from '@clack/prompts';
+
+import {
+  BridgeConfigError, configureBridge, disableBridge, readBridgeConfig, restoreBridgeConfig,
+  normalizeBridgeAllowedHost, withBridgeOperationLock,
+} from './bridge-config.mjs';
+import {
+  clearBridgeStopControl, ensureBridgeDaemon, readBridgeDaemonDescriptor,
+  removeBridgeDaemonActiveMarker, removeBridgeDaemonDescriptor, requestBridgeDaemonStop,
+  stopBridgeDaemon,
+} from './bridge-daemon.mjs';
+import {
+  disableBridgeLaunchAgent, installBridgeLaunchAgent, restoreBridgeLaunchAgent,
+  snapshotBridgeLaunchAgent,
+} from './bridge-launch-agent.mjs';
+
+const RESULT_SCHEMA = 'lattice.bridge_cli_result.v1';
+
+function fail(stderr, code, message) {
+  stderr.write(`${JSON.stringify({ schema: 'lattice.cli_error.v2', code, message })}\n`);
+  return 2;
+}
+
+function parseOptions(words) {
+  const options = { address: undefined, port: undefined, upstream: undefined, allowedHosts: [] };
+  for (let index = 0; index < words.length; index += 1) {
+    const flag = words[index];
+    if (flag === '--listen') {
+      if (options.address !== undefined) throw new BridgeConfigError('USAGE', 'duplicate --listen');
+      options.address = words[++index];
+    }
+    else if (flag === '--port') {
+      if (options.port !== undefined) throw new BridgeConfigError('USAGE', 'duplicate --port');
+      const value = words[++index];
+      options.port = value === 'auto' ? null : Number(value);
+    } else if (flag === '--dashboard') {
+      if (options.upstream !== undefined) throw new BridgeConfigError('USAGE', 'upstream option is ambiguous');
+      options.upstream = { mode: 'dashboard_descriptor' };
+    } else if (flag === '--upstream') {
+      if (options.upstream !== undefined) throw new BridgeConfigError('USAGE', 'upstream option is ambiguous');
+      options.upstream = { mode: 'url', url: words[++index] };
+    } else if (flag === '--allow-host') options.allowedHosts.push(words[++index]);
+    else throw new BridgeConfigError('USAGE', `unknown bridge option: ${flag}`);
+    if ((flag === '--listen' || flag === '--port' || flag === '--upstream' || flag === '--allow-host')
+      && words[index] === undefined) throw new BridgeConfigError('USAGE', `missing value for ${flag}`);
+  }
+  return options;
+}
+
+function result(action, config, recovery = null) {
+  return { schema: RESULT_SCHEMA, action, configured: config !== null, enabled: config?.enabled ?? false,
+    listen: config?.listen ?? null, allowed_hosts: config?.allowed_hosts ?? null,
+    upstream: config?.upstream ?? null, updated_at: config?.updated_at ?? null, recovery };
+}
+
+export async function collectBridgeSetupWizard({ input, output, prompts = clack } = {}) {
+  const common = { input, output };
+  const enabled = await prompts.confirm({ ...common,
+    message: 'Lattice dashboardのnetwork bridgeを有効にしますか？', initialValue: false });
+  if (prompts.isCancel(enabled) || enabled !== true) return null;
+  const address = await prompts.text({ ...common, message: 'listenするIP address',
+    placeholder: '192.168.1.102', validate: (value) => isIP(value) === 0 ? 'IP literalを入力してください' : undefined });
+  if (prompts.isCancel(address)) return null;
+  const portMode = await prompts.select({ ...common, message: 'bridge port', initialValue: 'auto', options: [
+    { value: 'auto', label: '自動選択', hint: '49152–65535からexclusive bind' },
+    { value: 'custom', label: '指定する' },
+  ] });
+  if (prompts.isCancel(portMode)) return null;
+  let port = null;
+  if (portMode === 'custom') {
+    const selected = await prompts.text({ ...common, message: 'port (49152–65535)',
+      validate: (value) => /^\d+$/u.test(value) && Number(value) >= 49_152 && Number(value) <= 65_535
+        ? undefined : '49152–65535の整数を入力してください' });
+    if (prompts.isCancel(selected)) return null;
+    port = Number(selected);
+  }
+  const upstreamMode = await prompts.select({ ...common, message: 'upstream', initialValue: 'dashboard', options: [
+    { value: 'dashboard', label: '現在のLattice dashboard', hint: '再起動時もdescriptorから追従' },
+    { value: 'custom', label: '固定URL' },
+  ] });
+  if (prompts.isCancel(upstreamMode)) return null;
+  let upstream = { mode: 'dashboard_descriptor' };
+  if (upstreamMode === 'custom') {
+    const url = await prompts.text({ ...common, message: 'upstream HTTP(S) URL',
+      placeholder: 'http://127.0.0.1:4318/' });
+    if (prompts.isCancel(url)) return null;
+    upstream = { mode: 'url', url };
+  }
+  const publicHost = await prompts.text({ ...common,
+    message: '追加で許可する公開hostname（なければ空欄）', placeholder: 'lattice.kitepon.dev',
+    validate: (value) => {
+      if (value === '') return undefined;
+      try { normalizeBridgeAllowedHost(value); return undefined; } catch {
+        return 'portやschemeを含まないhostnameを入力してください';
+      }
+    } });
+  if (prompts.isCancel(publicHost)) return null;
+  return { address, port, upstream, allowedHosts: publicHost === '' ? [] : [publicHost] };
+}
+
+export async function runBridgeCli({ argv, stdout, stderr, env = process.env,
+  stdin = process.stdin, daemon = { ensure: ensureBridgeDaemon, requestStop: requestBridgeDaemonStop,
+    stop: stopBridgeDaemon, clearStop: clearBridgeStopControl },
+  launchAgent = { snapshot: snapshotBridgeLaunchAgent, install: installBridgeLaunchAgent,
+    disable: disableBridgeLaunchAgent, restore: restoreBridgeLaunchAgent },
+  prompts = clack } = {}) {
+  if (!Array.isArray(argv)) {
+    return fail(stderr, 'USAGE', 'usage: lattice bridge <setup|reconfigure|status|disable> [options] --json');
+  }
+  const wizard = argv.length === 1 && argv[0] === 'setup';
+  if (!wizard && argv.at(-1) !== '--json') {
+    return fail(stderr, 'USAGE', 'usage: lattice bridge <setup|reconfigure|status|disable> [options] --json');
+  }
+  if (wizard && (!stdin?.isTTY || !stdout?.isTTY)) {
+    return fail(stderr, 'BRIDGE_SETUP_REQUIRES_TTY',
+      'interactive setup requires a TTY; use lattice bridge setup --listen <IP> --port auto --dashboard --json');
+  }
+  const [command, ...words] = wizard ? argv : argv.slice(0, -1);
+  try {
+    let config;
+    let recovery = null;
+    if (command === 'status' && words.length === 0) config = await readBridgeConfig({ env });
+    else if (command === 'disable' && words.length === 0) {
+      config = await withBridgeOperationLock({ env }, async () => {
+        let previous;
+        let descriptor = null;
+        let invalidConfig = false;
+        let invalidDescriptor = false;
+        try {
+          previous = await readBridgeConfig({ env });
+        } catch (error) {
+          if (!['BRIDGE_CONFIG_INVALID', 'BRIDGE_CONFIG_MODE_INVALID'].includes(error?.code)) throw error;
+          invalidConfig = true;
+        }
+        try { descriptor = await readBridgeDaemonDescriptor({ env }); } catch (error) {
+          if (error?.code !== 'BRIDGE_DAEMON_DESCRIPTOR_INVALID') throw error;
+          invalidDescriptor = true;
+        }
+        const agentSnapshot = await launchAgent.snapshot({ env });
+        const witnessedListen = previous?.listen ?? (descriptor === null ? null
+          : { address: descriptor.address, port: descriptor.port });
+        let stopResult = null;
+        try {
+          await launchAgent.disable({ snapshot: agentSnapshot, listen: witnessedListen, env });
+          if (!agentSnapshot.loaded) {
+            const requestStop = daemon.requestStop ?? daemon.stop ?? requestBridgeDaemonStop;
+            stopResult = await requestStop({ env, listen: witnessedListen });
+          }
+          const disabled = invalidConfig ? await restoreBridgeConfig(null, { env })
+            : await disableBridge({ env });
+          if (invalidConfig) recovery = 'invalid_config_removed_after_fail_closed_shutdown';
+          else if (invalidDescriptor) recovery = 'invalid_descriptor_removed_after_fail_closed_shutdown';
+          await removeBridgeDaemonDescriptor({ env });
+          await removeBridgeDaemonActiveMarker({ env });
+          const clearStop = daemon.clearStop ?? clearBridgeStopControl;
+          await clearStop({ env });
+          if (stopResult?.state === 'not_running' && recovery === null) recovery = 'bridge_was_not_running';
+          return disabled;
+        } catch (error) {
+          try {
+            await launchAgent.restore({ snapshot: agentSnapshot, listen: witnessedListen,
+              config: previous, env });
+          }
+          catch (rollbackError) {
+            throw new BridgeConfigError('BRIDGE_ROLLBACK_FAILED',
+              `bridge disable failed and LaunchAgent rollback failed: ${rollbackError.message}`, undefined, error);
+          }
+          throw error;
+        }
+      });
+    }
+    else if (command === 'setup' || command === 'reconfigure') {
+      const options = wizard ? await collectBridgeSetupWizard({ input: stdin, output: stdout, prompts })
+        : parseOptions(words);
+      if (options === null) {
+        stdout.write('Lattice bridge setupを取り消しました。設定は変更していません。\n');
+        return 0;
+      }
+      if (command === 'setup' && options.address === undefined) {
+        throw new BridgeConfigError('USAGE', 'setup requires explicit --listen <IP> opt-in');
+      }
+      config = await withBridgeOperationLock({ env }, async () => {
+        const clearStop = daemon.clearStop ?? clearBridgeStopControl;
+        await clearStop({ env });
+        const current = await readBridgeConfig({ env });
+        const agentSnapshot = await launchAgent.snapshot({ env });
+        const configured = await configureBridge({
+          address: options.address ?? current?.listen.address,
+          port: options.port === undefined ? (command === 'reconfigure' ? current?.listen.port ?? null : null) : options.port,
+          upstream: options.upstream ?? current?.upstream ?? { mode: 'dashboard_descriptor' }, env,
+          allowedHosts: options.allowedHosts.length > 0 ? options.allowedHosts
+            : current?.allowed_hosts?.filter((host) => host !== current.listen.address) ?? [],
+          reuseCurrentPort: options.port === undefined,
+        });
+        try {
+          if (!agentSnapshot.loaded && current !== null) {
+            const requestStop = daemon.requestStop ?? daemon.stop ?? requestBridgeDaemonStop;
+            await requestStop({ env, listen: current.listen });
+            await clearStop({ env });
+          }
+          await launchAgent.install({ config: configured, previousListen: current?.listen ?? null, env });
+        } catch (error) {
+          try {
+            await restoreBridgeConfig(current, { env });
+            await clearStop({ env });
+            await launchAgent.restore({ snapshot: agentSnapshot, listen: configured.listen,
+              config: current, env });
+            if (current?.enabled && !agentSnapshot.loaded) await daemon.ensure({ env });
+          } catch (rollbackError) {
+            throw new BridgeConfigError('BRIDGE_ROLLBACK_FAILED',
+              `bridge setup failed and rollback failed: ${rollbackError.message}`, undefined, error);
+          }
+          throw error;
+        }
+        return configured;
+      });
+    } else return fail(stderr, 'USAGE', 'unknown bridge command or options');
+    if (wizard) stdout.write(`Lattice bridgeを${config.listen.address}:${config.listen.port}で有効にしました。\n`);
+    else stdout.write(`${JSON.stringify(result(command, config, recovery))}\n`);
+    return 0;
+  } catch (error) {
+    stderr.write(`${JSON.stringify({ schema: 'lattice.cli_error.v2',
+      code: error?.code ?? 'BRIDGE_FAILED', message: error?.message ?? 'bridge command failed' })}\n`);
+    return error?.code === 'USAGE' ? 2 : 1;
+  }
+}