@hwip/cli 0.0.1 → 0.1.0

package/dist/agent-state.d.ts

@@ -0,0 +1,84 @@
+import type { AgentKind } from './remote-agents.js';
+export type AgentState = 'working' | 'blocked' | 'idle' | 'unknown';
+export interface RuleCondition {
+    /** All strings must appear (case-insensitive). */
+    contains?: string[];
+    /** All patterns must match. */
+    regex?: string[];
+}
+export interface DetectionRule {
+    id: string;
+    state: AgentState;
+    /** Higher wins; first match ends evaluation. */
+    priority: number;
+    /** 'tail' = last N non-empty lines (default), 'whole' = full capture. */
+    region?: 'tail' | 'whole';
+    /** Lines for region 'tail'. Default 10. */
+    tailLines?: number;
+    contains?: string[];
+    regex?: string[];
+    /** At least one condition group must match (OR). */
+    any?: RuleCondition[];
+    /** No condition group may match (exclusion). */
+    not?: RuleCondition[];
+    /**
+     * On match, keep the previous state instead of this rule's state.
+     * For overlay screens (transcript viewer, menus) that would
+     * otherwise pollute the state while the agent is still working.
+     */
+    skipStateUpdate?: boolean;
+}
+export interface DetectionManifest {
+    engineVersion: number;
+    /** Date.revision, e.g. "2026.07.04.1" — for OTA freshness compare. */
+    version: string;
+    /** Kill-switch: rule ids to ignore without shipping a new manifest shape. */
+    disabledRuleIds?: string[];
+    agents: Partial<Record<AgentKind, DetectionRule[]>>;
+}
+export declare const ENGINE_VERSION = 1;
+export interface EvaluationResult {
+    state: AgentState;
+    /** Rule that decided the state — for verbose logs and rule debugging. */
+    ruleId?: string;
+}
+/** Why a rule or watch pattern will never match, or null when it compiles. */
+export declare const patternError: (pattern: string) => string | null;
+/** Test hook: manifest swaps call this so stale patterns don't pin memory. */
+export declare const clearRegexCache: () => void;
+/**
+ * Classify one pane capture. `prev` feeds skipStateUpdate rules — an
+ * overlay match returns the previous confirmed state unchanged.
+ */
+export declare const evaluateState: (paneText: string, agentKind: AgentKind, manifest: DetectionManifest, prev?: AgentState) => EvaluationResult;
+/**
+ * Safe one-pattern probe for output-match watches (§S5 v2). Same caps
+ * as rule evaluation — user-authored watch patterns are exactly as
+ * untrusted as OTA rules. Returns the matched line for the push body.
+ */
+export declare const findPatternMatch: (pattern: string, paneText: string) => {
+    line: string;
+} | null;
+export interface StateTracker {
+    /** Last CONFIRMED state — what gets reported to the server. */
+    confirmed: AgentState;
+    confirmedAt: number;
+    ruleId?: string;
+    /** Pending different observation awaiting its second sighting. */
+    candidate?: AgentState;
+    candidateRuleId?: string;
+    /** Hash of the pane text behind the last evaluation (skip re-eval). */
+    contentHash?: string;
+}
+/**
+ * Consecutive-confirmation debounce: a NEW state must be observed on
+ * two consecutive cycles (~10 s at the 5 s report interval) before it
+ * replaces the confirmed one. Menus flashed open, mid-render frames,
+ * and scroll artifacts all last one cycle and die as candidates.
+ *
+ * The very first observation confirms immediately — a fresh tracker
+ * has no baseline to protect, and the server treats a session's first
+ * reported state as baseline, not as a transition (§S2).
+ */
+export declare const advanceState: (tracker: StateTracker | undefined, observed: EvaluationResult, now: number) => StateTracker;
+//# sourceMappingURL=agent-state.d.ts.map

package/dist/agent-state.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.advanceState = exports.findPatternMatch = exports.evaluateState = exports.clearRegexCache = exports.patternError = exports.ENGINE_VERSION = void 0;
+/**
+ * Agent state detection engine — classifies a tmux pane's visible text
+ * into `working | blocked | idle | unknown` using declarative rules.
+ *
+ * Design constraints:
+ * - Rules are DATA, not code: they ship bundled but are replaceable
+ *   over the air (§S7), so agent UI changes never require a daemon
+ *   release. Everything here must therefore survive hostile or
+ *   malformed manifests: pattern-length caps, input-size caps, and
+ *   per-rule isolation of regex compile failures.
+ * - Pure functions only. The listener owns timing, tmux, and I/O;
+ *   this module owns classification and flap suppression so both are
+ *   unit-testable without a terminal.
+ * - `done` is deliberately NOT a wire state: "finished but unseen" is
+ *   per-user view state, derived client-side. The daemon reports only
+ *   what it can observe.
+ */
+const re2js_1 = require("re2js");
+exports.ENGINE_VERSION = 1;
+// OTA manifests are semi-trusted (schema-validated, authored by humans,
+// fetched over the network) and watch patterns come from the phone. Both run
+// synchronously on the daemon's one thread, where a backtracking engine is a
+// freeze waiting to happen: `(a+)+$` hangs V8 on 29 characters and
+// `.*.*.*x` takes seconds on 300. So patterns run on RE2 (re2js, pure JS),
+// whose time is the input length times the compiled program's size. Counted
+// repeats grow that program (`\w{1,1000}\w{1,1000}z` takes seconds on 8 KiB),
+// so a program past MAX_PROGRAM_SIZE is refused too. RE2 has no lookaround or
+// backreferences — a pattern using them does not compile and its rule or
+// watch stays inert — its `\s`, `\w`, `\d` are ASCII-only, and `$` does not
+// match before `\r`.
+// hwip server/src/lib/watch-pattern.ts applies the same limits and flags to a
+// watch pattern before storing it (C75) — keep the two in step.
+const MAX_PATTERN_LENGTH = 200;
+/**
+ * Bundled and pi rules compile to 6–37 steps. At 200, a match search over
+ * 8 KiB measured 100–300 ms; at 64 it stays under about 40 ms.
+ */
+const MAX_PROGRAM_SIZE = 64;
+const MAX_INPUT_BYTES = 8 * 1024;
+const DEFAULT_TAIL_LINES = 10;
+/** The last MAX_INPUT_BYTES of the pane as UTF-8 — the bottom is the signal. */
+const tailBytes = (text) => {
+    if (Buffer.byteLength(text, 'utf-8') <= MAX_INPUT_BYTES)
+        return text;
+    const bytes = Buffer.from(text, 'utf-8');
+    // Drop what is left of a character the cut went through.
+    return bytes.subarray(-MAX_INPUT_BYTES).toString('utf-8').replace(/^\uFFFD+/, '');
+};
+// Compiled-regex cache. Rules are static between manifest swaps, so
+// compiling once per (pattern) is enough; a failed compile is cached as
+// its reason so a bad OTA pattern logs once, not every 5-second cycle.
+const regexCache = new Map();
+const compilePattern = (pattern) => {
+    const cached = regexCache.get(pattern);
+    if (cached !== undefined)
+        return cached;
+    let compiled;
+    if (pattern.length > MAX_PATTERN_LENGTH) {
+        compiled = `longer than ${MAX_PATTERN_LENGTH} characters`;
+    }
+    else {
+        try {
+            compiled = re2js_1.RE2JS.compile(pattern, re2js_1.RE2JS.CASE_INSENSITIVE | re2js_1.RE2JS.MULTILINE);
+            if (compiled.programSize() > MAX_PROGRAM_SIZE)
+                compiled = `compiles to more than ${MAX_PROGRAM_SIZE} steps`;
+        }
+        catch (err) {
+            compiled = err instanceof Error ? err.message : String(err);
+        }
+    }
+    regexCache.set(pattern, compiled);
+    return compiled;
+};
+/** Why a rule or watch pattern will never match, or null when it compiles. */
+const patternError = (pattern) => {
+    const compiled = compilePattern(pattern);
+    return typeof compiled === 'string' ? compiled : null;
+};
+exports.patternError = patternError;
+/** Test hook: manifest swaps call this so stale patterns don't pin memory. */
+const clearRegexCache = () => {
+    regexCache.clear();
+};
+exports.clearRegexCache = clearRegexCache;
+const conditionMatches = (cond, text, lowerText) => {
+    for (const needle of cond.contains ?? []) {
+        if (!lowerText.includes(needle.toLowerCase()))
+            return false;
+    }
+    for (const pattern of cond.regex ?? []) {
+        const compiled = compilePattern(pattern);
+        // A pattern that failed to compile can never be satisfied —
+        // fail the condition rather than silently passing it, so a
+        // broken OTA rule becomes inert instead of over-matching.
+        if (typeof compiled === 'string' || !compiled.test(text))
+            return false;
+    }
+    return true;
+};
+const ruleMatches = (rule, text, lowerText) => {
+    if (!conditionMatches({ contains: rule.contains, regex: rule.regex }, text, lowerText))
+        return false;
+    if (rule.any && rule.any.length > 0) {
+        if (!rule.any.some((c) => conditionMatches(c, text, lowerText)))
+            return false;
+    }
+    for (const excluded of rule.not ?? []) {
+        if (conditionMatches(excluded, text, lowerText))
+            return false;
+    }
+    return true;
+};
+const tailOf = (lines, count) => lines.filter((l) => l.trim().length > 0).slice(-count).join('\n');
+/**
+ * Classify one pane capture. `prev` feeds skipStateUpdate rules — an
+ * overlay match returns the previous confirmed state unchanged.
+ */
+const evaluateState = (paneText, agentKind, manifest, prev = 'unknown') => {
+    // Truncate from the FRONT: the bottom of the pane is where every
+    // agent renders its live status, so the tail is the signal.
+    const text = tailBytes(paneText);
+    const lines = text.split('\n');
+    const disabled = new Set(manifest.disabledRuleIds ?? []);
+    const rules = (manifest.agents[agentKind] ?? [])
+        .filter((r) => !disabled.has(r.id))
+        .sort((a, b) => b.priority - a.priority);
+    for (const rule of rules) {
+        const scope = rule.region === 'whole'
+            ? text
+            : tailOf(lines, rule.tailLines ?? DEFAULT_TAIL_LINES);
+        if (ruleMatches(rule, scope, scope.toLowerCase())) {
+            if (rule.skipStateUpdate)
+                return { state: prev, ruleId: rule.id };
+            return { state: rule.state, ruleId: rule.id };
+        }
+    }
+    return { state: 'unknown' };
+};
+exports.evaluateState = evaluateState;
+/**
+ * Safe one-pattern probe for output-match watches (§S5 v2). Same caps
+ * as rule evaluation — user-authored watch patterns are exactly as
+ * untrusted as OTA rules. Returns the matched line for the push body.
+ */
+const findPatternMatch = (pattern, paneText) => {
+    const text = tailBytes(paneText);
+    const compiled = compilePattern(pattern);
+    // `test` is the fast path; only a pane that matches pays for `find`.
+    if (typeof compiled === 'string' || !compiled.test(text))
+        return null;
+    const matcher = compiled.matcher(text);
+    if (!matcher.find())
+        return null;
+    const at = matcher.start();
+    const start = text.lastIndexOf('\n', at) + 1;
+    const endIdx = text.indexOf('\n', at);
+    const line = text.slice(start, endIdx === -1 ? undefined : endIdx).trim();
+    return { line };
+};
+exports.findPatternMatch = findPatternMatch;
+/**
+ * Consecutive-confirmation debounce: a NEW state must be observed on
+ * two consecutive cycles (~10 s at the 5 s report interval) before it
+ * replaces the confirmed one. Menus flashed open, mid-render frames,
+ * and scroll artifacts all last one cycle and die as candidates.
+ *
+ * The very first observation confirms immediately — a fresh tracker
+ * has no baseline to protect, and the server treats a session's first
+ * reported state as baseline, not as a transition (§S2).
+ */
+const advanceState = (tracker, observed, now) => {
+    if (!tracker) {
+        return { confirmed: observed.state, confirmedAt: now, ruleId: observed.ruleId };
+    }
+    if (observed.state === tracker.confirmed) {
+        // Re-confirmation clears any pending candidate.
+        return { ...tracker, candidate: undefined, candidateRuleId: undefined, ruleId: observed.ruleId ?? tracker.ruleId };
+    }
+    if (observed.state === tracker.candidate) {
+        // Second consecutive sighting — promote.
+        return { confirmed: observed.state, confirmedAt: now, ruleId: observed.ruleId };
+    }
+    return { ...tracker, candidate: observed.state, candidateRuleId: observed.ruleId };
+};
+exports.advanceState = advanceState;

package/dist/agent-target.d.ts

@@ -0,0 +1,60 @@
+/** A subset of a `/devices` record (hwip `Device`). */
+export interface AgentTargetDevice {
+    deviceId: string;
+    nickname?: string;
+    isOnline?: boolean;
+    agentSessions?: {
+        name: string;
+        project?: string;
+        label?: string | null;
+        providerSessionName?: string | null;
+        parentName?: string;
+        /** What runs in the session: an agent kind, or `shell` for a `hwip sh` session. */
+        agentKind?: string;
+    }[];
+    agentSessionAliases?: Record<string, string>;
+}
+/** A resolved agent session: the listener's device id and its tmux name. */
+export interface AgentTarget {
+    deviceId: string;
+    name: string;
+    /** `<deviceId>:<name>` — the stable key the app groups the session's chat by. */
+    key: string;
+}
+/**
+ * The target named nothing, named more than one session, or is on a machine
+ * that is offline. The message lists the keys to retry with.
+ */
+export declare class AgentTargetError extends Error {
+    readonly code: 'UNKNOWN_TARGET' | 'AMBIGUOUS_TARGET' | 'TARGET_OFFLINE';
+    constructor(code: 'UNKNOWN_TARGET' | 'AMBIGUOUS_TARGET' | 'TARGET_OFFLINE', message: string);
+}
+/**
+ * Whether an agent may type into this session. Subagents are view-only (no
+ * input). A `hwip sh` session is a real shell: an agent typing into it would
+ * run commands on that machine, on another PC as easily as on its own.
+ */
+export declare const isAgentTarget: (s: {
+    parentName?: string;
+    agentKind?: string;
+}) => boolean;
+/**
+ * Resolve `target` to one live agent session.
+ *
+ * The key `<deviceId>:<tmuxName>` is exact. Anything else is matched against
+ * the tmux name, the user's alias, the agent's own session name and the
+ * listener's label, and must match exactly one session: the same tmux name on
+ * two PCs is the routing bug a guess would reintroduce, so two matches are an
+ * error that lists both keys. The sender's own session (`selfKey`) is left out
+ * of name matching, so the same project on two PCs resolves to the other one;
+ * named alone, it resolves to itself for the caller to refuse.
+ *
+ * A session on an offline machine is refused rather than sent to: the listener
+ * takes commands over its socket only and fetches none it missed, so the
+ * message would be stored and never typed.
+ *
+ * A copy of mcp-server/src/agent-target.ts: this package depends on that one,
+ * but its entry point starts the MCP server when imported. Change both.
+ */
+export declare const resolveAgentTarget: (devices: AgentTargetDevice[], target: string, selfKey?: string) => AgentTarget;
+//# sourceMappingURL=agent-target.d.ts.map

package/dist/agent-target.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAgentTarget = exports.isAgentTarget = exports.AgentTargetError = void 0;
+/**
+ * The target named nothing, named more than one session, or is on a machine
+ * that is offline. The message lists the keys to retry with.
+ */
+class AgentTargetError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'AgentTargetError';
+    }
+}
+exports.AgentTargetError = AgentTargetError;
+/**
+ * Whether an agent may type into this session. Subagents are view-only (no
+ * input). A `hwip sh` session is a real shell: an agent typing into it would
+ * run commands on that machine, on another PC as easily as on its own.
+ */
+const isAgentTarget = (s) => !s.parentName && s.agentKind !== 'shell';
+exports.isAgentTarget = isAgentTarget;
+const candidatesOf = (devices) => devices.flatMap((d) => (d.agentSessions ?? [])
+    .filter(exports.isAgentTarget)
+    .map((s) => ({
+    deviceId: d.deviceId,
+    name: s.name,
+    key: `${d.deviceId}:${s.name}`,
+    alias: d.agentSessionAliases?.[s.name],
+    label: s.label,
+    providerSessionName: s.providerSessionName,
+    host: d.nickname ?? d.deviceId,
+    offline: d.isOnline === false,
+})));
+const listCandidates = (list) => list.map((c) => `${c.key} (${c.alias ?? c.providerSessionName ?? c.label ?? c.name} on ${c.host})`).join(', ') || 'none';
+/**
+ * Resolve `target` to one live agent session.
+ *
+ * The key `<deviceId>:<tmuxName>` is exact. Anything else is matched against
+ * the tmux name, the user's alias, the agent's own session name and the
+ * listener's label, and must match exactly one session: the same tmux name on
+ * two PCs is the routing bug a guess would reintroduce, so two matches are an
+ * error that lists both keys. The sender's own session (`selfKey`) is left out
+ * of name matching, so the same project on two PCs resolves to the other one;
+ * named alone, it resolves to itself for the caller to refuse.
+ *
+ * A session on an offline machine is refused rather than sent to: the listener
+ * takes commands over its socket only and fetches none it missed, so the
+ * message would be stored and never typed.
+ *
+ * A copy of mcp-server/src/agent-target.ts: this package depends on that one,
+ * but its entry point starts the MCP server when imported. Change both.
+ */
+const resolveAgentTarget = (devices, target, selfKey) => {
+    const all = candidatesOf(devices);
+    const toTarget = ({ deviceId, name, key, host, offline }) => {
+        if (offline) {
+            throw new AgentTargetError('TARGET_OFFLINE', `${key} is on ${host}, which is offline — the message would never be typed`);
+        }
+        return { deviceId, name, key };
+    };
+    const exact = all.find((c) => c.key === target);
+    if (exact)
+        return toTarget(exact);
+    const named = (c) => [c.name, c.alias, c.providerSessionName, c.label].some((n) => n === target);
+    const others = all.filter((c) => c.key !== selfKey);
+    const matches = others.filter(named);
+    if (matches.length === 1)
+        return toTarget(matches[0]);
+    if (matches.length === 0) {
+        const self = all.find((c) => c.key === selfKey && named(c));
+        if (self)
+            return toTarget(self);
+    }
+    if (matches.length > 1) {
+        throw new AgentTargetError('AMBIGUOUS_TARGET', `ambiguous target "${target}" — use one of these keys: ${listCandidates(matches)}`);
+    }
+    throw new AgentTargetError('UNKNOWN_TARGET', `unknown target "${target}" — other agent sessions: ${listCandidates(others)}`);
+};
+exports.resolveAgentTarget = resolveAgentTarget;

package/dist/agents.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Per-agent GLOBAL skill directories, keyed by the same `id` used in
+ * `detectAgents`. Scan targets for `command-scan.ts` — keep next to the
+ * detection table so the two can never disagree about which agents exist.
+ *
+ * Global only: project-level dirs depend on a session's cwd, and the catalog is
+ * device-level (one scan per listener, shared by every session on the machine).
+ *
+ * pi's two entries come from its own docs (`docs/skills.md § Locations`,
+ * pi 0.85.1): global is `~/.pi/agent/skills/` and `~/.agents/skills/`, while
+ * `.pi/skills/` is the PROJECT dir — scanning `~/.pi/skills` found only three
+ * dangling symlinks and reported pi as having no skills at all.
+ */
+export declare const AGENT_SKILL_DIRS: Record<string, string[]>;
+export interface Agent {
+    name: string;
+    id: string;
+    detected: boolean;
+}
+/**
+ * Absolute path of a command on PATH, or null when it isn't there.
+ * `execFileSync`, not a shell: `process.execve` needs a real path (it does no
+ * PATH lookup of its own), and building `which ${cmd}` as a shell string would
+ * let a path containing a space split into two words.
+ */
+export declare const resolveCommand: (cmd: string) => string | null;
+/** The first executable `cmd` on PATH, found without spawning anything. */
+export declare const findOnPath: (cmd: string) => string | null;
+export declare const hasCommand: (cmd: string) => boolean;
+export declare const detectAgents: () => Agent[];
+//# sourceMappingURL=agents.d.ts.map

package/dist/agents.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectAgents = exports.hasCommand = exports.findOnPath = exports.resolveCommand = exports.AGENT_SKILL_DIRS = void 0;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+// Agent detection shared by install / uninstall / verify. Kept in one place
+// so the three commands can never disagree about which agents exist or how
+// they're detected.
+/**
+ * Per-agent GLOBAL skill directories, keyed by the same `id` used in
+ * `detectAgents`. Scan targets for `command-scan.ts` — keep next to the
+ * detection table so the two can never disagree about which agents exist.
+ *
+ * Global only: project-level dirs depend on a session's cwd, and the catalog is
+ * device-level (one scan per listener, shared by every session on the machine).
+ *
+ * pi's two entries come from its own docs (`docs/skills.md § Locations`,
+ * pi 0.85.1): global is `~/.pi/agent/skills/` and `~/.agents/skills/`, while
+ * `.pi/skills/` is the PROJECT dir — scanning `~/.pi/skills` found only three
+ * dangling symlinks and reported pi as having no skills at all.
+ */
+exports.AGENT_SKILL_DIRS = {
+    claude: ['.claude/skills'],
+    codex: ['.codex/skills'],
+    pi: ['.pi/agent/skills', '.agents/skills'],
+};
+const HOME = (0, os_1.homedir)();
+/**
+ * Absolute path of a command on PATH, or null when it isn't there.
+ * `execFileSync`, not a shell: `process.execve` needs a real path (it does no
+ * PATH lookup of its own), and building `which ${cmd}` as a shell string would
+ * let a path containing a space split into two words.
+ */
+const resolveCommand = (cmd) => {
+    try {
+        return (0, child_process_1.execFileSync)('which', [cmd], { encoding: 'utf-8' }).trim() || null;
+    }
+    catch {
+        // Minimal images (Arch base, Fedora/RHEL minimal) ship no `which`;
+        // walking PATH ourselves answers the same question there.
+        return (0, exports.findOnPath)(cmd);
+    }
+};
+exports.resolveCommand = resolveCommand;
+/** The first executable `cmd` on PATH, found without spawning anything. */
+const findOnPath = (cmd) => {
+    for (const dir of (process.env.PATH ?? '').split(path_1.delimiter)) {
+        if (!dir)
+            continue;
+        try {
+            (0, fs_1.accessSync)((0, path_1.join)(dir, cmd), fs_1.constants.X_OK);
+            return (0, path_1.join)(dir, cmd);
+        }
+        catch { /* not in this directory */ }
+    }
+    return null;
+};
+exports.findOnPath = findOnPath;
+const hasCommand = (cmd) => (0, exports.resolveCommand)(cmd) !== null;
+exports.hasCommand = hasCommand;
+const detectAgents = () => [
+    { name: 'Claude Code', id: 'claude', detected: (0, exports.hasCommand)('claude') },
+    { name: 'Cursor', id: 'cursor', detected: (0, fs_1.existsSync)((0, path_1.join)(HOME, '.cursor')) },
+    { name: 'Windsurf', id: 'windsurf', detected: (0, fs_1.existsSync)((0, path_1.join)(HOME, '.codeium')) },
+    { name: 'Gemini CLI', id: 'gemini', detected: (0, exports.hasCommand)('gemini') },
+    { name: 'Codex CLI', id: 'codex', detected: (0, exports.hasCommand)('codex') },
+    { name: 'Copilot CLI', id: 'copilot', detected: (0, fs_1.existsSync)((0, path_1.join)(HOME, '.copilot')) },
+    { name: 'Cline', id: 'cline', detected: (0, fs_1.existsSync)((0, path_1.join)(HOME, '.cline')) },
+    { name: 'Aider', id: 'aider', detected: (0, exports.hasCommand)('aider') },
+    { name: 'Pi', id: 'pi', detected: (0, fs_1.existsSync)((0, path_1.join)(HOME, '.pi')) || (0, exports.hasCommand)('pi') },
+    { name: 'OpenCode', id: 'opencode', detected: (0, fs_1.existsSync)((0, path_1.join)(HOME, '.config', 'opencode')) || (0, exports.hasCommand)('opencode') },
+];
+exports.detectAgents = detectAgents;

package/dist/api.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The two things every call to the account API from this daemon repeats:
+ * where the endpoint is, and that the request carries this machine's key
+ * and cannot outlive its budget. The callers keep their own error
+ * handling — a publish logs and returns false, a directory refresh throws
+ * — because what a failure means differs; only the convention lives here.
+ */
+/** `baseUrl` with its trailing slashes trimmed, plus `path`. */
+export declare const apiUrl: (baseUrl: string, path: string) => string;
+/**
+ * Can this API key travel in a header? It must fit the server's header limit and pass mcp-server's
+ * `fitsInHeader` rule — `fetch` drops white space at either end, and what is left must be a tab,
+ * printable ASCII or U+0080–U+00FF — so a key saved with a trailing newline still works. Checked
+ * before any `fetch`, so the key is never handed to an error that quotes it whole (C150).
+ */
+export declare const fitsInHeader: (key: string) => boolean;
+/**
+ * Authenticated request with a hard deadline. A JSON body sets its own content type.
+ * It never follows a redirect: undici drops `authorization` across origins but not
+ * `X-API-Key`, so a redirect would hand the key to whatever host it names. A refused
+ * redirect is rethrown in the words `hwip ask` and `HwipHook` use (still a `TypeError`),
+ * for callers that log what it throws — and so is a header `fetch` would not send, whose
+ * own words quote the key, and an address it would not take (not one at all, or one with a
+ * user name or password in it), whose own words quote the address; any other failure is left
+ * as `fetch` threw it.
+ */
+export declare const apiFetch: (fetchFn: typeof fetch, url: string, apiKey: string, timeoutMs: number, init?: RequestInit) => Promise<Response>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * The two things every call to the account API from this daemon repeats:
+ * where the endpoint is, and that the request carries this machine's key
+ * and cannot outlive its budget. The callers keep their own error
+ * handling — a publish logs and returns false, a directory refresh throws
+ * — because what a failure means differs; only the convention lives here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiFetch = exports.fitsInHeader = exports.apiUrl = void 0;
+const http_failure_js_1 = require("./http-failure.js");
+const ws_url_js_1 = require("./ws-url.js");
+/** `baseUrl` with its trailing slashes trimmed, plus `path`. */
+const apiUrl = (baseUrl, path) => `${baseUrl.replace(/\/+$/, '')}${path}`;
+exports.apiUrl = apiUrl;
+/**
+ * Can this API key travel in a header? It must fit the server's header limit and pass mcp-server's
+ * `fitsInHeader` rule — `fetch` drops white space at either end, and what is left must be a tab,
+ * printable ASCII or U+0080–U+00FF — so a key saved with a trailing newline still works. Checked
+ * before any `fetch`, so the key is never handed to an error that quotes it whole (C150).
+ */
+const fitsInHeader = (key) => Buffer.byteLength(key, 'utf-8') <= 8192
+    && !/[^\t -~\u0080-ÿ]/.test(key.replace(/^[\t\n\r ]+|[\t\n\r ]+$/g, ''));
+exports.fitsInHeader = fitsInHeader;
+/**
+ * Authenticated request with a hard deadline. A JSON body sets its own content type.
+ * It never follows a redirect: undici drops `authorization` across origins but not
+ * `X-API-Key`, so a redirect would hand the key to whatever host it names. A refused
+ * redirect is rethrown in the words `hwip ask` and `HwipHook` use (still a `TypeError`),
+ * for callers that log what it throws — and so is a header `fetch` would not send, whose
+ * own words quote the key, and an address it would not take (not one at all, or one with a
+ * user name or password in it), whose own words quote the address; any other failure is left
+ * as `fetch` threw it.
+ */
+const apiFetch = async (fetchFn, url, apiKey, timeoutMs, init = {}) => {
+    // Permanent configuration problems, said before anything is tried: no `cause` is kept, as
+    // `fetch`'s own words for these quote the key or the address whole. Outside the `try`, so
+    // the `catch` below cannot rewrap them.
+    if (!(0, exports.fitsInHeader)(apiKey))
+        throw new TypeError('a header could not be sent — check the API key for stray characters');
+    if ((0, ws_url_js_1.carriesCredentials)(url))
+        throw new TypeError((0, http_failure_js_1.networkFailureMessage)(new TypeError('not used'), url));
+    try {
+        void new URL(url);
+    }
+    catch {
+        throw new TypeError('the base URL is not a valid address — check --base-url, HWIP_BASE_URL or "baseUrl" in ~/.hwip/config.json');
+    }
+    try {
+        return await fetchFn(url, {
+            ...init,
+            headers: {
+                'X-API-Key': apiKey,
+                ...(init.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                ...init.headers,
+            },
+            signal: AbortSignal.timeout(timeoutMs),
+            redirect: 'error',
+        });
+    }
+    catch (err) {
+        // No cause kept for these: what `fetch` said is the address itself, password and all, and callers log what they catch.
+        // An address that does not parse may be one whose password has a `/`, `?` or `#` in it.
+        const quotesAddress = (0, ws_url_js_1.carriesCredentials)(url) || (0, http_failure_js_1.isInvalidUrl)(err);
+        if (err instanceof TypeError && quotesAddress)
+            throw new TypeError((0, http_failure_js_1.networkFailureMessage)(err, url));
+        // A refused redirect keeps its original: its words name no secret. An unsendable header's
+        // words quote the key whole, so its cause is dropped — the message already says what to fix.
+        if (err instanceof TypeError && (0, http_failure_js_1.isRedirectRefusal)(err))
+            throw new TypeError((0, http_failure_js_1.networkFailureMessage)(err, url), { cause: err });
+        if (err instanceof TypeError && (0, http_failure_js_1.isUnsendableHeader)(err))
+            throw new TypeError((0, http_failure_js_1.networkFailureMessage)(err, url));
+        throw err;
+    }
+};
+exports.apiFetch = apiFetch;