@asidedev/cli 0.1.1

package/dist/commands/about.js

@@ -0,0 +1,38 @@
+import { BACKEND_URL, CLI_VERSION } from "../config.js";
+import { peekInstallId } from "../core/identity.js";
+const REPO_URL = "https://github.com/asidedev/aside";
+/** Plain-language transparency disclosure (Section 5.4). */
+export function runAbout() {
+    const installId = peekInstallId();
+    const lines = [
+        `Aside v${CLI_VERSION} — transparency`,
+        ``,
+        `WHAT ASIDE READS`,
+        `  • Your local curiosity cache and rotation state (~/.aside/).`,
+        `  • An anonymous install_id generated on your machine${installId ? ` (current: ${installId})` : ""}.`,
+        `  • From the stdin Claude Code sends to the status line, ONLY two fields:`,
+        `      - session_id        (used only locally, to pin the session's curiosity)`,
+        `      - model.display_name (used only for formatting)`,
+        `    Everything else in stdin (cwd, workspace.*, worktree.*, repo.*, pr.*,`,
+        `    transcript_path, cost.*, context_window.*, environment variables) is`,
+        `    received and DISCARDED — never written to disk, never sent over the network.`,
+        ``,
+        `WHAT ASIDE SENDS (only on the background sync)`,
+        `  • install_id, cli_version, and os ('darwin'|'linux'|'win32').`,
+        `  • Which curiosities were SHOWN (id, whether sponsored). Clicks on`,
+        `    sponsored items are counted by the server via a redirect — nothing more.`,
+        ``,
+        `WHAT ASIDE NEVER DOES`,
+        `  • Never reads, stores, or sends: code, prompts, responses, file contents,`,
+        `    file names, paths, repository metadata, pull request data, transcripts,`,
+        `    or environment variables.`,
+        `  • Never opens the file pointed to by transcript_path.`,
+        `  • Never makes a network request on the 'status' path (never blocks your terminal).`,
+        `  • Never sends paths/repo/PR.`,
+        ``,
+        `Backend: ${BACKEND_URL}`,
+        `Open source: ${REPO_URL}`,
+        `Public transparency: ${BACKEND_URL}/about`,
+    ];
+    process.stdout.write(lines.join("\n") + "\n");
+}

package/dist/commands/install.js

@@ -0,0 +1,60 @@
+import { resolve } from "node:path";
+import { CLAUDE_SETTINGS_PATH } from "../config.js";
+import { readJsonSafe, writeJsonAtomic, fileExists } from "../core/fsutil.js";
+import { getInstallId } from "../core/identity.js";
+import { runSync } from "../core/syncCore.js";
+/** Build the absolute status-line command (item: never use npx — cold start). */
+export function asideStatusCommand() {
+    const entry = resolve(process.argv[1] ?? "");
+    // Quote both node and the entry path to survive spaces.
+    return `"${process.execPath}" "${entry}" status`;
+}
+/** Heuristic: does an existing statusLine command belong to Aside? */
+export function pointsToAside(cmd) {
+    if (!cmd)
+        return false;
+    const c = cmd.toLowerCase();
+    return ((c.includes("aside") && c.includes("status")) ||
+        c.includes(resolve(process.argv[1] ?? "").toLowerCase()));
+}
+export async function runInstall(opts) {
+    const out = (s) => process.stdout.write(s + "\n");
+    // 1. Anonymous identity.
+    const installId = getInstallId();
+    // 2. Best-effort initial sync (user-invoked path: awaiting is fine).
+    try {
+        await runSync();
+    }
+    catch {
+        out("⚠ Initial sync failed (offline?). Continuing — the cache fills on the next sync.");
+    }
+    // 3. Non-destructive merge into settings.json.
+    const settings = readJsonSafe(CLAUDE_SETTINGS_PATH, {});
+    const existing = settings.statusLine;
+    if (existing && existing.command && !pointsToAside(existing.command)) {
+        if (!opts.force) {
+            out("✋ A status line is already configured and it's NOT Aside's:");
+            out(`   ${existing.command}`);
+            out("   I won't overwrite it without confirmation. Re-run with --force to replace it.");
+            // TODO(mel): interactive confirmation prompt instead of requiring --force.
+            process.exitCode = 1;
+            return;
+        }
+        out("⚠ Replacing the existing status line (--force).");
+    }
+    settings.statusLine = {
+        type: "command",
+        command: asideStatusCommand(),
+    };
+    if (settings.disableAllHooks === true) {
+        out("⚠ 'disableAllHooks: true' is set — the status line will be INACTIVE until you turn it off.");
+    }
+    if (!fileExists(CLAUDE_SETTINGS_PATH)) {
+        out(`ℹ Creating ${CLAUDE_SETTINGS_PATH}.`);
+    }
+    writeJsonAtomic(CLAUDE_SETTINGS_PATH, settings);
+    out("✅ Aside installed.");
+    out(`   anonymous install_id: ${installId}`);
+    out("   A curiosity appears in the status line on your next interaction with Claude Code.");
+    out("   See exactly what is read/sent:  aside about");
+}

package/dist/commands/status.js

@@ -0,0 +1,148 @@
+import { spawn } from "node:child_process";
+import { readStatusInput } from "../core/stdin.js";
+import { readCache, curiosityById } from "../core/cache.js";
+import { readState, writeState, gcPins, } from "../core/state.js";
+import { rotate } from "../core/rotation.js";
+import { withStateLock } from "../core/lock.js";
+import { appendImpression } from "../core/queue.js";
+import { makeClickToken } from "../core/token.js";
+import { renderLine } from "../core/render.js";
+import { getInstallId } from "../core/identity.js";
+import { BACKEND_URL, SLOT_TTL_MS, TURN_GAP_MS, CACHE_STALE_MS, SYNC_MIN_INTERVAL_MS, } from "../config.js";
+function supportsHyperlinks() {
+    if (process.env.ASIDE_FORCE_HYPERLINKS === "1")
+        return true;
+    if (process.env.ASIDE_NO_HYPERLINKS === "1")
+        return false;
+    const tp = process.env.TERM_PROGRAM;
+    if (tp === "iTerm.app" || tp === "WezTerm" || tp === "vscode")
+        return true;
+    if (process.env.KITTY_WINDOW_ID)
+        return true;
+    return false;
+}
+function columns() {
+    const env = Number(process.env.COLUMNS);
+    if (Number.isFinite(env) && env > 0)
+        return env;
+    if (process.stdout.columns && process.stdout.columns > 0) {
+        return process.stdout.columns;
+    }
+    return 80;
+}
+/**
+ * Reuse the pinned curiosity only while we're still in the SAME turn — renders
+ * cluster within ~300ms around one assistant message, so a gap larger than
+ * TURN_GAP_MS means a new prompt → rotate. Also rotate if the slot is very old
+ * (hard cap) to cover a single very long turn.
+ */
+function sameTurn(pin, now) {
+    if (!pin)
+        return false;
+    const lastRender = pin.last_render_at ?? pin.slot_started_at;
+    return now - lastRender < TURN_GAP_MS && now - pin.slot_started_at < SLOT_TTL_MS;
+}
+/**
+ * Core, side-effecting selection done under the state lock. Returns what to
+ * render. All disk writes to state happen here (atomic, locked).
+ */
+function decide(cache, sessionId, installId, now) {
+    return withStateLock(() => {
+        const state = readState();
+        gcPins(state, now);
+        let pin = state.pins[sessionId];
+        let curiosity = null;
+        if (sameTurn(pin, now)) {
+            // Same turn → keep the curiosity stable across this turn's re-renders.
+            curiosity = curiosityById(cache, pin.curiosity_id) ?? null;
+            if (curiosity)
+                pin.last_render_at = now;
+        }
+        if (!curiosity) {
+            // New turn (or no/expired pin) → rotate to a fresh curiosity.
+            curiosity = rotate(cache, state, sessionId, {
+                now,
+                rng: Math.random,
+            });
+            pin = state.pins[sessionId];
+        }
+        if (!curiosity || !pin) {
+            writeState(state);
+            return { curiosity: null, emitImpression: false, clickToken: null };
+        }
+        let emit = false;
+        if (!pin.impression_emitted) {
+            // Generate the self-contained click token for sponsored items so the
+            // OSC 8 link works regardless of sync ordering (item 1).
+            if (curiosity.is_sponsored && curiosity.click_url) {
+                pin.click_token = makeClickToken(curiosity.id, installId);
+            }
+            pin.impression_emitted = true;
+            emit = true;
+        }
+        state.pins[sessionId] = pin;
+        writeState(state);
+        return {
+            curiosity,
+            emitImpression: emit,
+            clickToken: pin.click_token,
+        };
+    });
+}
+function maybeSpawnSync(now) {
+    // Read state outside the lock (cheap, best-effort).
+    const state = readState();
+    const cache = readCache();
+    const cacheStale = now - cache.fetched_at > CACHE_STALE_MS;
+    const syncRecently = now - state.last_sync_at < SYNC_MIN_INTERVAL_MS;
+    if (!cacheStale || syncRecently)
+        return;
+    withStateLock(() => {
+        const s = readState();
+        if (now - s.last_sync_at < SYNC_MIN_INTERVAL_MS)
+            return;
+        s.last_sync_at = now;
+        writeState(s);
+    });
+    try {
+        const child = spawn(process.execPath, [process.argv[1] ?? "", "sync"], { detached: true, stdio: "ignore" });
+        child.unref();
+    }
+    catch {
+        /* never let a spawn failure affect the render */
+    }
+}
+export function runStatus() {
+    const now = Date.now();
+    const input = readStatusInput();
+    const sessionId = input.session_id ?? "default";
+    const cache = readCache();
+    const installId = getInstallId();
+    // Nothing to show yet (e.g. offline first run): render nothing.
+    if (cache.curiosities.length === 0) {
+        process.stdout.write("");
+        maybeSpawnSync(now);
+        return;
+    }
+    const decision = decide(cache, sessionId, installId, now);
+    if (!decision.curiosity) {
+        process.stdout.write(""); // status line disappears
+        maybeSpawnSync(now);
+        return;
+    }
+    if (decision.emitImpression) {
+        appendImpression({
+            curiosity_id: decision.curiosity.id,
+            is_sponsored: decision.curiosity.is_sponsored,
+            event: "shown",
+            click_token: decision.clickToken,
+        });
+    }
+    const line = renderLine(decision.curiosity, decision.clickToken, {
+        columns: columns(),
+        supportsHyperlinks: supportsHyperlinks(),
+        backendUrl: BACKEND_URL,
+    });
+    process.stdout.write(line + "\n");
+    maybeSpawnSync(now);
+}

package/dist/commands/sync.js

@@ -0,0 +1,11 @@
+import { runSync } from "../core/syncCore.js";
+/** Internal command, normally spawned detached by `status`. */
+export async function runSyncCommand() {
+    try {
+        await runSync();
+    }
+    catch {
+        // Background process: swallow errors, never surface to the terminal.
+        process.exitCode = 0;
+    }
+}

package/dist/commands/uninstall.js

@@ -0,0 +1,35 @@
+import { rmSync } from "node:fs";
+import { CLAUDE_SETTINGS_PATH, ASIDE_DIR } from "../config.js";
+import { readJsonSafe, writeJsonAtomic, fileExists } from "../core/fsutil.js";
+import { pointsToAside } from "./install.js";
+export function runUninstall() {
+    const out = (s) => process.stdout.write(s + "\n");
+    if (fileExists(CLAUDE_SETTINGS_PATH)) {
+        const settings = readJsonSafe(CLAUDE_SETTINGS_PATH, {});
+        const cmd = settings.statusLine?.command;
+        if (settings.statusLine && pointsToAside(cmd)) {
+            delete settings.statusLine;
+            writeJsonAtomic(CLAUDE_SETTINGS_PATH, settings);
+            out("✅ Aside status line removed from settings.json (all other keys preserved).");
+        }
+        else if (settings.statusLine) {
+            out("ℹ The current status line is NOT Aside's — leaving it untouched:");
+            out(`   ${cmd ?? "(no command)"}`);
+        }
+        else {
+            out("ℹ No status line configured in settings.json.");
+        }
+    }
+    else {
+        out("ℹ settings.json doesn't exist — nothing to remove there.");
+    }
+    // Remove ~/.aside/ (config, cache, state, queue).
+    try {
+        rmSync(ASIDE_DIR, { recursive: true, force: true });
+        out(`✅ Removed ${ASIDE_DIR}.`);
+    }
+    catch {
+        out(`⚠ Couldn't remove ${ASIDE_DIR} (delete it manually if needed).`);
+    }
+    out("Uninstalled. Thanks for using Aside. 👋");
+}

package/dist/commands/wrap.js

@@ -0,0 +1,157 @@
+import { createRequire } from "node:module";
+import { readCache, liveCuriosities } from "../core/cache.js";
+import { truncateVisible, visibleWidth } from "../core/render.js";
+/**
+ * EXPERIMENTAL terminal wrapper (the "hack" path). Runs `claude` inside a PTY
+ * and rewrites its thinking-spinner line so the gerund ("Churned for 5s") is
+ * replaced by a developer curiosity that changes on each new prompt.
+ *
+ * This fights a live TUI, so it is best-effort: it relies on the observed fact
+ * that Claude Code redraws the spinner on a single line via carriage return,
+ * and only touches lines beginning with a sparkle spinner glyph.
+ */
+/**
+ * We detect the spinner by its STATUS TEXT, not by the leading glyph — Claude
+ * cycles through glyphs from several families (✦ ✛ ✻ + * …) and chasing them is
+ * a losing game. The working line is always a gerund followed by an elapsed-time
+ * marker: "Channelling… (7s · ↓ 268 tokens)" or "Baked for 2s". That tail is
+ * distinctive enough to key off reliably.
+ *
+ * Groups: (1) optional leading glyph char, (2) the gerund, (3) the time tail.
+ */
+const SPINNER_RE = /([^\s\r\nA-Za-z\x1b]?)[ \t]*([A-Z][A-Za-z]+(?:…|\.\.\.)?)( for \d+s\b| \(\d+s[^)\r\n]{0,60}\)?)/g;
+/** Pure transform — exported for tests. Rewrites spinner frames in `chunk`. */
+export function rewriteSpinner(chunk, st) {
+    if (st.pool.length === 0)
+        return chunk;
+    SPINNER_RE.lastIndex = 0;
+    if (!SPINNER_RE.test(chunk))
+        return chunk;
+    const now = st.now();
+    // New thinking session? (first spinner frame after a quiet gap) → rotate.
+    if (st.current === null || now - st.lastSpinnerTs > st.gapMs) {
+        st.idx = (st.idx + 1) % st.pool.length;
+        st.current = st.pool[st.idx];
+    }
+    st.lastSpinnerTs = now;
+    const display = st.current;
+    SPINNER_RE.lastIndex = 0;
+    return chunk.replace(SPINNER_RE, (_m, glyph) => {
+        // Claude draws its spinner glyph SEPARATELY (e.g. `✻` ESC[3G `Churned…`),
+        // so the regex usually captures no glyph (group1 empty) — the gerund text is
+        // preceded by a cursor-position escape. In that case DON'T add a glyph (that
+        // caused a double-glyph + 1-char shift); just write the curiosity where
+        // Claude already positioned the cursor. Cap width so it never wraps, and
+        // erase to end-of-line to wipe any leftover from a longer previous frame.
+        // Claude positions the cursor right after its glyph (e.g. ESC[3G), so when
+        // we captured no glyph we still emit one leading space to sit clear of it.
+        const prefix = glyph ? glyph + " " : " ";
+        const room = Math.max(8, st.cols - visibleWidth(prefix) - 4);
+        const text = truncateVisible(display, room);
+        return `${prefix}${text}\x1b[K`;
+    });
+}
+const MARKER = String.fromCodePoint(0x261e); // ☞ manicule — the "margin note" emblem
+function buildPool() {
+    const cache = readCache();
+    return liveCuriosities(cache).map((c) => {
+        const handle = c.sponsor_handle ? c.sponsor_handle.replace(/^@+/, "") : "aside";
+        const body = c.body.replace(/\s+/g, " ").trim();
+        return `${MARKER} ${body} — @${handle}`;
+    });
+}
+/** Interactive entry point. */
+export async function runWrap(passthroughArgs) {
+    const require = createRequire(import.meta.url);
+    let pty;
+    try {
+        pty = require("node-pty");
+        healSpawnHelper(require); // prebuilt spawn-helper often ships without +x
+    }
+    catch {
+        process.stderr.write("aside wrap needs the optional 'node-pty' dependency.\n" +
+            "Install it:  npm i -g node-pty   (or reinstall @asidedev/cli)\n");
+        process.exitCode = 1;
+        return;
+    }
+    const pool = buildPool();
+    if (pool.length === 0) {
+        process.stderr.write("No curiosities cached yet. Run `aside sync` (or `aside install`) first.\n");
+        process.exitCode = 1;
+        return;
+    }
+    const claudeBin = process.env.ASIDE_CLAUDE_BIN || "claude";
+    const cols = process.stdout.columns || 120;
+    const rows = process.stdout.rows || 30;
+    const state = {
+        current: null,
+        lastSpinnerTs: 0,
+        idx: -1,
+        pool,
+        cols,
+        now: () => Date.now(),
+        gapMs: 700,
+    };
+    let term;
+    try {
+        term = pty.spawn(claudeBin, passthroughArgs, {
+            name: process.env.TERM || "xterm-256color",
+            cols,
+            rows,
+            cwd: process.cwd(),
+            env: process.env,
+        });
+    }
+    catch (err) {
+        process.stderr.write(`aside wrap could not launch '${claudeBin}': ${err.message}\n` +
+            "Make sure Claude Code is installed and on your PATH " +
+            "(or set ASIDE_CLAUDE_BIN to its full path).\n");
+        process.exitCode = 1;
+        return;
+    }
+    term.onData((data) => {
+        state.cols = process.stdout.columns || state.cols;
+        process.stdout.write(rewriteSpinner(data, state));
+    });
+    const stdin = process.stdin;
+    if (stdin.isTTY)
+        stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on("data", (d) => term.write(d.toString("utf8")));
+    const onResize = () => term.resize(process.stdout.columns || cols, process.stdout.rows || rows);
+    process.stdout.on("resize", onResize);
+    term.onExit(({ exitCode }) => {
+        if (stdin.isTTY)
+            stdin.setRawMode(false);
+        stdin.pause();
+        process.stdout.removeListener("resize", onResize);
+        process.exit(exitCode ?? 0);
+    });
+}
+/**
+ * node-pty's prebuilt `spawn-helper` frequently lands without the execute bit
+ * (npm extracts it 0644), which makes pty.spawn fail with "posix_spawnp failed".
+ * Best-effort: find it next to the loaded node-pty and chmod +x.
+ */
+function healSpawnHelper(require) {
+    try {
+        // Lazy, optional imports so this never breaks the main path.
+        const { dirname, join } = require("node:path");
+        const fs = require("node:fs");
+        const pkg = require.resolve("node-pty/package.json");
+        const root = dirname(pkg);
+        for (const arch of ["darwin-arm64", "darwin-x64", "linux-x64", "linux-arm64"]) {
+            const helper = join(root, "prebuilds", arch, "spawn-helper");
+            try {
+                if (fs.existsSync(helper))
+                    fs.chmodSync(helper, 0o755);
+            }
+            catch {
+                /* ignore individual failures */
+            }
+        }
+    }
+    catch {
+        /* node-pty layout differs or perms denied — nothing we can do, proceed */
+    }
+}

package/dist/config.js

@@ -0,0 +1,32 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Backend base URL. Overridable for local dev / self-hosting. */
+export const BACKEND_URL = process.env.ASIDE_BACKEND_URL?.replace(/\/+$/, "") ||
+    "https://asidedev.vercel.app";
+export const ASIDE_DIR = process.env.ASIDE_HOME || join(homedir(), ".aside");
+export const CLAUDE_SETTINGS_PATH = process.env.ASIDE_CLAUDE_SETTINGS || join(homedir(), ".claude", "settings.json");
+export const PATHS = {
+    dir: ASIDE_DIR,
+    config: join(ASIDE_DIR, "config.json"),
+    cache: join(ASIDE_DIR, "cache.json"),
+    state: join(ASIDE_DIR, "state.json"),
+    queue: join(ASIDE_DIR, "queue.jsonl"),
+    /** Lock for read-modify-write on state.json (multi-session safety). */
+    stateLock: join(ASIDE_DIR, "state.lock"),
+};
+/** Schema version for on-disk state/cache files. Bump on breaking changes. */
+export const STATE_VERSION = 1;
+// Rotation tuning (Section 8).
+export const DAILY_CAP = 1000; // sanity bound only — the footer rotates per prompt
+export const DISPLAY_PROBABILITY = 1; // always show a curiosity when a new slot is allowed
+export const SPONSORED_RATIO = 0.2; // ~20% of slots are sponsored
+export const RECENT_WINDOW = 30; // anti-repetition window
+// A new prompt/turn is detected by a gap between status-line renders: renders
+// cluster (debounced ~300ms) around each assistant message, with seconds of
+// quiet between turns. A gap longer than this rotates to a fresh curiosity.
+export const TURN_GAP_MS = 2500;
+export const SLOT_TTL_MS = 30 * 60 * 1000; // hard cap: rotate within a very long single turn
+export const PIN_GC_MS = 24 * 60 * 60 * 1000; // drop pins older than 24h
+export const CACHE_STALE_MS = 6 * 60 * 60 * 1000; // refresh cache if older than 6h
+export const SYNC_MIN_INTERVAL_MS = 30 * 60 * 1000; // don't spawn sync more than every 30 min
+export const CLI_VERSION = "0.1.1";

package/dist/core/cache.js

@@ -0,0 +1,25 @@
+import { PATHS, STATE_VERSION } from "../config.js";
+import { readJsonSafe, writeJsonAtomic } from "./fsutil.js";
+const EMPTY = {
+    version: STATE_VERSION,
+    served_at: null,
+    fetched_at: 0,
+    curiosities: [],
+};
+export function readCache() {
+    const c = readJsonSafe(PATHS.cache, EMPTY);
+    // Reinit on version mismatch (Section 14 extended to upgrades).
+    if (!c || c.version !== STATE_VERSION || !Array.isArray(c.curiosities)) {
+        return { ...EMPTY };
+    }
+    return c;
+}
+export function writeCache(cache) {
+    writeJsonAtomic(PATHS.cache, cache);
+}
+export function liveCuriosities(cache) {
+    return cache.curiosities.filter((c) => c.status === "live");
+}
+export function curiosityById(cache, id) {
+    return cache.curiosities.find((c) => c.id === id);
+}

package/dist/core/fsutil.js

@@ -0,0 +1,29 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync, existsSync, } from "node:fs";
+import { dirname } from "node:path";
+import { ASIDE_DIR } from "../config.js";
+export function ensureDir() {
+    mkdirSync(ASIDE_DIR, { recursive: true });
+}
+export function readJsonSafe(path, fallback) {
+    try {
+        const raw = readFileSync(path, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Atomic write: temp file + rename (Section 3.1 / 6.1). */
+export function writeAtomic(path, data) {
+    mkdirSync(dirname(path), { recursive: true });
+    // Unique-ish temp suffix without Math.random (pid + hrtime).
+    const tmp = `${path}.tmp-${process.pid}-${process.hrtime.bigint()}`;
+    writeFileSync(tmp, data, "utf8");
+    renameSync(tmp, path);
+}
+export function writeJsonAtomic(path, value) {
+    writeAtomic(path, JSON.stringify(value, null, 2));
+}
+export function fileExists(path) {
+    return existsSync(path);
+}

package/dist/core/identity.js

@@ -0,0 +1,27 @@
+import { randomUUID } from "node:crypto";
+import { platform } from "node:os";
+import { PATHS } from "../config.js";
+import { readJsonSafe, writeJsonAtomic, ensureDir } from "./fsutil.js";
+/** Read the anonymous install_id, generating + persisting one on first use. */
+export function getInstallId() {
+    const cfg = readJsonSafe(PATHS.config, {});
+    if (cfg.install_id && typeof cfg.install_id === "string") {
+        return cfg.install_id;
+    }
+    ensureDir();
+    const id = randomUUID();
+    writeJsonAtomic(PATHS.config, { install_id: id });
+    return id;
+}
+/** Read install_id without creating one (returns null if absent). */
+export function peekInstallId() {
+    const cfg = readJsonSafe(PATHS.config, {});
+    return typeof cfg.install_id === "string" ? cfg.install_id : null;
+}
+/** Normalized OS string — the only platform info ever sent (Section 4.1.4). */
+export function normalizedOs() {
+    const p = platform();
+    if (p === "darwin" || p === "linux" || p === "win32")
+        return p;
+    return "linux"; // conservative fallback; never leak the raw value
+}

package/dist/core/lock.js

@@ -0,0 +1,83 @@
+import { openSync, closeSync, rmSync, readFileSync, statSync, writeSync, } from "node:fs";
+import { PATHS } from "../config.js";
+/**
+ * Minimal cross-process advisory lock (item 3 fix: multi-session safety on
+ * state.json). Uses O_EXCL create as the lock primitive. Best-effort: if the
+ * lock cannot be acquired quickly we proceed anyway rather than blocking the
+ * status render — correctness of counters degrades gracefully, the host tool
+ * is never delayed.
+ */
+const STALE_MS = 5000; // a held lock older than this is considered abandoned
+const MAX_WAIT_MS = 400; // never block the render for long
+const RETRY_MS = 15;
+function sleepBusy(ms) {
+    const end = process.hrtime.bigint() + BigInt(ms) * 1000000n;
+    while (process.hrtime.bigint() < end) {
+        /* spin briefly; lock contention is rare and short */
+    }
+}
+export function withStateLock(fn) {
+    const path = PATHS.stateLock;
+    let fd = null;
+    const start = Date.now();
+    while (fd === null) {
+        try {
+            fd = openSync(path, "wx");
+            // record holder for stale diagnostics
+            try {
+                writeSync(fd, String(process.pid));
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        catch (err) {
+            if (err.code !== "EEXIST") {
+                // unexpected error — proceed without lock
+                return fn();
+            }
+            // Lock exists. Break it if stale.
+            try {
+                const age = Date.now() - statSync(path).mtimeMs;
+                if (age > STALE_MS) {
+                    rmSync(path, { force: true });
+                    continue;
+                }
+            }
+            catch {
+                /* race: lock vanished, retry */
+            }
+            if (Date.now() - start > MAX_WAIT_MS) {
+                // Give up waiting; proceed unlocked rather than block render.
+                return fn();
+            }
+            sleepBusy(RETRY_MS);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            rmSync(path, { force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/** Exposed for diagnostics/tests. */
+export function lockHolder() {
+    try {
+        return readFileSync(PATHS.stateLock, "utf8");
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/queue.js

@@ -0,0 +1,74 @@
+import { appendFileSync, existsSync, readFileSync, renameSync, rmSync, mkdirSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+import { PATHS } from "../config.js";
+import { writeAtomic } from "./fsutil.js";
+const SENDING = `${PATHS.queue}.sending`;
+/** Append one impression (only ever "shown" from the client). */
+export function appendImpression(ev) {
+    mkdirSync(dirname(PATHS.queue), { recursive: true });
+    const entry = { ...ev, client_event_id: randomUUID() };
+    appendFileSync(PATHS.queue, JSON.stringify(entry) + "\n", "utf8");
+}
+function parseLines(raw) {
+    return raw
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .map((l) => {
+        try {
+            return JSON.parse(l);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((x) => x !== null);
+}
+/**
+ * Atomically take the pending batch for flushing (item 2 fix). Rotates
+ * queue.jsonl out of the way so concurrent appends during the network POST are
+ * never clobbered. Any leftover .sending batch (from a previous failed flush
+ * or crash) is merged in, giving at-least-once delivery.
+ */
+export function takeBatch() {
+    let carry = [];
+    if (existsSync(SENDING)) {
+        carry = parseLines(safeRead(SENDING));
+    }
+    let fresh = [];
+    if (existsSync(PATHS.queue)) {
+        const rotated = `${PATHS.queue}.rotate-${process.pid}-${process.hrtime.bigint()}`;
+        try {
+            renameSync(PATHS.queue, rotated); // new appends create a fresh queue.jsonl
+            fresh = parseLines(safeRead(rotated));
+            rmSync(rotated, { force: true });
+        }
+        catch {
+            /* race: another flush grabbed it; ignore */
+        }
+    }
+    const combined = [...carry, ...fresh];
+    if (combined.length === 0) {
+        if (existsSync(SENDING))
+            rmSync(SENDING, { force: true });
+        return [];
+    }
+    // Persist the in-flight batch so it survives a crash mid-POST.
+    writeAtomic(SENDING, combined.map((e) => JSON.stringify(e)).join("\n") + "\n");
+    return combined;
+}
+/** Call after a successful POST: discard the in-flight batch. */
+export function flushSucceeded() {
+    if (existsSync(SENDING))
+        rmSync(SENDING, { force: true });
+}
+/** On failure, the .sending file is left in place; the next takeBatch() merges it. */
+function safeRead(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}

package/dist/core/render.js

@@ -0,0 +1,75 @@
+const ESC = String.fromCharCode(27);
+const DIM = `${ESC}[2m`;
+const RESET = `${ESC}[0m`;
+/** Manicule (☞, U+261E) — points at the curiosity; the "margin note" emblem. */
+const MARKER = String.fromCodePoint(0x261e);
+/** OSC 8 hyperlink wrappers. */
+function osc8(url, label) {
+    return `${ESC}]8;;${url}${ESC}\\${label}${ESC}]8;;${ESC}\\`;
+}
+/**
+ * Format one status line (Section 9). Truncation is width-aware on the VISIBLE
+ * text only (item 6 fix): we never count escape bytes toward width and never
+ * cut inside an escape/OSC 8 sequence. The hyperlink/ANSI is applied AFTER the
+ * visible text has been truncated.
+ */
+export function renderLine(c, clickToken, opts) {
+    const cols = opts.columns > 10 ? opts.columns : 80;
+    const handle = c.sponsor_handle ? `@${stripAt(c.sponsor_handle)}` : "@aside";
+    // Signature is mandatory on every render (screenshot-distribution engine).
+    const signature = ` — ${handle}`;
+    const sponsorMark = c.is_sponsored && c.sponsor_handle ? ` · by ${stripAt(c.sponsor_handle)}` : "";
+    // Leading manicule points at the curiosity — the "note in the margin" emblem.
+    // It travels in every screenshot, for free.
+    const head = `${MARKER} `;
+    // Reserve room for the marker + signature + sponsor mark; truncate body to fit.
+    const tail = signature + sponsorMark;
+    const room = Math.max(8, cols - visibleWidth(head) - visibleWidth(tail) - 1);
+    const body = truncateVisible(c.body.replace(/\s+/g, " ").trim(), room);
+    // Build the visible string, then decorate.
+    let line = head + body + tail;
+    // Apply OSC 8 only to the signature token, only for sponsored w/ click_url.
+    if (c.is_sponsored &&
+        c.click_url &&
+        clickToken &&
+        opts.supportsHyperlinks) {
+        const url = `${opts.backendUrl}/api/r/${encodeURIComponent(clickToken)}`;
+        const linked = osc8(url, handle);
+        // Replace the (already-truncated) plain handle with the linked version.
+        line = head + body + ` — ${linked}` + sponsorMark;
+    }
+    // Subtle dim on the tail for readability; never affects width math.
+    return colorizeTail(line, tail);
+}
+function colorizeTail(line, tail) {
+    const idx = line.lastIndexOf(tail.trimEnd());
+    if (idx < 0)
+        return line;
+    return line; // keep plain by default; ANSI is optional (MAY) — avoid surprises
+    // (Dim styling intentionally left off to keep screenshots clean; see DIM/RESET.)
+}
+function stripAt(h) {
+    return h.replace(/^@+/, "");
+}
+/** Visible width = code points outside escape/OSC 8 sequences. */
+export function visibleWidth(s) {
+    return stripSequences(s).length;
+}
+/** Remove ANSI CSI and OSC 8 sequences for width measurement. */
+function stripSequences(s) {
+    // OSC 8: ESC ] 8 ; ; URL ESC \   (and the closing ESC ] 8 ; ; ESC \)
+    let out = s.replace(/\]8;;.*?\\/g, "");
+    // CSI: ESC [ ... letter
+    out = out.replace(/\[[0-9;]*[A-Za-z]/g, "");
+    return out;
+}
+/** Truncate a PLAIN string (no escapes) to maxWidth visible chars, adding an ellipsis. */
+export function truncateVisible(plain, maxWidth) {
+    const chars = [...plain];
+    if (chars.length <= maxWidth)
+        return plain;
+    if (maxWidth <= 1)
+        return chars.slice(0, Math.max(0, maxWidth)).join("");
+    return chars.slice(0, maxWidth - 1).join("") + "…";
+}
+export { DIM, RESET };

package/dist/core/rotation.js

@@ -0,0 +1,66 @@
+import { DAILY_CAP, DISPLAY_PROBABILITY, SPONSORED_RATIO, RECENT_WINDOW, } from "../config.js";
+import { liveCuriosities } from "./cache.js";
+import { rollDayIfNeeded, gcPins, } from "./state.js";
+/** A sponsored curiosity is eligible only if live (campaign liveness is
+ *  enforced server-side at feed time, so anything sponsored in the cache is
+ *  already campaign-live as of the last sync). */
+function isEligibleSponsored(c) {
+    return c.is_sponsored && c.status === "live";
+}
+function pick(arr, rng) {
+    if (arr.length === 0)
+        return undefined;
+    return arr[Math.floor(rng() * arr.length)];
+}
+/**
+ * Select a curiosity for a NEW slot using local state only (Section 8 / 15.2).
+ * Mutates `state` atomically-in-memory (caller persists under lock).
+ * Returns the chosen curiosity, or null to render nothing.
+ */
+export function rotate(cache, state, sessionId, deps) {
+    const { now, rng } = deps;
+    rollDayIfNeeded(state, now);
+    gcPins(state, now);
+    if (state.slots_today >= DAILY_CAP)
+        return null;
+    if (rng() > DISPLAY_PROBABILITY)
+        return null; // ~1 in 3 attempts shows
+    const pool = liveCuriosities(cache).filter((c) => !state.recent.includes(c.id));
+    if (pool.length === 0)
+        return null;
+    const wantSponsored = rng() < SPONSORED_RATIO && state.last_sponsored === false;
+    let candidates;
+    if (wantSponsored) {
+        candidates = pool.filter(isEligibleSponsored);
+        if (candidates.length === 0) {
+            candidates = pool.filter((c) => !c.is_sponsored);
+        }
+    }
+    else {
+        candidates = pool.filter((c) => !c.is_sponsored);
+        // If we have nothing non-sponsored but the guard allows, fall back to any.
+        if (candidates.length === 0 && state.last_sponsored === false) {
+            candidates = pool.filter(isEligibleSponsored);
+        }
+    }
+    if (candidates.length === 0)
+        return null;
+    const chosen = pick(candidates, rng);
+    if (!chosen)
+        return null;
+    const pin = {
+        curiosity_id: chosen.id,
+        slot_started_at: now,
+        last_render_at: now,
+        impression_emitted: false,
+        click_token: null,
+    };
+    state.pins[sessionId] = pin;
+    state.slots_today += 1;
+    state.recent.push(chosen.id);
+    if (state.recent.length > RECENT_WINDOW) {
+        state.recent.splice(0, state.recent.length - RECENT_WINDOW);
+    }
+    state.last_sponsored = chosen.is_sponsored;
+    return chosen;
+}

package/dist/core/state.js

@@ -0,0 +1,54 @@
+import { PATHS, STATE_VERSION, PIN_GC_MS } from "../config.js";
+import { readJsonSafe, writeJsonAtomic } from "./fsutil.js";
+function empty() {
+    return {
+        version: STATE_VERSION,
+        pins: {},
+        day_key: "",
+        slots_today: 0,
+        recent: [],
+        last_sponsored: false,
+        last_sync_at: 0,
+    };
+}
+export function readState() {
+    const s = readJsonSafe(PATHS.state, empty());
+    if (!s || s.version !== STATE_VERSION || typeof s.pins !== "object") {
+        return empty();
+    }
+    // Defensive defaults for partially-written / older files.
+    return {
+        version: STATE_VERSION,
+        pins: s.pins ?? {},
+        day_key: s.day_key ?? "",
+        slots_today: s.slots_today ?? 0,
+        recent: Array.isArray(s.recent) ? s.recent : [],
+        last_sponsored: !!s.last_sponsored,
+        last_sync_at: s.last_sync_at ?? 0,
+    };
+}
+export function writeState(state) {
+    writeJsonAtomic(PATHS.state, state);
+}
+/** Local calendar day key (YYYY-MM-DD), used to reset the daily cap. */
+export function dayKey(nowMs) {
+    const d = new Date(nowMs);
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${y}-${m}-${day}`;
+}
+/** Drop pins older than PIN_GC_MS so the map cannot grow unbounded (item 5). */
+export function gcPins(state, nowMs) {
+    for (const [sid, pin] of Object.entries(state.pins)) {
+        if (nowMs - pin.slot_started_at > PIN_GC_MS)
+            delete state.pins[sid];
+    }
+}
+export function rollDayIfNeeded(state, nowMs) {
+    const key = dayKey(nowMs);
+    if (state.day_key !== key) {
+        state.day_key = key;
+        state.slots_today = 0;
+    }
+}

package/dist/core/stdin.js

@@ -0,0 +1,48 @@
+import { readFileSync } from "node:fs";
+/**
+ * Read the host tool's stdin JSON and extract ONLY the allowlisted fields
+ * (Section 5.1 — receive-but-discard). Everything else (cwd, workspace.*,
+ * worktree.*, repo.*, pr.*, transcript_path, cost.*, context_window.*, env)
+ * is read into memory transiently and never returned, persisted, or sent.
+ *
+ * MUST tolerate absent / null / partial / malformed JSON without crashing.
+ */
+export function readStatusInput() {
+    let raw = "";
+    try {
+        // fd 0 = stdin. Synchronous, non-blocking-friendly read.
+        raw = readFileSync(0, "utf8");
+    }
+    catch {
+        return { session_id: null };
+    }
+    if (!raw.trim())
+        return { session_id: null };
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        return { session_id: null };
+    }
+    return allowlist(obj);
+}
+/** Pure allowlist extractor — exported for tests. */
+export function allowlist(obj) {
+    if (!obj || typeof obj !== "object")
+        return { session_id: null };
+    const o = obj;
+    const session_id = typeof o.session_id === "string" && o.session_id.length > 0
+        ? o.session_id
+        : null;
+    let model_display_name = null;
+    const model = o.model;
+    if (model && typeof model === "object") {
+        const dn = model.display_name;
+        if (typeof dn === "string")
+            model_display_name = dn;
+    }
+    // Note: we deliberately construct a fresh object containing ONLY these two
+    // fields. No path, repo, pr, transcript, cost, or context field is copied.
+    return { session_id, model_display_name };
+}

package/dist/core/syncCore.js

@@ -0,0 +1,66 @@
+import { BACKEND_URL, CLI_VERSION } from "../config.js";
+import { getInstallId, normalizedOs } from "./identity.js";
+import { readCache, writeCache } from "./cache.js";
+import { STATE_VERSION } from "../config.js";
+import { takeBatch, flushSucceeded } from "./queue.js";
+const FETCH_TIMEOUT_MS = 8000;
+async function httpJson(url, init) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, { ...init, signal: ctrl.signal });
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Background sync (Section 12). NEVER called from the foreground status path.
+ * 1. Fetch a FULL snapshot of live curiosities and replace the cache (item 4:
+ *    snapshot, not incremental — avoids shrinking the pool).
+ * 2. Flush the impression queue in one batch; on success discard the in-flight
+ *    file, on failure keep it for the next run (at-least-once).
+ */
+export async function runSync() {
+    const installId = getInstallId();
+    const os = normalizedOs();
+    // 1. Refresh cache (full snapshot).
+    const url = `${BACKEND_URL}/api/curiosities?install_id=${encodeURIComponent(installId)}&cli_version=${encodeURIComponent(CLI_VERSION)}&os=${encodeURIComponent(os)}`;
+    const feed = await httpJson(url, { method: "GET" });
+    if (feed && Array.isArray(feed.curiosities)) {
+        const cache = {
+            version: STATE_VERSION,
+            served_at: feed.served_at ?? null,
+            fetched_at: Date.now(),
+            curiosities: feed.curiosities,
+        };
+        writeCache(cache);
+    }
+    else {
+        // Touch fetched_at lightly so we don't hammer a down backend? No — leave
+        // fetched_at unchanged so staleness logic can retry next opportunity.
+        void readCache();
+    }
+    // 2. Flush impressions.
+    const batch = takeBatch();
+    if (batch.length > 0) {
+        const body = {
+            install_id: installId,
+            events: batch,
+        };
+        const ok = await httpJson(`${BACKEND_URL}/api/impressions`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (ok)
+            flushSucceeded();
+        // else: leave .sending in place; next runSync() merges + retries.
+    }
+}

package/dist/core/token.js

@@ -0,0 +1,16 @@
+import { randomUUID } from "node:crypto";
+/**
+ * Self-contained click token (item 1 fix). The token CARRIES the curiosity_id
+ * (and install_id) so the redirect endpoint can resolve the destination
+ * WITHOUT depending on the "shown" event having synced first. It is not signed:
+ * the client is open-source and cannot hold a server secret, and click counts
+ * are explicitly best-effort / not fraud-resistant (Section 5.3 limitation).
+ *
+ * Format: base64url(`${curiosityId}~${installId}~${nonce}`)
+ * The nonce (uuid v4, 122 bits) gives per-shown uniqueness for idempotency.
+ */
+export function makeClickToken(curiosityId, installId) {
+    const nonce = randomUUID();
+    const payload = `${curiosityId}~${installId}~${nonce}`;
+    return Buffer.from(payload, "utf8").toString("base64url");
+}

package/dist/index.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { CLI_VERSION } from "./config.js";
+const program = new Command();
+program
+    .name("aside")
+    .description("Developer microcuriosities in the Claude Code status line")
+    .version(CLI_VERSION);
+program
+    .command("status")
+    .description("Print the current curiosity (invoked by the status line). Local-only, synchronous.")
+    .action(async () => {
+    const { runStatus } = await import("./commands/status.js");
+    runStatus();
+});
+program
+    .command("install")
+    .description("Register the Aside status line in ~/.claude/settings.json (non-destructive).")
+    .option("--force", "overwrite an existing non-Aside status line")
+    .action(async (opts) => {
+    const { runInstall } = await import("./commands/install.js");
+    await runInstall(opts);
+});
+program
+    .command("uninstall")
+    .description("Remove the Aside status line and ~/.aside/.")
+    .action(async () => {
+    const { runUninstall } = await import("./commands/uninstall.js");
+    runUninstall();
+});
+program
+    .command("about")
+    .description("Print exactly what Aside reads, sends, and never does.")
+    .action(async () => {
+    const { runAbout } = await import("./commands/about.js");
+    runAbout();
+});
+program
+    .command("sync")
+    .description("(internal) Refresh the cache and flush impressions. Run detached.")
+    .action(async () => {
+    const { runSyncCommand } = await import("./commands/sync.js");
+    await runSyncCommand();
+});
+program
+    .command("wrap", { isDefault: false })
+    .description("(experimental) Run `claude` and show a curiosity in the thinking spinner.")
+    .allowUnknownOption(true)
+    .allowExcessArguments(true)
+    .argument("[args...]", "arguments passed through to claude")
+    .action(async (args) => {
+    const { runWrap } = await import("./commands/wrap.js");
+    await runWrap(args ?? []);
+});
+program.parseAsync(process.argv).catch(() => {
+    // Never let a CLI error leak a stack trace into a status line render.
+    process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@asidedev/cli",
+  "version": "0.1.1",
+  "description": "Aside CLI — renders developer microcuriosities in the Claude Code status line",
+  "type": "module",
+  "bin": {
+    "aside": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "optionalDependencies": {
+    "node-pty": "^1.1.0"
+  },
+  "devDependencies": {
+    "@aside/shared": "*",
+    "@types/node": "^22.0.0",
+    "@xterm/headless": "^5.5.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asidedev/aside.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/asidedev/aside#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}