harnery 0.0.1 → 0.2.0

package/package.json

@@ -1,13 +1,165 @@
 {
   "name": "harnery",
-  "version": "0.0.1",
-  "description": "Multi-agent coordination + harness adapters for Claude Code / Cursor / Codex — full release coming soon. https://harnery.com",
-  "main": "index.js",
+  "version": "0.2.0",
+  "description": "Multi-agent coordination + harness adapters + portable CLI utilities for Claude Code / Cursor / Codex.",
+  "license": "MIT",
+  "author": "Ryan Kelly",
+  "homepage": "https://harnery.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryanjkelly/harnery.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ryanjkelly/harnery/issues"
+  },
+  "keywords": [
+    "cli",
+    "multi-agent",
+    "coordination",
+    "claude-code",
+    "cursor",
+    "codex",
+    "agent-hooks",
+    "developer-tools"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "//exports": "Each entry resolves to TS source under Bun (zero-build dev + an embedding host) and to the built dist/ on Node/npm. The `bun` condition must stay first.",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./commander": {
+      "bun": "./src/commander.ts",
+      "types": "./dist/commander.d.ts",
+      "import": "./dist/commander.js"
+    },
+    "./core/agents": {
+      "bun": "./src/core/agents/index.ts",
+      "types": "./dist/core/agents/index.d.ts",
+      "import": "./dist/core/agents/index.js"
+    },
+    "./core/agents/session-events": {
+      "bun": "./src/core/agents/session-events.ts",
+      "types": "./dist/core/agents/session-events.d.ts",
+      "import": "./dist/core/agents/session-events.js"
+    },
+    "./core/hooks": {
+      "bun": "./src/core/hooks/index.ts",
+      "types": "./dist/core/hooks/index.d.ts",
+      "import": "./dist/core/hooks/index.js"
+    },
+    "./lib/agent-browser": {
+      "bun": "./src/lib/agent-browser/index.ts",
+      "types": "./dist/lib/agent-browser/index.d.ts",
+      "import": "./dist/lib/agent-browser/index.js"
+    },
+    "./lib/browser": {
+      "bun": "./src/lib/browser/index.ts",
+      "types": "./dist/lib/browser/index.d.ts",
+      "import": "./dist/lib/browser/index.js"
+    },
+    "./lib/cookies": {
+      "bun": "./src/lib/cookies/index.ts",
+      "types": "./dist/lib/cookies/index.d.ts",
+      "import": "./dist/lib/cookies/index.js"
+    },
+    "./lib/format": {
+      "bun": "./src/lib/format.ts",
+      "types": "./dist/lib/format.d.ts",
+      "import": "./dist/lib/format.js"
+    },
+    "./lib/http": {
+      "bun": "./src/lib/http/index.ts",
+      "types": "./dist/lib/http/index.d.ts",
+      "import": "./dist/lib/http/index.js"
+    },
+    "./lib/machine": {
+      "bun": "./src/lib/machine.ts",
+      "types": "./dist/lib/machine.d.ts",
+      "import": "./dist/lib/machine.js"
+    },
+    "./lib/readability": {
+      "bun": "./src/lib/readability/index.ts",
+      "types": "./dist/lib/readability/index.d.ts",
+      "import": "./dist/lib/readability/index.js"
+    },
+    "./lib/scratch": {
+      "bun": "./src/lib/scratch/index.ts",
+      "types": "./dist/lib/scratch/index.d.ts",
+      "import": "./dist/lib/scratch/index.js"
+    },
+    "./lib/tunnel/state": {
+      "bun": "./src/lib/tunnel/state.ts",
+      "types": "./dist/lib/tunnel/state.d.ts",
+      "import": "./dist/lib/tunnel/state.js"
+    }
+  },
+  "bin": {
+    "harn": "./bin/harn",
+    "agent-coord": "./bin/agent-coord",
+    "agent-hook": "./bin/agent-hook"
+  },
+  "//files": "src ships as TS so the `bun` export condition resolves to source; negate co-located tests so they don't ride into the tarball (a .npmignore is inert for paths already inside the files allowlist).",
+  "files": [
+    "bin",
+    "src",
+    "dist",
+    "schemas",
+    "README.md",
+    "LICENSE",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "packageManager": "bun@1.3.3",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsc -p tsconfig.build.json && node scripts/rewrite-dts-extensions.mjs",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "typecheck": "bun x tsc --noEmit",
+    "lint": "bun x @biomejs/biome check src",
+    "format": "bun x @biomejs/biome format --write src",
+    "test": "bun test src tests",
+    "test:web": "cd web && bun install && bun test",
+    "test:integration": "bash tests/integration/run.sh",
+    "docs:dev": "bun --cwd docs run dev",
+    "docs:build": "bun --cwd docs run build",
+    "brand:showcase": "node scripts/build-brand-showcase.mjs"
+  },
+  "dependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "commander": "^15.0.0",
+    "gpt-tokenizer": "^3.4.0",
+    "js-yaml": "^4.1.1",
+    "jsdom": "^29.0.2",
+    "mailparser": "^3.9.8",
+    "pixelmatch": "^7.2.0",
+    "playwright": "^1.59.1",
+    "pngjs": "^7.0.0",
+    "turndown": "^7.2.4",
+    "turndown-plugin-gfm": "^1.0.2"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "type": "commonjs"
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.0",
+    "@changesets/cli": "^2.27.0",
+    "@types/bun": "^1.2.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/jsdom": "^28.0.1",
+    "@types/mailparser": "^3.4.6",
+    "@types/node": "^26.0.0",
+    "@types/pixelmatch": "^5.2.6",
+    "@types/pngjs": "^6.0.5",
+    "@types/turndown": "^5.0.6",
+    "typescript": "^6.0.0"
+  }
 }

package/schemas/config.schema.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harnery.com/schemas/config.schema.json",
+  "title": "harnery configuration",
+  "description": "Settings file format for harnery. Lives at ~/.config/harnery/config.jsonc (user-global) or <project-root>/.harnery/config.jsonc (project). Project values override user values.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "URL of this schema. Included so editors provide autocomplete + validation."
+    },
+    "project_name": {
+      "type": "string",
+      "description": "Project identity surfaced to peers and in log lines. Defaults to the basename of the monorepo root."
+    },
+    "binName": {
+      "type": "string",
+      "default": "harn",
+      "description": "Host CLI bin name used in agent-facing strings (council prompts, end-of-turn nudges, command help). The coord binaries + web UI run as harnery and read this back since they can't see a consumer CLI's name. Stamped by `harn init` for a consumer. Resolution: HARNERY_BIN env -> this field -> 'harn'."
+    },
+    "coord": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "freshness_seconds": {
+          "type": "integer",
+          "minimum": 30,
+          "default": 600,
+          "description": "How stale a peer heartbeat can get before the sweeper prunes it."
+        },
+        "name_pool": {
+          "type": "string",
+          "default": "default",
+          "description": "Which agent-name pool to draw from. 'default' / 'hurricane' / a custom pool id."
+        }
+      }
+    },
+    "web": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "port": {
+          "type": "integer",
+          "minimum": 1024,
+          "maximum": 65535,
+          "default": 7777,
+          "description": "Port that `harn web up` binds to."
+        },
+        "bind": {
+          "type": "string",
+          "default": "127.0.0.1",
+          "description": "Bind address. Default localhost-only. Override with --bind 0.0.0.0 + gated IP allowlist to expose."
+        }
+      }
+    },
+    "files": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Universal file viewer (web dashboard) path-serving policy. The shipped secret denylist is a baked-in, non-removable floor in code; these knobs are ADDITIVE ONLY (they extend the floor, never replace or shrink it).",
+      "properties": {
+        "deny_globs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "Extra deny patterns on top of the shipped floor. Must be `**/`-anchored; supported shapes are `**/SEG` and `**/SEG/**` where SEG may use `*` and one `{a,b}` alternation. Matched case-insensitively against the canonical repo-relative path. Operator-added denies are treated as hard tier (never overridable). An entry that fails to compile disables the file viewer entirely (fail-closed) until fixed."
+        },
+        "allow_overrides": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "Rescue globs consulted ONLY when a deny came from a soft-tier floor pattern (the deliberately over-broad nets like `**/.env.*` or `**/*secret*.json`). Hard-tier matches (credentials, key/cert files, `.ssh`/`.aws`/`.gnupg`, SA-key/oauth/token JSON, `.git`) are never overridable; an override that names a hard family is loudly dropped at config load."
+        }
+      }
+    },
+    "backup": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "repo": {
+          "type": "string",
+          "description": "restic repository URL. Common: 'rclone:gdrive:harnery-backup/<project>' for Google Drive."
+        },
+        "schedule": {
+          "type": "string",
+          "enum": ["off", "daily", "hourly"],
+          "default": "off",
+          "description": "Auto-snapshot cadence. 'off' = manual only."
+        }
+      }
+    },
+    "sync": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Enable cross-machine sync via Google Drive."
+        },
+        "drive_folder": {
+          "type": "string",
+          "default": "harnery-sync",
+          "description": "Folder name in Google Drive that holds the synced subset."
+        }
+      }
+    }
+  }
+}

package/src/cli.ts

@@ -0,0 +1,22 @@
+/**
+ * `harn` CLI entry point.
+ *
+ * Parses argv, runs the Commander program returned by createHarneryProgram().
+ * Consumer CLIs import createHarneryProgram() from `harnery/commander` and
+ * compose their own commands on top. See examples/extending-with-commander.ts.
+ */
+
+import { createHarneryProgram } from "./commander.ts";
+
+async function main(): Promise<void> {
+  const program = createHarneryProgram({
+    binName: "harn",
+  });
+
+  await program.parseAsync(process.argv);
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/src/commander.ts

@@ -0,0 +1,242 @@
+/**
+ * `createHarneryProgram` is the composition point.
+ *
+ * harn (this package's CLI) calls this with `binName: 'harn'`.
+ * Consumer CLIs call this with their own binName, then `.addCommand()`
+ * their domain-specific subcommands and `parseAsync()`.
+ *
+ * The returned Commander program is harnery's full command tree. Adding
+ * a command with the same name on the consumer side overrides it, which is
+ * useful for project-specific overlays but uncommon.
+ *
+ * Future commands wire in via `registerXxxCommand(program)` calls below.
+ * Each subdirectory under src/commands/ exports its `register…` function
+ * (Commander pattern).
+ */
+
+import { Command } from "commander";
+import { registerAgentsCommand } from "./commands/agents.ts";
+import { registerBackupCommand } from "./commands/backup.ts";
+import { registerBrowseCommand } from "./commands/browse.ts";
+import { registerBrowseAiCommand } from "./commands/browse-ai.ts";
+import { registerCallersCommand } from "./commands/callers.ts";
+import { registerCompletionCommand } from "./commands/completion.ts";
+import { registerConfigGetCommand } from "./commands/config-get.ts";
+import { registerContextCommand } from "./commands/context.ts";
+import { registerCookiesCommand } from "./commands/cookies.ts";
+import { registerDocsCommand } from "./commands/docs.ts";
+import { registerDoctorCommand } from "./commands/doctor.ts";
+import { registerEditBatchCommand } from "./commands/edit-batch.ts";
+import { registerEmlCommand } from "./commands/eml.ts";
+import { registerEnvCommand } from "./commands/env.ts";
+import { registerFetchCommand } from "./commands/fetch.ts";
+import { registerFileHistoryCommand } from "./commands/file-history.ts";
+import { registerGrepCommand } from "./commands/grep.ts";
+import { registerInitCommand } from "./commands/init.ts";
+import { registerOutlineCommand } from "./commands/outline.ts";
+import { registerPresenceCommand } from "./commands/presence.ts";
+import { registerReadCommand } from "./commands/read.ts";
+import { registerScratchCommand } from "./commands/scratch.ts";
+import { registerSessionCommand } from "./commands/session.ts";
+import { registerSyncCommand } from "./commands/sync.ts";
+import { registerSectionCommand, registerTocCommand } from "./commands/toc.ts";
+import { registerTokensCommand } from "./commands/tokens.ts";
+import { registerTunnelCommand } from "./commands/tunnel.ts";
+import { registerUninstallCommand } from "./commands/uninstall.ts";
+import { registerWebCommand } from "./commands/web.ts";
+
+export interface HarneryContextOpts {
+  /**
+   * The binary name shown in --help output. Defaults to "harn". Consumer
+   * CLIs pass their own, e.g. `binName: "mycli"`.
+   */
+  binName?: string;
+
+  /**
+   * Project-scoped context. Commands that touch state (.harnery/agents/,
+   * .harnery/config.jsonc) consult this to resolve paths + project identity.
+   * Optional: harn standalone runs without it.
+   */
+  context?: HarneryProgramContext;
+
+  /**
+   * Adapter that lets consumers route structured emissions into their own
+   * OutputContext (e.g. an AsyncLocalStorage-bound writer). When omitted,
+   * harn standalone falls back to a default JSON-to-stdout emitter (see
+   * `defaultEmit` below).
+   */
+  emit?: EmitContext;
+
+  /**
+   * Top-level command names harnery should NOT register. Use when a
+   * consumer wants to replace harnery's implementation with its own
+   * (Commander throws on duplicate registration). Example: the host CLI has
+   * a project-specific `harn web` (docker stack shim) and passes
+   * `skipCommands: ["web"]` so harnery's generic `web` doesn't collide.
+   */
+  skipCommands?: readonly string[];
+}
+
+export interface HarneryProgramContext {
+  /** Project name (e.g., "my-monorepo"). Used in user-facing log lines + telemetry tags. */
+  projectName?: string;
+  /** Override the monorepo-root resolver. Default: walk up looking for `.harnery/`. */
+  resolveCoordRoot?: () => string | null;
+  /**
+   * Absolute path to the monorepo root. Commands like `env` use this as the
+   * default `cwd` for `git` invocations. When omitted, commands fall back to
+   * `process.cwd()`.
+   */
+  repoRoot?: string;
+  /**
+   * Submodule directory names relative to `repoRoot`. Consumed by `env` to
+   * report N/M initialized. When omitted, the `env` command skips the
+   * submodule row.
+   */
+  submodules?: readonly string[];
+  /**
+   * Optional callback that returns extra HTTP headers to attach to outbound
+   * `fetch` calls based on the target URL. Useful for consumers that need
+   * to inject auth or bypass headers on certain hostnames (e.g. private
+   * zones behind a WAF). harn standalone skips the callback entirely.
+   */
+  extraHeaders?: (url: string) => Record<string, string>;
+  /**
+   * Shell-completion provider-key lookup. Consumers wire this to a function
+   * mapping (commandPath, option/positional) to a provider key, so that
+   * `--workspace` / `--env` etc. tab-complete dynamically against
+   * consumer-specific data sources. harn standalone falls back to no-op
+   * (static completion only).
+   */
+  completionLookup?: (key: {
+    commandPath: string;
+    option?: string;
+    positional?: number;
+  }) => string | undefined;
+  /**
+   * Shell-completion provider runner. Invoked by the hidden `__complete`
+   * subcommand at tab-time to produce the actual list of completions for
+   * a given provider key.
+   */
+  completionRunner?: (key: string, partial: string) => Promise<string[]>;
+  /**
+   * Extra path prefixes that should be excluded from `harn docs lint`
+   * convention checks (auto-generated API reference dumps, vendored
+   * content directories, etc.). Combined with harnery's built-in
+   * exclusions (`.claude/`, `.harnery/`, `.codex/`, `.cursor/`).
+   */
+  extraDocsExcludedPrefixes?: readonly string[];
+  /**
+   * Default Host header for `tunnel up` when `--vhost` is omitted: a literal
+   * host, or a resolver evaluated at start time (e.g. read a dev stack's
+   * configured hostname so the tunnel lands on the right vhost). When unset, or
+   * the resolver returns null, the tunnel falls back to harnery's built-in
+   * default (`localhost`).
+   */
+  tunnelDefaultVhost?: string | (() => string | null | undefined);
+}
+
+/**
+ * Minimum emission surface harnery commands need to talk to a host CLI's
+ * OutputContext. Intentionally tiny: just the methods commands actually
+ * call. Designed to grow additively: consumers that want richer output
+ * routing implement these methods; everyone else gets `defaultEmit`'s
+ * JSON-to-stdout fallback.
+ */
+export interface EmitContext {
+  config(opts: { format?: string }): void;
+  data(payload: unknown): void;
+  rows(rows: Record<string, unknown>[]): void;
+  text(s: string): void;
+  file(path: string, summary: Record<string, unknown>): void;
+  error(err: { code: string; message: string; hint?: string } | Error | unknown): void;
+  log(msg: string, level?: "debug" | "info" | "warn" | "error"): void;
+  setExitCode(n: number): void;
+}
+
+export const defaultEmit: EmitContext = {
+  config() {
+    // No-op for harn standalone: there's only one format (JSON) and it's
+    // already the default. Consumer adapters route this to their own
+    // output-context configurator.
+  },
+  data(payload) {
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+  },
+  rows(rows) {
+    process.stdout.write(`${JSON.stringify(rows)}\n`);
+  },
+  text(s) {
+    process.stdout.write(s.endsWith("\n") ? s : `${s}\n`);
+  },
+  file(path, summary) {
+    process.stdout.write(`${JSON.stringify({ ok: true, file: path, ...summary })}\n`);
+  },
+  error(err) {
+    const payload =
+      err instanceof Error
+        ? { code: err.name || "error", message: err.message }
+        : typeof err === "object" && err !== null
+          ? err
+          : { code: "error", message: String(err) };
+    process.stderr.write(`${JSON.stringify({ error: payload })}\n`);
+    process.exitCode = 1;
+  },
+  log(msg, level = "info") {
+    process.stderr.write(`[${level}] ${msg}\n`);
+  },
+  setExitCode(n) {
+    process.exitCode = n;
+  },
+};
+
+export function createHarneryProgram(opts: HarneryContextOpts = {}): Command {
+  const program = new Command();
+  const emit = opts.emit ?? defaultEmit;
+  const skip = new Set(opts.skipCommands ?? []);
+  const include = (name: string) => !skip.has(name);
+
+  program
+    .name(opts.binName ?? "harn")
+    .description("Multi-agent coordination + harness adapters + portable CLI utilities.")
+    .version(readVersion());
+
+  registerTokensCommand(program, emit);
+  registerEmlCommand(program, emit);
+  registerEnvCommand(program, emit, opts.context);
+  registerPresenceCommand(program, emit);
+  registerConfigGetCommand(program, emit);
+  registerFileHistoryCommand(program, emit);
+  registerOutlineCommand(program, emit);
+  registerTocCommand(program, emit);
+  registerSectionCommand(program, emit);
+  registerCallersCommand(program, emit, opts.context);
+  registerEditBatchCommand(program, emit);
+  registerGrepCommand(program, emit, opts.context);
+  registerCookiesCommand(program, emit);
+  registerFetchCommand(program, emit, opts.context);
+  registerReadCommand(program, emit);
+  registerBrowseCommand(program, emit, opts.context);
+  registerBrowseAiCommand(program, emit);
+  registerSessionCommand(program, emit);
+  registerCompletionCommand(program, emit, opts.context);
+  registerContextCommand(program, emit, opts.context);
+  registerScratchCommand(program, emit);
+  registerTunnelCommand(program, emit, opts.context);
+  registerDocsCommand(program, emit, opts.context);
+  registerAgentsCommand(program, emit);
+  registerDoctorCommand(program, emit);
+  registerInitCommand(program, emit, opts.binName);
+  registerUninstallCommand(program, emit);
+  registerBackupCommand(program, emit);
+  registerSyncCommand(program, emit);
+  if (include("web")) registerWebCommand(program, emit);
+
+  return program;
+}
+
+function readVersion(): string {
+  // Static for the empty scaffold. Will be replaced by a build-time substitution
+  // (or a JSON import) once we have any command shipping.
+  return "0.1.0";
+}