harnery 0.2.1 → 0.3.0

package/dist/commander.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commander.d.ts","sourceRoot":"","sources":["../src/commander.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+BpC,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAEhC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IAEnB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,KAAK,MAAM,GAAG,SAAS,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACvE;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACjE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACxC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3D,KAAK,CAAC,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,GAAG,OAAO,GAAG,IAAI,CAAC;IACrF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IACpE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,eAAO,MAAM,WAAW,EAAE,WAkCzB,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,kBAAuB,GAAG,OAAO,CA2C3E"}
+{"version":3,"file":"commander.d.ts","sourceRoot":"","sources":["../src/commander.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+BpC,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAEhC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IAEnB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,KAAK,MAAM,GAAG,SAAS,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACvE;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACjE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACxC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3D,KAAK,CAAC,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,GAAG,OAAO,GAAG,IAAI,CAAC;IACrF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IACpE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,eAAO,MAAM,WAAW,EAAE,WAkCzB,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,kBAAuB,GAAG,OAAO,CA2C3E"}

package/dist/commander.js

@@ -13,6 +13,9 @@
  * Each subdirectory under src/commands/ exports its `register…` function
  * (Commander pattern).
  */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { registerAgentsCommand } from "./commands/agents.js";
 import { registerBackupCommand } from "./commands/backup.js";
@@ -120,7 +123,29 @@ export function createHarneryProgram(opts = {}) {
     return program;
 }
 function readVersion() {
-    // 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";
+    // Resolve package.json by walking up from this module. Works under Bun (this
+    // file runs from src/) and Node (from dist/): package.json sits at the
+    // package root above both. Falls back to "0.0.0" if it can't be found rather
+    // than crashing `--version`.
+    try {
+        let dir = dirname(fileURLToPath(import.meta.url));
+        for (let i = 0; i < 6; i++) {
+            try {
+                const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+                if (pkg.name === "harnery" && typeof pkg.version === "string")
+                    return pkg.version;
+            }
+            catch {
+                // no package.json at this level, or not ours; keep walking up
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch {
+        // import.meta.url unavailable or fs error; fall through
+    }
+    return "0.0.0";
 }

package/dist/commands/web-fetch.d.ts

@@ -0,0 +1,10 @@
+import type { EmitContext } from "../commander.js";
+/** bun if available (preferred), else npm. Both support `<runner> install` and `<runner> run <script>`. */
+export declare function webRunner(): "bun" | "npm";
+/**
+ * Ensure a cached harnery checkout's `web/` exists for this version and return
+ * its path, fetching (clone + install) on first use. Returns null on failure
+ * (after emitting an actionable error).
+ */
+export declare function lazyFetchWebRoot(emit: EmitContext): string | null;
+//# sourceMappingURL=web-fetch.d.ts.map

package/dist/commands/web-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-fetch.d.ts","sourceRoot":"","sources":["../../src/commands/web-fetch.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAiDnD,2GAA2G;AAC3G,wBAAgB,SAAS,IAAI,KAAK,GAAG,KAAK,CAGzC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAmDjE"}

package/dist/commands/web-fetch.js

@@ -0,0 +1,100 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Lazy-fetch of the web dashboard for npm consumers.
+ *
+ * The published npm package ships the CLI + coord engine but deliberately
+ * excludes `web/` (ADR 0001/0003: keep the core lean for CLI-only users). The
+ * dashboard also imports harnery's `src/` directly (see `web/next.config.ts`),
+ * so it can't be lifted out as a standalone folder. Instead, the first time
+ * `harn web up` runs from an install without a local `web/`, we clone the
+ * harnery repo at the *matching version tag* into a cache dir and install the
+ * web app's deps. Subsequent runs reuse the cache.
+ *
+ * The only thing `web/` pulls from `src/` is `harnery/lib/scratch` (a single,
+ * dependency-free module), so the install is `web/` deps only: no root install,
+ * no Playwright browser download.
+ */
+const DEFAULT_REPO_URL = "https://github.com/ryanjkelly/harnery.git";
+/** harnery's own package root: src/commands/ -> ../.. ; valid in both src/ and dist/. */
+function packageRoot() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, "..", "..");
+}
+function readPkg() {
+    try {
+        const pkg = JSON.parse(readFileSync(path.join(packageRoot(), "package.json"), "utf8"));
+        const raw = typeof pkg.repository === "string" ? pkg.repository : (pkg.repository?.url ?? "");
+        const repoUrl = raw.replace(/^git\+/, "") || DEFAULT_REPO_URL;
+        return { version: typeof pkg.version === "string" ? pkg.version : "0.0.0", repoUrl };
+    }
+    catch {
+        return { version: "0.0.0", repoUrl: DEFAULT_REPO_URL };
+    }
+}
+/** The git ref to fetch: HARNERY_WEB_REF override, else the version tag (`v<version>`). */
+function resolveRef(version) {
+    return process.env.HARNERY_WEB_REF || `v${version}`;
+}
+/** Per-ref cache dir under the XDG cache (matches harnery's `~/.cache/harnery/...`). */
+function webCacheRoot(ref) {
+    const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+    const safeRef = ref.replace(/[^\w.-]/g, "_");
+    return path.join(base, "harnery", "web", safeRef);
+}
+/** bun if available (preferred), else npm. Both support `<runner> install` and `<runner> run <script>`. */
+export function webRunner() {
+    const r = spawnSync("bun", ["--version"], { stdio: "ignore" });
+    return r.status === 0 ? "bun" : "npm";
+}
+/**
+ * Ensure a cached harnery checkout's `web/` exists for this version and return
+ * its path, fetching (clone + install) on first use. Returns null on failure
+ * (after emitting an actionable error).
+ */
+export function lazyFetchWebRoot(emit) {
+    const { version, repoUrl } = readPkg();
+    const ref = resolveRef(version);
+    const cacheRoot = webCacheRoot(ref);
+    const webDir = path.join(cacheRoot, "web");
+    // node_modules in the cached web/ is the "fetched + installed" marker.
+    if (existsSync(path.join(webDir, "node_modules"))) {
+        emit.log(`harn web · using cached dashboard (${ref})`, "info");
+        return webDir;
+    }
+    emit.log(`harn web · dashboard is not bundled in the npm package; fetching harnery ${ref} (one-time)`, "info");
+    emit.log(`           into ${cacheRoot}  ·  clone + web/ deps; pass --no-fetch to skip`, "info");
+    // Clear any partial/stale state so a retry is clean.
+    if (existsSync(cacheRoot))
+        rmSync(cacheRoot, { recursive: true, force: true });
+    mkdirSync(path.dirname(cacheRoot), { recursive: true });
+    const clone = spawnSync("git", ["clone", "--depth", "1", "--branch", ref, repoUrl, cacheRoot], {
+        stdio: "inherit",
+    });
+    if (clone.status !== 0) {
+        emit.error({
+            code: "web_fetch_failed",
+            message: `git clone of ${repoUrl} @ ${ref} failed${clone.error ? `: ${clone.error.message}` : ` (status ${clone.status})`}`,
+            hint: "Fetching the dashboard needs git + network. Do it manually: " +
+                `git clone ${repoUrl} && cd harnery/web && ${webRunner()} install, then run it pointed at your project via HARNERY_COORD_ROOT. ` +
+                "See https://harnery.com/cli/web/.",
+        });
+        return null;
+    }
+    const runner = webRunner();
+    emit.log(`harn web · installing dashboard deps (${runner} install in web/)`, "info");
+    const install = spawnSync(runner, ["install"], { cwd: webDir, stdio: "inherit" });
+    if (install.status !== 0) {
+        emit.error({
+            code: "web_fetch_failed",
+            message: `${runner} install in ${webDir} failed (status ${install.status})`,
+            hint: `Try manually: cd ${webDir} && ${runner} install`,
+        });
+        return null;
+    }
+    emit.log(`harn web · dashboard ready (cached at ${webDir})`, "info");
+    return webDir;
+}

package/dist/commands/web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/commands/web.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAsDnD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAqI5E"}
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/commands/web.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAwDnD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAwI5E"}

package/dist/commands/web.js

@@ -2,6 +2,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { lazyFetchWebRoot, webRunner } from "./web-fetch.js";
 /**
  * `harn web`: Next.js dashboard for harnery's coord state.
  *
@@ -15,6 +16,9 @@ import { fileURLToPath } from "node:url";
  * passing cwd here lets the dashboard show the right project regardless
  * of where the user invokes `harn web up` from.
  *
+ * The dashboard is not bundled in the npm package (ADR 0001/0003), so on an
+ * npm install `resolveWebRoot` lazy-fetches it on first use (see web-fetch.ts).
+ *
  * Localhost-only by default. Network exposure is intentionally out of
  * scope for v1.
  */
@@ -23,25 +27,25 @@ function webRoot() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     return path.resolve(here, "..", "..", "web");
 }
-function checkWebPresent(emit) {
-    const root = webRoot();
-    if (!existsSync(path.join(root, "package.json"))) {
-        emit.error({
-            code: "web_missing",
-            message: `harnery/web/ not found at ${root}`,
-            hint: "The dashboard ships with the harnery git repo, not the npm package (which is the CLI + " +
-                "coord engine only). Clone https://github.com/ryanjkelly/harnery, run `bun install`, then " +
-                "`harn web up --coord-root <your-project>` (or run it from inside that project). " +
-                "See https://harnery.com/cli/web/.",
-        });
-        return null;
-    }
-    return root;
-}
-function runner() {
-    // Prefer bun when available; fall back to npx/npm for plain Node installs.
-    const r = spawnSync("bun", ["--version"], { stdio: "ignore" });
-    return r.status === 0 ? "bun" : "npx";
+/**
+ * Resolve the web app root. A local `web/` (source checkout / submodule) wins.
+ * Otherwise, on an npm install, lazy-fetch it (clone + install) unless the
+ * caller passed --no-fetch, in which case emit the honest manual hint.
+ */
+function resolveWebRoot(emit, allowFetch) {
+    const local = webRoot();
+    if (existsSync(path.join(local, "package.json")))
+        return local;
+    if (allowFetch)
+        return lazyFetchWebRoot(emit);
+    emit.error({
+        code: "web_missing",
+        message: `harnery/web/ not found at ${local}`,
+        hint: "The dashboard is not bundled in the npm package. Re-run without --no-fetch to fetch it " +
+            "automatically, or clone https://github.com/ryanjkelly/harnery and run it from there. " +
+            "See https://harnery.com/cli/web/.",
+    });
+    return null;
 }
 export function registerWebCommand(program, emit) {
     const web = program
@@ -54,8 +58,9 @@ export function registerWebCommand(program, emit) {
         .option("-p, --port <port>", "Listen port", "9000")
         .option("--coord-root <dir>", "Override the coord root (default: cwd; web walks up looking for .harnery/)")
         .option("--prod", "Use next start instead of next dev (requires prior build)")
+        .option("--no-fetch", "Don't auto-fetch the dashboard if it's missing (npm installs)")
         .action(async (opts) => {
-        const root = checkWebPresent(emit);
+        const root = resolveWebRoot(emit, opts.fetch !== false);
         if (!root) {
             process.exitCode = 1;
             return;
@@ -77,7 +82,7 @@ export function registerWebCommand(program, emit) {
         }
         emit.log(`harn web · http://localhost:${port} (${mode})`, "info");
         emit.log(`reading .harnery/ from: ${coordRoot}`, "info");
-        const child = spawn(runner(), ["run", mode], {
+        const child = spawn(webRunner(), ["run", mode], {
             cwd: root,
             env: {
                 ...process.env,
@@ -105,14 +110,15 @@ export function registerWebCommand(program, emit) {
     web
         .command("build")
         .description("Build the production bundle (next build).")
-        .action(() => {
-        const root = checkWebPresent(emit);
+        .option("--no-fetch", "Don't auto-fetch the dashboard if it's missing (npm installs)")
+        .action((opts) => {
+        const root = resolveWebRoot(emit, opts.fetch !== false);
         if (!root) {
             process.exitCode = 1;
             return;
         }
         emit.log("running next build…", "info");
-        const r = spawnSync(runner(), ["run", "build"], {
+        const r = spawnSync(webRunner(), ["run", "build"], {
             cwd: root,
             stdio: "inherit",
         });
@@ -123,8 +129,9 @@ export function registerWebCommand(program, emit) {
         .description("Start the production server (next start). Requires prior `harn web build`.")
         .option("-p, --port <port>", "Listen port", "9000")
         .option("--coord-root <dir>", "Override the coord root")
+        .option("--no-fetch", "Don't auto-fetch the dashboard if it's missing (npm installs)")
         .action((opts) => {
-        const root = checkWebPresent(emit);
+        const root = resolveWebRoot(emit, opts.fetch !== false);
         if (!root) {
             process.exitCode = 1;
             return;
@@ -143,7 +150,7 @@ export function registerWebCommand(program, emit) {
         const port = String(opts.port);
         emit.log(`harn web · http://localhost:${port} (start)`, "info");
         emit.log(`reading .harnery/ from: ${coordRoot}`, "info");
-        const child = spawn(runner(), ["run", "start"], {
+        const child = spawn(webRunner(), ["run", "start"], {
             cwd: root,
             env: {
                 ...process.env,

package/dist/lib/readability/client.d.ts

@@ -4,12 +4,14 @@
  *
  * The library backing the `read` command.
  *
- * jsdom, @mozilla/readability, and turndown are heavy and (jsdom's tree)
- * ESM-fragile, so they are loaded lazily inside `htmlToMarkdown` rather than
- * at module top level. A static import would pull them into CLI startup (every
- * command is registered eagerly), and jsdom's transitive `html-encoding-sniffer`
- * crashes a plain `node` process via ERR_REQUIRE_ESM. Lazy-loading keeps the
- * CLI booting for users who never touch `read`/`browse`.
+ * linkedom, @mozilla/readability, and turndown are heavy, so they are loaded
+ * lazily inside `htmlToMarkdown` rather than at module top level. A static
+ * import would pull them into CLI startup (every command is registered
+ * eagerly). linkedom replaced jsdom here: jsdom's transitive dependency tree
+ * (`html-encoding-sniffer`, `whatwg-url`) does a CommonJS `require()` of the
+ * ESM-only `@exodus/bytes`, which crashes a plain `node` process via
+ * ERR_REQUIRE_ESM. linkedom is a lighter, CJS-friendly DOM with no such chain.
+ * See ADR 0002.
  */
 export interface ReadabilityOptions {
     /** Base URL for resolving relative links. Default `http://local/`. */

package/dist/lib/readability/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/readability/client.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAID;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CA8D5B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/readability/client.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAID;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CAwE5B"}

package/dist/lib/readability/client.js

@@ -10,14 +10,23 @@ export async function htmlToMarkdown(html, opts = {}) {
     if (!html.trim()) {
         throw new Error("Empty HTML input");
     }
-    const [{ Readability }, { JSDOM }, { default: TurndownService }, { tables }] = await Promise.all([
+    const [{ Readability }, { parseHTML }, { default: TurndownService }, { tables }] = await Promise.all([
         import("@mozilla/readability"),
-        import("jsdom"),
+        import("linkedom"),
         import("turndown"),
         import("turndown-plugin-gfm"),
     ]);
-    const dom = new JSDOM(html, { url: opts.url ?? "http://local/" });
-    const doc = dom.window.document;
+    // jsdom took a `url` option to set the document base so Readability resolves
+    // relative links to absolute. linkedom's parseHTML has no such option, so we
+    // inject a <base> tag, which sets doc.baseURI to the same effect. Only when
+    // the HTML doesn't already carry its own <base>.
+    const baseUrl = opts.url ?? "http://local/";
+    const htmlWithBase = /<base\b/i.test(html)
+        ? html
+        : html.replace(/<head\b[^>]*>/i, (m) => `${m}<base href="${baseUrl}">`);
+    // If there's no <head> to anchor the <base> into, fall back to the raw HTML
+    // (relative links stay relative, matching a document with no base).
+    const { document: doc } = parseHTML(htmlWithBase.includes("<base") ? htmlWithBase : html);
     preprocessDom(doc);
     let contentHtml;
     let title = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Multi-agent coordination + harness adapters + portable CLI utilities for Claude Code / Cursor / Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",
@@ -132,6 +132,7 @@
     "test": "bun test src tests",
     "test:web": "cd web && bun install && bun test",
     "test:integration": "bash tests/integration/run.sh",
+    "smoke": "node scripts/smoke-test.mjs",
     "docs:dev": "bun --cwd docs run dev",
     "docs:build": "bun --cwd docs run build",
     "brand:showcase": "node scripts/build-brand-showcase.mjs"
@@ -141,7 +142,7 @@
     "commander": "^15.0.0",
     "gpt-tokenizer": "^3.4.0",
     "js-yaml": "^4.1.1",
-    "jsdom": "^29.0.2",
+    "linkedom": "^0.18.0",
     "mailparser": "^3.9.8",
     "pixelmatch": "^7.2.0",
     "playwright": "^1.59.1",
@@ -154,7 +155,6 @@
     "@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",

package/src/commander.ts

@@ -14,6 +14,9 @@
  * (Commander pattern).
  */
 
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { registerAgentsCommand } from "./commands/agents.ts";
 import { registerBackupCommand } from "./commands/backup.ts";
@@ -236,7 +239,25 @@ export function createHarneryProgram(opts: HarneryContextOpts = {}): Command {
 }
 
 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";
+  // Resolve package.json by walking up from this module. Works under Bun (this
+  // file runs from src/) and Node (from dist/): package.json sits at the
+  // package root above both. Falls back to "0.0.0" if it can't be found rather
+  // than crashing `--version`.
+  try {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i++) {
+      try {
+        const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        if (pkg.name === "harnery" && typeof pkg.version === "string") return pkg.version;
+      } catch {
+        // no package.json at this level, or not ours; keep walking up
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+    // import.meta.url unavailable or fs error; fall through
+  }
+  return "0.0.0";
 }

package/src/commands/web-fetch.ts

@@ -0,0 +1,117 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { EmitContext } from "../commander.ts";
+
+/**
+ * Lazy-fetch of the web dashboard for npm consumers.
+ *
+ * The published npm package ships the CLI + coord engine but deliberately
+ * excludes `web/` (ADR 0001/0003: keep the core lean for CLI-only users). The
+ * dashboard also imports harnery's `src/` directly (see `web/next.config.ts`),
+ * so it can't be lifted out as a standalone folder. Instead, the first time
+ * `harn web up` runs from an install without a local `web/`, we clone the
+ * harnery repo at the *matching version tag* into a cache dir and install the
+ * web app's deps. Subsequent runs reuse the cache.
+ *
+ * The only thing `web/` pulls from `src/` is `harnery/lib/scratch` (a single,
+ * dependency-free module), so the install is `web/` deps only: no root install,
+ * no Playwright browser download.
+ */
+
+const DEFAULT_REPO_URL = "https://github.com/ryanjkelly/harnery.git";
+
+/** harnery's own package root: src/commands/ -> ../.. ; valid in both src/ and dist/. */
+function packageRoot(): string {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, "..", "..");
+}
+
+function readPkg(): { version: string; repoUrl: string } {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(packageRoot(), "package.json"), "utf8"));
+    const raw = typeof pkg.repository === "string" ? pkg.repository : (pkg.repository?.url ?? "");
+    const repoUrl = raw.replace(/^git\+/, "") || DEFAULT_REPO_URL;
+    return { version: typeof pkg.version === "string" ? pkg.version : "0.0.0", repoUrl };
+  } catch {
+    return { version: "0.0.0", repoUrl: DEFAULT_REPO_URL };
+  }
+}
+
+/** The git ref to fetch: HARNERY_WEB_REF override, else the version tag (`v<version>`). */
+function resolveRef(version: string): string {
+  return process.env.HARNERY_WEB_REF || `v${version}`;
+}
+
+/** Per-ref cache dir under the XDG cache (matches harnery's `~/.cache/harnery/...`). */
+function webCacheRoot(ref: string): string {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+  const safeRef = ref.replace(/[^\w.-]/g, "_");
+  return path.join(base, "harnery", "web", safeRef);
+}
+
+/** bun if available (preferred), else npm. Both support `<runner> install` and `<runner> run <script>`. */
+export function webRunner(): "bun" | "npm" {
+  const r = spawnSync("bun", ["--version"], { stdio: "ignore" });
+  return r.status === 0 ? "bun" : "npm";
+}
+
+/**
+ * Ensure a cached harnery checkout's `web/` exists for this version and return
+ * its path, fetching (clone + install) on first use. Returns null on failure
+ * (after emitting an actionable error).
+ */
+export function lazyFetchWebRoot(emit: EmitContext): string | null {
+  const { version, repoUrl } = readPkg();
+  const ref = resolveRef(version);
+  const cacheRoot = webCacheRoot(ref);
+  const webDir = path.join(cacheRoot, "web");
+
+  // node_modules in the cached web/ is the "fetched + installed" marker.
+  if (existsSync(path.join(webDir, "node_modules"))) {
+    emit.log(`harn web · using cached dashboard (${ref})`, "info");
+    return webDir;
+  }
+
+  emit.log(
+    `harn web · dashboard is not bundled in the npm package; fetching harnery ${ref} (one-time)`,
+    "info",
+  );
+  emit.log(`           into ${cacheRoot}  ·  clone + web/ deps; pass --no-fetch to skip`, "info");
+
+  // Clear any partial/stale state so a retry is clean.
+  if (existsSync(cacheRoot)) rmSync(cacheRoot, { recursive: true, force: true });
+  mkdirSync(path.dirname(cacheRoot), { recursive: true });
+
+  const clone = spawnSync("git", ["clone", "--depth", "1", "--branch", ref, repoUrl, cacheRoot], {
+    stdio: "inherit",
+  });
+  if (clone.status !== 0) {
+    emit.error({
+      code: "web_fetch_failed",
+      message: `git clone of ${repoUrl} @ ${ref} failed${clone.error ? `: ${clone.error.message}` : ` (status ${clone.status})`}`,
+      hint:
+        "Fetching the dashboard needs git + network. Do it manually: " +
+        `git clone ${repoUrl} && cd harnery/web && ${webRunner()} install, then run it pointed at your project via HARNERY_COORD_ROOT. ` +
+        "See https://harnery.com/cli/web/.",
+    });
+    return null;
+  }
+
+  const runner = webRunner();
+  emit.log(`harn web · installing dashboard deps (${runner} install in web/)`, "info");
+  const install = spawnSync(runner, ["install"], { cwd: webDir, stdio: "inherit" });
+  if (install.status !== 0) {
+    emit.error({
+      code: "web_fetch_failed",
+      message: `${runner} install in ${webDir} failed (status ${install.status})`,
+      hint: `Try manually: cd ${webDir} && ${runner} install`,
+    });
+    return null;
+  }
+
+  emit.log(`harn web · dashboard ready (cached at ${webDir})`, "info");
+  return webDir;
+}

package/src/commands/web.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
+import { lazyFetchWebRoot, webRunner } from "./web-fetch.ts";
 
 /**
  * `harn web`: Next.js dashboard for harnery's coord state.
@@ -18,6 +19,9 @@ import type { EmitContext } from "../commander.ts";
  * passing cwd here lets the dashboard show the right project regardless
  * of where the user invokes `harn web up` from.
  *
+ * The dashboard is not bundled in the npm package (ADR 0001/0003), so on an
+ * npm install `resolveWebRoot` lazy-fetches it on first use (see web-fetch.ts).
+ *
  * Localhost-only by default. Network exposure is intentionally out of
  * scope for v1.
  */
@@ -28,33 +32,31 @@ function webRoot(): string {
   return path.resolve(here, "..", "..", "web");
 }
 
-function checkWebPresent(emit: EmitContext): string | null {
-  const root = webRoot();
-  if (!existsSync(path.join(root, "package.json"))) {
-    emit.error({
-      code: "web_missing",
-      message: `harnery/web/ not found at ${root}`,
-      hint:
-        "The dashboard ships with the harnery git repo, not the npm package (which is the CLI + " +
-        "coord engine only). Clone https://github.com/ryanjkelly/harnery, run `bun install`, then " +
-        "`harn web up --coord-root <your-project>` (or run it from inside that project). " +
-        "See https://harnery.com/cli/web/.",
-    });
-    return null;
-  }
-  return root;
-}
-
-function runner(): string {
-  // Prefer bun when available; fall back to npx/npm for plain Node installs.
-  const r = spawnSync("bun", ["--version"], { stdio: "ignore" });
-  return r.status === 0 ? "bun" : "npx";
+/**
+ * Resolve the web app root. A local `web/` (source checkout / submodule) wins.
+ * Otherwise, on an npm install, lazy-fetch it (clone + install) unless the
+ * caller passed --no-fetch, in which case emit the honest manual hint.
+ */
+function resolveWebRoot(emit: EmitContext, allowFetch: boolean): string | null {
+  const local = webRoot();
+  if (existsSync(path.join(local, "package.json"))) return local;
+  if (allowFetch) return lazyFetchWebRoot(emit);
+  emit.error({
+    code: "web_missing",
+    message: `harnery/web/ not found at ${local}`,
+    hint:
+      "The dashboard is not bundled in the npm package. Re-run without --no-fetch to fetch it " +
+      "automatically, or clone https://github.com/ryanjkelly/harnery and run it from there. " +
+      "See https://harnery.com/cli/web/.",
+  });
+  return null;
 }
 
 interface UpOpts {
   port: string;
   coordRoot?: string;
   prod?: boolean;
+  fetch?: boolean;
 }
 
 export function registerWebCommand(program: Command, emit: EmitContext): void {
@@ -74,8 +76,9 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
       "Override the coord root (default: cwd; web walks up looking for .harnery/)",
     )
     .option("--prod", "Use next start instead of next dev (requires prior build)")
+    .option("--no-fetch", "Don't auto-fetch the dashboard if it's missing (npm installs)")
     .action(async (opts: UpOpts) => {
-      const root = checkWebPresent(emit);
+      const root = resolveWebRoot(emit, opts.fetch !== false);
       if (!root) {
         process.exitCode = 1;
         return;
@@ -101,7 +104,7 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
       emit.log(`harn web · http://localhost:${port} (${mode})`, "info");
       emit.log(`reading .harnery/ from: ${coordRoot}`, "info");
 
-      const child = spawn(runner(), ["run", mode], {
+      const child = spawn(webRunner(), ["run", mode], {
         cwd: root,
         env: {
           ...process.env,
@@ -130,14 +133,15 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
   web
     .command("build")
     .description("Build the production bundle (next build).")
-    .action(() => {
-      const root = checkWebPresent(emit);
+    .option("--no-fetch", "Don't auto-fetch the dashboard if it's missing (npm installs)")
+    .action((opts: { fetch?: boolean }) => {
+      const root = resolveWebRoot(emit, opts.fetch !== false);
       if (!root) {
         process.exitCode = 1;
         return;
       }
       emit.log("running next build…", "info");
-      const r = spawnSync(runner(), ["run", "build"], {
+      const r = spawnSync(webRunner(), ["run", "build"], {
         cwd: root,
         stdio: "inherit",
       });
@@ -149,8 +153,9 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
     .description("Start the production server (next start). Requires prior `harn web build`.")
     .option("-p, --port <port>", "Listen port", "9000")
     .option("--coord-root <dir>", "Override the coord root")
-    .action((opts: { port: string; coordRoot?: string }) => {
-      const root = checkWebPresent(emit);
+    .option("--no-fetch", "Don't auto-fetch the dashboard if it's missing (npm installs)")
+    .action((opts: { port: string; coordRoot?: string; fetch?: boolean }) => {
+      const root = resolveWebRoot(emit, opts.fetch !== false);
       if (!root) {
         process.exitCode = 1;
         return;
@@ -170,7 +175,7 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
       emit.log(`harn web · http://localhost:${port} (start)`, "info");
       emit.log(`reading .harnery/ from: ${coordRoot}`, "info");
 
-      const child = spawn(runner(), ["run", "start"], {
+      const child = spawn(webRunner(), ["run", "start"], {
         cwd: root,
         env: {
           ...process.env,

package/src/lib/readability/client.ts

@@ -6,12 +6,14 @@
  *
  * The library backing the `read` command.
  *
- * jsdom, @mozilla/readability, and turndown are heavy and (jsdom's tree)
- * ESM-fragile, so they are loaded lazily inside `htmlToMarkdown` rather than
- * at module top level. A static import would pull them into CLI startup (every
- * command is registered eagerly), and jsdom's transitive `html-encoding-sniffer`
- * crashes a plain `node` process via ERR_REQUIRE_ESM. Lazy-loading keeps the
- * CLI booting for users who never touch `read`/`browse`.
+ * linkedom, @mozilla/readability, and turndown are heavy, so they are loaded
+ * lazily inside `htmlToMarkdown` rather than at module top level. A static
+ * import would pull them into CLI startup (every command is registered
+ * eagerly). linkedom replaced jsdom here: jsdom's transitive dependency tree
+ * (`html-encoding-sniffer`, `whatwg-url`) does a CommonJS `require()` of the
+ * ESM-only `@exodus/bytes`, which crashes a plain `node` process via
+ * ERR_REQUIRE_ESM. linkedom is a lighter, CJS-friendly DOM with no such chain.
+ * See ADR 0002.
  */
 
 export interface ReadabilityOptions {
@@ -50,15 +52,25 @@ export async function htmlToMarkdown(
     throw new Error("Empty HTML input");
   }
 
-  const [{ Readability }, { JSDOM }, { default: TurndownService }, { tables }] = await Promise.all([
-    import("@mozilla/readability"),
-    import("jsdom"),
-    import("turndown"),
-    import("turndown-plugin-gfm"),
-  ]);
+  const [{ Readability }, { parseHTML }, { default: TurndownService }, { tables }] =
+    await Promise.all([
+      import("@mozilla/readability"),
+      import("linkedom"),
+      import("turndown"),
+      import("turndown-plugin-gfm"),
+    ]);
 
-  const dom = new JSDOM(html, { url: opts.url ?? "http://local/" });
-  const doc = dom.window.document;
+  // jsdom took a `url` option to set the document base so Readability resolves
+  // relative links to absolute. linkedom's parseHTML has no such option, so we
+  // inject a <base> tag, which sets doc.baseURI to the same effect. Only when
+  // the HTML doesn't already carry its own <base>.
+  const baseUrl = opts.url ?? "http://local/";
+  const htmlWithBase = /<base\b/i.test(html)
+    ? html
+    : html.replace(/<head\b[^>]*>/i, (m) => `${m}<base href="${baseUrl}">`);
+  // If there's no <head> to anchor the <base> into, fall back to the raw HTML
+  // (relative links stay relative, matching a document with no base).
+  const { document: doc } = parseHTML(htmlWithBase.includes("<base") ? htmlWithBase : html);
   preprocessDom(doc);
 
   let contentHtml: string;