harnery 0.0.1 → 0.2.0

package/src/commands/outline.ts

@@ -0,0 +1,564 @@
+import { existsSync, readFileSync } from "node:fs";
+import { extname, resolve } from "node:path";
+import type { Command } from "commander";
+import * as ts from "typescript";
+import type { EmitContext } from "../commander.ts";
+import { resolveBinName } from "../core/config.ts";
+
+/**
+ * `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
+ * AST; PHP and Python use a regex pass. Token-efficient substitute for reading
+ * a whole large file just to find one symbol.
+ *
+ * For markdown files, dispatch to `harn toc`.
+ */
+
+interface OutlineOpts {
+  json?: boolean;
+  exportsOnly?: boolean;
+  imports?: boolean; // Commander sets to false on --no-imports
+  members?: boolean; // Commander sets to false on --no-members
+}
+
+interface SymbolEntry {
+  kind: string;
+  name: string;
+  signature?: string;
+  line: number;
+  exported?: boolean;
+  members?: SymbolEntry[];
+}
+
+interface OutlineResult {
+  file: string;
+  language: string;
+  total_lines: number;
+  imports: string[];
+  symbols: SymbolEntry[];
+}
+
+export function registerOutlineCommand(program: Command, emit: EmitContext): void {
+  program
+    .command("outline <file>")
+    .description(
+      `Print the structural skeleton of a code file (imports + top-level decls + line numbers). Supports TS/JS/TSX/JSX (AST), PHP/Python (regex). Use \`${resolveBinName()} toc\` for markdown.`,
+    )
+    .option("--json", "Structured JSON envelope")
+    .option("--exports-only", "Only show exported symbols")
+    .option("--no-imports", "Skip the imports summary block")
+    .option("--no-members", "Don't expand class/interface members")
+    .action(async (file: string, opts: OutlineOpts) => {
+      try {
+        const result = await runOutline(file, opts);
+        if (opts.json) {
+          emit.config({ format: "json" });
+          emit.data(result);
+          return;
+        }
+        emit.text(`${renderOutline(result, opts)}\n`);
+      } catch (err) {
+        emit.error({ code: "outline_failed", message: (err as Error).message });
+        process.exit(1);
+      }
+    });
+}
+
+async function runOutline(file: string, opts: OutlineOpts): Promise<OutlineResult> {
+  const absPath = resolve(file);
+  if (!existsSync(absPath)) throw new Error(`no such file: ${file}`);
+
+  const content = readFileSync(absPath, "utf8");
+  const total_lines = content.split("\n").length;
+  const ext = extname(absPath).toLowerCase();
+
+  let language = "";
+  let parsed: { imports: string[]; symbols: SymbolEntry[] };
+
+  if ([".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"].includes(ext)) {
+    language = ext.slice(1);
+    parsed = outlineTypeScript(content, absPath, ext);
+  } else if (ext === ".php") {
+    language = "php";
+    parsed = outlinePhp(content);
+  } else if (ext === ".py") {
+    language = "python";
+    parsed = outlinePython(content);
+  } else if ([".md", ".mdx"].includes(ext)) {
+    throw new Error(`use \`${resolveBinName()} toc ${file}\` for markdown files`);
+  } else {
+    throw new Error(
+      `unsupported file type: ${ext || "(no extension)"} (supported: ts/tsx/js/jsx/php/py)`,
+    );
+  }
+
+  if (opts.exportsOnly) {
+    parsed.symbols = parsed.symbols.filter((s) => s.exported);
+  }
+
+  return {
+    file,
+    language,
+    total_lines,
+    imports: parsed.imports,
+    symbols: parsed.symbols,
+  };
+}
+
+function outlineTypeScript(
+  content: string,
+  path: string,
+  ext: string,
+): { imports: string[]; symbols: SymbolEntry[] } {
+  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);
+
+  const imports: string[] = [];
+  const symbols: SymbolEntry[] = [];
+
+  const lineOf = (node: ts.Node) =>
+    source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+  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;
+    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 clause = stmt.importClause;
+      const isTypeOnly = clause?.isTypeOnly ? "type " : "";
+      let what = "";
+      if (clause?.name) what = clause.name.text;
+      if (clause?.namedBindings) {
+        if (ts.isNamespaceImport(clause.namedBindings)) {
+          what = `${what ? `${what}, ` : ""}* as ${clause.namedBindings.name.text}`;
+        } else {
+          const names = clause.namedBindings.elements.map((e) => e.name.text).join(", ");
+          what = `${what ? `${what}, ` : ""}{${names}}`;
+        }
+      }
+      imports.push(`${isTypeOnly}${what || "(side-effect)"} from "${moduleSpec}"`);
+      continue;
+    }
+
+    const exported = isExported(stmt);
+
+    if (ts.isFunctionDeclaration(stmt) && stmt.name) {
+      symbols.push({
+        kind: "function",
+        name: stmt.name.text,
+        signature: renderFnSig(stmt, content, source),
+        line: lineOf(stmt),
+        exported,
+      });
+    } else if (ts.isClassDeclaration(stmt) && stmt.name) {
+      const heritage = (stmt.heritageClauses || [])
+        .map(
+          (h) =>
+            (h.token === ts.SyntaxKind.ExtendsKeyword ? "extends " : "implements ") +
+            h.types.map((t) => text(t.expression)).join(", "),
+        )
+        .join(" ");
+      const members: SymbolEntry[] = [];
+      for (const member of stmt.members) {
+        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),
+            line: lineOf(member),
+          });
+        } else if (ts.isConstructorDeclaration(member)) {
+          members.push({
+            kind: "method",
+            name: "constructor",
+            signature: renderFnSig(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),
+            signature: member.type ? `: ${text(member.type)}` : "",
+            line: lineOf(member),
+          });
+        }
+      }
+      symbols.push({
+        kind: "class",
+        name: stmt.name.text,
+        signature: heritage,
+        line: lineOf(stmt),
+        exported,
+        members,
+      });
+    } else if (ts.isInterfaceDeclaration(stmt)) {
+      const heritage = (stmt.heritageClauses || [])
+        .flatMap((h) => h.types.map((t) => text(t.expression)))
+        .join(", ");
+      const members: SymbolEntry[] = [];
+      for (const member of stmt.members) {
+        if (ts.isPropertySignature(member) && member.name) {
+          members.push({
+            kind: "property",
+            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),
+            line: lineOf(member),
+          });
+        }
+      }
+      symbols.push({
+        kind: "interface",
+        name: stmt.name.text,
+        signature: heritage ? `extends ${heritage}` : "",
+        line: lineOf(stmt),
+        exported,
+        members,
+      });
+    } else if (ts.isTypeAliasDeclaration(stmt)) {
+      const sigText = text(stmt.type);
+      symbols.push({
+        kind: "type",
+        name: stmt.name.text,
+        signature: `= ${sigText.slice(0, 80)}${sigText.length > 80 ? "…" : ""}`,
+        line: lineOf(stmt),
+        exported,
+      });
+    } else if (ts.isEnumDeclaration(stmt)) {
+      symbols.push({
+        kind: "enum",
+        name: stmt.name.text,
+        line: lineOf(stmt),
+        exported,
+        members: stmt.members.map((m) => ({
+          kind: "enumMember",
+          name: (m.name as ts.Identifier).text || text(m.name),
+          line: lineOf(m),
+        })),
+      });
+    } else if (ts.isVariableStatement(stmt)) {
+      const flags = stmt.declarationList.flags;
+      const isConst = (flags & ts.NodeFlags.Const) !== 0;
+      const isLet = (flags & ts.NodeFlags.Let) !== 0;
+      const kind = isConst ? "const" : isLet ? "let" : "var";
+      const stmtExported = isExported(stmt);
+      for (const decl of stmt.declarationList.declarations) {
+        if (!ts.isIdentifier(decl.name)) continue;
+        let sig = "";
+        if (decl.type) sig = `: ${text(decl.type)}`;
+        else if (
+          decl.initializer &&
+          (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer))
+        ) {
+          sig = renderFnSig(decl.initializer, content, source);
+        }
+        symbols.push({
+          kind,
+          name: decl.name.text,
+          signature: sig,
+          line: lineOf(decl),
+          exported: stmtExported,
+        });
+      }
+    } else if (ts.isExportDeclaration(stmt)) {
+      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}"`
+          : "";
+        symbols.push({
+          kind: "re-export",
+          name: `{${names}}${fromText}`,
+          line: lineOf(stmt),
+          exported: true,
+        });
+      } else if (stmt.moduleSpecifier) {
+        symbols.push({
+          kind: "re-export",
+          name: `* from "${(stmt.moduleSpecifier as ts.StringLiteral).text}"`,
+          line: lineOf(stmt),
+          exported: true,
+        });
+      }
+    } else if (ts.isModuleDeclaration(stmt) && stmt.name) {
+      symbols.push({
+        kind: "namespace",
+        name: (stmt.name as ts.Identifier).text || text(stmt.name),
+        line: lineOf(stmt),
+        exported,
+      });
+    }
+  }
+
+  return { imports, symbols };
+}
+
+function renderFnSig(
+  fn: ts.FunctionLikeDeclarationBase | ts.MethodSignature,
+  content: string,
+  source: ts.SourceFile,
+): string {
+  const params = (fn.parameters || [])
+    .map((p) => {
+      const name = ts.isIdentifier(p.name)
+        ? p.name.text
+        : content.slice(p.name.getStart(source), p.name.getEnd());
+      const type = p.type
+        ? content.slice(p.type.getStart(source), p.type.getEnd()).replace(/\s+/g, " ").trim()
+        : "";
+      const optional = p.questionToken ? "?" : "";
+      return type ? `${name}${optional}: ${type}` : `${name}${optional}`;
+    })
+    .join(", ");
+  const ret = fn.type
+    ? `: ${content.slice(fn.type.getStart(source), fn.type.getEnd()).replace(/\s+/g, " ").trim()}`
+    : "";
+  return `(${params})${ret}`;
+}
+
+function outlinePhp(content: string): { imports: string[]; symbols: SymbolEntry[] } {
+  const lines = content.split("\n");
+  const imports: string[] = [];
+  const symbols: SymbolEntry[] = [];
+  let currentContainer: SymbolEntry | null = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNum = i + 1;
+    const trimmed = line.trim();
+    const isIndented = /^[ \t]/.test(line);
+
+    if (
+      trimmed === "" ||
+      trimmed.startsWith("//") ||
+      trimmed.startsWith("#") ||
+      trimmed.startsWith("*") ||
+      trimmed.startsWith("/*")
+    )
+      continue;
+
+    const nsMatch = trimmed.match(/^namespace\s+([\w\\]+)\s*;/);
+    if (nsMatch && !isIndented) {
+      symbols.push({ kind: "namespace", name: nsMatch[1], line: lineNum });
+      continue;
+    }
+    const useMatch = trimmed.match(/^use\s+([\w\\]+)(?:\s+as\s+(\w+))?\s*;/);
+    if (useMatch && !isIndented) {
+      imports.push(useMatch[2] ? `${useMatch[1]} as ${useMatch[2]}` : useMatch[1]);
+      continue;
+    }
+    if (!isIndented) {
+      const classMatch = trimmed.match(
+        /^(?:abstract\s+|final\s+)?class\s+(\w+)(?:\s+extends\s+(\w+))?(?:\s+implements\s+([\w,\s]+))?/,
+      );
+      if (classMatch) {
+        currentContainer = {
+          kind: "class",
+          name: classMatch[1],
+          signature: [
+            classMatch[2] ? `extends ${classMatch[2]}` : "",
+            classMatch[3] ? `implements ${classMatch[3].trim()}` : "",
+          ]
+            .filter(Boolean)
+            .join(" "),
+          line: lineNum,
+          members: [],
+        };
+        symbols.push(currentContainer);
+        continue;
+      }
+      const interfaceMatch = trimmed.match(/^interface\s+(\w+)/);
+      if (interfaceMatch) {
+        currentContainer = {
+          kind: "interface",
+          name: interfaceMatch[1],
+          line: lineNum,
+          members: [],
+        };
+        symbols.push(currentContainer);
+        continue;
+      }
+      const traitMatch = trimmed.match(/^trait\s+(\w+)/);
+      if (traitMatch) {
+        currentContainer = { kind: "trait", name: traitMatch[1], line: lineNum, members: [] };
+        symbols.push(currentContainer);
+        continue;
+      }
+    }
+    const fnMatch = trimmed.match(
+      /^(?:public\s+|private\s+|protected\s+)?(?:static\s+)?function\s+(\w+)\s*\(([^)]*)\)/,
+    );
+    if (fnMatch) {
+      const entry: SymbolEntry = {
+        kind: isIndented && currentContainer ? "method" : "function",
+        name: fnMatch[1],
+        signature: `(${fnMatch[2].trim()})`,
+        line: lineNum,
+      };
+      if (isIndented && currentContainer) {
+        currentContainer.members!.push(entry);
+      } else {
+        symbols.push(entry);
+      }
+    }
+  }
+
+  return { imports, symbols };
+}
+
+function outlinePython(content: string): { imports: string[]; symbols: SymbolEntry[] } {
+  const lines = content.split("\n");
+  const imports: string[] = [];
+  const symbols: SymbolEntry[] = [];
+  let currentClass: SymbolEntry | null = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNum = i + 1;
+    const trimmed = line.trim();
+    const indent = line.match(/^ */)![0].length;
+
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+
+    const importMatch = trimmed.match(/^import\s+(.+)$/);
+    const fromMatch = trimmed.match(/^from\s+(\S+)\s+import\s+(.+)$/);
+    if (importMatch && indent === 0) {
+      imports.push(importMatch[1]);
+      continue;
+    }
+    if (fromMatch && indent === 0) {
+      imports.push(`${fromMatch[2].trim()} from ${fromMatch[1]}`);
+      continue;
+    }
+
+    const classMatch = trimmed.match(/^class\s+(\w+)(?:\(([^)]*)\))?:/);
+    if (classMatch && indent === 0) {
+      currentClass = {
+        kind: "class",
+        name: classMatch[1],
+        signature: classMatch[2] ? `(${classMatch[2]})` : "",
+        line: lineNum,
+        members: [],
+      };
+      symbols.push(currentClass);
+      continue;
+    }
+
+    const methodMatch = trimmed.match(/^(?:async\s+)?def\s+(\w+)\s*\(([^)]*)\)/);
+    if (methodMatch) {
+      if (indent === 0) {
+        symbols.push({
+          kind: "function",
+          name: methodMatch[1],
+          signature: `(${methodMatch[2].trim()})`,
+          line: lineNum,
+        });
+        currentClass = null;
+      } else if (currentClass) {
+        currentClass.members!.push({
+          kind: "method",
+          name: methodMatch[1],
+          signature: `(${methodMatch[2].trim()})`,
+          line: lineNum,
+        });
+      }
+      continue;
+    }
+
+    if (indent === 0 && trimmed.length > 0 && currentClass) {
+      currentClass = null;
+    }
+  }
+
+  return { imports, symbols };
+}
+
+function renderOutline(r: OutlineResult, opts: OutlineOpts): string {
+  const lines: string[] = [];
+  const symbolCount = r.symbols.length;
+  lines.push(
+    `outline · ${r.file} (${r.language}, ${r.total_lines} lines, ${symbolCount} top-level symbol${symbolCount === 1 ? "" : "s"})`,
+  );
+
+  if (opts.imports !== false && r.imports.length > 0) {
+    lines.push("");
+    if (r.imports.length <= 4) {
+      lines.push(`imports: ${r.imports.join(" · ")}`);
+    } else {
+      lines.push(`imports (${r.imports.length}):`);
+      for (const imp of r.imports) lines.push(`  ${imp}`);
+    }
+  }
+
+  if (r.symbols.length > 0) {
+    lines.push("");
+    for (const sym of r.symbols) {
+      lines.push(renderSymbol(sym, 0, opts));
+    }
+  } else {
+    lines.push("");
+    lines.push("(no top-level symbols)");
+  }
+
+  return lines.join("\n");
+}
+
+function renderSymbol(s: SymbolEntry, depth: number, opts: OutlineOpts): string {
+  const indent = "  ".repeat(depth);
+  const lineMark = `L${s.line}`.padEnd(6);
+  const exp = s.exported ? "★ " : "  ";
+  const kindAbbr = kindToAbbr(s.kind);
+  const sig = s.signature ? ` ${s.signature}` : "";
+  const head = `${indent}${exp}${lineMark} ${kindAbbr} ${s.name}${sig}`;
+
+  if (opts.members !== false && s.members && s.members.length > 0) {
+    return [head, ...s.members.map((m) => renderSymbol(m, depth + 1, opts))].join("\n");
+  }
+  return head;
+}
+
+function kindToAbbr(kind: string): string {
+  switch (kind) {
+    case "function":
+      return "fn  ";
+    case "class":
+      return "cl  ";
+    case "interface":
+      return "if  ";
+    case "type":
+      return "ty  ";
+    case "const":
+      return "ct  ";
+    case "let":
+      return "let ";
+    case "var":
+      return "var ";
+    case "enum":
+      return "en  ";
+    case "enumMember":
+      return "em  ";
+    case "method":
+      return "mt  ";
+    case "property":
+      return "pr  ";
+    case "namespace":
+      return "ns  ";
+    case "trait":
+      return "tr  ";
+    case "re-export":
+      return "rx  ";
+    default:
+      return kind.slice(0, 4).padEnd(4);
+  }
+}

package/src/commands/presence.ts

@@ -0,0 +1,152 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import {
+  emitCanonical,
+  normalizeHarness,
+  readHeartbeat,
+  resolveOwner,
+} from "../core/agents/index.ts";
+import {
+  ageSeconds,
+  applyDetection,
+  clearPresence,
+  formatAge,
+  type PresenceState,
+  presenceFilePath,
+  readPresence,
+  writePresence,
+} from "../lib/presence.ts";
+
+/**
+ * `presence`: mobile/office state for agents (~/.claude/presence).
+ *
+ * Uses the injected EmitContext so composed and standalone consumers share
+ * one code path. The state file path is Claude-Code-specific (lives under
+ * ~/.claude/) but the detect/set/clear logic is generic: any agent harness
+ * can adopt the same convention.
+ */
+export function registerPresenceCommand(program: Command, emit: EmitContext): void {
+  const cmd = program
+    .command("presence")
+    .description("Mobile/office state for agents (~/.claude/presence)")
+    .action(() => {
+      printStatus(emit);
+    });
+
+  cmd
+    .command("get")
+    .description('Print just the state ("mobile" / "office"), or full record with --json')
+    .option("--json", "Print the full record as JSON")
+    .action((opts: { json?: boolean }) => {
+      const r = readPresence();
+      if (opts.json) {
+        emit.config({ format: "json" });
+        emit.data({
+          state: r.state,
+          updated_at: r.updated_at,
+          source: r.source,
+          is_default: r.is_default,
+          path: presenceFilePath(),
+        });
+        return;
+      }
+      emit.text(`${r.state}\n`);
+    });
+
+  cmd
+    .command("set")
+    .argument("<state>", "mobile | office")
+    .description("Set state explicitly (source=cli). Hook auto-detection can still overwrite.")
+    .action((state: string) => {
+      if (state !== "mobile" && state !== "office") {
+        emit.error({
+          code: "invalid_state",
+          message: `state must be "mobile" or "office" (got: ${JSON.stringify(state)})`,
+        });
+        process.exit(2);
+      }
+      const before = readPresence();
+      writePresence(state as PresenceState, "cli");
+      emitPresenceChange(before.state, state as PresenceState, "cli");
+      printStatus(emit);
+    });
+
+  cmd
+    .command("clear")
+    .description('Delete the state file (next read returns the default, "office")')
+    .action(() => {
+      const removed = clearPresence();
+      emit.data({
+        ok: true,
+        removed,
+        path: presenceFilePath(),
+      });
+    });
+
+  cmd
+    .command("detect")
+    .description(
+      "Internal: read prompt text from stdin, apply detection rules, update state if signal is clear",
+    )
+    .option("--from-stdin", "Read prompt from stdin (the only supported input mode today)")
+    .option("--verbose", "Print the detection result to stderr")
+    .action(async (opts: { fromStdin?: boolean; verbose?: boolean }) => {
+      const prompt = await readStdin();
+      if (!prompt) {
+        if (opts.verbose) emit.log("(no input on stdin; skipping)", "info");
+        return;
+      }
+      const result = applyDetection(prompt);
+      if (opts.verbose) {
+        emit.log(
+          JSON.stringify({
+            detected: result.detected,
+            before: result.before,
+            after: result.after,
+            changed: result.changed,
+          }),
+          "info",
+        );
+      }
+    });
+}
+
+function printStatus(emit: EmitContext): void {
+  const r = readPresence();
+  emit.data({
+    state: r.state,
+    updated_at: r.updated_at,
+    source: r.source,
+    is_default: r.is_default,
+    age_seconds: r.is_default ? null : ageSeconds(r.updated_at),
+    age_human: r.is_default ? "(default: file missing)" : formatAge(ageSeconds(r.updated_at)),
+    path: presenceFilePath(),
+  });
+}
+
+async function readStdin(): Promise<string> {
+  if (process.stdin.isTTY) return "";
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function emitPresenceChange(
+  from: PresenceState,
+  to: PresenceState,
+  source: "cli" | "hook" | "user",
+): void {
+  if (from === to) return;
+  const owner = resolveOwner();
+  if (!owner) return;
+  const hb = readHeartbeat(owner);
+  emitCanonical({
+    type: "state.presence_change",
+    owner,
+    session: hb?.session_id ?? owner,
+    harness: normalizeHarness(hb?.platform),
+    data: { from, to, source },
+  });
+}