Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
5.2 KB
Raw Blame
/**
 * `o2b brain scaffold-stub <list|write>` - the unresolved wikilink
 * targets, and the verb that materialises one (B3).
 *
 * CLI mirror of the `brain_scaffold_stub` MCP tool; both delegate to
 * `core/brain/notes/scaffold-stub.ts`, so the fail-closed target
 * resolution and the index refusal cannot mean two different things on
 * two surfaces.
 *
 * `list` prints the REFUSAL when the index is missing or only partially
 * resolved, and it exits zero doing so: an unmeasurable index is an
 * answer, not a failure of this command. What it must never do is print
 * an empty list, which a shell reads as a clean vault.
 */

import { defaultConfigPath } from "../../../core/config.ts";
import {
  listDanglingTargets,
  scaffoldStub,
  DANGLING_SCAN,
  type DanglingScanResult,
  type ScaffoldStubResult,
} from "../../../core/brain/notes/scaffold-stub.ts";
import {
  CREATE_NOTE_IF_EXISTS,
  type CreateNoteIfExists,
} from "../../../core/brain/notes/create-note.ts";
import { normalizeFlagString, ok, okJson, parse, resolveBrainVault } from "../helpers.ts";

const USAGE_ERROR_EXIT = 2;

/** The two sub-actions, named once so the usage line cannot drift. */
const ACTIONS = Object.freeze(["list", "write"] as const);

function usageError(message: string): number {
  process.stderr.write(`error: ${message}\n`);
  return USAGE_ERROR_EXIT;
}

function renderScanJson(scan: DanglingScanResult): Record<string, unknown> {
  return {
    state: scan.state,
    targets: scan.targets.map((t) => ({ target: t.target, sources: [...t.sources] })),
    detail: scan.detail,
    next_command: scan.nextCommand,
  };
}

/**
 * The human rendering. A refusal names its state, its detail and the
 * command that resolves it; a measured scan with nothing in it says so
 * in words that cannot be confused with a refusal.
 */
function renderScanText(scan: DanglingScanResult): string {
  if (scan.state !== DANGLING_SCAN.measured) {
    return (
      `dangling targets: ${scan.state} (not measured)\n` +
      `  ${scan.detail ?? ""}\n` +
      `  next: ${scan.nextCommand}`
    );
  }
  if (scan.targets.length === 0) return "dangling targets: measured, none";
  const lines = scan.targets.map((t) => `  ${t.target} <- ${t.sources.join(", ")}`);
  return [`dangling targets: measured, ${scan.targets.length}`, ...lines].join("\n");
}

function renderStubJson(res: ScaffoldStubResult): Record<string, unknown> {
  return {
    target: res.target,
    path: res.path,
    applied: res.applied,
    outcome: res.outcome,
    sources: [...res.sources],
  };
}

export async function cmdBrainScaffoldStub(argv: string[]): Promise<number> {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    config: { type: "string" },
    path: { type: "string" },
    source: { type: "string-array" },
    "if-exists": { type: "string" },
    limit: { type: "string" },
    apply: { type: "boolean" },
    json: { type: "boolean" },
  });

  const action = positional[0];
  if (action === undefined || !(ACTIONS as ReadonlyArray<string>).includes(action)) {
    return usageError(`brain scaffold-stub requires an action: ${ACTIONS.join(" | ")}`);
  }

  const config = (flags["config"] as string | undefined) ?? defaultConfigPath();
  const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
  const wantsJson = flags["json"] === true;

  try {
    if (action === "list") {
      const limitRaw = normalizeFlagString(flags["limit"]);
      const limit = limitRaw === null ? null : Number(limitRaw);
      if (limit !== null && (!Number.isInteger(limit) || limit < 0)) {
        return usageError("brain scaffold-stub --limit must be a non-negative integer");
      }
      const scan = await listDanglingTargets(vault, limit === null ? {} : { limit });
      if (wantsJson) okJson(renderScanJson(scan));
      else ok(renderScanText(scan));
      return 0;
    }

    const target = positional[1];
    if (target === undefined) {
      return usageError("brain scaffold-stub write requires a wikilink target");
    }
    const ifExistsRaw = normalizeFlagString(flags["if-exists"]);
    if (
      ifExistsRaw !== null &&
      !CREATE_NOTE_IF_EXISTS.includes(ifExistsRaw as CreateNoteIfExists)
    ) {
      return usageError(
        `brain scaffold-stub --if-exists must be one of ${CREATE_NOTE_IF_EXISTS.join(", ")}`,
      );
    }
    const path = normalizeFlagString(flags["path"]);
    const rawSources = flags["source"];
    const sources = Array.isArray(rawSources)
      ? rawSources.filter((s): s is string => typeof s === "string")
      : typeof rawSources === "string"
        ? [rawSources]
        : [];

    const res = scaffoldStub(vault, {
      target,
      ...(path !== null ? { path } : {}),
      sources,
      ...(ifExistsRaw !== null ? { ifExists: ifExistsRaw as CreateNoteIfExists } : {}),
      apply: flags["apply"] === true,
    });
    if (wantsJson) okJson(renderStubJson(res));
    else {
      ok(
        `${res.applied ? (res.outcome ?? "") : "plan"}: ${res.target} -> ${res.path}` +
          (res.sources.length > 0 ? ` (${res.sources.length} source(s))` : ""),
      );
    }
    return 0;
  } catch (exc) {
    process.stderr.write(`error: ${(exc as Error).message ?? String(exc)}\n`);
    return 1;
  }
}