harnery 0.0.1 → 0.2.1

package/src/commands/session.ts

@@ -0,0 +1,187 @@
+import { spawn } from "node:child_process";
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import { resolveOwner, selfDisplayName } from "../core/agents/index.ts";
+import {
+  clampField,
+  newCmdId,
+  readLastIntent,
+  writeSessionEvent,
+} from "../core/agents/session-events.ts";
+import { resolveBinName } from "../core/config.ts";
+
+/** Strip the `agent-` prefix so structured event `agent` field matches heartbeat.name. */
+function bareAgentName(): string {
+  const full = selfDisplayName();
+  return full.startsWith("agent-") ? full.slice(6) : full;
+}
+
+function selfOwnerId(): string | undefined {
+  return resolveOwner() ?? undefined;
+}
+
+/**
+ * `harn session`: run a command (or narrate) and emit canonical coordination
+ * events for follow-along.
+ *
+ * Follow-along happens through the canonical `.harnery/events.ndjson` stream +
+ * the `/live` web viewer (or `harn agents watch`): `harn session -- <cmd>` runs
+ * the command, forwards its output to the terminal verbatim, and emits canonical
+ * `command.start/output/end`; `harn session log` emits a canonical `narration`
+ * event. The file-management subcommands (`tail`/`clear`/`trim`/`path`) are
+ * retired no-op stubs; `trim` is a silent no-op so a SessionStart hook that
+ * calls it keeps working.
+ *
+ * Usage:
+ *   harn session "<intent>" -- <cmd> [args...]   run command, emit command.* events
+ *   harn session log "<message>"                 emit a narration event
+ */
+let emit: EmitContext;
+
+export function registerSessionCommand(program: Command, emitParam: EmitContext): void {
+  emit = emitParam;
+  const session = program
+    .command("session")
+    .description("Run a command (or narrate) and emit canonical coordination events");
+
+  // Narration-only entry → canonical narration event.
+  session
+    .command("log <message...>")
+    .description("Emit a narration event (no command run)")
+    .action((messageParts: string[]) => {
+      const message = messageParts.join(" ");
+      writeSessionEvent("narration", bareAgentName(), {
+        instance_id: selfOwnerId(),
+        message: clampField(message),
+      });
+      emit.text(`⋯ ${message}\n`);
+    });
+
+  // Retired file-management subcommands, kept as graceful no-op stubs so
+  // existing callers (hooks, muscle memory) don't error. `trim` is the one a
+  // hook invokes, so it must exit 0 silently.
+  session
+    .command("trim")
+    .description("(retired): no-op kept for hook compatibility")
+    .option("-y, --yes", "(ignored)")
+    .option("--max-entries <n>", "(ignored)")
+    .option("--max-bytes <size>", "(ignored)")
+    .allowUnknownOption()
+    .allowExcessArguments()
+    .action(() => {
+      /* silent no-op, exit 0 */
+    });
+
+  for (const name of ["tail", "clear", "path"] as const) {
+    session
+      .command(name)
+      .description(`(retired): watch /live or '${resolveBinName()} agents watch'`)
+      .allowUnknownOption()
+      .action(() => {
+        emit.text(
+          `Retired. Live activity flows to .harnery/events.ndjson; watch the /live web viewer or run '${resolveBinName()} agents watch'.\n`,
+        );
+      });
+  }
+
+  // Default form: harn session "<intent>" -- <cmd> [args]
+  session
+    .argument("<intent>", "One-line description of what this action is for")
+    .argument("<cmd...>", "The command to run (prefix with -- if it has its own flags)")
+    .allowUnknownOption()
+    .action((intent: string, cmd: string[]) => {
+      runLogged(intent, cmd);
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Core
+// ---------------------------------------------------------------------------
+
+/**
+ * Strip ONLY carriage-return redraw noise (progress bars like `docker pull`'s
+ * sticky line) from a chunk before splitting into event lines. Terminal
+ * forwarding keeps the raw bytes; this only cleans the canonical event copy.
+ */
+function stripCRNoise(text: string): string {
+  return text.replace(/[^\n]*\r(?!\n)/g, "");
+}
+
+function runLogged(intent: string, cmdArg: string[]): void {
+  // Strip a leading `--` separator if commander left one in.
+  const cmd = cmdArg[0] === "--" ? cmdArg.slice(1) : cmdArg;
+  if (cmd.length === 0) {
+    emit.error({ code: "usage", message: "Usage: harn session <intent> -- <cmd> [args...]" });
+    process.exit(2);
+  }
+
+  const cmdLine = cmd.map(quoteArg).join(" ");
+  const agent = bareAgentName();
+  const instanceId = selfOwnerId();
+  const cmdId = newCmdId();
+
+  // Intent precedence: explicit arg wins; else the PreToolUse-stamped intent
+  // file; else the command line itself.
+  const resolvedIntent =
+    intent && intent.trim().length > 0 ? intent : (readLastIntent(instanceId) ?? cmdLine);
+  writeSessionEvent("command_start", agent, {
+    instance_id: instanceId,
+    cmd_id: cmdId,
+    intent: clampField(resolvedIntent),
+    cmd: clampField(cmdLine),
+  });
+
+  const start = Date.now();
+  const child = spawn(cmd[0]!, cmd.slice(1), {
+    stdio: ["inherit", "pipe", "pipe"],
+    env: process.env,
+  });
+
+  child.stdout?.on("data", (chunk: Buffer) => {
+    process.stdout.write(chunk); // lint-ok-emission: harn session forwards child stdout verbatim; this IS the command's primary purpose
+    for (const line of stripCRNoise(chunk.toString("utf8")).split("\n")) {
+      if (line.length === 0) continue;
+      writeSessionEvent("output", agent, {
+        instance_id: instanceId,
+        cmd_id: cmdId,
+        stream: "stdout",
+        line: clampField(line),
+      });
+    }
+  });
+  child.stderr?.on("data", (chunk: Buffer) => {
+    process.stderr.write(chunk); // lint-ok-emission: harn session forwards child stderr verbatim; this IS the command's primary purpose
+    for (const line of stripCRNoise(chunk.toString("utf8")).split("\n")) {
+      if (line.length === 0) continue;
+      writeSessionEvent("output", agent, {
+        instance_id: instanceId,
+        cmd_id: cmdId,
+        stream: "stderr",
+        line: clampField(line),
+      });
+    }
+  });
+
+  child.on("error", (err) => {
+    process.stderr.write(`✗ spawn failed: ${err.message}\n`);
+    process.exit(127);
+  });
+
+  child.on("close", (code, signal) => {
+    const durationMs = Date.now() - start;
+    writeSessionEvent("command_end", agent, {
+      instance_id: instanceId,
+      cmd_id: cmdId,
+      exit: code ?? null,
+      signal: signal ?? null,
+      duration_ms: durationMs,
+    });
+    process.exit(code ?? 1);
+  });
+}
+
+/** Shell-safe quote an argument for human-readable logging (not for eval). */
+function quoteArg(arg: string): string {
+  if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(arg)) return arg;
+  return `'${arg.replace(/'/g, `'\\''`)}'`;
+}

package/src/commands/sync.ts

@@ -0,0 +1,306 @@
+/**
+ * `harn sync`: keep a curated subset of `.harnery/` live across machines
+ * via rclone (typically a Google Drive remote, but any rclone remote works).
+ *
+ * Scope: a deliberately small set of file types: durable identities,
+ * archived scratchpads, council manifests. The high-churn machine-local
+ * stuff (events.ndjson, .pid-map/, active/, .last-intent.*) stays put.
+ *
+ * Subcommands:
+ *   init:    interactive: `rclone config` walks through Google OAuth, then
+ *            we record the chosen remote name in ~/.config/harnery/sync.json
+ *   status:  diff local vs remote (rclone check --one-way)
+ *   push:    local to remote (rclone copy)
+ *   pull:    remote to local (rclone copy)
+ *   list:    show what's in the remote
+ *
+ * Power users override via env (HARNERY_SYNC_REMOTE, HARNERY_SYNC_PREFIX) or by
+ * editing the config file. Like `harn backup`, this surfaces rclone rather
+ * than abstracting it.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+
+// What we sync. Anything matching one of these (relative to .harnery/) is
+// considered part of the sync set. Everything else stays local-only.
+const SYNC_PATHS = ["identities/", "scratch/archived/", "councils/"];
+
+interface SyncConfig {
+  remote: string;
+  prefix: string;
+}
+
+function configPath(): string {
+  return path.join(os.homedir(), ".config", "harnery", "sync.json");
+}
+
+function loadConfig(): SyncConfig | null {
+  const envRemote = process.env.HARNERY_SYNC_REMOTE;
+  const envPrefix = process.env.HARNERY_SYNC_PREFIX ?? "harnery";
+  if (envRemote) return { remote: envRemote, prefix: envPrefix };
+  const p = configPath();
+  if (!existsSync(p)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(p, "utf-8")) as SyncConfig;
+    if (typeof parsed.remote === "string" && typeof parsed.prefix === "string") {
+      return parsed;
+    }
+  } catch {
+    /* fall through */
+  }
+  return null;
+}
+
+function saveConfig(cfg: SyncConfig): void {
+  const p = configPath();
+  mkdirSync(path.dirname(p), { recursive: true });
+  writeFileSync(p, `${JSON.stringify(cfg, null, 2)}\n`, "utf-8");
+}
+
+function findHarneryDir(): string | null {
+  let dir = process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(path.join(dir, ".harnery"))) {
+      return path.join(dir, ".harnery");
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function checkRclone(emit: EmitContext): boolean {
+  const r = spawnSync("rclone", ["version"], { encoding: "utf-8" });
+  if (r.status !== 0) {
+    emit.error({
+      code: "rclone_missing",
+      message: "rclone is not on PATH",
+      hint:
+        "Install via `curl https://rclone.org/install.sh | sudo bash` or " +
+        "https://rclone.org/downloads/",
+    });
+    return false;
+  }
+  return true;
+}
+
+function listRemotes(): string[] {
+  const r = spawnSync("rclone", ["listremotes"], { encoding: "utf-8" });
+  if (r.status !== 0) return [];
+  return r.stdout
+    .split("\n")
+    .map((s) => s.trim().replace(/:$/, ""))
+    .filter(Boolean);
+}
+
+function ensureConfig(emit: EmitContext): SyncConfig | null {
+  const cfg = loadConfig();
+  if (cfg) return cfg;
+  emit.error({
+    code: "not_initialized",
+    message: "no harn sync config",
+    hint: "Run `harn sync init` to pick an rclone remote and record it.",
+  });
+  return null;
+}
+
+function buildRcloneArgs(
+  cfg: SyncConfig,
+  harneryDir: string,
+  direction: "push" | "pull",
+): {
+  local: string;
+  remote: string;
+} {
+  const local = harneryDir;
+  const remote = `${cfg.remote}:${cfg.prefix}`;
+  return direction === "push" ? { local, remote } : { local, remote };
+}
+
+interface FilterOpts {
+  dryRun?: boolean;
+  verbose?: boolean;
+}
+
+function syncIncludeFlags(): string[] {
+  const out: string[] = [];
+  for (const p of SYNC_PATHS) {
+    out.push("--include", `/${p}**`);
+  }
+  return out;
+}
+
+export function registerSyncCommand(program: Command, emit: EmitContext): void {
+  const sync = program
+    .command("sync")
+    .description(
+      "Cross-machine sync of curated .harnery/ subset (identities, archived " +
+        "scratchpads, council manifests) via rclone. Google Drive is the " +
+        "expected remote; any rclone backend works.",
+    );
+
+  sync
+    .command("init")
+    .description(
+      "Pick the rclone remote to sync against. Run `rclone config` first " +
+        "if you haven't set up a remote yet (harnery doesn't wrap the OAuth " +
+        "flow; rclone's own config wizard handles that).",
+    )
+    .option("--remote <name>", "Use this rclone remote (skips the picker)")
+    .option("--prefix <path>", "Subpath under the remote root (default: harnery)", "harnery")
+    .action((opts: { remote?: string; prefix: string }) => {
+      if (!checkRclone(emit)) {
+        emit.setExitCode(1);
+        return;
+      }
+      const remotes = listRemotes();
+      if (remotes.length === 0) {
+        emit.error({
+          code: "no_remotes",
+          message: "rclone has no remotes configured",
+          hint: "Run `rclone config` to add one (Google Drive: choose `drive`).",
+        });
+        emit.setExitCode(1);
+        return;
+      }
+
+      let remote = opts.remote;
+      if (!remote) {
+        if (remotes.length === 1) {
+          remote = remotes[0];
+        } else {
+          emit.error({
+            code: "remote_required",
+            message: `multiple rclone remotes; pass --remote <name>; available: ${remotes.join(", ")}`,
+          });
+          emit.setExitCode(1);
+          return;
+        }
+      }
+      if (!remotes.includes(remote)) {
+        emit.error({
+          code: "unknown_remote",
+          message: `remote "${remote}" not in rclone config (have: ${remotes.join(", ")})`,
+        });
+        emit.setExitCode(1);
+        return;
+      }
+
+      saveConfig({ remote, prefix: opts.prefix });
+      emit.text(`recorded: remote=${remote}  prefix=${opts.prefix}`);
+      emit.text(`config: ${configPath()}`);
+    });
+
+  sync
+    .command("status")
+    .description("Diff local .harnery/ subset vs the remote (rclone check --one-way).")
+    .option("--dry-run", "Same as no-op for status; kept for symmetry with push/pull")
+    .option("--verbose", "Pass -v to rclone")
+    .action((opts: FilterOpts) => {
+      if (!checkRclone(emit)) {
+        emit.setExitCode(1);
+        return;
+      }
+      const cfg = ensureConfig(emit);
+      if (!cfg) {
+        emit.setExitCode(1);
+        return;
+      }
+      const hDir = findHarneryDir();
+      if (!hDir) {
+        emit.error({ code: "no_harnery", message: "no .harnery/ found above cwd" });
+        emit.setExitCode(1);
+        return;
+      }
+      const { local, remote } = buildRcloneArgs(cfg, hDir, "push");
+      const args = ["check", local, remote, "--one-way", ...syncIncludeFlags()];
+      if (opts.verbose) args.push("-v");
+      const r = spawnSync("rclone", args, { stdio: "inherit" });
+      emit.setExitCode(r.status ?? 1);
+    });
+
+  sync
+    .command("push")
+    .description("Push local .harnery/ subset to the remote (rclone copy).")
+    .option("--dry-run", "Pass --dry-run to rclone")
+    .option("--verbose", "Pass -v to rclone")
+    .action((opts: FilterOpts) => {
+      if (!checkRclone(emit)) {
+        emit.setExitCode(1);
+        return;
+      }
+      const cfg = ensureConfig(emit);
+      if (!cfg) {
+        emit.setExitCode(1);
+        return;
+      }
+      const hDir = findHarneryDir();
+      if (!hDir) {
+        emit.error({ code: "no_harnery", message: "no .harnery/ found above cwd" });
+        emit.setExitCode(1);
+        return;
+      }
+      const { local, remote } = buildRcloneArgs(cfg, hDir, "push");
+      const args = ["copy", local, remote, ...syncIncludeFlags()];
+      if (opts.dryRun) args.push("--dry-run");
+      if (opts.verbose) args.push("-v");
+      const r = spawnSync("rclone", args, { stdio: "inherit" });
+      emit.setExitCode(r.status ?? 1);
+    });
+
+  sync
+    .command("pull")
+    .description("Pull the remote subset down into local .harnery/ (rclone copy).")
+    .option("--dry-run", "Pass --dry-run to rclone")
+    .option("--verbose", "Pass -v to rclone")
+    .action((opts: FilterOpts) => {
+      if (!checkRclone(emit)) {
+        emit.setExitCode(1);
+        return;
+      }
+      const cfg = ensureConfig(emit);
+      if (!cfg) {
+        emit.setExitCode(1);
+        return;
+      }
+      const hDir = findHarneryDir();
+      if (!hDir) {
+        emit.error({ code: "no_harnery", message: "no .harnery/ found above cwd" });
+        emit.setExitCode(1);
+        return;
+      }
+      const { local, remote } = buildRcloneArgs(cfg, hDir, "pull");
+      const args = ["copy", remote, local, ...syncIncludeFlags()];
+      if (opts.dryRun) args.push("--dry-run");
+      if (opts.verbose) args.push("-v");
+      const r = spawnSync("rclone", args, { stdio: "inherit" });
+      emit.setExitCode(r.status ?? 1);
+    });
+
+  sync
+    .command("list")
+    .description("List what's currently in the remote (rclone lsf).")
+    .option("--depth <n>", "Max recursion depth", "4")
+    .action((opts: { depth: string }) => {
+      if (!checkRclone(emit)) {
+        emit.setExitCode(1);
+        return;
+      }
+      const cfg = ensureConfig(emit);
+      if (!cfg) {
+        emit.setExitCode(1);
+        return;
+      }
+      const remote = `${cfg.remote}:${cfg.prefix}`;
+      const r = spawnSync("rclone", ["lsf", remote, "-R", "--max-depth", opts.depth], {
+        stdio: "inherit",
+      });
+      emit.setExitCode(r.status ?? 1);
+    });
+}

package/src/commands/toc.ts

@@ -0,0 +1,218 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import { resolveBinName } from "../core/config.ts";
+
+/**
+ * `harn toc <file.md>`: markdown header outline (level + text + line number).
+ * `harn section <file.md> <header>`: extract one section by header substring.
+ *
+ * Companion to `harn outline` for code files. Both let you navigate long docs
+ * without reading the whole thing.
+ */
+
+interface TocOpts {
+  json?: boolean;
+  depth?: string;
+  withSizes?: boolean;
+}
+
+interface SectionOpts {
+  json?: boolean;
+  caseSensitive?: boolean;
+}
+
+interface Header {
+  level: number;
+  text: string;
+  line: number;
+  size_lines?: number;
+}
+
+interface TocResult {
+  file: string;
+  total_lines: number;
+  headers: Header[];
+}
+
+interface SectionResult {
+  file: string;
+  matched_header: string;
+  matched_level: number;
+  line_start: number;
+  line_end: number;
+  content: string;
+}
+
+export function registerTocCommand(program: Command, emit: EmitContext): void {
+  program
+    .command("toc <file>")
+    .description("Print the markdown header outline (level + text + line number).")
+    .option("--json", "Structured JSON envelope")
+    .option("-d, --depth <n>", "Maximum header depth (1-6)")
+    .option("--with-sizes", "Include line count per section")
+    .action(async (file: string, opts: TocOpts) => {
+      try {
+        const result = await runToc(file, opts);
+        if (opts.json) {
+          emit.config({ format: "json" });
+          emit.data(result);
+          return;
+        }
+        emit.text(`${renderToc(result)}\n`);
+      } catch (err) {
+        emit.error({ code: "toc_failed", message: (err as Error).message });
+        process.exit(1);
+      }
+    });
+}
+
+export function registerSectionCommand(program: Command, emit: EmitContext): void {
+  program
+    .command("section <file> <header...>")
+    .description(
+      "Extract one section from a markdown file by header substring (case-insensitive by default). " +
+        "Joins multi-word args into one query string.",
+    )
+    .option(
+      "--json",
+      "Structured JSON envelope: {file, matched_header, line_start, line_end, content}",
+    )
+    .option("--case-sensitive", "Case-sensitive header match")
+    .action(async (file: string, header: string[], opts: SectionOpts) => {
+      try {
+        const result = await runSection(file, header.join(" "), opts);
+        if (opts.json) {
+          emit.config({ format: "json" });
+          emit.data(result);
+          return;
+        }
+        emit.text(`${result.content}\n`);
+      } catch (err) {
+        emit.error({ code: "section_failed", message: (err as Error).message });
+        process.exit(1);
+      }
+    });
+}
+
+async function runToc(file: string, opts: TocOpts): Promise<TocResult> {
+  const absPath = resolve(file);
+  if (!existsSync(absPath)) throw new Error(`no such file: ${file}`);
+  const content = readFileSync(absPath, "utf8");
+  const lines = content.split("\n");
+  const maxDepth = opts.depth ? Number.parseInt(opts.depth, 10) : 6;
+  if (!Number.isFinite(maxDepth) || maxDepth < 1 || maxDepth > 6) {
+    throw new Error(`--depth must be 1-6 (got ${opts.depth})`);
+  }
+
+  const headers: Header[] = [];
+  let inFence = false;
+  let fenceMarker = "";
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fenceMatch = line.match(/^(\s*)(`{3,}|~{3,})/);
+    if (fenceMatch) {
+      const marker = fenceMatch[2];
+      if (!inFence) {
+        inFence = true;
+        fenceMarker = marker[0];
+      } else if (marker[0] === fenceMarker) {
+        inFence = false;
+      }
+      continue;
+    }
+    if (inFence) continue;
+
+    const headerMatch = line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);
+    if (headerMatch) {
+      const level = headerMatch[1].length;
+      if (level > maxDepth) continue;
+      headers.push({
+        level,
+        text: headerMatch[2],
+        line: i + 1,
+      });
+    }
+  }
+
+  if (opts.withSizes) {
+    for (let i = 0; i < headers.length; i++) {
+      const nextLine = i + 1 < headers.length ? headers[i + 1].line : lines.length + 1;
+      headers[i].size_lines = nextLine - headers[i].line;
+    }
+  }
+
+  return {
+    file,
+    total_lines: lines.length,
+    headers,
+  };
+}
+
+function renderToc(r: TocResult): string {
+  const lines: string[] = [];
+  lines.push(
+    `toc · ${r.file} (${r.headers.length} header${r.headers.length === 1 ? "" : "s"}, ${r.total_lines} lines)`,
+  );
+
+  if (r.headers.length === 0) {
+    lines.push("(no markdown headers found)");
+    return lines.join("\n");
+  }
+
+  lines.push("");
+  for (const h of r.headers) {
+    const indent = "  ".repeat(h.level - 1);
+    const lineMark = `L${h.line}`.padEnd(6);
+    const size = h.size_lines !== undefined ? `  (${h.size_lines}L)` : "";
+    lines.push(`  ${lineMark}${indent}${"#".repeat(h.level)} ${h.text}${size}`);
+  }
+  return lines.join("\n");
+}
+
+async function runSection(file: string, query: string, opts: SectionOpts): Promise<SectionResult> {
+  if (!query.trim()) throw new Error("header query required");
+  const tocResult = await runToc(file, {});
+  const absPath = resolve(file);
+  const lines = readFileSync(absPath, "utf8").split("\n");
+
+  const matches = tocResult.headers.filter((h) =>
+    opts.caseSensitive
+      ? h.text.includes(query)
+      : h.text.toLowerCase().includes(query.toLowerCase()),
+  );
+  if (matches.length === 0) {
+    throw new Error(
+      `no header matching "${query}". Run \`${resolveBinName()} toc ${file}\` to list available headers.`,
+    );
+  }
+  if (matches.length > 1) {
+    const list = matches.map((h) => `  L${h.line}  ${"#".repeat(h.level)} ${h.text}`).join("\n");
+    throw new Error(
+      `multiple headers match "${query}":\n${list}\n\nRefine the query or use exact text.`,
+    );
+  }
+
+  const matched = matches[0];
+  const idx = tocResult.headers.findIndex((h) => h.line === matched.line);
+  let endLine = lines.length;
+  for (let i = idx + 1; i < tocResult.headers.length; i++) {
+    if (tocResult.headers[i].level <= matched.level) {
+      endLine = tocResult.headers[i].line - 1;
+      break;
+    }
+  }
+
+  const content = lines.slice(matched.line - 1, endLine).join("\n");
+
+  return {
+    file,
+    matched_header: matched.text,
+    matched_level: matched.level,
+    line_start: matched.line,
+    line_end: endLine,
+    content,
+  };
+}