@hwip/cli 0.0.1 → 0.1.0

package/dist/notify-failure.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * The last failed `hwip notify`, kept so a failure is visible after the fact.
+ *
+ * Every agent hook runs `hwip notify … 2>/dev/null || true`: a hook must never
+ * break the session, so the error output is thrown away. A revoked key, a used
+ * up quota or a dead network then looked exactly like "quiet mode, nothing to
+ * send". `hwip notify` itself writes this file on failure and deletes it on
+ * success — the one writer — so the record survives whatever the hook does
+ * with stderr. Concurrent hooks race last-writer-wins: a failure that finishes
+ * after a newer success stays until the next good push clears it. `hwip verify` and the Claude Code plugin (/hwip-mode, the
+ * SessionStart hook) only read it.
+ *
+ * THE CONTRACT (the plugin reads it with jq and node, so changing it is a
+ * cross-repo change — notify-failure.test.ts pins it):
+ *
+ *   path  ${XDG_STATE_HOME:-~/.local/state}/hwip/last-notify-failure.json
+ *         — the same state dir as the mute and push-mode dials (gate.ts
+ *         stateDir, plugin hooks/gate.sh HWIP_STATE_DIR)
+ *   body  {"v":1,"at":"<ISO 8601 UTC>","kind":"<kind>","status":<int|null>,"code":"<string|null>"}
+ *   kind  no-key | auth | quota | rate-limit | client | server | timeout | network | no-app | unsealed
+ *
+ * `no-app` (NO_APP_DEVICE) and `unsealed` (E2E_REQUIRED) are refusals made here, before the push went out: they
+ * carry no HTTP status, so a reader never shows one as the server's answer.
+ *
+ * A device whose key changed is not recorded here: the pin that replaced it writes
+ * key-changes.json (key-changes.ts), which another process's push cannot clear.
+ *
+ * No message text and nothing from the request: `status` is the HTTP status
+ * and `code` the server's error code (e.g. QUOTA_EXCEEDED), so the file can
+ * never carry a key, a title or a body.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTransientNotifyFailure = exports.describeNotifyFailure = exports.readNotifyFailure = exports.withNotifyFailureRecord = exports.clearNotifyFailure = exports.recordNotifyFailure = exports.classifyNotifyFailure = exports.notifyFailurePath = exports.NOTIFY_FAILURE_KINDS = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const errors_js_1 = require("./errors.js");
+const gate_js_1 = require("./gate.js");
+const private_files_js_1 = require("./private-files.js");
+exports.NOTIFY_FAILURE_KINDS = [
+    'no-key', 'auth', 'quota', 'rate-limit', 'client', 'server', 'timeout', 'network', 'no-app', 'unsealed',
+];
+const notifyFailurePath = () => (0, path_1.join)((0, gate_js_1.stateDir)(), 'last-notify-failure.json');
+exports.notifyFailurePath = notifyFailurePath;
+/** What went wrong, in the contract's terms. Anything that is not an HwipError
+ *  never got an HTTP answer — fetch rejects on DNS, refused or reset. The code is read before the
+ *  status: a refusal made here carries a status (400) the server never sent. */
+const classifyNotifyFailure = (err) => {
+    if (err instanceof errors_js_1.AuthenticationError)
+        return { kind: 'auth', status: err.status, code: err.code };
+    if (err instanceof errors_js_1.QuotaExceededError)
+        return { kind: 'quota', status: err.status, code: err.code };
+    if (err instanceof errors_js_1.HwipError) {
+        const { status, code } = err;
+        if (code === 'NO_APP_DEVICE')
+            return { kind: 'no-app', status: null, code };
+        if (code === 'E2E_REQUIRED')
+            return { kind: 'unsealed', status: null, code };
+        if (code === 'TIMEOUT')
+            return { kind: 'timeout', status: null, code };
+        if (code === 'NETWORK_ERROR')
+            return { kind: 'network', status: null, code: null };
+        if (status === 429)
+            return { kind: 'rate-limit', status, code };
+        if (status >= 500)
+            return { kind: 'server', status, code };
+        return { kind: 'client', status, code };
+    }
+    return { kind: 'network', status: null, code: null };
+};
+exports.classifyNotifyFailure = classifyNotifyFailure;
+/** Best effort: a hook must never fail because its failure could not be noted. */
+const recordNotifyFailure = (failure, now = new Date()) => {
+    const record = { v: 1, at: now.toISOString(), ...failure };
+    const path = (0, exports.notifyFailurePath)();
+    const tmp = `${path}.${process.pid}.tmp`;
+    try {
+        (0, private_files_js_1.mkdirHandedBack)((0, gate_js_1.stateDir)());
+        // Temp + rename: a reader never sees half a file.
+        (0, fs_1.writeFileSync)(tmp, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+        (0, private_files_js_1.handBackToSudoUser)(tmp);
+        (0, fs_1.renameSync)(tmp, path);
+    }
+    catch {
+        try {
+            (0, fs_1.unlinkSync)(tmp);
+        }
+        catch { /* never written */ }
+    }
+};
+exports.recordNotifyFailure = recordNotifyFailure;
+const clearNotifyFailure = () => {
+    try {
+        (0, fs_1.unlinkSync)((0, exports.notifyFailurePath)());
+    }
+    catch { /* nothing recorded */ }
+};
+exports.clearNotifyFailure = clearNotifyFailure;
+/** Run one push attempt and leave the record matching its outcome. */
+const withNotifyFailureRecord = async (send) => {
+    try {
+        const result = await send();
+        (0, exports.clearNotifyFailure)();
+        return result;
+    }
+    catch (err) {
+        (0, exports.recordNotifyFailure)((0, exports.classifyNotifyFailure)(err));
+        throw err;
+    }
+};
+exports.withNotifyFailureRecord = withNotifyFailureRecord;
+/** null when there is no record, or one this version cannot read. */
+const readNotifyFailure = () => {
+    try {
+        const raw = JSON.parse((0, fs_1.readFileSync)((0, exports.notifyFailurePath)(), 'utf-8'));
+        if (raw.v !== 1 || typeof raw.at !== 'string')
+            return null;
+        if (!exports.NOTIFY_FAILURE_KINDS.includes(raw.kind))
+            return null;
+        return {
+            v: 1,
+            at: raw.at,
+            kind: raw.kind,
+            status: typeof raw.status === 'number' ? raw.status : null,
+            code: typeof raw.code === 'string' ? raw.code : null,
+        };
+    }
+    catch {
+        return null;
+    }
+};
+exports.readNotifyFailure = readNotifyFailure;
+const KIND_TEXT = {
+    'no-key': 'no API key — run: hwip install',
+    auth: 'API key rejected — it may have been revoked; run: hwip login',
+    quota: 'push quota used up',
+    'rate-limit': 'rate limited by the server',
+    client: 'request rejected by the server',
+    server: 'server error',
+    timeout: 'request timed out',
+    network: 'could not reach the server',
+    'no-app': 'no app is signed in — sign in to the Hwip app on an iPhone or Android phone',
+    unsealed: 'could not encrypt the push, so nothing was sent — run: hwip verify',
+};
+/** One line for a person: what, when, and the HTTP status when there was one. */
+const describeNotifyFailure = (f) => `last push failed at ${f.at}: ${KIND_TEXT[f.kind]}${f.status === null ? '' : ` (HTTP ${f.status})`}`;
+exports.describeNotifyFailure = describeNotifyFailure;
+/** Transient kinds clear themselves on the next good push; the rest need the user. */
+const isTransientNotifyFailure = (f) => f.kind === 'timeout' || f.kind === 'network' || f.kind === 'server' || f.kind === 'rate-limit';
+exports.isTransientNotifyFailure = isTransientNotifyFailure;

package/dist/opencode-transcript.d.ts

@@ -0,0 +1,139 @@
+/**
+ * opencode's session store, read into the events the timeline draws.
+ *
+ * opencode keeps no transcript file. 2.x writes every session to SQLite
+ * (`opencode.db`, WAL), one `session_message` row per user message and per
+ * assistant step, and rewrites an assistant row in place while it streams. So
+ * this file is both halves the other agents split: a reader that asks the
+ * database what changed (`readOpencodeTranscript`, the `TranscriptReader`
+ * behind the opencode row) and a projector for what it hands back
+ * (`projectOpencodeEntries`).
+ *
+ * Shape measured 2026-10-10 against opencode 2.0.24 — the schema with
+ * `.schema`, the JSON with `json_each` key and type counts over 3,965 rows on
+ * this machine, and a scratch store written by sessions run for the purpose.
+ * No conversation text was opened.
+ *
+ *  - `session_message(id, session_id, type, seq, time_created, time_updated,
+ *    data)`, `seq` increasing per session. `type` is `user` · `assistant` ·
+ *    `system` · `synthetic` · `idle` · `compaction` · `*-switched`; only the
+ *    first two are drawn.
+ *  - user `data`: `{ text, time: { created }, files, agents, skills }`.
+ *  - assistant `data`: `{ model: { id, providerID }, content: [...], tokens:
+ *    { input, output, reasoning, cache: { read, write } }, time: { created,
+ *    completed?, streamed? }, finish, … }` — `time.completed` is set once the
+ *    step is over. `content` items are `{ type: "text", text }`,
+ *    `{ type: "reasoning", … }` and `{ type: "tool", id, name, state: { status,
+ *    input, content: [{ type: "text", text }], error }, time }`; a finished
+ *    call is `completed` or `error`.
+ *  - 1.x wrote `session` · `message` · `part` instead. 2.x leaves those alone
+ *    and this file does not read them.
+ *
+ * The lines the reader hands over are `TurnEvent`s already, one JSON object
+ * each, so the projector only checks them. The work of deciding what is new
+ * lives in `opencodeLinesOf`, which is pure and is where the tests point.
+ */
+import { type TailRead, type TailState, type TranscriptProjector } from './transcript-tail.js';
+/** Where opencode 2.x keeps its store, by the rules opencode itself follows (`opencode debug paths db`, 2.0.24). */
+export declare const opencodeDbPath: (env?: NodeJS.ProcessEnv) => string;
+/**
+ * A session id as opencode mints them (`ses_` + base62, measured). The query
+ * below has nowhere to bind a parameter (`sqliteJson` runs the `sqlite3`
+ * binary), so an id goes into the SQL text only after it passes this.
+ */
+export declare const OPENCODE_SESSION_ID: RegExp;
+/**
+ * The transcript "path" an opencode pane resolves to: the store and the session
+ * in one string. A string because every consumer compares and logs paths, and
+ * because the session changing — a new one in the same pane — has to read as
+ * the path changing, which is what makes `turn-watch` start over on it.
+ */
+export declare const opencodeSourcePath: (db: string, sessionId: string) => string;
+/** One `content` item, reduced in SQL to the fields drawn — a tool's input and output can be megabytes. */
+export interface OpencodeItem {
+    type?: string | null;
+    id?: string | null;
+    name?: string | null;
+    text?: string | null;
+    status?: string | null;
+    target?: string | null;
+    lines?: number | null;
+    at?: number | null;
+}
+/** One `session_message` row as the query below returns it. */
+export interface OpencodeRow {
+    id: string;
+    seq: number;
+    type: string;
+    created: number;
+    completed?: number | null;
+    text?: string | null;
+    model?: string | null;
+    out?: number | null;
+    input?: number | null;
+    cacheRead?: number | null;
+    cacheWrite?: number | null;
+    /** `error.type` of a step that failed (`provider.quota`, `aborted`, …). */
+    errorType?: string | null;
+    errorText?: string | null;
+    items?: OpencodeItem[] | string | null;
+}
+/** Rows read on the first look at a session — enough for the turn in flight and a screen above it. */
+export declare const OPENCODE_BACKFILL_ROWS = 200;
+/** Rows read per look after that. */
+export declare const OPENCODE_ROWS_PER_READ = 500;
+/** How far behind the newest row an unfinished one may hold the read position. */
+export declare const OPENCODE_OPEN_WINDOW = 200;
+/** The fewest milliseconds between two queries for one session. */
+export declare const OPENCODE_MIN_QUERY_MS = 1000;
+/**
+ * The rows of one session from `from` on, or its last `OPENCODE_BACKFILL_ROWS`
+ * when `from` is null. Exported for the test that pins the id check.
+ */
+export declare const opencodeRowsSql: (sessionId: string, from: number | null) => string;
+/**
+ * What these rows add to what was already sent, and where the next read starts.
+ *
+ * Every piece of a row gets a key (`<seq>:<part><index>`), and a key sent once
+ * is never sent again. A user row is final when written. An assistant row is
+ * not: its text is sent once something follows it in the row or the row is
+ * closed, a tool call once it runs, its result once the call has one, and
+ * the step's token count and any error when the step is finished. A row is
+ * closed when it is finished, when a later assistant step exists (opencode
+ * starts one only after the last is over, so an unfinished one behind it died
+ * mid-stream), or when it falls out of the `OPENCODE_OPEN_WINDOW` rows behind
+ * the newest — closing is what sends a dead step's last words, which nothing
+ * would otherwise send. `from` stays on the oldest row still open, so the next
+ * read sees it again. `emitted` keeps only the keys at or after `from`;
+ * nothing before it is read again.
+ */
+export declare const opencodeLinesOf: (rows: readonly OpencodeRow[], sent: {
+    from: number;
+    emitted: readonly string[];
+}) => {
+    lines: string[];
+    from: number;
+    emitted: string[];
+};
+export interface OpencodeReadDeps {
+    /** Rows of a SQLite file, null when the read failed (`sqliteJson`). */
+    query: (db: string, sql: string) => unknown[] | null;
+    /** The store's files, size and mtime — any write to the session shows up in one of them. */
+    stamp?: (db: string) => string | null;
+    now?: () => number;
+}
+/**
+ * What changed in one opencode session since `prev`, or null when nothing did
+ * — the store's files have not moved, the last query was under
+ * `OPENCODE_MIN_QUERY_MS` ago, or the store cannot be read. The WAL moves on
+ * every write by every opencode session on this machine, so the time floor is
+ * what keeps a busy neighbour from turning a 500 ms poll into a `sqlite3`
+ * spawn per tick.
+ */
+export declare const readOpencodeTranscript: (path: string, prev: TailState | null, deps: OpencodeReadDeps) => TailRead | null;
+/**
+ * The reader's lines back into events. They were built as events, so this
+ * only refuses what is not one and names what the reader marked unknown.
+ */
+export declare const projectOpencodeEntries: TranscriptProjector;
+//# sourceMappingURL=opencode-transcript.d.ts.map