@expitc/termad 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EXPITC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/POLICY.md

@@ -0,0 +1,91 @@
+# termad — Content & Platform Policy
+
+This policy governs (a) ads served through a termad endpoint, and (b) the
+termad platform (advertisers, runners, revenue share). It exists so every
+party — advertiser, runner, and the person who sees the ad — knows exactly
+what is and isn't allowed. terms of use for the platform should reference
+this file.
+
+## 1. What an ad is
+
+An ad in termad is **one line of plain text plus an optional URL**, printed
+above the CLI's own output with a fixed `[ad]` label. It is never mixed into
+the CLI's output, never styled to look like the CLI's own messages, and is
+always removable with `termad uninstall`.
+
+## 2. Allowed ad content
+
+- Honest, legal products and services aimed at developers.
+- Clear claims. No "your machine is infected" urgency, no fake system
+  warnings, no impersonation of terminals, OS dialogs, or AI assistants.
+- URLs must resolve to the advertised destination (no cloaking, no
+  redirect chains to unrelated domains).
+
+## 3. Prohibited ad content
+
+- Malware, phishing, credential harvesting, or any link whose landing page
+  would fail a safe-browsing check.
+- Illegal goods/services; adult content; violence; deceptive financial
+  offers ("guaranteed returns"); counterfeit goods.
+- Content that mimics terminal output, error messages, or the branding of
+  claude/codex/opencode/gemini or their companies.
+- Ads claiming affiliation with, or endorsement by, the CLIs termad runs in.
+- Self-promotion loops: an ad for an endpoint is fine; an ad that instructs
+  viewers to click it, or to run commands that generate ad impressions, is
+  not (see §5).
+
+Enforcement: the operator of an endpoint is responsible for its inventory.
+Anyone may propose additions/exceptions via PR to this file; removals for
+policy violations are immediate.
+
+## 4. Measurement honesty
+
+- An **impression** means: the ad was rendered into a terminal the viewer
+  was already using. Counting starts when the wrapper prints the line.
+- termad clients never click their own ads and never simulate engagement.
+  No auto-follow of ad URLs, no beacon on render, no fingerprinting, no
+  cross-site identifiers. The viewer's `uid` is a random local identifier
+  used only for per-install ad rotation and revenue accounting.
+- Reported numbers in the dashboard are raw counts (per ad, per surface)
+  — not modeled, not extrapolated. Gaps (e.g. offline periods) are gaps.
+
+## 5. Revenue share (the 50%)
+
+- Advertisers prepay credit (via the platform's payment provider).
+- For each reported impression: **50% of the ad's CPM value is credited to
+  the runner** (the person/organization whose terminals display the ad),
+  50% stays with the platform to cover payment processing and operations.
+- Runners never need to (and never should) click ads, ask others to click,
+  or inflate counts mechanically — counts come from actual renders only.
+- Payouts are made against the runner's recorded balance; the ledger in
+  the dashboard is the source of truth and shows every credited impression.
+
+## 6. Trademarks & non-affiliation
+
+`claude`, `codex`, `opencode`, and `gemini` are trademarks of their
+respective owners. termad uses these names only to identify compatible
+software. **termad is not affiliated with, sponsored by, or endorsed by
+Anthropic, OpenAI, Google, or the opencode project.** Ad content may not
+claim such affiliation either.
+
+## 7. Privacy
+
+- Collected: random install `uid`, impression timestamps, ad id, surface.
+- Not collected: prompts, conversations, file paths, machine identifiers,
+  IP-based profiles. Impressions are counted by the client and reported in
+  batches; no per-render network activity occurs.
+- Deletion: `termad uninstall` removes local state; operators may purge
+  `uid` records from their ledger at any time on request.
+
+## 8. Reversibility commitment
+
+Every termad change is (a) shown to the user before consent,
+(b) sha256-recorded in a local manifest, and (c) fully reverted by
+`termad uninstall`. `termad audit` re-verifies (b) and refuses to restore
+from a backup that fails verification.
+
+## 9. Contact / takedown
+
+Report policy-violating ads to the operator of the endpoint that served
+them (the endpoint is always identifiable by the serving domain). For
+platform-level issues, open an issue in this repository.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# termad
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Opt-in, fully reversible text ads for terminal AI CLIs — **claude**, **codex**,
+**opencode**, **gemini**. Your words, your endpoint, one line in the terminal.
+
+```
+$ opencode --version
+
+  [ad]  termad — put your words in the terminal
+  https://github.com/yourname/termad
+
+opencode v2.1.1
+```
+
+## How it works
+
+| Surface | Mechanism | Risk |
+|---|---|---|
+| **claude** | Public `statusLine` in `~/.claude/settings.json` (chained — your existing statusline is captured and still runs) | none — documented feature |
+| **codex / opencode / gemini** | Marker-tagged wrapper script in front of the binary; original backed up as `<bin>.termad-orig` | fully reversible |
+
+- Ads are fetched from **your** HTTP endpoint once, cached to
+  `~/.termad/ad.txt`, and printed by the wrapper — zero network in the CLI's
+  hot path, and CLIs keep working if the endpoint is down.
+- Click = a bare URL the terminal auto-links. No tracking, no beacons.
+- `termad uninstall` restores every binary and your settings verbatim.
+  If a CLI self-updates over the wrapper, termad detects the marker is gone
+  and leaves the new binary alone.
+
+## Quick start
+
+```sh
+npm install && npm run build
+
+# 1. start your ad server (zero deps)
+node server/server.mjs 8787
+
+# 2. point termad at it
+node dist/cli.js set-endpoint http://localhost:8787
+
+# 3. install (choose surfaces, or omit for all opted-in)
+node dist/cli.js install claude codex opencode
+
+# 4. anytime: full revert
+node dist/cli.js uninstall
+```
+
+Other commands: `status`, `sync`, `watch` (poll endpoint), `style line|banner`.
+
+## Trust & compliance
+
+```sh
+node dist/cli.js install      # shows the exact plan, asks for consent
+                              # (non-interactive: --yes required)
+node dist/cli.js audit        # sha256-verifies every recorded change
+```
+
+- **Consent first** — nothing is modified until the plan (files, backups)
+  is shown and confirmed.
+- **Tamper-evident** — every change is recorded in `~/.termad/manifest.json`
+  with sha256 of original and installed content. `audit` flags tampering,
+  and `uninstall` *refuses* to restore from a backup that fails its check.
+- **No tracking** — no beacons, no click counting, no fingerprints. One
+  impression = one render, counted locally, reported in batches.
+- Content rules: [POLICY.md](POLICY.md).
+- **Non-affiliation**: claude, codex, opencode, and gemini are trademarks of
+  their respective owners (Anthropic, OpenAI, Google, opencode project).
+  termad is not affiliated with, sponsored by, or endorsed by any of them.
+
+## Ad inventory
+
+Edit `server/ads.json` — plain JSON, hot-reloads every 30s:
+
+```json
+{ "ads": [
+  { "id": "sponsor:acme", "text": "Acme — ship faster", "url": "https://acme.dev" }
+]}
+```
+
+Round-robin rotation per install `uid`; impressions counted in memory
+(`GET /v1/stats`). Swap in a DB when it's real.
+
+## Programmatic use
+
+```ts
+import { install, uninstall, renderBanner, fetchAd } from "termad";
+```
+
+## Design notes
+
+- **Never breaks the CLI**: every ad operation is wrapped; worst case is a
+  missing banner.
+- **Opt-in per surface**, stored in `~/.termad/config.json`.
+- `TERMAD_HOME`, `TERMAD_<CLI>_BIN`, `TERMAD_CLAUDE_HOME` override all paths
+  (used for testing; nothing touches your real setup without `install`).

package/assets/wrapper.cmd.asset

@@ -0,0 +1,31 @@
+@ECHO off
+REM ===== TERMAD-CLI =====
+REM Reversible termad wrapper. Prints a one-line ad banner read from
+REM "__TERMAD_AD__" (line 1 = wording, line 2 = click URL, line 4 = ad id)
+REM then delegates to the pristine binary at "__TERMAD_BACKUP__".
+REM Each render is appended to "__TERMAD_COUNT__" (one line of ad id — the
+REM batch counter `termad sync` reports; no network happens here).
+REM Restore: copy the backup over this file, or run `termad uninstall`.
+setlocal enabledelayedexpansion
+set "__AD_FILE=__TERMAD_AD__"
+set "__COUNT_FILE=__TERMAD_COUNT__"
+set "__AD="
+set "__URL="
+set "__ID="
+set "__N=0"
+if exist "%__AD_FILE%" (
+  for /f "usebackq delims=" %%A in ("%__AD_FILE%") do (
+    if !__N! EQU 0 set "__AD=%%A"
+    if !__N! EQU 1 set "__URL=%%A"
+    if !__N! EQU 3 set "__ID=%%A"
+    set /a __N+=1
+  )
+)
+if defined __AD (
+  echo.
+  echo   [ad]  !__AD!
+  if defined __URL if not "!__URL!"=="-" echo   !__URL!
+  echo.
+  if defined __ID echo !__ID!>>"%__COUNT_FILE%"
+)
+endlocal & call "__TERMAD_BACKUP__" %*

package/assets/wrapper.sh.asset

@@ -0,0 +1,29 @@
+#!/bin/sh
+# ===== TERMAD-CLI =====
+# Reversible termad wrapper. Prints a one-line ad banner read from
+# "__TERMAD_AD__" (line 1 = wording, line 2 = click URL, line 4 = ad id)
+# then exec's the pristine binary at "__TERMAD_BACKUP__".
+# Each render is appended to "__TERMAD_COUNT__" (one line of ad id — the
+# batch counter `termad sync` reports; no network happens here).
+# Restore: copy the backup over this file, or run `termad uninstall`.
+AD_FILE="__TERMAD_AD__"
+COUNT_FILE="__TERMAD_COUNT__"
+AD_TEXT=""
+AD_URL=""
+AD_ID=""
+if [ -r "$AD_FILE" ]; then
+  AD_TEXT=$(head -n 1 "$AD_FILE" 2>/dev/null)
+  AD_URL=$(sed -n 2p "$AD_FILE" 2>/dev/null)
+  AD_ID=$(sed -n 4p "$AD_FILE" 2>/dev/null)
+fi
+if [ -n "$AD_TEXT" ]; then
+  printf '\n  [ad]  %s\n' "$AD_TEXT"
+  case "$AD_URL" in
+    http://*|https://*) printf '  %s\n\n' "$AD_URL" ;;
+    *) printf '\n' ;;
+  esac
+  if [ -n "$AD_ID" ]; then
+    printf '%s\n' "$AD_ID" >> "$COUNT_FILE" 2>/dev/null || true
+  fi
+fi
+exec "__TERMAD_BACKUP__" "$@"

package/dist/assets/wrapper.cmd.asset

@@ -0,0 +1,31 @@
+@ECHO off
+REM ===== TERMAD-CLI =====
+REM Reversible termad wrapper. Prints a one-line ad banner read from
+REM "__TERMAD_AD__" (line 1 = wording, line 2 = click URL, line 4 = ad id)
+REM then delegates to the pristine binary at "__TERMAD_BACKUP__".
+REM Each render is appended to "__TERMAD_COUNT__" (one line of ad id — the
+REM batch counter `termad sync` reports; no network happens here).
+REM Restore: copy the backup over this file, or run `termad uninstall`.
+setlocal enabledelayedexpansion
+set "__AD_FILE=__TERMAD_AD__"
+set "__COUNT_FILE=__TERMAD_COUNT__"
+set "__AD="
+set "__URL="
+set "__ID="
+set "__N=0"
+if exist "%__AD_FILE%" (
+  for /f "usebackq delims=" %%A in ("%__AD_FILE%") do (
+    if !__N! EQU 0 set "__AD=%%A"
+    if !__N! EQU 1 set "__URL=%%A"
+    if !__N! EQU 3 set "__ID=%%A"
+    set /a __N+=1
+  )
+)
+if defined __AD (
+  echo.
+  echo   [ad]  !__AD!
+  if defined __URL if not "!__URL!"=="-" echo   !__URL!
+  echo.
+  if defined __ID echo !__ID!>>"%__COUNT_FILE%"
+)
+endlocal & call "__TERMAD_BACKUP__" %*

package/dist/assets/wrapper.sh.asset

@@ -0,0 +1,29 @@
+#!/bin/sh
+# ===== TERMAD-CLI =====
+# Reversible termad wrapper. Prints a one-line ad banner read from
+# "__TERMAD_AD__" (line 1 = wording, line 2 = click URL, line 4 = ad id)
+# then exec's the pristine binary at "__TERMAD_BACKUP__".
+# Each render is appended to "__TERMAD_COUNT__" (one line of ad id — the
+# batch counter `termad sync` reports; no network happens here).
+# Restore: copy the backup over this file, or run `termad uninstall`.
+AD_FILE="__TERMAD_AD__"
+COUNT_FILE="__TERMAD_COUNT__"
+AD_TEXT=""
+AD_URL=""
+AD_ID=""
+if [ -r "$AD_FILE" ]; then
+  AD_TEXT=$(head -n 1 "$AD_FILE" 2>/dev/null)
+  AD_URL=$(sed -n 2p "$AD_FILE" 2>/dev/null)
+  AD_ID=$(sed -n 4p "$AD_FILE" 2>/dev/null)
+fi
+if [ -n "$AD_TEXT" ]; then
+  printf '\n  [ad]  %s\n' "$AD_TEXT"
+  case "$AD_URL" in
+    http://*|https://*) printf '  %s\n\n' "$AD_URL" ;;
+    *) printf '\n' ;;
+  esac
+  if [ -n "$AD_ID" ]; then
+    printf '%s\n' "$AD_ID" >> "$COUNT_FILE" 2>/dev/null || true
+  fi
+fi
+exec "__TERMAD_BACKUP__" "$@"

package/dist/audit.d.ts

@@ -0,0 +1,9 @@
+export interface AuditRow {
+    surface: string;
+    target: string;
+    status: "ok" | "restored" | "updated" | "tampered" | "missing" | "unknown";
+    detail: string;
+}
+export declare function audit(): AuditRow[];
+/** Exit-code helper: only true integrity problems fail an audit. */
+export declare function auditFailed(rows: AuditRow[]): boolean;

package/dist/audit.js

@@ -0,0 +1,54 @@
+/**
+ * `termad audit` — re-verify every recorded change against the filesystem.
+ *
+ * Statuses:
+ *   ok        wrapper/statusline installed, backup matches the recorded original
+ *   restored  target matches the recorded original (uninstalled or reinstalled by the CLI)
+ *   updated   marker gone AND content changed — the CLI self-updated; termad left it alone
+ *   tampered  termad's own wrapper was altered, or the backup no longer matches
+ *             the recorded original — NOT something termad did silently
+ *   missing   the target file no longer exists
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { loadManifest, sha256File } from "./core/manifest.js";
+import { isWrapped } from "./surfaces/wrap.js";
+export function audit() {
+    const m = loadManifest();
+    return m.entries.map((e) => {
+        const base = { surface: e.surface, target: e.target };
+        if (!existsSync(e.target))
+            return { ...base, status: "missing", detail: "target file no longer exists" };
+        if (e.mechanism === "statusline") {
+            let installed = false;
+            try {
+                installed = readFileSync(e.target, "utf8").includes("termad");
+            }
+            catch { }
+            if (installed)
+                return { ...base, status: "ok", detail: "statusline installed, original captured in backup" };
+            return { ...base, status: "restored", detail: "settings no longer reference termad" };
+        }
+        const cur = sha256File(e.target);
+        const wrapped = isWrapped(e.target);
+        if (wrapped) {
+            if (cur !== e.sha256Installed)
+                return { ...base, status: "tampered", detail: "wrapper content differs from what termad installed" };
+            if (!e.backup || sha256File(e.backup) === null)
+                return { ...base, status: "tampered", detail: "wrapper present but original backup is missing" };
+            if (sha256File(e.backup) !== e.sha256Original)
+                return { ...base, status: "tampered", detail: "backup no longer matches the recorded original" };
+            return { ...base, status: "ok", detail: "wrapper installed, original backup verified (sha256)" };
+        }
+        if (cur === e.sha256Original)
+            return { ...base, status: "restored", detail: "target byte-identical to recorded original" };
+        return {
+            ...base,
+            status: "updated",
+            detail: "marker absent and content changed — CLI replaced the wrapper; termad left it untouched",
+        };
+    });
+}
+/** Exit-code helper: only true integrity problems fail an audit. */
+export function auditFailed(rows) {
+    return rows.some((r) => r.status === "tampered" || r.status === "missing");
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

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;