harnery 0.2.0 → 0.2.1

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

@@ -1 +1 @@
-{"version":3,"file":"outline.d.ts","sourceRoot":"","sources":["../../src/commands/outline.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAoCnD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAwBhF"}
+{"version":3,"file":"outline.d.ts","sourceRoot":"","sources":["../../src/commands/outline.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAqDnD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAwBhF"}

package/dist/commands/outline.js

@@ -1,7 +1,21 @@
 import { existsSync, readFileSync } from "node:fs";
 import { extname, resolve } from "node:path";
-import * as ts from "typescript";
 import { resolveBinName } from "../core/config.js";
+/**
+ * `typescript` is a devDependency, not a runtime dependency, so it is loaded
+ * lazily here and only when outlining a TS/JS file. A static top-level import
+ * would make the whole CLI fail to boot for an end user who installed harnery
+ * without dev deps (every command is registered at startup). PHP/Python
+ * outlines use regex and never touch this.
+ */
+async function loadTypeScript() {
+    try {
+        return (await import("typescript"));
+    }
+    catch {
+        throw new Error("outlining TS/JS files needs the `typescript` package; install it (npm i -D typescript) or use outline on PHP/Python files");
+    }
+}
 export function registerOutlineCommand(program, emit) {
     program
         .command("outline <file>")
@@ -37,7 +51,7 @@ async function runOutline(file, opts) {
     let parsed;
     if ([".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"].includes(ext)) {
         language = ext.slice(1);
-        parsed = outlineTypeScript(content, absPath, ext);
+        parsed = await outlineTypeScript(content, absPath, ext);
     }
     else if (ext === ".php") {
         language = "php";
@@ -64,7 +78,8 @@ async function runOutline(file, opts) {
         symbols: parsed.symbols,
     };
 }
-function outlineTypeScript(content, path, ext) {
+async function outlineTypeScript(content, path, ext) {
+    const ts = await loadTypeScript();
     const isTsx = ext === ".tsx" || ext === ".jsx";
     const scriptKind = isTsx ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
     const source = ts.createSourceFile(path, content, ts.ScriptTarget.Latest, true, scriptKind);
@@ -101,7 +116,7 @@ function outlineTypeScript(content, path, ext) {
             symbols.push({
                 kind: "function",
                 name: stmt.name.text,
-                signature: renderFnSig(stmt, content, source),
+                signature: renderFnSig(ts, stmt, content, source),
                 line: lineOf(stmt),
                 exported,
             });
@@ -117,7 +132,7 @@ function outlineTypeScript(content, path, ext) {
                     members.push({
                         kind: "method",
                         name: member.name.text || text(member.name),
-                        signature: renderFnSig(member, content, source),
+                        signature: renderFnSig(ts, member, content, source),
                         line: lineOf(member),
                     });
                 }
@@ -125,7 +140,7 @@ function outlineTypeScript(content, path, ext) {
                     members.push({
                         kind: "method",
                         name: "constructor",
-                        signature: renderFnSig(member, content, source),
+                        signature: renderFnSig(ts, member, content, source),
                         line: lineOf(member),
                     });
                 }
@@ -165,7 +180,7 @@ function outlineTypeScript(content, path, ext) {
                     members.push({
                         kind: "method",
                         name: member.name.text || text(member.name),
-                        signature: renderFnSig(member, content, source),
+                        signature: renderFnSig(ts, member, content, source),
                         line: lineOf(member),
                     });
                 }
@@ -216,7 +231,7 @@ function outlineTypeScript(content, path, ext) {
                     sig = `: ${text(decl.type)}`;
                 else if (decl.initializer &&
                     (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer))) {
-                    sig = renderFnSig(decl.initializer, content, source);
+                    sig = renderFnSig(ts, decl.initializer, content, source);
                 }
                 symbols.push({
                     kind,
@@ -260,7 +275,7 @@ function outlineTypeScript(content, path, ext) {
     }
     return { imports, symbols };
 }
-function renderFnSig(fn, content, source) {
+function renderFnSig(ts, fn, content, source) {
     const params = (fn.parameters || [])
         .map((p) => {
         const name = ts.isIdentifier(p.name)

package/dist/commands/read.js

@@ -17,9 +17,9 @@ export function registerReadCommand(program, emitParam) {
         .option("--selector <css>", "Use this CSS selector instead of Readability (fallback when extraction misses content)")
         .option("--raw", "Output cleaned HTML instead of markdown (debugging)")
         .option("--max-chars <n>", "Truncate output to N characters (0 = disable)", "100000")
-        .action((htmlFile, opts) => {
+        .action(async (htmlFile, opts) => {
         try {
-            runRead(htmlFile, opts);
+            await runRead(htmlFile, opts);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -28,9 +28,9 @@ export function registerReadCommand(program, emitParam) {
         }
     });
 }
-function runRead(htmlFile, opts) {
+async function runRead(htmlFile, opts) {
     const input = htmlFile && htmlFile !== "-" ? readFileSync(htmlFile, "utf-8") : readFileSync(0, "utf-8");
-    const result = htmlToMarkdown(input, {
+    const result = await htmlToMarkdown(input, {
         url: opts.url,
         selector: opts.selector,
         raw: opts.raw,

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

@@ -3,6 +3,13 @@
  * Turndown (HTML → markdown).
  *
  * 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`.
  */
 export interface ReadabilityOptions {
     /** Base URL for resolving relative links. Default `http://local/`. */
@@ -28,5 +35,5 @@ export interface ReadabilityResult {
  * Throws if input is empty, the selector matches nothing, or Readability
  * fails to find a main article (caller should retry with `selector`).
  */
-export declare function htmlToMarkdown(html: string, opts?: ReadabilityOptions): ReadabilityResult;
+export declare function htmlToMarkdown(html: string, opts?: ReadabilityOptions): Promise<ReadabilityResult>;
 //# sourceMappingURL=client.d.ts.map

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":"AAMA;;;;;GAKG;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,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,iBAAiB,CAuD7F"}
+{"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"}

package/dist/lib/readability/client.js

@@ -1,8 +1,4 @@
 /// <reference path="./turndown-plugin-gfm.d.ts" />
-import { Readability } from "@mozilla/readability";
-import { JSDOM } from "jsdom";
-import TurndownService from "turndown";
-import { tables } from "turndown-plugin-gfm";
 const DEFAULT_MAX_CHARS = 100_000;
 /**
  * Convert raw HTML to clean markdown.
@@ -10,10 +6,16 @@ const DEFAULT_MAX_CHARS = 100_000;
  * Throws if input is empty, the selector matches nothing, or Readability
  * fails to find a main article (caller should retry with `selector`).
  */
-export function htmlToMarkdown(html, opts = {}) {
+export async function htmlToMarkdown(html, opts = {}) {
     if (!html.trim()) {
         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 dom = new JSDOM(html, { url: opts.url ?? "http://local/" });
     const doc = dom.window.document;
     preprocessDom(doc);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Multi-agent coordination + harness adapters + portable CLI utilities for Claude Code / Cursor / Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",

package/src/commands/outline.ts

@@ -1,10 +1,27 @@
 import { existsSync, readFileSync } from "node:fs";
 import { extname, resolve } from "node:path";
 import type { Command } from "commander";
-import * as ts from "typescript";
+import type * as TS from "typescript";
 import type { EmitContext } from "../commander.ts";
 import { resolveBinName } from "../core/config.ts";
 
+/**
+ * `typescript` is a devDependency, not a runtime dependency, so it is loaded
+ * lazily here and only when outlining a TS/JS file. A static top-level import
+ * would make the whole CLI fail to boot for an end user who installed harnery
+ * without dev deps (every command is registered at startup). PHP/Python
+ * outlines use regex and never touch this.
+ */
+async function loadTypeScript(): Promise<typeof TS> {
+  try {
+    return (await import("typescript")) as unknown as typeof TS;
+  } catch {
+    throw new Error(
+      "outlining TS/JS files needs the `typescript` package; install it (npm i -D typescript) or use outline on PHP/Python files",
+    );
+  }
+}
+
 /**
  * `harn outline <file>`: print the structural skeleton of a code file (imports
  * + top-level decls + line numbers). TS/JS/TSX/JSX use the TypeScript compiler
@@ -77,7 +94,7 @@ async function runOutline(file: string, opts: OutlineOpts): Promise<OutlineResul
 
   if ([".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"].includes(ext)) {
     language = ext.slice(1);
-    parsed = outlineTypeScript(content, absPath, ext);
+    parsed = await outlineTypeScript(content, absPath, ext);
   } else if (ext === ".php") {
     language = "php";
     parsed = outlinePhp(content);
@@ -105,11 +122,12 @@ async function runOutline(file: string, opts: OutlineOpts): Promise<OutlineResul
   };
 }
 
-function outlineTypeScript(
+async function outlineTypeScript(
   content: string,
   path: string,
   ext: string,
-): { imports: string[]; symbols: SymbolEntry[] } {
+): Promise<{ imports: string[]; symbols: SymbolEntry[] }> {
+  const ts = await loadTypeScript();
   const isTsx = ext === ".tsx" || ext === ".jsx";
   const scriptKind = isTsx ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
   const source = ts.createSourceFile(path, content, ts.ScriptTarget.Latest, true, scriptKind);
@@ -117,18 +135,18 @@ function outlineTypeScript(
   const imports: string[] = [];
   const symbols: SymbolEntry[] = [];
 
-  const lineOf = (node: ts.Node) =>
+  const lineOf = (node: TS.Node) =>
     source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
-  const text = (node: ts.Node) =>
+  const text = (node: TS.Node) =>
     content.slice(node.getStart(source), node.getEnd()).replace(/\s+/g, " ").trim();
-  const isExported = (node: ts.Node): boolean => {
-    const mods = (node as { modifiers?: ReadonlyArray<ts.ModifierLike> }).modifiers;
+  const isExported = (node: TS.Node): boolean => {
+    const mods = (node as { modifiers?: ReadonlyArray<TS.ModifierLike> }).modifiers;
     return mods?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
   };
 
   for (const stmt of source.statements) {
     if (ts.isImportDeclaration(stmt)) {
-      const moduleSpec = (stmt.moduleSpecifier as ts.StringLiteral).text;
+      const moduleSpec = (stmt.moduleSpecifier as TS.StringLiteral).text;
       const clause = stmt.importClause;
       const isTypeOnly = clause?.isTypeOnly ? "type " : "";
       let what = "";
@@ -151,7 +169,7 @@ function outlineTypeScript(
       symbols.push({
         kind: "function",
         name: stmt.name.text,
-        signature: renderFnSig(stmt, content, source),
+        signature: renderFnSig(ts, stmt, content, source),
         line: lineOf(stmt),
         exported,
       });
@@ -168,21 +186,21 @@ function outlineTypeScript(
         if (ts.isMethodDeclaration(member) && member.name) {
           members.push({
             kind: "method",
-            name: (member.name as ts.Identifier).text || text(member.name),
-            signature: renderFnSig(member, content, source),
+            name: (member.name as TS.Identifier).text || text(member.name),
+            signature: renderFnSig(ts, member, content, source),
             line: lineOf(member),
           });
         } else if (ts.isConstructorDeclaration(member)) {
           members.push({
             kind: "method",
             name: "constructor",
-            signature: renderFnSig(member, content, source),
+            signature: renderFnSig(ts, member, content, source),
             line: lineOf(member),
           });
         } else if (ts.isPropertyDeclaration(member) && member.name) {
           members.push({
             kind: "property",
-            name: (member.name as ts.Identifier).text || text(member.name),
+            name: (member.name as TS.Identifier).text || text(member.name),
             signature: member.type ? `: ${text(member.type)}` : "",
             line: lineOf(member),
           });
@@ -205,15 +223,15 @@ function outlineTypeScript(
         if (ts.isPropertySignature(member) && member.name) {
           members.push({
             kind: "property",
-            name: (member.name as ts.Identifier).text || text(member.name),
+            name: (member.name as TS.Identifier).text || text(member.name),
             signature: member.type ? `: ${text(member.type)}` : "",
             line: lineOf(member),
           });
         } else if (ts.isMethodSignature(member) && member.name) {
           members.push({
             kind: "method",
-            name: (member.name as ts.Identifier).text || text(member.name),
-            signature: renderFnSig(member, content, source),
+            name: (member.name as TS.Identifier).text || text(member.name),
+            signature: renderFnSig(ts, member, content, source),
             line: lineOf(member),
           });
         }
@@ -243,7 +261,7 @@ function outlineTypeScript(
         exported,
         members: stmt.members.map((m) => ({
           kind: "enumMember",
-          name: (m.name as ts.Identifier).text || text(m.name),
+          name: (m.name as TS.Identifier).text || text(m.name),
           line: lineOf(m),
         })),
       });
@@ -261,7 +279,7 @@ function outlineTypeScript(
           decl.initializer &&
           (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer))
         ) {
-          sig = renderFnSig(decl.initializer, content, source);
+          sig = renderFnSig(ts, decl.initializer, content, source);
         }
         symbols.push({
           kind,
@@ -275,7 +293,7 @@ function outlineTypeScript(
       if (stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
         const names = stmt.exportClause.elements.map((e) => e.name.text).join(", ");
         const fromText = stmt.moduleSpecifier
-          ? ` from "${(stmt.moduleSpecifier as ts.StringLiteral).text}"`
+          ? ` from "${(stmt.moduleSpecifier as TS.StringLiteral).text}"`
           : "";
         symbols.push({
           kind: "re-export",
@@ -286,7 +304,7 @@ function outlineTypeScript(
       } else if (stmt.moduleSpecifier) {
         symbols.push({
           kind: "re-export",
-          name: `* from "${(stmt.moduleSpecifier as ts.StringLiteral).text}"`,
+          name: `* from "${(stmt.moduleSpecifier as TS.StringLiteral).text}"`,
           line: lineOf(stmt),
           exported: true,
         });
@@ -294,7 +312,7 @@ function outlineTypeScript(
     } else if (ts.isModuleDeclaration(stmt) && stmt.name) {
       symbols.push({
         kind: "namespace",
-        name: (stmt.name as ts.Identifier).text || text(stmt.name),
+        name: (stmt.name as TS.Identifier).text || text(stmt.name),
         line: lineOf(stmt),
         exported,
       });
@@ -305,9 +323,10 @@ function outlineTypeScript(
 }
 
 function renderFnSig(
-  fn: ts.FunctionLikeDeclarationBase | ts.MethodSignature,
+  ts: typeof TS,
+  fn: TS.FunctionLikeDeclarationBase | TS.MethodSignature,
   content: string,
-  source: ts.SourceFile,
+  source: TS.SourceFile,
 ): string {
   const params = (fn.parameters || [])
     .map((p) => {

package/src/commands/read.ts

@@ -26,9 +26,9 @@ export function registerReadCommand(program: Command, emitParam: EmitContext): v
     )
     .option("--raw", "Output cleaned HTML instead of markdown (debugging)")
     .option("--max-chars <n>", "Truncate output to N characters (0 = disable)", "100000")
-    .action((htmlFile: string | undefined, opts: ReadOpts) => {
+    .action(async (htmlFile: string | undefined, opts: ReadOpts) => {
       try {
-        runRead(htmlFile, opts);
+        await runRead(htmlFile, opts);
       } catch (err: unknown) {
         const msg = err instanceof Error ? err.message : String(err);
         emit.error({ code: "read_error", message: msg });
@@ -45,10 +45,10 @@ interface ReadOpts {
   maxChars: string;
 }
 
-function runRead(htmlFile: string | undefined, opts: ReadOpts): void {
+async function runRead(htmlFile: string | undefined, opts: ReadOpts): Promise<void> {
   const input =
     htmlFile && htmlFile !== "-" ? readFileSync(htmlFile, "utf-8") : readFileSync(0, "utf-8");
-  const result = htmlToMarkdown(input, {
+  const result = await htmlToMarkdown(input, {
     url: opts.url,
     selector: opts.selector,
     raw: opts.raw,

package/src/lib/readability/client.ts

@@ -1,14 +1,17 @@
 /// <reference path="./turndown-plugin-gfm.d.ts" />
-import { Readability } from "@mozilla/readability";
-import { JSDOM } from "jsdom";
-import TurndownService from "turndown";
-import { tables } from "turndown-plugin-gfm";
 
 /**
  * HTML → clean markdown via Readability (main-content extraction) +
  * Turndown (HTML → markdown).
  *
  * 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`.
  */
 
 export interface ReadabilityOptions {
@@ -39,11 +42,21 @@ const DEFAULT_MAX_CHARS = 100_000;
  * Throws if input is empty, the selector matches nothing, or Readability
  * fails to find a main article (caller should retry with `selector`).
  */
-export function htmlToMarkdown(html: string, opts: ReadabilityOptions = {}): ReadabilityResult {
+export async function htmlToMarkdown(
+  html: string,
+  opts: ReadabilityOptions = {},
+): Promise<ReadabilityResult> {
   if (!html.trim()) {
     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 dom = new JSDOM(html, { url: opts.url ?? "http://local/" });
   const doc = dom.window.document;
   preprocessDom(doc);