harnery 0.0.1 → 0.2.0

package/src/commands/backup.ts

@@ -0,0 +1,305 @@
+/**
+ * `harn backup`: restic-backed snapshots of `.harnery/`.
+ *
+ * Wraps `restic` with sensible defaults so single-user use doesn't require
+ * remembering env vars. Repo path + password file live under XDG-style
+ * paths and are init'd on first `harn backup init`. Subcommands:
+ *
+ *   init      restic init the repo (one-time)
+ *   snapshot  restic backup .harnery/
+ *   list      restic snapshots
+ *   restore   restic restore <id>
+ *   prune     restic forget --keep-daily 7 --keep-weekly 4 --prune
+ *
+ * Power users override via env vars (HARNERY_RESTIC_REPO, HARNERY_RESTIC_PASSWORD_FILE)
+ * or by passing through any restic args after `--`. The wrapper deliberately
+ * doesn't try to abstract restic; it surfaces it, with opinionated defaults plus
+ * passthrough.
+ */
+
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, 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";
+
+function defaultRepo(): string {
+  const home = os.homedir();
+  return process.env.HARNERY_RESTIC_REPO ?? path.join(home, ".cache", "harnery", "restic-repo");
+}
+
+function defaultPasswordFile(): string {
+  const home = os.homedir();
+  return (
+    process.env.HARNERY_RESTIC_PASSWORD_FILE ??
+    path.join(home, ".config", "harnery", "restic-password")
+  );
+}
+
+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 ensurePasswordFile(file: string): void {
+  if (existsSync(file)) return;
+  mkdirSync(path.dirname(file), { recursive: true });
+  const pw = randomBytes(24).toString("base64");
+  writeFileSync(file, `${pw}\n`, { encoding: "utf-8", mode: 0o600 });
+}
+
+interface RunOpts {
+  repo?: string;
+  passwordFile?: string;
+  passThrough?: string[];
+  stdio?: "inherit" | "pipe";
+}
+
+function runRestic(args: string[], opts: RunOpts = {}): { exitCode: number; stdout: string } {
+  const repo = opts.repo ?? defaultRepo();
+  const pwFile = opts.passwordFile ?? defaultPasswordFile();
+  const wantInherit = opts.stdio === "inherit";
+  const r = spawnSync("restic", [...args, ...(opts.passThrough ?? [])], {
+    env: {
+      ...process.env,
+      RESTIC_REPOSITORY: repo,
+      RESTIC_PASSWORD_FILE: pwFile,
+    },
+    encoding: "utf-8",
+    stdio: wantInherit ? "inherit" : "pipe",
+  });
+  return {
+    exitCode: r.status ?? 1,
+    stdout: wantInherit ? "" : (r.stdout ?? "") + (r.stderr ?? ""),
+  };
+}
+
+function checkRestic(emit: EmitContext): boolean {
+  const r = spawnSync("restic", ["version"], { encoding: "utf-8" });
+  if (r.status !== 0) {
+    emit.error({
+      code: "restic_missing",
+      message: "restic is not on PATH",
+      hint: "brew install restic (mac) / apt-get install restic (ubuntu) / https://restic.readthedocs.io/en/stable/020_installation.html",
+    });
+    return false;
+  }
+  return true;
+}
+
+interface BaseOpts {
+  repo?: string;
+  passwordFile?: string;
+  json?: boolean;
+}
+
+export function registerBackupCommand(program: Command, emit: EmitContext): void {
+  const backup = program
+    .command("backup")
+    .description("restic-backed snapshots of .harnery/ (multi-machine recovery insurance)");
+
+  // -- init --
+  backup
+    .command("init")
+    .description("Create the restic repository + password file (one-time).")
+    .option("--repo <path>", `Repository path (default: ${defaultRepo()})`)
+    .option(
+      "--password-file <path>",
+      `Password file (default: ${defaultPasswordFile()}, autogenerated)`,
+    )
+    .action((opts: BaseOpts) => {
+      if (!checkRestic(emit)) {
+        emit.setExitCode(1);
+        return;
+      }
+      const repo = opts.repo ?? defaultRepo();
+      const pwFile = opts.passwordFile ?? defaultPasswordFile();
+      ensurePasswordFile(pwFile);
+      mkdirSync(path.dirname(repo), { recursive: true });
+      const r = runRestic(["init"], { repo, passwordFile: pwFile, stdio: "inherit" });
+      if (r.exitCode === 0) {
+        emit.text(`restic repo initialized at ${repo}\npassword file: ${pwFile}`);
+      } else {
+        emit.setExitCode(r.exitCode);
+      }
+    });
+
+  // -- snapshot --
+  backup
+    .command("snapshot")
+    .description(
+      "Take a restic snapshot of .harnery/ (excluding events.ndjson and " +
+        ".lock files by default). Pass --target to back up a different path.",
+    )
+    .option("--target <path>", "Path to snapshot (default: .harnery/ from cwd walk-up)")
+    .option("--tag <tag>", "Restic tag (repeatable)", collect, [] as string[])
+    .option("--repo <path>", "Repository path")
+    .option("--password-file <path>", "Password file")
+    .option(
+      "--include-events",
+      "Don't exclude events.ndjson (default: excluded; large + machine-local)",
+    )
+    .action((opts: BaseOpts & { target?: string; tag: string[]; includeEvents?: boolean }) => {
+      if (!checkRestic(emit)) {
+        emit.setExitCode(1);
+        return;
+      }
+      const target = opts.target ?? findHarneryDir();
+      if (!target) {
+        emit.error({
+          code: "target_missing",
+          message:
+            "No .harnery/ found above cwd; pass --target explicitly or run from a monorepo with .harnery/",
+        });
+        emit.setExitCode(1);
+        return;
+      }
+      const passThrough: string[] = [];
+      if (!opts.includeEvents) {
+        passThrough.push("--exclude", "events.ndjson");
+        passThrough.push("--exclude", ".lock");
+        passThrough.push("--exclude", ".log.lock");
+      }
+      for (const t of opts.tag) {
+        passThrough.push("--tag", t);
+      }
+      const r = runRestic(["backup", target], {
+        repo: opts.repo,
+        passwordFile: opts.passwordFile,
+        stdio: "inherit",
+        passThrough,
+      });
+      emit.setExitCode(r.exitCode);
+    });
+
+  // -- list --
+  backup
+    .command("list")
+    .description("List snapshots in the repo.")
+    .option("--repo <path>", "Repository path")
+    .option("--password-file <path>", "Password file")
+    .option("--json", "JSON output")
+    .action((opts: BaseOpts) => {
+      if (!checkRestic(emit)) {
+        emit.setExitCode(1);
+        return;
+      }
+      const args = ["snapshots"];
+      if (opts.json) args.push("--json");
+      const r = runRestic(args, {
+        repo: opts.repo,
+        passwordFile: opts.passwordFile,
+        stdio: opts.json ? "pipe" : "inherit",
+      });
+      if (opts.json && r.exitCode === 0) {
+        try {
+          emit.data(JSON.parse(r.stdout));
+        } catch {
+          emit.text(r.stdout);
+        }
+      }
+      emit.setExitCode(r.exitCode);
+    });
+
+  // -- restore --
+  backup
+    .command("restore <snapshotId>")
+    .description("Restore a snapshot to a target directory (default: ./restore-<timestamp>).")
+    .option("--target <path>", "Restore destination")
+    .option("--repo <path>", "Repository path")
+    .option("--password-file <path>", "Password file")
+    .action((snapshotId: string, opts: BaseOpts & { target?: string }) => {
+      if (!checkRestic(emit)) {
+        emit.setExitCode(1);
+        return;
+      }
+      const target = opts.target ?? path.join(process.cwd(), `restore-${Date.now()}`);
+      mkdirSync(target, { recursive: true });
+      const r = runRestic(["restore", snapshotId, "--target", target], {
+        repo: opts.repo,
+        passwordFile: opts.passwordFile,
+        stdio: "inherit",
+      });
+      if (r.exitCode === 0) {
+        emit.text(`restored to: ${target}`);
+      }
+      emit.setExitCode(r.exitCode);
+    });
+
+  // -- prune --
+  backup
+    .command("prune")
+    .description("Forget + prune snapshots (default policy: keep 7 daily / 4 weekly / 6 monthly).")
+    .option("--keep-daily <n>", "Daily snapshots to keep", "7")
+    .option("--keep-weekly <n>", "Weekly snapshots to keep", "4")
+    .option("--keep-monthly <n>", "Monthly snapshots to keep", "6")
+    .option("--dry-run", "Show what would be pruned without actually pruning")
+    .option("--repo <path>", "Repository path")
+    .option("--password-file <path>", "Password file")
+    .action(
+      (
+        opts: BaseOpts & {
+          keepDaily: string;
+          keepWeekly: string;
+          keepMonthly: string;
+          dryRun?: boolean;
+        },
+      ) => {
+        if (!checkRestic(emit)) {
+          emit.setExitCode(1);
+          return;
+        }
+        const args = [
+          "forget",
+          "--keep-daily",
+          opts.keepDaily,
+          "--keep-weekly",
+          opts.keepWeekly,
+          "--keep-monthly",
+          opts.keepMonthly,
+        ];
+        if (!opts.dryRun) args.push("--prune");
+        else args.push("--dry-run");
+        const r = runRestic(args, {
+          repo: opts.repo,
+          passwordFile: opts.passwordFile,
+          stdio: "inherit",
+        });
+        emit.setExitCode(r.exitCode);
+      },
+    );
+
+  // -- check --
+  backup
+    .command("check")
+    .description("restic check: verify repo integrity")
+    .option("--repo <path>", "Repository path")
+    .option("--password-file <path>", "Password file")
+    .action((opts: BaseOpts) => {
+      if (!checkRestic(emit)) {
+        emit.setExitCode(1);
+        return;
+      }
+      const r = runRestic(["check"], {
+        repo: opts.repo,
+        passwordFile: opts.passwordFile,
+        stdio: "inherit",
+      });
+      emit.setExitCode(r.exitCode);
+    });
+}
+
+function collect(value: string, acc: string[]): string[] {
+  acc.push(value);
+  return acc;
+}

package/src/commands/browse-ai.ts

@@ -0,0 +1,198 @@
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import { AgentBrowser, type ExecResult } from "../lib/agent-browser/index.ts";
+import { CookieJar } from "../lib/cookies/index.ts";
+
+// Module-scoped emit assigned by registerBrowseAiCommand. Same pattern as
+// cookies/read/browse: helper functions close over `emit` so action
+// callbacks stay concise.
+let emit: EmitContext;
+
+/**
+ * `harn browse-ai <url>`: wraps Vercel Labs' agent-browser Rust CLI.
+ *
+ * Sister command to `harn browse` (which uses Playwright). Differences:
+ *
+ *   - **Output shape.** `agent-browser` returns an accessibility-tree
+ *     snapshot with element refs (`@e1`, `@e2`), purpose-built for LLM
+ *     consumption. `harn browse` returns DOM/HTML/innerText.
+ *   - **Process model.** `agent-browser` runs as a daemon: successive
+ *     calls reuse the same Chrome instance until something explicitly
+ *     closes it. `harn browse` opens + closes per call.
+ *   - **Auth model.** `harn browse-ai` doesn't have a `--login` flow; use
+ *     `harn browse --login` for one-time auth, then both tools share the
+ *     same cookie jar.
+ *
+ * Mirrors the agent-side `browse` wrapper (sandbox side) so a script written for one
+ * works on the other modulo path differences.
+ */
+
+const DEFAULT_STORE = resolve(homedir(), ".cache", "harnery", "cookies.json");
+
+interface BrowseAiOpts {
+  snapshot?: boolean;
+  interactive?: boolean;
+  screenshot?: string;
+  fullPage?: boolean;
+  annotate?: string;
+  click?: string;
+  fill?: string;
+  press?: string;
+  waitFor?: string;
+  evaluate?: string;
+  batch?: string;
+  networkHar?: string;
+  store?: string;
+  cookies?: boolean;
+  json?: boolean;
+  timeout: string;
+}
+
+export function registerBrowseAiCommand(program: Command, emitParam: EmitContext): void {
+  emit = emitParam;
+  program
+    .command("browse-ai <url>")
+    .description(
+      "agent-browser (Vercel Labs) wrapper: accessibility-tree snapshots with element refs (@e1, @e2) for LLM consumption. " +
+        "Daemon-mode: successive calls reuse the same browser instance. Sister to harn browse (Playwright).",
+    )
+    .option("--snapshot", "Print accessibility tree (default action when no other output flag)")
+    .option("-i, --interactive", "Snapshot interactive elements only (with --snapshot)")
+    .option("--screenshot <path>", "Save a screenshot to the given path")
+    .option("--no-full-page", "Capture only the viewport (with --screenshot)")
+    .option(
+      "--annotate <path>",
+      "Save an annotated screenshot with numbered labels (vision-model friendly)",
+    )
+    .option("--click <ref>", "Click an element ref (@e5) or CSS selector after open")
+    .option(
+      "--fill <ref=>value>",
+      "Fill input: '@e3=>hello' (separator is `=>` so attribute selectors don't collide)",
+    )
+    .option("--press <key>", "Press a key after open/fill (Enter, Tab, etc.)")
+    .option("--wait-for <selector|ms>", "Wait for selector OR a number of ms before output")
+    .option("--evaluate <js>", "Run JS in the page context (escape-hatch for power users)")
+    .option(
+      "--batch <commands>",
+      "Run multiple agent-browser steps in one session, semicolon-separated. " +
+        'E.g., --batch "click @e5; wait 1000; snapshot"',
+    )
+    .option("--network-har <path>", "Record a HAR file from open() through end of run")
+    .option("--no-cookies", "Skip cookie-jar attach and persist")
+    .option("--store <path>", `Cookie store path (default ${DEFAULT_STORE})`)
+    .option("--json", "Emit a JSON envelope (snapshot, screenshot path, step results)")
+    .option("--timeout <ms>", "Per-step timeout in ms", "60000")
+    .action((url: string, opts: BrowseAiOpts) => {
+      try {
+        runBrowseAi(url, opts);
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        emit.error({ code: "browse_ai_error", message: msg });
+        process.exit(1);
+      }
+    });
+}
+
+function runBrowseAi(url: string, opts: BrowseAiOpts): void {
+  const jar =
+    opts.cookies === false
+      ? null
+      : new CookieJar({ path: opts.store ?? DEFAULT_STORE, source: "bp-browse-ai" });
+  const ab = new AgentBrowser({
+    jar,
+    timeoutMs: Number.parseInt(opts.timeout, 10),
+  });
+
+  const stepLog: { step: string; ok: boolean; output: string }[] = [];
+
+  // 1. Open + optional HAR start.
+  if (opts.networkHar) ab.harStart(opts.networkHar);
+  ab.open(url);
+  stepLog.push({ step: `open ${url}`, ok: true, output: "" });
+
+  // 2. Pre-output actions, in the order they make sense for typical flows.
+  if (opts.fill) {
+    const sep = opts.fill.indexOf("=>");
+    if (sep < 0) {
+      throw new Error(
+        `--fill expects 'ref=>value' (got: ${opts.fill}). Separator is '=>' (not '=').`,
+      );
+    }
+    const ref = opts.fill.slice(0, sep);
+    const value = opts.fill.slice(sep + 2);
+    const r = ab.fill(ref, value);
+    stepLog.push({ step: `fill ${ref}`, ok: r.ok, output: r.stdout.trim() });
+  }
+  if (opts.click) {
+    const r = ab.click(opts.click);
+    stepLog.push({ step: `click ${opts.click}`, ok: r.ok, output: r.stdout.trim() });
+  }
+  if (opts.press) {
+    const r = ab.press(opts.press);
+    stepLog.push({ step: `press ${opts.press}`, ok: r.ok, output: r.stdout.trim() });
+  }
+  if (opts.waitFor) {
+    const r = ab.wait(opts.waitFor);
+    stepLog.push({ step: `wait ${opts.waitFor}`, ok: r.ok, output: r.stdout.trim() });
+  }
+  if (opts.batch) {
+    const steps = opts.batch
+      .split(";")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    const results = ab.batch(steps);
+    steps.forEach((step, i) => {
+      const r = results[i] as ExecResult | undefined;
+      stepLog.push({ step, ok: r?.ok ?? false, output: r?.stdout.trim() ?? "" });
+    });
+  }
+  if (opts.evaluate) {
+    const out = ab.evaluate(opts.evaluate);
+    stepLog.push({ step: "eval", ok: true, output: out });
+  }
+
+  // 3. Output capture.
+  let snapshot: string | null = null;
+  if (opts.snapshot || (!opts.screenshot && !opts.annotate && !opts.evaluate)) {
+    snapshot = ab.snapshot({ interactive: opts.interactive });
+  }
+
+  if (opts.screenshot) {
+    ab.screenshot(opts.screenshot, { full: opts.fullPage !== false });
+  }
+  if (opts.annotate) {
+    ab.screenshot(opts.annotate, { annotate: true });
+  }
+
+  if (opts.networkHar) ab.harStop(opts.networkHar);
+
+  // 4. Cookie sync back to jar.
+  const cookieStats = ab.syncCookiesToJar();
+
+  // 5. Output.
+  if (opts.json) {
+    const envelope: Record<string, unknown> = {
+      url,
+      steps: stepLog,
+      cookiesSaved: cookieStats.saved,
+    };
+    if (snapshot !== null) envelope.snapshot = snapshot;
+    if (opts.screenshot) envelope.screenshot = opts.screenshot;
+    if (opts.annotate) envelope.annotated = opts.annotate;
+    if (opts.networkHar) envelope.har = opts.networkHar;
+    emit.data(envelope);
+    return;
+  }
+
+  if (snapshot !== null) emit.text(snapshot);
+  if (opts.screenshot) emit.log(`screenshot: ${opts.screenshot}`, "info");
+  if (opts.annotate) emit.log(`annotated: ${opts.annotate}`, "info");
+  if (cookieStats.saved > 0) {
+    emit.log(
+      `saved ${cookieStats.saved} cookie${cookieStats.saved === 1 ? "" : "s"} to ${jar?.path}`,
+      "info",
+    );
+  }
+}