vericify 0.1.0

package/src/index.js

@@ -0,0 +1,464 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import {
+  DEFAULT_ADAPTER,
+  attachAdapter,
+  detectAdapters,
+  listDefaultWorkspacePaths,
+  loadWorkspaceState,
+} from "./adapters/index.js";
+import { buildRunComparison, findRunById } from "./compare/engine.js";
+import { appendProcessPost } from "./post/process-posts.js";
+import { publishRunArtifact } from "./publish/artifact.js";
+import { projectWorkspaceState } from "./projection/runs.js";
+import { upsertHandoff } from "./store/handoffs.js";
+import { appendRunLedgerEntry } from "./store/run-ledger.js";
+import { appendStatusEvent } from "./store/status-events.js";
+import { upsertTodoNode } from "./store/todo-state.js";
+import { enqueueSyncOutboxItem } from "./sync/outbox.js";
+import { runHub } from "./tui/app.js";
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const command = args[0] && !args[0].startsWith("--") ? args[0] : "hub";
+  const options = {
+    workspaceRoot: process.cwd(),
+    feedFile: undefined,
+    adapter: undefined,
+    sessionId: undefined,
+    captureMode: undefined,
+    label: undefined,
+    notes: undefined,
+    runId: undefined,
+    compareRunId: undefined,
+    agentId: undefined,
+    kind: undefined,
+    summary: undefined,
+    laneId: undefined,
+    branchId: undefined,
+    checkpointRef: undefined,
+    toolRefs: [],
+    evidenceRefs: [],
+    id: undefined,
+    title: undefined,
+    status: undefined,
+    from: undefined,
+    to: undefined,
+    note: undefined,
+    actor: undefined,
+    taskType: undefined,
+    priority: undefined,
+    sourceFile: undefined,
+    category: undefined,
+    tool: undefined,
+    artifacts: [],
+    metadataJson: undefined,
+    eventType: undefined,
+    sourceModule: undefined,
+    traceId: undefined,
+    objectiveId: undefined,
+    decisionId: undefined,
+    payloadJson: undefined,
+    message: undefined,
+    section: undefined,
+    sourceLine: undefined,
+    dependsOn: [],
+    sourceTodoPath: undefined,
+    timestamp: undefined,
+    endpoint: undefined,
+    target: undefined,
+  };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--workspace-root" && args[i + 1]) {
+      options.workspaceRoot = resolve(args[++i]);
+    } else if (arg === "--feed" && args[i + 1]) {
+      options.feedFile = resolve(args[++i]);
+    } else if (arg === "--adapter" && args[i + 1]) {
+      options.adapter = args[++i];
+    } else if (arg === "--session-id" && args[i + 1]) {
+      options.sessionId = args[++i];
+    } else if (arg === "--capture-mode" && args[i + 1]) {
+      options.captureMode = args[++i];
+    } else if (arg === "--label" && args[i + 1]) {
+      options.label = args[++i];
+    } else if (arg === "--notes" && args[i + 1]) {
+      options.notes = args[++i];
+    } else if (arg === "--run-id" && args[i + 1]) {
+      options.runId = args[++i];
+    } else if (arg === "--compare-run-id" && args[i + 1]) {
+      options.compareRunId = args[++i];
+    } else if (arg === "--agent-id" && args[i + 1]) {
+      options.agentId = args[++i];
+    } else if (arg === "--kind" && args[i + 1]) {
+      options.kind = args[++i];
+    } else if (arg === "--summary" && args[i + 1]) {
+      options.summary = args[++i];
+    } else if (arg === "--lane-id" && args[i + 1]) {
+      options.laneId = args[++i];
+    } else if (arg === "--branch-id" && args[i + 1]) {
+      options.branchId = args[++i];
+    } else if (arg === "--checkpoint-ref" && args[i + 1]) {
+      options.checkpointRef = args[++i];
+    } else if (arg === "--tool-ref" && args[i + 1]) {
+      options.toolRefs.push(args[++i]);
+    } else if (arg === "--evidence-ref" && args[i + 1]) {
+      options.evidenceRefs.push(args[++i]);
+    } else if (arg === "--id" && args[i + 1]) {
+      options.id = args[++i];
+    } else if (arg === "--title" && args[i + 1]) {
+      options.title = args[++i];
+    } else if (arg === "--status" && args[i + 1]) {
+      options.status = args[++i];
+    } else if (arg === "--from" && args[i + 1]) {
+      options.from = args[++i];
+    } else if (arg === "--to" && args[i + 1]) {
+      options.to = args[++i];
+    } else if (arg === "--note" && args[i + 1]) {
+      options.note = args[++i];
+    } else if (arg === "--actor" && args[i + 1]) {
+      options.actor = args[++i];
+    } else if (arg === "--task-type" && args[i + 1]) {
+      options.taskType = args[++i];
+    } else if (arg === "--priority" && args[i + 1]) {
+      options.priority = args[++i];
+    } else if (arg === "--source-file" && args[i + 1]) {
+      options.sourceFile = args[++i];
+    } else if (arg === "--category" && args[i + 1]) {
+      options.category = args[++i];
+    } else if (arg === "--tool" && args[i + 1]) {
+      options.tool = args[++i];
+    } else if (arg === "--artifact" && args[i + 1]) {
+      options.artifacts.push(args[++i]);
+    } else if (arg === "--metadata-json" && args[i + 1]) {
+      options.metadataJson = args[++i];
+    } else if (arg === "--event-type" && args[i + 1]) {
+      options.eventType = args[++i];
+    } else if (arg === "--source-module" && args[i + 1]) {
+      options.sourceModule = args[++i];
+    } else if (arg === "--trace-id" && args[i + 1]) {
+      options.traceId = args[++i];
+    } else if (arg === "--objective-id" && args[i + 1]) {
+      options.objectiveId = args[++i];
+    } else if (arg === "--decision-id" && args[i + 1]) {
+      options.decisionId = args[++i];
+    } else if (arg === "--payload-json" && args[i + 1]) {
+      options.payloadJson = args[++i];
+    } else if (arg === "--message" && args[i + 1]) {
+      options.message = args[++i];
+    } else if (arg === "--section" && args[i + 1]) {
+      options.section = args[++i];
+    } else if (arg === "--source-line" && args[i + 1]) {
+      options.sourceLine = Number(args[++i]);
+    } else if (arg === "--depends-on" && args[i + 1]) {
+      options.dependsOn.push(args[++i]);
+    } else if (arg === "--source-todo-path" && args[i + 1]) {
+      options.sourceTodoPath = args[++i];
+    } else if (arg === "--timestamp" && args[i + 1]) {
+      options.timestamp = args[++i];
+    } else if (arg === "--endpoint" && args[i + 1]) {
+      options.endpoint = args[++i];
+    } else if (arg === "--target" && args[i + 1]) {
+      options.target = args[++i];
+    }
+  }
+  return { command, options };
+}
+
+function parseOptionalJson(raw, label) {
+  if (!raw) return undefined;
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`Invalid ${label}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function buildProjectedState(workspaceRoot) {
+  return projectWorkspaceState(loadWorkspaceState(workspaceRoot));
+}
+
+function printHelp() {
+  process.stdout.write(
+    [
+      "Vericify",
+      "",
+      `Default adapter: ${DEFAULT_ADAPTER}`,
+      "",
+      "Commands:",
+      "  hub       Launch the terminal hub (default)",
+      "  adapters  List available adapter contracts and current workspace status",
+      "  attach    Attach an adapter profile to this workspace",
+      "  compare   Print a structured comparison between two runs",
+      "  publish   Materialize a shareable run artifact under .vericify/published/",
+      "  sync      Queue a published run artifact into .vericify/sync-outbox/",
+      "  handoff   Upsert a native handoff into .vericify/handoffs.json",
+      "  todo      Upsert a native todo node into .vericify/todo-state.json",
+      "  ledger    Append a native run-ledger entry into .vericify/run-ledger.json",
+      "  event     Append a native status event into .vericify/status-events.ndjson",
+      "  post      Append a structured process post into .vericify/process-posts.json",
+      "  snapshot  Print the current projected run state as JSON",
+      "  help      Show this help",
+      "",
+      "Options:",
+      "  --workspace-root <path>  Read workspace input artifacts from the given root",
+      "  --feed <path>            Execute startup commands from a text file before returning control to keyboard",
+      "  --adapter <id>           Adapter id for adapters/attach commands",
+      "  --session-id <id>        Optional adapter session identifier",
+      "  --capture-mode <mode>    Adapter capture mode override",
+      "  --label <text>           Human label for attached adapter or publish title",
+      "  --notes <text>           Freeform note for attached adapter",
+      "  --id <id>                Handoff/todo record id",
+      "  --title <text>           Handoff/todo title",
+      "  --status <value>         Handoff/todo/event status",
+      "  --from <id>              Handoff sender",
+      "  --to <id>                Handoff recipient",
+      "  --note <text>            Handoff history note",
+      "  --actor <id>             Handoff history actor",
+      "  --task-type <text>       Handoff task type",
+      "  --priority <text>        Handoff/todo priority",
+      "  --source-file <path>     Handoff source file",
+      "  --tool <id>              Run-ledger tool id",
+      "  --category <value>       Run-ledger category",
+      "  --message <text>         Run-ledger message",
+      "  --artifact <path>        Run-ledger artifact ref, repeatable",
+      "  --metadata-json <json>   Run-ledger metadata object",
+      "  --source-module <id>     Status-event source module",
+      "  --event-type <text>      Status-event type",
+      "  --trace-id <id>          Status-event trace id",
+      "  --objective-id <id>      Status-event objective id",
+      "  --decision-id <id>       Status-event decision id",
+      "  --payload-json <json>    Status-event payload object",
+      "  --section <text>         Todo section",
+      "  --source-line <n>        Todo source line",
+      "  --depends-on <id>        Todo dependency id, repeatable",
+      "  --source-todo-path <p>   Todo source path",
+      "  --timestamp <iso8601>    Optional timestamp override",
+      "  --run-id <id>            Process-post target run id",
+      "  --compare-run-id <id>    Optional second run for compare/publish/sync",
+      "  --agent-id <id>          Process-post author",
+      "  --kind <kind>            Process-post kind: intent|progress|blocker|handoff_note|completion",
+      "  --summary <text>         Process-post summary",
+      "  --lane-id <id>           Optional process-post lane id",
+      "  --branch-id <id>         Optional process-post branch id",
+      "  --checkpoint-ref <id>    Optional process-post checkpoint ref",
+      "  --tool-ref <id>          Optional tool ref, repeatable",
+      "  --evidence-ref <path>    Optional evidence ref, repeatable",
+      "  --endpoint <url>         Optional hosted sync endpoint to record in the outbox item",
+      "  --target <name>          Sync target name, default vericify-cloud-v1",
+      "",
+      "Storage:",
+      "  Vericify prefers .vericify/* and also reads partner agent-state/* when present",
+      "  native writers mirror into partner agent-state/* when a partner ACE workspace is detected",
+      "",
+      "Keyboard:",
+      "  q quit | j/k select | Enter inspect | c compare | y history | / command | r refresh | h hub | Ctrl+R history search",
+      "",
+    ].join("\n")
+  );
+}
+
+async function printSnapshot(workspaceRoot) {
+  const projected = buildProjectedState(workspaceRoot);
+  process.stdout.write(`${JSON.stringify(projected, null, 2)}\n`);
+}
+
+async function printAdapters(workspaceRoot) {
+  const adapters = detectAdapters(workspaceRoot);
+  process.stdout.write(`${JSON.stringify({ workspace_root: workspaceRoot, adapters }, null, 2)}\n`);
+}
+
+async function writeAdapterAttachment(options) {
+  const result = attachAdapter(options.workspaceRoot, {
+    adapter_id: options.adapter,
+    session_id: options.sessionId,
+    capture_mode: options.captureMode,
+    label: options.label,
+    notes: options.notes,
+  });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+async function printComparison(options) {
+  const projected = buildProjectedState(options.workspaceRoot);
+  const left = findRunById(projected, options.runId);
+  const right = findRunById(projected, options.compareRunId);
+  if (!left) throw new Error(`Unknown run id: ${options.runId}`);
+  if (!right) throw new Error(`Unknown compare run id: ${options.compareRunId}`);
+  const compare_report = buildRunComparison(left, right);
+  process.stdout.write(`${JSON.stringify({ generated_at: projected.generated_at, workspace: projected.workspace, compare_report }, null, 2)}\n`);
+}
+
+async function writePublishedArtifact(options) {
+  const projected = buildProjectedState(options.workspaceRoot);
+  const result = publishRunArtifact({
+    workspaceRoot: options.workspaceRoot,
+    projected,
+    runId: options.runId,
+    compareRunId: options.compareRunId,
+    title: options.title ?? options.label,
+  });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+async function queueSyncArtifact(options) {
+  const projected = buildProjectedState(options.workspaceRoot);
+  const published = publishRunArtifact({
+    workspaceRoot: options.workspaceRoot,
+    projected,
+    runId: options.runId,
+    compareRunId: options.compareRunId,
+    title: options.title ?? options.label,
+  });
+  const sync = enqueueSyncOutboxItem({
+    workspaceRoot: options.workspaceRoot,
+    artifact: published.artifact,
+    artifactPath: published.artifact_path,
+    endpoint: options.endpoint,
+    target: options.target,
+  });
+  process.stdout.write(`${JSON.stringify({ published, sync }, null, 2)}\n`);
+}
+
+async function writeProcessPost(options) {
+  const result = appendProcessPost(options.workspaceRoot, {
+    run_id: options.runId,
+    branch_id: options.branchId,
+    lane_id: options.laneId,
+    agent_id: options.agentId,
+    kind: options.kind,
+    summary: options.summary,
+    tool_refs: options.toolRefs,
+    evidence_refs: options.evidenceRefs,
+    checkpoint_ref: options.checkpointRef,
+  });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+async function writeHandoff(options) {
+  const result = upsertHandoff(options.workspaceRoot, {
+    handoff_id: options.id,
+    from: options.from,
+    to: options.to,
+    title: options.title,
+    status: options.status,
+    note: options.note,
+    actor: options.actor,
+    task_type: options.taskType,
+    priority: options.priority,
+    source_file: options.sourceFile,
+    agent_id: options.agentId,
+    timestamp: options.timestamp,
+  });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+async function writeTodo(options) {
+  const result = upsertTodoNode(options.workspaceRoot, {
+    id: options.id,
+    title: options.title,
+    status: options.status,
+    section: options.section,
+    source_line: options.sourceLine,
+    depends_on: options.dependsOn,
+    priority: options.priority,
+    source_todo_path: options.sourceTodoPath,
+  });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+async function writeLedgerEntry(options) {
+  const result = appendRunLedgerEntry(options.workspaceRoot, {
+    id: options.id,
+    timestamp_utc: options.timestamp,
+    tool: options.tool,
+    category: options.category,
+    message: options.message,
+    artifacts: options.artifacts,
+    metadata: parseOptionalJson(options.metadataJson, "metadata-json"),
+  });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+async function writeStatusEvent(options) {
+  const result = appendStatusEvent(options.workspaceRoot, {
+    event_id: options.id,
+    trace_id: options.traceId,
+    timestamp: options.timestamp,
+    source_module: options.sourceModule,
+    event_type: options.eventType,
+    status: options.status,
+    objective_id: options.objectiveId,
+    decision_id: options.decisionId,
+    payload: parseOptionalJson(options.payloadJson, "payload-json"),
+  });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+async function main() {
+  const { command, options } = parseArgs(process.argv);
+  if (command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+  if (command === "adapters") {
+    await printAdapters(options.workspaceRoot);
+    return;
+  }
+  if (command === "attach") {
+    await writeAdapterAttachment(options);
+    return;
+  }
+  if (command === "snapshot") {
+    await printSnapshot(options.workspaceRoot);
+    return;
+  }
+  if (command === "compare") {
+    await printComparison(options);
+    return;
+  }
+  if (command === "publish") {
+    await writePublishedArtifact(options);
+    return;
+  }
+  if (command === "sync") {
+    await queueSyncArtifact(options);
+    return;
+  }
+  if (command === "post") {
+    await writeProcessPost(options);
+    return;
+  }
+  if (command === "handoff") {
+    await writeHandoff(options);
+    return;
+  }
+  if (command === "todo") {
+    await writeTodo(options);
+    return;
+  }
+  if (command === "ledger") {
+    await writeLedgerEntry(options);
+    return;
+  }
+  if (command === "event") {
+    await writeStatusEvent(options);
+    return;
+  }
+  if (command === "hub") {
+    await runHub({
+      workspaceRoot: options.workspaceRoot,
+      feedFile: options.feedFile,
+      loadState: () => projectWorkspaceState(loadWorkspaceState(options.workspaceRoot)),
+      watchedPaths: listDefaultWorkspacePaths(options.workspaceRoot),
+    });
+    return;
+  }
+  process.stderr.write(`Unknown command: ${command}\n`);
+  process.exitCode = 1;
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+  process.exitCode = 1;
+});

package/src/post/process-posts.js

@@ -0,0 +1,72 @@
+import { existsSync } from "node:fs";
+import { readJson, writeJson } from "../core/fs.js";
+import { asArray, hashText, isoNow, slugify } from "../core/util.js";
+import { resolveStoreLayout } from "../store/paths.js";
+
+export function getProcessPostsPaths(workspaceRoot) {
+  const layout = resolveStoreLayout(workspaceRoot);
+  return {
+    primary: layout.vericify.processPosts,
+    mirrors: [layout.partner.processPosts],
+  };
+}
+
+export function normalizeProcessPost(post) {
+  const timestamp = post.timestamp ?? isoNow();
+  const summary = String(post.summary ?? "").trim();
+  const agentId = String(post.agent_id ?? "").trim();
+  const runId = String(post.run_id ?? "").trim();
+  const kind = String(post.kind ?? "").trim();
+  if (!runId) throw new Error("Process posts require --run-id.");
+  if (!agentId) throw new Error("Process posts require --agent-id.");
+  if (!kind) throw new Error("Process posts require --kind.");
+  if (!summary) throw new Error("Process posts require --summary.");
+  return {
+    process_post_id:
+      post.process_post_id ??
+      `pp-${slugify(`${agentId}-${kind}`) || "post"}-${hashText(`${runId}:${agentId}:${kind}:${summary}:${timestamp}`).slice(0, 10)}`,
+    run_id: runId,
+    branch_id: post.branch_id,
+    lane_id: post.lane_id,
+    agent_id: agentId,
+    kind,
+    summary,
+    tool_refs: asArray(post.tool_refs),
+    evidence_refs: asArray(post.evidence_refs),
+    checkpoint_ref: post.checkpoint_ref,
+    timestamp,
+  };
+}
+
+export function appendProcessPost(workspaceRoot, input) {
+  const { primary, mirrors } = getProcessPostsPaths(workspaceRoot);
+  const path = primary;
+  const current = readJson(path, { version: 1, posts: [] });
+  const post = normalizeProcessPost(input);
+  const posts = [...(Array.isArray(current.posts) ? current.posts : []), post].sort((left, right) =>
+    String(left.timestamp).localeCompare(String(right.timestamp))
+  );
+  writeJson(path, {
+    version: current.version ?? 1,
+    updated_at: isoNow(),
+    posts,
+  });
+  const mirrored_paths = [];
+  for (const mirrorPath of mirrors) {
+    if (!existsSync(mirrorPath) && !existsSync(mirrorPath.replace(/\/process-posts\.json$/, ""))) continue;
+    const mirrorCurrent = readJson(mirrorPath, { version: 1, posts: [] });
+    const mirrorPosts = [...(Array.isArray(mirrorCurrent.posts) ? mirrorCurrent.posts : []), post]
+      .sort((left, right) => String(left.timestamp).localeCompare(String(right.timestamp)));
+    writeJson(mirrorPath, {
+      version: mirrorCurrent.version ?? 1,
+      updated_at: isoNow(),
+      posts: mirrorPosts,
+    });
+    mirrored_paths.push(mirrorPath);
+  }
+  return {
+    path,
+    mirrored_paths,
+    post,
+  };
+}