@expitc/termad 0.0.0-stage → 0.1.1

package/dist/cli.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * termad — opt-in, reversible text ads for terminal AI CLIs.
+ *
+ *   termad install [claude|codex|opencode|gemini ...]   install (default: all opted-in)
+ *   termad uninstall [surface ...]                      full revert
+ *   termad audit                                        re-verify every recorded change
+ *   termad status                                       what's installed where
+ *   termad sync                                         fetch ad now, write cache
+ *   termad watch                                        poll endpoint, refresh cache
+ *   termad set-endpoint <url>                           point at your ad server
+ *   termad style line|banner                            render style
+ */
+import { ALL_SURFACES, loadConfig, saveConfig } from "./core/config.js";
+import { readSync } from "node:fs";
+import { paths, termadHome } from "./core/paths.js";
+import { readAdCache, fetchAd } from "./core/source.js";
+import { install, uninstall, sync, planInstall } from "./install.js";
+import { surfaces } from "./surfaces/surfaces.js";
+import { isWrapped } from "./surfaces/wrap.js";
+import { isStatuslineInstalled } from "./surfaces/statusline.js";
+import { render } from "./render/render.js";
+import { audit, auditFailed } from "./audit.js";
+const [cmd, ...args] = process.argv.slice(2);
+import { reportDisplays } from "./report.js";
+function confirmPlan(surfaces, force = false) {
+    if (args.includes("--yes"))
+        return;
+    const plan = planInstall(surfaces, force);
+    console.log("termad will make these changes (nothing happens without your consent):\n");
+    for (const p of plan) {
+        console.log(`  ${p.surface.padEnd(9)} ${p.action}`);
+        console.log(`  ${"".padEnd(9)} → ${p.target}`);
+    }
+    console.log(`
+  • every change is sha256-recorded in ${paths.manifest()}
+  • \`termad uninstall\` restores everything byte-for-byte
+  • \`termad audit\` re-verifies all of it at any time`);
+    if (!process.stdin.isTTY) {
+        console.error("\nnon-interactive session: re-run with --yes to confirm");
+        process.exit(1);
+    }
+    process.stdout.write("\nProceed? [y/N] ");
+    const answer = readlineSync();
+    if (!/^y(es)?$/i.test(answer.trim())) {
+        console.log("aborted — nothing changed");
+        process.exit(1);
+    }
+}
+function readlineSync() {
+    // Minimal blocking read for the consent prompt (no deps).
+    try {
+        const buf = Buffer.alloc(1024);
+        const n = readSync(0, buf, 0, 1024, null);
+        return buf.subarray(0, n).toString("utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function parseSurfaces(argv) {
+    const picked = argv.filter((a) => ALL_SURFACES.includes(a));
+    return picked.length ? picked : undefined;
+}
+function printOutcomes(out) {
+    for (const o of out)
+        console.log(`  ${o.ok ? "✓" : "✗"} ${o.surface.padEnd(9)} ${o.detail}`);
+    if (out.some((o) => !o.ok))
+        process.exitCode = 1;
+}
+switch (cmd) {
+    case "install": {
+        const force = args.includes("--force");
+        confirmPlan(parseSurfaces(args), force);
+        const out = await install(parseSurfaces(args), { force });
+        printOutcomes(out);
+        const ad = readAdCache();
+        if (ad)
+            console.log(`\n  ad cache: ${paths.adCache()}\n  ${render(ad, loadConfig().style)}`);
+        const rows = audit();
+        if (rows.length)
+            console.log(`  audit: ${rows.length} change(s) recorded → \`termad audit\` to re-verify`);
+        break;
+    }
+    case "uninstall": {
+        const out = uninstall(parseSurfaces(args));
+        printOutcomes(out);
+        break;
+    }
+    case "status": {
+        const cfg = loadConfig();
+        console.log(`termad home : ${termadHome()}`);
+        console.log(`endpoint    : ${cfg.endpoint ?? "(none — local/house ads only)"}`);
+        console.log(`style       : ${cfg.style}`);
+        console.log("");
+        for (const s of surfaces) {
+            const bin = s.locate();
+            const state = s.id === "claude"
+                ? isStatuslineInstalled()
+                    ? "installed (statusline)"
+                    : "—"
+                : bin && isWrapped(bin)
+                    ? `installed (wrapper)`
+                    : "—";
+            console.log(`  ${s.id.padEnd(9)} ${String(bin ?? "not found").padEnd(42)} ${state}`);
+        }
+        const ad = readAdCache();
+        if (ad)
+            console.log(`\ncached ad:\n${render(ad, cfg.style)}`);
+        break;
+    }
+    case "audit": {
+        const rows = audit();
+        if (!rows.length) {
+            console.log(`  no recorded changes (nothing installed by this CLI yet)`);
+            break;
+        }
+        console.log(`  ${"SURFACE".padEnd(9)} ${"STATUS".padEnd(9)} DETAIL`);
+        for (const r of rows) {
+            const icon = r.status === "ok" ? "✓" : r.status === "tampered" || r.status === "missing" ? "✗" : "•";
+            console.log(`  ${icon} ${r.surface.padEnd(9)} ${r.status.padEnd(9)} ${r.detail}`);
+            console.log(`    ${"".padEnd(9)} ${"".padEnd(9)} ${r.target}`);
+        }
+        if (auditFailed(rows)) {
+            console.log(`\n  integrity problems found — see entries above`);
+            process.exit(1);
+        }
+        console.log(`\n  all recorded changes verified (sha256)`);
+        break;
+    }
+    case "sync": {
+        const text = await sync();
+        const rep = await reportDisplays();
+        console.log(`  ad cache refreshed: ${text}`);
+        if (rep)
+            console.log(`  display report: ${rep}`);
+        else
+            console.log(`  display report: nothing pending (or endpoint unreachable — counts retained)`);
+        break;
+    }
+    case "watch": {
+        const cfg = loadConfig();
+        if (!cfg.endpoint) {
+            console.error("  no endpoint configured — run: termad set-endpoint <url>");
+            process.exit(1);
+        }
+        console.log(`  watching ${cfg.endpoint} every ${cfg.pollSeconds}s (ctrl-c to stop)`);
+        for (;;) {
+            const text = await sync().catch(() => null);
+            if (text)
+                process.stdout.write(`  ${new Date().toISOString()}  ${text}\n`);
+            await new Promise((r) => setTimeout(r, cfg.pollSeconds * 1000));
+        }
+        break;
+    }
+    case "set-endpoint": {
+        if (!args[0]) {
+            console.error("  usage: termad set-endpoint <url>");
+            process.exit(1);
+        }
+        const cfg = loadConfig();
+        cfg.endpoint = args[0].replace(/\/+$/, "");
+        saveConfig(cfg);
+        console.log(`  endpoint set: ${cfg.endpoint}`);
+        // Pull the first ad immediately so the cache isn't empty.
+        const ad = await fetchAd("claude").catch(() => null);
+        if (ad)
+            console.log(`  first ad: ${ad.text}`);
+        break;
+    }
+    case "style": {
+        if (args[0] !== "line" && args[0] !== "banner") {
+            console.error("  usage: termad style line|banner");
+            process.exit(1);
+        }
+        const cfg = loadConfig();
+        cfg.style = args[0];
+        saveConfig(cfg);
+        console.log(`  style set: ${args[0]}`);
+        break;
+    }
+    default:
+        console.log(`termad — opt-in, reversible text ads for terminal AI CLIs
+
+  termad install [surface ...]     install (claude | codex | opencode | gemini)
+  termad uninstall [surface ...]   remove everything termad added
+  termad audit                     re-verify every recorded change (sha256)
+  termad status                    show installed surfaces + cached ad
+  termad set-endpoint <url>        point at your ad server
+  termad sync                      fetch ad now + report pending displays
+  termad watch                     poll the endpoint continuously
+  termad style line|banner         render style`);
+}

package/dist/core/ad.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The smallest possible ad: one line of wording, optionally a URL.
+ * No images, no beacons, no HTML — the terminal renders it.
+ */
+export interface Ad {
+    /** Unique id (server-assigned or slug of the text). */
+    id: string;
+    /** The wording shown to the user. Kept short — terminal line. */
+    text: string;
+    /** Click target. Rendered as a bare URL so the terminal auto-links it. */
+    url?: string;
+    /** Optional second line (e.g. "sponsored by …"). */
+    sub?: string;
+}
+/** Shape the HTTP endpoint returns. */
+export interface AdResponse {
+    ad: Ad;
+}
+export declare function isValidAd(v: unknown): v is Ad;

package/dist/core/ad.js

@@ -0,0 +1,12 @@
+export function isValidAd(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const a = v;
+    return (typeof a.id === "string" &&
+        a.id.length > 0 &&
+        typeof a.text === "string" &&
+        a.text.length > 0 &&
+        a.text.length <= 300 &&
+        (a.url === undefined ||
+            (typeof a.url === "string" && /^https?:\/\//.test(a.url) && a.url.length <= 500)));
+}

package/dist/core/config.d.ts

@@ -0,0 +1,18 @@
+export type SurfaceId = "claude" | "codex" | "opencode" | "gemini";
+export declare const ALL_SURFACES: SurfaceId[];
+export interface TermadConfig {
+    /** Your ad endpoint. GET <endpoint>/v1/ad?surface=<s>&uid=<u> → {ad:{...}} */
+    endpoint: string | null;
+    /** Stable anonymous install id (rotation/frequency capping server-side). */
+    uid: string;
+    /** How often `termad watch` re-fetches, seconds. */
+    pollSeconds: number;
+    /** Which surfaces are opted in. */
+    surfaces: Record<SurfaceId, boolean>;
+    /** "line" | "banner" — render style in the terminal. */
+    style: "line" | "banner";
+}
+export declare function loadConfig(): TermadConfig;
+export declare function saveConfig(cfg: TermadConfig): void;
+/** Atomic-ish write so wrappers never read a half-written cache. */
+export declare function writeFileAtomic(path: string, data: string): void;

package/dist/core/config.js

@@ -0,0 +1,33 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { paths, termadHome } from "./paths.js";
+export const ALL_SURFACES = ["claude", "codex", "opencode", "gemini"];
+function defaultConfig() {
+    return {
+        endpoint: null,
+        uid: crypto.randomUUID(),
+        pollSeconds: 900,
+        surfaces: { claude: false, codex: false, opencode: false, gemini: false },
+        style: "line",
+    };
+}
+export function loadConfig() {
+    try {
+        const raw = JSON.parse(readFileSync(paths.config(), "utf8"));
+        return { ...defaultConfig(), ...raw, surfaces: { ...defaultConfig().surfaces, ...raw.surfaces } };
+    }
+    catch {
+        return defaultConfig();
+    }
+}
+export function saveConfig(cfg) {
+    mkdirSync(termadHome(), { recursive: true });
+    writeFileSync(paths.config(), JSON.stringify(cfg, null, 2) + "\n");
+}
+/** Atomic-ish write so wrappers never read a half-written cache. */
+export function writeFileAtomic(path, data) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = path + ".tmp";
+    writeFileSync(tmp, data);
+    renameSync(tmp, path);
+}

package/dist/core/manifest.d.ts

@@ -0,0 +1,20 @@
+export interface ManifestEntry {
+    surface: string;
+    target: string;
+    mechanism: "wrapper" | "statusline";
+    /** Backup holding the pristine original (null if none was needed). */
+    backup: string | null;
+    sha256Original: string | null;
+    sha256Installed: string | null;
+    at: string;
+}
+export interface Manifest {
+    version: 1;
+    entries: ManifestEntry[];
+}
+export declare function sha256File(p: string): string | null;
+export declare function loadManifest(): Manifest;
+export declare function saveManifest(m: Manifest): void;
+/** Record (or replace) the entry for one surface+target pair. */
+export declare function recordEntry(e: Omit<ManifestEntry, "at">): void;
+export declare function removeEntries(surface: string): void;

package/dist/core/manifest.js

@@ -0,0 +1,42 @@
+/**
+ * Tamper-evident audit manifest: every change termad makes is recorded with
+ * sha256 fingerprints of the original and the installed file. `termad audit`
+ * re-verifies the chain, so any modification — by termad, the user, the CLI
+ * itself, or a third party — is attributable.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { paths } from "./paths.js";
+import { writeFileAtomic } from "./config.js";
+export function sha256File(p) {
+    try {
+        return createHash("sha256").update(readFileSync(p)).digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+export function loadManifest() {
+    try {
+        const m = JSON.parse(readFileSync(paths.manifest(), "utf8"));
+        if (m?.version === 1 && Array.isArray(m.entries))
+            return m;
+    }
+    catch { }
+    return { version: 1, entries: [] };
+}
+export function saveManifest(m) {
+    writeFileAtomic(paths.manifest(), JSON.stringify(m, null, 2) + "\n");
+}
+/** Record (or replace) the entry for one surface+target pair. */
+export function recordEntry(e) {
+    const m = loadManifest();
+    m.entries = m.entries.filter((x) => !(x.surface === e.surface && x.target === e.target));
+    m.entries.push({ ...e, at: new Date().toISOString() });
+    saveManifest(m);
+}
+export function removeEntries(surface) {
+    const m = loadManifest();
+    m.entries = m.entries.filter((x) => x.surface !== surface);
+    saveManifest(m);
+}

package/dist/core/paths.d.ts

@@ -0,0 +1,24 @@
+/** All termad state lives under ~/.termad (override with TERMAD_HOME). */
+export declare function termadHome(): string;
+export declare const paths: {
+    config: () => string;
+    /** Cache file the wrappers read: line 1 = text, line 2 = url, line 3 = sub. */
+    adCache: () => string;
+    /** Claude statusline launcher installed into ~/.claude/settings.json. */
+    statuslineScript: () => string;
+    /** Captured pre-install statusLine (chain capture, like claude does natively). */
+    prevStatusline: () => string;
+    log: () => string;
+    /** Tamper-evident record of every change (`termad audit` re-verifies it). */
+    manifest: () => string;
+    /**
+     * Display counter: one line of ad id per render, appended by the wrapper,
+     * reported in batches by `termad sync` (never per-render — no network on
+     * the CLI hot path, no per-view beacon).
+     */
+    displayLog: () => string;
+};
+/** Wrapper backup for a binary/shim lives next to it: <bin>.termad-orig. */
+export declare function backupPath(target: string): string;
+export declare const WRAPPER_MARKER = "===== TERMAD-CLI =====";
+export declare const OVERLAY_MARKER = "===== TERMAD-OVERLAY =====";

package/dist/core/paths.js

@@ -0,0 +1,30 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** All termad state lives under ~/.termad (override with TERMAD_HOME). */
+export function termadHome() {
+    return process.env.TERMAD_HOME || join(homedir(), ".termad");
+}
+export const paths = {
+    config: () => join(termadHome(), "config.json"),
+    /** Cache file the wrappers read: line 1 = text, line 2 = url, line 3 = sub. */
+    adCache: () => join(termadHome(), "ad.txt"),
+    /** Claude statusline launcher installed into ~/.claude/settings.json. */
+    statuslineScript: () => join(termadHome(), "statusline.mjs"),
+    /** Captured pre-install statusLine (chain capture, like claude does natively). */
+    prevStatusline: () => join(termadHome(), "prev-statusline.json"),
+    log: () => join(termadHome(), "termad.log"),
+    /** Tamper-evident record of every change (`termad audit` re-verifies it). */
+    manifest: () => join(termadHome(), "manifest.json"),
+    /**
+     * Display counter: one line of ad id per render, appended by the wrapper,
+     * reported in batches by `termad sync` (never per-render — no network on
+     * the CLI hot path, no per-view beacon).
+     */
+    displayLog: () => join(termadHome(), "display.log"),
+};
+/** Wrapper backup for a binary/shim lives next to it: <bin>.termad-orig. */
+export function backupPath(target) {
+    return target + ".termad-orig";
+}
+export const WRAPPER_MARKER = "===== TERMAD-CLI =====";
+export const OVERLAY_MARKER = "===== TERMAD-OVERLAY =====";

package/dist/core/source.d.ts

@@ -0,0 +1,18 @@
+import { Ad } from "./ad.js";
+import { type SurfaceId } from "./config.js";
+/** Last-good ad survives endpoint outages (write-through cache). */
+export declare function fetchAd(surface: SurfaceId): Promise<Ad>;
+/**
+ * Write the ad cache the wrappers read:
+ *   line 1 = wording, line 2 = click URL, line 3 = sub, line 4 = ad id.
+ * Lines 2/3 are padded with "-" when absent so line-numbered readers
+ * (including cmd's `for /f`, which skips blank lines) stay positional.
+ * Wrappers only ever read this file — zero network in the hot path.
+ * Line 4 (ad id) is what the wrapper appends to the display counter.
+ */
+export declare function writeAdCache(ad: Ad): void;
+export declare function readAdCache(): {
+    text: string;
+    url?: string;
+    sub?: string;
+} | null;

package/dist/core/source.js

@@ -0,0 +1,78 @@
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { isValidAd } from "./ad.js";
+import { loadConfig, writeFileAtomic } from "./config.js";
+import { paths, termadHome } from "./paths.js";
+const FETCH_TIMEOUT_MS = 4000;
+/** Fallback ad if nothing is configured or the endpoint is down. */
+const HOUSE_AD = { id: "house:default", text: "termad — ads for your terminal" };
+/** Last-good ad survives endpoint outages (write-through cache). */
+export async function fetchAd(surface) {
+    const cfg = loadConfig();
+    if (cfg.endpoint) {
+        try {
+            const url = `${cfg.endpoint.replace(/\/+$/, "")}/v1/ad?surface=${surface}&uid=${cfg.uid}`;
+            const res = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+            if (res.ok) {
+                const body = (await res.json());
+                if (isValidAd(body.ad)) {
+                    writeLastGood(body.ad);
+                    return body.ad;
+                }
+            }
+        }
+        catch {
+            // fall through to cache / house ad — never break the CLI over an ad
+        }
+    }
+    return lastGood() ?? HOUSE_AD;
+}
+function lastGoodPath() {
+    return paths.adCache() + ".json";
+}
+function writeLastGood(ad) {
+    try {
+        mkdirSync(termadHome(), { recursive: true });
+        writeFileSync(lastGoodPath(), JSON.stringify(ad));
+    }
+    catch { }
+}
+function lastGood() {
+    try {
+        const ad = JSON.parse(readFileSync(lastGoodPath(), "utf8"));
+        return isValidAd(ad) ? ad : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write the ad cache the wrappers read:
+ *   line 1 = wording, line 2 = click URL, line 3 = sub, line 4 = ad id.
+ * Lines 2/3 are padded with "-" when absent so line-numbered readers
+ * (including cmd's `for /f`, which skips blank lines) stay positional.
+ * Wrappers only ever read this file — zero network in the hot path.
+ * Line 4 (ad id) is what the wrapper appends to the display counter.
+ */
+export function writeAdCache(ad) {
+    const lines = [
+        ad.text.replace(/[\r\n]+/g, " ").trim(),
+        ad.url ?? "-",
+        ad.sub ? ad.sub.replace(/[\r\n]+/g, " ").trim() : "-",
+        ad.id || "-",
+    ];
+    writeFileAtomic(paths.adCache(), lines.join("\n") + "\n");
+}
+export function readAdCache() {
+    try {
+        const raw = readFileSync(paths.adCache(), "utf8").split("\n");
+        const text = (raw[0] ?? "").trim();
+        if (!text)
+            return null;
+        const url = (raw[1] ?? "").trim();
+        const sub = (raw[2] ?? "").trim();
+        return { text, url: url && url !== "-" ? url : undefined, sub: sub && sub !== "-" ? sub : undefined };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { type Ad, isValidAd } from "./core/ad.js";
+export { fetchAd, writeAdCache, readAdCache } from "./core/source.js";
+export { loadConfig, saveConfig, type SurfaceId, type TermadConfig } from "./core/config.js";
+export { install, uninstall, sync } from "./install.js";
+export { render, renderLine, renderBanner } from "./render/render.js";
+export { installWrapper, uninstallWrapper, isWrapped, locateCli } from "./surfaces/wrap.js";
+export { installStatusline, uninstallStatusline, isStatuslineInstalled } from "./surfaces/statusline.js";
+export { surfaces, getSurface, type Surface } from "./surfaces/surfaces.js";
+export { paths, termadHome, backupPath } from "./core/paths.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export { isValidAd } from "./core/ad.js";
+export { fetchAd, writeAdCache, readAdCache } from "./core/source.js";
+export { loadConfig, saveConfig } from "./core/config.js";
+export { install, uninstall, sync } from "./install.js";
+export { render, renderLine, renderBanner } from "./render/render.js";
+export { installWrapper, uninstallWrapper, isWrapped, locateCli } from "./surfaces/wrap.js";
+export { installStatusline, uninstallStatusline, isStatuslineInstalled } from "./surfaces/statusline.js";
+export { surfaces, getSurface } from "./surfaces/surfaces.js";
+export { paths, termadHome, backupPath } from "./core/paths.js";

package/dist/install.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Install / uninstall orchestration across all opted-in surfaces.
+ *
+ * Every change is recorded in the sha256 audit manifest BEFORE the user
+ * consents (the plan is shown) and re-verified by `termad audit`.
+ */
+import { type SurfaceId } from "./core/config.js";
+export interface SurfaceOutcome {
+    surface: SurfaceId;
+    ok: boolean;
+    detail: string;
+}
+export interface PlanItem {
+    surface: SurfaceId;
+    target: string;
+    action: string;
+}
+/** What `termad install` would change — shown to the user before consent. */
+export declare function planInstall(surfaces?: SurfaceId[], force?: boolean): PlanItem[];
+/** Fetch the ad, write the cache, then install the opted-in surfaces. */
+export declare function install(surfaces?: SurfaceId[], opts?: {
+    force?: boolean;
+}): Promise<SurfaceOutcome[]>;
+export declare function uninstall(surfaces?: SurfaceId[]): SurfaceOutcome[];
+/** Refresh the ad cache (used by `termad watch` and cron). */
+export declare function sync(): Promise<string>;