freeharness 0.4.1

package/dist/cli/doctor.d.ts

@@ -0,0 +1,205 @@
+import { type Scope } from "@freeharness/core";
+/** A runtime dependency probe result. */
+export interface DepStatus {
+    name: string;
+    present: boolean;
+    version?: string;
+    neededBy: string;
+}
+/**
+ * Probes every runtime dependency on the current PATH.
+ * @returns One status per dependency, in table order.
+ */
+export declare function probeDeps(): DepStatus[];
+/**
+ * Renders the deps table.
+ * @param deps Probe results.
+ * @returns Printable lines.
+ */
+export declare function depLines(deps: DepStatus[]): string[];
+/** Hook conflicts in a settings.json: duplicate commands, a foreign memory-injecting SessionStart hook, claude-mem hooks kept while the plugin is installed; empty when settings.json is absent. */
+export declare function hookConflictLines(settingsPath: string, pluginInstalled: boolean): string[];
+/** Canonical agent file names and skill dir names: what a project could duplicate, and what doctor tells apart from the user's own content. */
+export declare function canonicalNames(canonicalDir: string): {
+    agents: string[];
+    skills: string[];
+};
+/** Skills and agents under a Claude dir that FreeHarness did not emit (the user's own content); never a global `openspec-*` copy or a manifest-recorded retired name. */
+export declare function foreignContentLines(claudeDir: string, canonicalDir: string, scope: Scope, projectRoot: string): string[];
+/**
+ * Flags a CLI that runs from outside `~/.local/bin` while the install.sh symlink exists there:
+ * the shell resolved an older link (a global `npm link`, a stale PATH entry) ahead of ours.
+ * @param argv1 `process.argv[1]` of the running CLI.
+ * @param home Home directory.
+ * @returns One WARN line, or none.
+ */
+export declare function runningFromLines(argv1: string | undefined, home: string): string[];
+/**
+ * Whether claude-mem is enabled in settings.json or registered in installed_plugins.json.
+ * @param claudeDir The ~/.claude (or project .claude) dir.
+ * @returns True when found in either place.
+ */
+export declare function memoryPluginInstalled(claudeDir: string): boolean;
+/**
+ * PROVENANCE baseline vs upstream fork HEAD for each vendored engine.
+ * @param canonicalDir Resolved canonical directory.
+ * @returns Printable lines, one per engine.
+ */
+export declare function baselineLines(canonicalDir: string): string[];
+/** SDD status of a project's changes (the SessionStart hook computes the same numbers). */
+export interface OpenspecChangeStatus {
+    /** Active change ids under openspec/changes (archive excluded), sorted. */
+    inFlight: string[];
+    /** Ids whose tasks.md has at least one checked and no unchecked task. */
+    complete: string[];
+    /** Ids in .freeharness/sdd/blockers.json still active; null without the file. */
+    blocked: string[] | null;
+}
+/**
+ * Reads the change status from tasks.md checkbox counts and the optional blockers file.
+ * @param projectRoot Project root.
+ * @returns Status, or null when <projectRoot>/openspec/changes is absent.
+ */
+export declare function openspecChangeStatus(projectRoot: string): OpenspecChangeStatus | null;
+/**
+ * The SDD status summary: WARN naming the complete-but-not-archived changes, OK otherwise.
+ * @param projectRoot Project root.
+ * @returns One line, or none when the project has no openspec/changes.
+ */
+export declare function openspecChangeLines(projectRoot: string): string[];
+/**
+ * Install-manifest presence and drift (listed files that are gone).
+ * @param manifestFile The manifest path for the scope.
+ * @returns Printable lines.
+ */
+export declare function manifestLines(manifestFile: string): string[];
+/**
+ * Roots of the emitted prose for a scope: the rules file plus the harness content dirs.
+ * @param scope `user` or `project`.
+ * @param base `~/.claude` (user) or the project root (project).
+ * @returns Existing or not, in scan order; missing roots are skipped by the lint.
+ */
+export declare function emittedProseRoots(scope: "user" | "project", base: string): string[];
+/**
+ * `doctor --context-budget` section: the language lint over canonical and the emitted
+ * content (gerund preambles, Portuguese outside declared pt-BR sections). Advisory only.
+ * @param canonicalDir Resolved canonical directory (null when unresolved).
+ * @param emittedRoots Emitted prose roots for the scope.
+ * @returns Printable lines, indented under a `Context budget:` header.
+ */
+export declare function contextBudgetLines(canonicalDir: string | null, emittedRoots: string[]): string[];
+/** Inputs of the token side of `doctor --context-budget`. */
+export interface BudgetInputs {
+    /** `~` of the user. */
+    home: string;
+    /** Cwd or --project. */
+    projectRoot: string;
+    /** Prefix budget in tokens. */
+    budget?: number;
+}
+/**
+ * Token side of `doctor --context-budget`: CLAUDE.md lines vs 200, hook/MCP counts, the
+ * prefix estimate vs budget, cache TTLs and cache invalidators. Each line is OK or FAIL; the
+ * section never blocks.
+ * @param inp Home, project root, budget.
+ * @returns Printable lines (indented, no header).
+ */
+export declare function budgetLines(inp: BudgetInputs): string[];
+/**
+ * Context-window line of `doctor --context-budget`: WARN when the user or project `model`
+ * carries a `[1m]` suffix (a week on it measured 1.69B cache-read tokens), naming the suffix
+ * and the standard-window id; OK otherwise, naming the effective model (project overrides user).
+ * @param userSettings `~/.claude/settings.json` content.
+ * @param projectSettings Merged `<project>/.claude/settings.json` + `settings.local.json`.
+ * @returns One printable line.
+ */
+export declare function contextWindowLine(userSettings: Record<string, unknown>, projectSettings: Record<string, unknown>): string;
+/** Outcome of probing a local model server. */
+export interface ProbeResult {
+    ok: boolean;
+    /** Server kind that answered (/api/version vs /v1/models). */
+    kind?: "ollama" | "openai";
+    /** Ollama version, or the model count for an OpenAI-compatible server. */
+    detail?: string;
+    /** Server-listed models (OpenAI /v1/models or Ollama /api/tags), when available. */
+    models?: string[];
+    error?: string;
+}
+/** ms; a local server that misses this is down. */
+export declare const PROBE_TIMEOUT_MS = 1500;
+/**
+ * Probes a local model server: `<base>/api/version` (Ollama) first, then `<base>/v1/models`
+ * (any OpenAI-compatible server such as llama.cpp, vLLM, LM Studio). Down = error text
+ * (ECONNREFUSED, timeout), never a throw.
+ * @param baseUrl The ANTHROPIC_BASE_URL / provider base URL.
+ * @param timeoutMs Timeout per request.
+ * @returns Probe result.
+ */
+export declare function probeLocalServer(baseUrl: string, timeoutMs?: number): Promise<ProbeResult>;
+/**
+ * The active local-model profile as seen in a settings.json env block.
+ * @param settingsFile settings.json path.
+ * @returns Base URL and tier models, or undefined when no base URL is set.
+ */
+export declare function activeProfile(settingsFile: string): {
+    baseUrl: string;
+    tiers: Partial<Record<"strong" | "standard" | "fast", string>>;
+    subagent?: string;
+} | undefined;
+/**
+ * Doctor's profile line: no base URL = one OK line (default endpoint); a base URL = the
+ * probe result with the server version and the tier models (FAIL with the error when down,
+ * WARN for a tier model the server does not list).
+ * @param settingsFile settings.json path.
+ * @param probe Probe function (injectable for tests).
+ * @returns Printable lines.
+ */
+export declare function profileLines(settingsFile: string, probe?: (baseUrl: string) => Promise<ProbeResult>): Promise<string[]>;
+/**
+ * Tool counts per MCP server name from the catalogs (the mcp profile and servers.json).
+ * @param canonicalDir Resolved canonical directory.
+ * @returns name -> approximate tool count.
+ */
+export declare function mcpToolCounts(canonicalDir: string): Record<string, number>;
+/**
+ * MCP servers with their catalog tool counts, then one line per (server, scope) naming where
+ * it lives and the exact `claude mcp remove -s <scope>` command (Claude Code keeps user/local
+ * scope in `.claude.json`, project scope in `<project>/.mcp.json`).
+ * @param home Home directory.
+ * @param projectRoot Project root.
+ * @param counts Tool counts from `mcpToolCounts`.
+ * @returns Printable lines.
+ */
+export declare function mcpLines(home: string, projectRoot: string, counts: Record<string, number>): string[];
+/**
+ * What the install dirs hold: skill directories and agent `.md` files. Dotfiles (`.DS_Store`
+ * on macOS) and stray files never count.
+ * @param claudeDir `~/.claude` (or a project `.claude`).
+ * @returns Counts, or -1 for a missing directory.
+ */
+export declare function installedContentCounts(claudeDir: string): {
+    skills: number;
+    agents: number;
+};
+/** Roots a hook command may point at without being flagged foreign. */
+export declare function trustedHookRoots(home: string): string[];
+/**
+ * Extracts the script path of a hook command: the first quoted or bare token that looks
+ * like a path (starts with `/`, `~` or `$`), skipping an interpreter (`node`, `bash`, `sh`,
+ * `bun`, `python3`).
+ * @param command Hook command.
+ * @returns The path and whether an interpreter precedes it; undefined for a bare command.
+ */
+export declare function hookScriptPath(command: string): {
+    script: string;
+    interpreter?: string;
+} | undefined;
+/**
+ * Scans the hook commands of a settings.json: a command whose script lies outside the
+ * trusted roots is WARN foreign; a script that is missing, or invoked directly without the
+ * executable bit, is WARN.
+ * @param settingsPath settings.json path.
+ * @param home Home directory.
+ * @returns Printable lines (an OK line when nothing is found; empty when the file is absent).
+ */
+export declare function hookScanLines(settingsPath: string, home: string): string[];