@gmickel/gno 1.37.1 → 1.39.0

package/src/cli/commands/agents/block.ts

@@ -0,0 +1,164 @@
+/**
+ * GNO agents protocol block: content, markers, hashing, extraction.
+ *
+ * One compact, versioned instruction block bounded by stable BEGIN/END
+ * markers. Install/update/uninstall touch ONLY the owned block; content
+ * outside the markers stays byte-identical. The block content is static —
+ * identical on every machine — so a block is current exactly when its stamp
+ * version matches the installed release and its hash matches its body.
+ *
+ * @module src/cli/commands/agents/block
+ */
+
+import { CliError } from "../../errors.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Version of the protocol block content. Bump on any content change. */
+export const BLOCK_VERSION = 2;
+
+/** Stable across block versions — never change these once shipped. */
+export const BEGIN_MARKER = "<!-- gno:agents:begin -->";
+export const END_MARKER = "<!-- gno:agents:end -->";
+
+const STAMP_RE = /^<!-- gno-agents block v(\d+) sha256:([0-9a-f]{16}) /;
+const HASH_PREFIX_LENGTH = 16;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Rendering
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The protocol block body (between stamp line and end marker). Compact by
+ * design: the retrieval ladder + the writing contract. Detailed workflows live
+ * in the GNO skill; the block just points at it. No filesystem paths — the
+ * text is the same on every machine.
+ */
+export function renderBlockBody(): string {
+  return `## GNO knowledge retrieval
+
+Local knowledge search over indexed collections. Source files are the truth; the GNO index is disposable, machine-local.
+
+Ladder — scope to a collection first (\`--collection <name>\`):
+
+1. Exact term/identifier/quote/error: \`gno search "<text>"\`
+2. Entity or known document: \`gno query "<question>" --fast -n 10\`
+3. Multi-document evidence for a goal: \`gno context build "<goal>" --budget 12000\`
+4. Change/dependency questions: \`gno changes\` / \`gno diff <doc>\` / \`gno impact <doc>\`
+5. Generated factual answer: \`gno ask "<question>" --verify\` (abstention is valid)
+6. Expected document missing: reformulate + re-check collection scope (\`gno query diagnose "<query>" --target <doc>\`) before any grep fallback.
+
+Writing: retrieve first — a question alone is read-only. Edit an existing canonical note in its source file; \`gno capture\` creates genuinely new notes (collection, title/path, source kind, provenance) — never an update API. After writes: reindex the collection, verify retrieval.
+
+Cite with gno:// URIs. Advanced retrieval (structured queries, filters, backlinks, similar, capture recipes) lives in the \`gno\` skill: load it (\`/gno\`) when installed, otherwise run \`gno skill install --scope user\` first.`;
+}
+
+/** SHA-256 hex digest of the body, truncated for the stamp line. */
+export function hashBlockBody(body: string): string {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(body);
+  return hasher.digest("hex").slice(0, HASH_PREFIX_LENGTH);
+}
+
+/** Render the stamp line carrying version + body hash. */
+export function renderStampLine(body: string): string {
+  return `<!-- gno-agents block v${BLOCK_VERSION} sha256:${hashBlockBody(body)} — managed by \`gno agents\`; manual edits inside the markers are overwritten -->`;
+}
+
+/** Render the complete block: BEGIN marker, stamp, body, END marker. */
+export function renderBlock(): string {
+  const body = renderBlockBody();
+  return `${BEGIN_MARKER}\n${renderStampLine(body)}\n${body}\n${END_MARKER}`;
+}
+
+/** True when the extracted stamp's hash matches the extracted body. */
+export function stampAuthenticates(block: ExtractedBlock): boolean {
+  return block.stamp !== null && block.stamp.hash === hashBlockBody(block.body);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Extraction & Validation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ExtractedBlock {
+  /** Offset of the BEGIN marker in the file content. */
+  start: number;
+  /** Offset just past the END marker. */
+  end: number;
+  /** Everything between the markers (stamp line + body), without markers. */
+  inner: string;
+  /** Body without the stamp line (equal to inner when no stamp present). */
+  body: string;
+  /** Parsed stamp, when present and well-formed. */
+  stamp: { version: number; hash: string } | null;
+}
+
+export type BlockExtraction =
+  | { found: false }
+  | { found: true; block: ExtractedBlock };
+
+function countOccurrences(haystack: string, needle: string): number {
+  let count = 0;
+  let idx = haystack.indexOf(needle);
+  while (idx !== -1) {
+    count += 1;
+    idx = haystack.indexOf(needle, idx + needle.length);
+  }
+  return count;
+}
+
+const MARKER_GUIDANCE =
+  "Fix or remove the markers manually (or restore the file from its .gno-agents.bak backup), then re-run.";
+
+/**
+ * Extract the managed block from file content.
+ * Fail-closed: malformed or duplicate markers throw with guidance — the
+ * installer never guesses or "repairs".
+ */
+export function extractBlock(
+  content: string,
+  filePath: string
+): BlockExtraction {
+  const begins = countOccurrences(content, BEGIN_MARKER);
+  const ends = countOccurrences(content, END_MARKER);
+
+  if (begins === 0 && ends === 0) {
+    return { found: false };
+  }
+  if (begins !== 1 || ends !== 1) {
+    throw new CliError(
+      "VALIDATION",
+      `Malformed GNO agents markers in ${filePath}: found ${begins} BEGIN and ${ends} END marker(s), expected exactly one of each. ${MARKER_GUIDANCE}`
+    );
+  }
+
+  const start = content.indexOf(BEGIN_MARKER);
+  const endMarkerStart = content.indexOf(END_MARKER);
+  if (endMarkerStart < start) {
+    throw new CliError(
+      "VALIDATION",
+      `Malformed GNO agents markers in ${filePath}: END marker appears before BEGIN marker. ${MARKER_GUIDANCE}`
+    );
+  }
+
+  const end = endMarkerStart + END_MARKER.length;
+  const rawInner = content.slice(start + BEGIN_MARKER.length, endMarkerStart);
+  // Trim exactly the structural newlines install added around the inner text.
+  const inner = rawInner.replace(/^\n/, "").replace(/\n$/, "");
+
+  const newlineIdx = inner.indexOf("\n");
+  const firstLine = newlineIdx === -1 ? inner : inner.slice(0, newlineIdx);
+  const stampMatch = STAMP_RE.exec(firstLine);
+  const version = stampMatch ? Number(stampMatch[1]) : Number.NaN;
+  // An absurd version (not a safe integer) is an unparseable stamp, not a
+  // numeric verdict — it would otherwise serialize as null in JSON receipts.
+  const stamp =
+    stampMatch && Number.isSafeInteger(version)
+      ? { version, hash: stampMatch[2] ?? "" }
+      : null;
+  const body = stamp && newlineIdx !== -1 ? inner.slice(newlineIdx + 1) : inner;
+
+  return { found: true, block: { start, end, inner, body, stamp } };
+}

package/src/cli/commands/agents/commands.ts

@@ -0,0 +1,413 @@
+/**
+ * `gno agents` command runners: install, update, verify, uninstall.
+ *
+ * @module src/cli/commands/agents/commands
+ */
+
+import { CliError } from "../../errors.js";
+import { getGlobals } from "../../program.js";
+import {
+  BLOCK_VERSION,
+  extractBlock,
+  renderBlock,
+  stampAuthenticates,
+} from "./block.js";
+import {
+  applyPlan,
+  decodeInstructionFile,
+  type PlanMode,
+  planTargets,
+  planWrites,
+  type TargetPlan,
+  unifiedDiff,
+} from "./engine.js";
+import {
+  type HarnessId,
+  HARNESS_IDS,
+  type ResolvedTarget,
+  resolveTargets,
+} from "./harnesses.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Shared
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AgentsOptions {
+  target?: HarnessId | "all";
+  extraDirs?: string[];
+  dryRun?: boolean;
+  json?: boolean;
+  quiet?: boolean;
+  /** Override for testing / sandboxed live verification. */
+  homeDir?: string;
+}
+
+function safeGetGlobals(): { json: boolean; quiet: boolean } {
+  try {
+    return getGlobals();
+  } catch {
+    return { json: false, quiet: false };
+  }
+}
+
+export function parseTargetOption(raw: string): HarnessId | "all" {
+  if (raw === "all" || (HARNESS_IDS as string[]).includes(raw)) {
+    return raw as HarnessId | "all";
+  }
+  throw new CliError(
+    "VALIDATION",
+    `Invalid target: ${raw}. Must be one of ${HARNESS_IDS.join(", ")}, or 'all'.`
+  );
+}
+
+function outputSettings(opts: AgentsOptions): {
+  json: boolean;
+  quiet: boolean;
+} {
+  const globals = safeGetGlobals();
+  return {
+    json: opts.json ?? globals.json,
+    quiet: opts.quiet ?? globals.quiet,
+  };
+}
+
+interface TargetReport {
+  target: string;
+  label: string;
+  path: string;
+  action: string;
+  detected: boolean;
+  via?: string;
+  detail?: string;
+  backup?: string | null;
+}
+
+function reportFor(
+  plan: TargetPlan,
+  backup: string | null | undefined
+): TargetReport {
+  return {
+    target: plan.target.id,
+    label: plan.target.label,
+    path: plan.target.file,
+    action: plan.action,
+    detected: plan.target.detected,
+    ...(plan.via && { via: plan.via }),
+    ...(plan.detail && { detail: plan.detail }),
+    ...(backup !== undefined && { backup }),
+  };
+}
+
+function printHumanReports(reports: TargetReport[]): void {
+  for (const r of reports) {
+    const via = r.via ? ` (${r.detail ?? `via ${r.via}`})` : "";
+    const detail = !r.via && r.detail ? `: ${r.detail}` : "";
+    process.stdout.write(
+      `${r.action.padEnd(12)} ${r.target.padEnd(10)} ${r.path}${via}${detail}\n`
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Install / Update / Uninstall (shared mutation runner)
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function runMutation(
+  verb: "install" | "update" | "uninstall",
+  mode: PlanMode,
+  opts: AgentsOptions
+): Promise<void> {
+  const { json, quiet } = outputSettings(opts);
+  const dryRun = opts.dryRun ?? false;
+
+  const targets = resolveTargets(opts.target ?? "all", {
+    homeDir: opts.homeDir,
+    extraDirs: opts.extraDirs,
+  });
+  const plans = await planTargets(targets, mode);
+
+  const reports: TargetReport[] = [];
+  const diffs: string[] = [];
+  const failedPaths: string[] = [];
+  let validationErrors = 0;
+
+  for (const plan of plans) {
+    if (plan.action === "error") {
+      failedPaths.push(plan.target.file);
+      if (plan.errorCode !== "RUNTIME") {
+        validationErrors += 1;
+      }
+      reports.push(reportFor(plan, undefined));
+      continue;
+    }
+    if (!planWrites(plan)) {
+      reports.push(reportFor(plan, undefined));
+      continue;
+    }
+    if (dryRun) {
+      diffs.push(
+        unifiedDiff(plan.oldContent, plan.newContent, plan.target.file)
+      );
+      reports.push(reportFor(plan, null));
+      continue;
+    }
+    // A failing write must not abort the run before the receipt is emitted:
+    // earlier targets may already have been written, and the operator needs
+    // to see exactly which. Record an `error` row and keep going.
+    try {
+      reports.push(reportFor(plan, await applyPlan(plan)));
+    } catch (err) {
+      failedPaths.push(plan.target.file);
+      reports.push({
+        ...reportFor(plan, undefined),
+        action: "error",
+        detail: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  // Fallback: when the installer could not apply the block somewhere, hand
+  // the operator the exact block to paste (install/update only — uninstall
+  // guidance is in the per-target detail).
+  const manualBlock =
+    failedPaths.length > 0 && mode === "install" ? renderBlock() : undefined;
+
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          command: verb,
+          blockVersion: BLOCK_VERSION,
+          dryRun,
+          results: reports,
+          ...(dryRun && { diffs }),
+          ...(manualBlock !== undefined && { manualBlock }),
+        },
+        null,
+        2
+      )}\n`
+    );
+  } else if (!quiet) {
+    printHumanReports(reports);
+    if (dryRun) {
+      for (const diff of diffs) {
+        if (diff) {
+          process.stdout.write(`\n${diff}\n`);
+        }
+      }
+      process.stdout.write("\nDry run — nothing was written.\n");
+    }
+    if (manualBlock !== undefined) {
+      process.stdout.write(
+        `\nCould not apply the block to: ${failedPaths.join(", ")}\n` +
+          "Append this block to the file yourself (replacing any existing gno:agents block):\n\n" +
+          `${manualBlock}\n`
+      );
+    }
+  }
+
+  if (failedPaths.length > 0) {
+    // Exit-code contract (spec/cli.md): 1 = validation (malformed markers,
+    // non-UTF-8), 2 = runtime (I/O). Any validation failure makes it 1.
+    throw new CliError(
+      validationErrors > 0 ? "VALIDATION" : "RUNTIME",
+      `${verb} failed for ${failedPaths.length} target(s); see per-target detail above. Nothing was written to the failing file(s).`
+    );
+  }
+}
+
+/**
+ * Install or refresh the protocol block. Both verbs converge the block to
+ * the current release: install appends when absent, update replaces an
+ * older/stale block in place; a current block is a no-op for either.
+ */
+export function installAgents(
+  opts: AgentsOptions = {},
+  verb: "install" | "update" = "install"
+): Promise<void> {
+  return runMutation(verb, "install", opts);
+}
+
+/** Remove the protocol block and its markers, leaving the rest untouched. */
+export function uninstallAgents(opts: AgentsOptions = {}): Promise<void> {
+  return runMutation("uninstall", "uninstall", opts);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Verify
+// ─────────────────────────────────────────────────────────────────────────────
+
+type VerifyStatus =
+  | "ok"
+  | "outdated"
+  | "missing"
+  | "malformed"
+  | "error"
+  | "covered"
+  | "not-detected";
+
+interface VerifyReport {
+  target: string;
+  label: string;
+  path: string;
+  status: VerifyStatus;
+  detected: boolean;
+  via?: string;
+  detail?: string;
+  blockVersion?: number;
+  hashOk?: boolean;
+}
+
+/** Inner text (stamp + body, no markers) of the current release's block. */
+function expectedInner(): string {
+  return renderBlock().split("\n").slice(1, -1).join("\n");
+}
+
+async function verifyTarget(
+  target: ResolvedTarget,
+  runContext: {
+    resolvedIds: Set<string>;
+    requiredCovering: Set<string>;
+    /** Real-file identity → id of the target that owns verification. */
+    owners: Map<string, string>;
+  }
+): Promise<VerifyReport> {
+  const base = {
+    target: target.id,
+    label: target.label,
+    path: target.file,
+    detected: target.detected,
+  };
+
+  if (!(target.detected || runContext.requiredCovering.has(target.id))) {
+    return { ...base, status: "not-detected" };
+  }
+  if (target.coveredBy) {
+    if (!runContext.resolvedIds.has(target.coveredBy)) {
+      return {
+        ...base,
+        status: "missing",
+        detail: `covered via ${target.coveredBy}, but ${target.coveredBy} was not resolved in this run`,
+      };
+    }
+    return {
+      ...base,
+      status: "covered",
+      via: target.coveredBy,
+      detail: `covered via ${target.coveredBy}`,
+    };
+  }
+  const owner = runContext.owners.get(target.realFile);
+  if (owner) {
+    return {
+      ...base,
+      status: "covered",
+      via: owner,
+      detail: `covered via ${owner} (same file)`,
+    };
+  }
+  runContext.owners.set(target.realFile, target.id);
+
+  const file = Bun.file(target.file);
+  if (!(await file.exists())) {
+    return { ...base, status: "missing", detail: "instruction file not found" };
+  }
+  let bytes: Uint8Array;
+  try {
+    bytes = await file.bytes();
+  } catch (err) {
+    return {
+      ...base,
+      status: "error",
+      detail: `could not read instruction file: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+  let extraction: ReturnType<typeof extractBlock>;
+  try {
+    const { content } = decodeInstructionFile(bytes, target.file);
+    extraction = extractBlock(content, target.file);
+  } catch (err) {
+    return {
+      ...base,
+      status: "malformed",
+      detail: err instanceof Error ? err.message : String(err),
+    };
+  }
+  if (!extraction.found) {
+    return { ...base, status: "missing", detail: "no GNO agents block" };
+  }
+
+  const { block } = extraction;
+  const hashOk = stampAuthenticates(block);
+  const versionOk = block.stamp?.version === BLOCK_VERSION;
+  const isCurrent = versionOk && hashOk && block.inner === expectedInner();
+  const versioned = { blockVersion: block.stamp?.version, hashOk };
+  if (isCurrent) {
+    return { ...base, status: "ok", ...versioned };
+  }
+  const detail = !block.stamp
+    ? "block has no valid stamp line (missing or unparseable) — run `gno agents update`"
+    : !hashOk
+      ? "block content does not match its stamp hash (edited inside markers?) — run `gno agents update`"
+      : !versionOk
+        ? `block v${block.stamp?.version ?? "?"} does not match installed release v${BLOCK_VERSION} — run \`gno agents update\``
+        : "block content differs from the installed release — run `gno agents update`";
+  return { ...base, status: "outdated", ...versioned, detail };
+}
+
+export async function verifyAgents(opts: AgentsOptions = {}): Promise<void> {
+  const { json, quiet } = outputSettings(opts);
+  const targets = resolveTargets(opts.target ?? "all", {
+    homeDir: opts.homeDir,
+    extraDirs: opts.extraDirs,
+  });
+
+  const resolvedIds = new Set(targets.map((t) => t.id as string));
+  const requiredCovering = new Set<string>();
+  for (const t of targets) {
+    if (t.detected && t.coveredBy) {
+      requiredCovering.add(t.coveredBy);
+    }
+  }
+  const owners = new Map<string, string>();
+  const results: VerifyReport[] = [];
+  for (const target of targets) {
+    results.push(
+      await verifyTarget(target, { resolvedIds, requiredCovering, owners })
+    );
+  }
+
+  const failing = results.filter(
+    (r) => !["ok", "covered", "not-detected"].includes(r.status)
+  );
+  const ok = failing.length === 0;
+
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        { command: "verify", blockVersion: BLOCK_VERSION, ok, results },
+        null,
+        2
+      )}\n`
+    );
+  } else if (!quiet) {
+    for (const r of results) {
+      const detail = r.detail ? ` — ${r.detail}` : "";
+      process.stdout.write(
+        `${r.status.padEnd(13)} ${r.target.padEnd(10)} ${r.path}${detail}\n`
+      );
+    }
+  }
+
+  if (!ok) {
+    // 2 when the only failures were unreadable files (could not check),
+    // 1 for any content verdict (outdated / missing / malformed).
+    const allRuntime = failing.every((r) => r.status === "error");
+    throw new CliError(
+      allRuntime ? "RUNTIME" : "VALIDATION",
+      `verification failed for ${failing.length} target(s): ${failing
+        .map((r) => `${r.target} (${r.status})`)
+        .join(", ")}`
+    );
+  }
+}