@inversealtruism/cairn-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InverseAltruism
+
+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/README.md

@@ -0,0 +1,76 @@
+# cairn-cli
+
+A command-line client for a Cairn signal board on Compute Substrate. Browse what the community is
+backing, and with a token, propose or support items, all from your terminal.
+
+Cairn is a fee-weighted "paid attention" board: people spend CSD to surface what should be built,
+fixed, or funded. `cairn-cli` is a thin HTTP client for a Cairn instance. Browsing needs no `csd`
+binary and no key files.
+
+## Install
+
+```bash
+npm install -g @inversealtruism/cairn-cli
+```
+
+Or run it without installing:
+
+```bash
+npx @inversealtruism/cairn-cli ls
+```
+
+Or build from source:
+
+```bash
+git clone https://github.com/InverseAltruism/cairn-cli
+cd cairn-cli
+npm install
+npm run build
+npm link
+```
+
+## Use
+
+```bash
+cairn                        # help
+cairn domains                # list categories + open domains
+cairn ls csd:tools           # browse a category (or any open domain, or: cairn ls)
+cairn ls --window trending   # trending / 7d / 30d / all
+cairn ls --sort quadratic    # lens: totalWeight|quadratic|repWeight|conviction|supporterCount|createdHeight
+cairn watch                  # live auto-refreshing board
+cairn recent                 # recent proposals and support
+cairn show   <id>            # item detail and integrity check
+cairn verify <id>            # recompute the content hash and check it
+cairn ls --json              # machine-readable output
+```
+
+Posting needs a token from the board operator:
+
+```bash
+export CAIRN_TOKEN=…         # the instance's write token
+cairn propose --domain csd:features --title "Wallet GUI" --body "A graphical wallet…" --link https://…
+cairn support <id> --fee 5000000 --score 90 --confidence 80
+```
+
+## Configuration (environment variables)
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `CAIRN_API` | `https://cairn-substrate.com` | the board to talk to (use your own, e.g. `http://127.0.0.1:7777`) |
+| `CAIRN_TOKEN` | – | required only to post (propose or support) |
+| `CAIRN_RPC` | – | optional csd node RPC; enables fully trustless `verify` by recomputing the hash and confirming the one on-chain |
+
+## How it works
+
+- `browse`, `show`, `recent`, and `watch` read the board's public API.
+- `verify` fetches an item, recomputes `sha256(canonical content)` locally, and if `CAIRN_RPC` is set,
+  confirms that hash is the one committed on-chain. You trust the math, not the server.
+- `propose` and `support` post through the instance, which records the item and submits the on-chain
+  proposal or attestation. Fees go to miners. Support is a paid demand signal, not a payment to the
+  author.
+
+Fees are in base units (1 CSD = 1e8). Minimums are 0.25 CSD to propose and 0.05 CSD to attest.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+// cairn — command-line client for a Cairn signal board on Compute Substrate.
+// Reads are public; posting needs CAIRN_TOKEN. Config via env: CAIRN_API, CAIRN_TOKEN, CAIRN_RPC.
+import { CAIRN_API, MIN_FEE_PROPOSE, MIN_FEE_ATTEST, CSD_PER_COIN, csdToCoins } from "./lib/config.js";
+import * as api from "./lib/api.js";
+import { buildCommitment } from "./lib/item.js";
+import { c, banner, bannerAnimated, rule, badge, bar, csd as csdFmt, ok, warn, err, key as kdim, pad, spinner, sleep, isTty, clearScreen } from "./lib/ui.js";
+function parse(argv) {
+    const _ = [];
+    const flags = {};
+    const multi = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("--")) {
+            const k = a.slice(2);
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("--"))
+                flags[k] = true;
+            else {
+                flags[k] = next;
+                (multi[k] ??= []).push(next);
+                i++;
+            }
+        }
+        else
+            _.push(a);
+    }
+    return { _, flags, multi };
+}
+const age = (sec) => {
+    if (!sec)
+        return "—";
+    const d = Math.max(0, Math.floor(Date.now() / 1000) - sec);
+    return d < 3600 ? `${Math.floor(d / 60)}m` : d < 86400 ? `${Math.floor(d / 3600)}h` : `${Math.floor(d / 86400)}d`;
+};
+// Lenses: each is one transparent reading of the same on-chain data (matches the web
+// UI). The board returns all of these precomputed; we just sort client-side by one.
+const LENS = {
+    totalWeight: "CSD support (raw)", quadratic: "quadratic", repWeight: "reputation-weighted",
+    conviction: "conviction", supporterCount: "# supporters", createdHeight: "newest",
+};
+function printRows(items, sort = "totalWeight") {
+    if (!items.length) {
+        console.log(c.gray("  (no items here)"));
+        return;
+    }
+    const max = items[0]?.[sort] || items[0]?.totalWeight || 1;
+    items.slice(0, 25).forEach((r, i) => {
+        // annotate only lenses whose value isn't already shown in the row (raw + supporters are)
+        const lens = !["totalWeight", "supporterCount"].includes(sort) && r[sort] != null
+            ? c.gray(" · " + (sort === "createdHeight" ? "h" + r[sort] : csdFmt(r[sort]) + " " + sort)) : "";
+        console.log("");
+        console.log(`  ${c.magenta(c.bold("#" + (i + 1)))}  ${c.white(c.bold(r.title))}  ${badge(r.source)}${r.sealed ? "  " + c.gray(r.revealed ? "🔓 revealed" : "🔒 sealed") : ""}`);
+        console.log(`      ${bar(r[sort] || r.totalWeight, max)}  ${csdFmt(r.totalWeight)} ${c.gray("·")} ${c.green(String(r.supporterCount))} ${c.gray("supporters · score " + r.avgScore + " · " + age(r.createdTime) + " ago")}${lens}`);
+        console.log(c.gray(`      ${r.domain} · id ${String(r.id).slice(0, 22)}…`));
+    });
+}
+async function cmdList(a) {
+    const domain = a._[1] ?? "all";
+    const window = String(a.flags.window ?? "all");
+    const sort = LENS[String(a.flags.sort ?? "")] ? String(a.flags.sort) : "totalWeight";
+    const r = await api.apiBoard(domain, window);
+    let items = r.items ?? [];
+    if (sort !== "totalWeight")
+        items = items.slice().sort((x, y) => (y[sort] || 0) - (x[sort] || 0));
+    if (a.flags.json) {
+        console.log(JSON.stringify(items, null, 2));
+        return;
+    }
+    banner();
+    rule(`${domain} · ${LENS[sort]} · ${window} · ${CAIRN_API.replace(/^https?:\/\//, "")}`);
+    printRows(items, sort);
+}
+async function cmdWatch(a) {
+    const domain = a._[1] ?? "all";
+    const window = String(a.flags.window ?? "trending");
+    if (!isTty) {
+        printRows((await api.apiBoard(domain, window)).items);
+        return;
+    }
+    process.stdout.write("\x1b[?25l");
+    process.on("SIGINT", () => { process.stdout.write("\x1b[?25h\n"); process.exit(0); });
+    for (;;) {
+        const r = await api.apiBoard(domain, window).catch(() => ({ items: [] }));
+        clearScreen();
+        banner();
+        rule(`watch · ${domain} · ${window} · ${new Date().toLocaleTimeString()}`);
+        printRows(r.items);
+        console.log(c.gray("\n  ") + c.green("●") + c.gray(" live · refreshes every 5s · Ctrl+C to exit"));
+        await sleep(5000);
+    }
+}
+async function cmdRecent() {
+    const r = await api.apiActivity();
+    banner();
+    rule("recent activity");
+    for (const ev of r.activity ?? []) {
+        const verb = ev.type === "support" ? c.green("◈ supported") : c.cyan("✎ proposed ");
+        console.log(`  ${verb} ${c.white(String(ev.item).slice(0, 42))} ${c.gray("· " + age(ev.time) + " ago · " + (ev.amount / 1e8) + " CSD")}`);
+    }
+}
+async function cmdShow(a) {
+    const id = a._[1];
+    if (!id) {
+        console.log(warn("usage: cairn show <id>"));
+        return;
+    }
+    const r = await api.apiItem(id).catch(() => null);
+    if (!r || !r.ok) {
+        console.log(err("not found"));
+        return;
+    }
+    const it = r.item;
+    rule(it.title);
+    console.log(`  ${badge(it.source)}  ${c.gray("·")}  ${c.cyan(it.domain)}`);
+    console.log(`\n  ${c.white(it.body)}\n`);
+    if (it.links?.length)
+        console.log(`  ${kdim("links")}     ${it.links.map((l) => c.cyan(l)).join(", ")}`);
+    const total = (r.supports ?? []).reduce((x, s) => x + s.weight, 0);
+    console.log(`  ${kdim("support")}   ${csdFmt(total)} ${c.gray("from")} ${c.green(String(new Set((r.supports ?? []).map((s) => s.attester)).size))} ${c.gray("supporters")}`);
+    console.log(`  ${kdim("proposer")}  ${c.gray(it.proposerHandle || it.proposer)}`);
+    console.log(`  ${kdim("hash")}      ${c.magenta(it.payloadHash)}`);
+    console.log(`  ${kdim("integrity")} ${r.integrityOk ? ok("content matches commitment") : err("MISMATCH")}`);
+}
+async function cmdVerify(a) {
+    const id = a._[1];
+    if (!id) {
+        console.log(warn("usage: cairn verify <id>"));
+        return;
+    }
+    const sp = spinner("fetching + recomputing");
+    const r = await api.apiItem(id).catch(() => null);
+    if (!r || !r.ok) {
+        sp.stop();
+        console.log(err("not found"));
+        return;
+    }
+    const it = r.item;
+    const { payloadHash } = buildCommitment({ v: 1, domain: it.domain, title: it.title, body: it.body, links: it.links ?? [] });
+    const chain = await api.chainProposal(it.id);
+    sp.stop();
+    console.log(`${kdim("recomputed")}  ${c.magenta(payloadHash)}`);
+    console.log(`${kdim("reported")}    ${c.magenta(it.payloadHash)}`);
+    const contentOk = payloadHash.toLowerCase() === String(it.payloadHash).toLowerCase();
+    if (chain?.payload_hash) {
+        console.log(`${kdim("on-chain")}    ${c.magenta(chain.payload_hash)}`);
+        console.log(contentOk && String(chain.payload_hash).toLowerCase() === payloadHash.toLowerCase()
+            ? ok("VERIFIED — content matches the on-chain commitment (trustless, via CAIRN_RPC)")
+            : err("MISMATCH"));
+    }
+    else {
+        console.log(contentOk ? ok("content matches the reported commitment") + c.gray("  (set CAIRN_RPC to also check the chain directly)") : err("content does NOT match the reported hash"));
+    }
+}
+async function cmdPropose(a) {
+    const domain = String(a.flags.domain ?? "");
+    const title = String(a.flags.title ?? "");
+    const body = String(a.flags.body ?? "");
+    const links = a.multi.link ?? [];
+    if (!domain || !title) {
+        console.log(warn("usage: ") + c.cyan("cairn propose --domain csd:features --title <t> --body <b> [--link <url>] [--fee <base>]"));
+        return;
+    }
+    const fee = Number(a.flags.fee ?? MIN_FEE_PROPOSE);
+    const sp = spinner("posting to Cairn");
+    try {
+        const r = await api.apiPropose({ domain, title, body, links, fee: Number.isFinite(fee) && fee >= MIN_FEE_PROPOSE ? Math.floor(fee) : MIN_FEE_PROPOSE });
+        sp.stop();
+        console.log(r.ok ? ok(`proposed  ${c.cyan(r.id)}`) : err(r.error || "failed"));
+    }
+    catch (e) {
+        sp.stop();
+        console.log(err(e.message));
+    }
+}
+async function cmdSupport(a) {
+    const id = a._[1];
+    if (!id) {
+        console.log(warn("usage: ") + c.cyan("cairn support <id> --fee <base> [--score 0-100] [--confidence 0-100]"));
+        return;
+    }
+    const fee = Number(a.flags.fee ?? MIN_FEE_ATTEST);
+    const sp = spinner("posting support to Cairn");
+    try {
+        const r = await api.apiSupport({ id, fee: Number.isFinite(fee) && fee >= MIN_FEE_ATTEST ? Math.floor(fee) : MIN_FEE_ATTEST, score: Number(a.flags.score ?? 75), confidence: Number(a.flags.confidence ?? 60) });
+        sp.stop();
+        console.log(r.ok ? ok(`supported  ${c.cyan(r.id)}`) : err(r.error || "failed"));
+    }
+    catch (e) {
+        sp.stop();
+        console.log(err(e.message));
+    }
+}
+async function cmdDomains() {
+    const r = await api.apiDomains();
+    banner();
+    rule("categories");
+    for (const dom of r.domains ?? [])
+        console.log(`  ${c.cyan(pad(dom.key, 20))} ${c.white(dom.title)} ${c.gray(dom.count != null ? "(" + dom.count + ")" : "")}`);
+    // open domains: anyone can create one by proposing into it (cairn ls <domain> works for any).
+    const disc = r.discovered ?? [];
+    if (disc.length) {
+        console.log(c.gray("\n  open domains (created by proposing into them):"));
+        for (const d of disc)
+            console.log(`  ${c.cyan(pad(d.key, 20))} ${c.gray((d.count != null ? d.count + " items" : "") + (d.totalWeight ? " · " + csdToCoins(d.totalWeight) + " CSD" : ""))}`);
+    }
+}
+async function help() {
+    await bannerAnimated();
+    const cmd = (n, args, d) => console.log(`  ${c.cyan(pad(n, 9))} ${c.gray(pad(args, 44))} ${c.dim(d)}`);
+    console.log(c.bold("  commands"));
+    cmd("domains", "", "list categories + open domains");
+    cmd("ls", "[domain] --window trending|7d|30d|all --sort <lens>", "browse the board (+ --json)");
+    cmd("top", "[domain]", "alias for ls");
+    cmd("watch", "[domain]", "live auto-refreshing board");
+    cmd("recent", "", "recent proposals + support");
+    cmd("show", "<id>", "item detail + integrity");
+    cmd("verify", "<id>", "recompute hash, check vs chain");
+    cmd("propose", "--domain <d> --title <t> --body <b>", "post an item (needs CAIRN_TOKEN)");
+    cmd("support", "<id> --fee <base>", "back an item (needs CAIRN_TOKEN)");
+    console.log(c.gray("\n  lenses (--sort): " + Object.keys(LENS).join(" · ")));
+    console.log(c.gray(`  api: ${CAIRN_API}  ·  1 CSD = ${CSD_PER_COIN} base · propose ≥ ${MIN_FEE_PROPOSE} · attest ≥ ${MIN_FEE_ATTEST}`));
+    console.log(c.gray("  config: CAIRN_API (board url) · CAIRN_TOKEN (instance write token, to post) · CAIRN_RPC (trustless verify)"));
+    console.log(c.gray("  display: honors NO_COLOR · --no-color · --no-anim · TERM=dumb (color/animation auto-off when piped)"));
+    console.log(c.gray("  keyless non-custodial posting + sealed claims: use the Cairn Wallet (browser extension)."));
+}
+async function main() {
+    const a = parse(process.argv.slice(2));
+    switch (a._[0]) {
+        case "domains": return cmdDomains();
+        case "ls":
+        case "list":
+        case "top": return cmdList(a);
+        case "watch": return cmdWatch(a);
+        case "recent": return cmdRecent();
+        case "show": return cmdShow(a);
+        case "verify": return cmdVerify(a);
+        case "propose": return cmdPropose(a);
+        case "support": return cmdSupport(a);
+        default: return help();
+    }
+}
+main().catch((e) => { console.error(err(String(e?.message ?? e))); process.exit(1); });

package/dist/lib/api.js

@@ -0,0 +1,48 @@
+// Thin client for a Cairn instance's HTTP API. Reads are public; writes need a token.
+import { CAIRN_API, CAIRN_TOKEN, CAIRN_RPC } from "./config.js";
+async function req(path, init) {
+    let res;
+    try {
+        res = await fetch(`${CAIRN_API}${path}`, { signal: AbortSignal.timeout(8000), ...init });
+    }
+    catch (e) {
+        throw new Error(`cannot reach ${CAIRN_API} (${e?.message ?? e}) — set CAIRN_API to a running Cairn instance`);
+    }
+    if (res.status === 401)
+        throw new Error(`${CAIRN_API} is password-gated (401). Point CAIRN_API at a public instance or your own (e.g. http://127.0.0.1:7777)`);
+    if (!res.ok)
+        throw new Error(`API ${path} → HTTP ${res.status}`);
+    return res.json();
+}
+function writeReq(path, body) {
+    if (!CAIRN_TOKEN)
+        throw new Error("posting needs a token — set CAIRN_TOKEN (the operator's write token)");
+    return req(path, {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-cairn-token": CAIRN_TOKEN },
+        body: JSON.stringify(body),
+    });
+}
+export const apiHealth = () => req("/api/health");
+export const apiDomains = () => req("/api/domains");
+export const apiStats = () => req("/api/stats");
+export const apiBoard = (domain, window) => req(`/api/board?domain=${encodeURIComponent(domain)}&window=${encodeURIComponent(window)}`);
+export const apiItem = (id) => req(`/api/item/${encodeURIComponent(id)}`);
+export const apiActivity = () => req("/api/activity");
+export const apiPropose = (body) => writeReq("/api/propose", body);
+export const apiSupport = (body) => writeReq("/api/support", body);
+// optional: query a raw csd node RPC (for trustless verify)
+export async function chainProposal(id) {
+    if (!CAIRN_RPC)
+        return null;
+    try {
+        const r = await fetch(`${CAIRN_RPC}/proposal/${id}`, { signal: AbortSignal.timeout(6000) });
+        if (!r.ok)
+            return null;
+        const j = await r.json();
+        return j.proposal ?? j ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/config.js

@@ -0,0 +1,10 @@
+// cairn-cli configuration (env-overridable).
+export const CAIRN_API = (process.env.CAIRN_API ?? "https://cairn-substrate.com").replace(/\/+$/, "");
+export const CAIRN_TOKEN = process.env.CAIRN_TOKEN ?? ""; // required only for posting
+export const CAIRN_RPC = process.env.CAIRN_RPC ?? ""; // optional: a csd node RPC, enables trustless verify
+export const CSD_PER_COIN = 100_000_000;
+export const MIN_FEE_PROPOSE = 25_000_000; // 0.25 CSD
+export const MIN_FEE_ATTEST = 5_000_000; // 0.05 CSD
+export function csdToCoins(base) {
+    return (base / CSD_PER_COIN).toLocaleString(undefined, { maximumFractionDigits: 4 });
+}

package/dist/lib/item.js

@@ -0,0 +1,26 @@
+// Canonical item record + integrity commitment.
+// payload_hash = sha256(canonical JSON of the content record). No salt: the board
+// is public, so the hash is for tamper-evidence, not secrecy.
+import { createHash } from "node:crypto";
+// Deterministic JSON: recursively sorted keys, no insignificant whitespace.
+export function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
+}
+export function sha256Hex(data) {
+    return "0x" + createHash("sha256").update(data).digest("hex");
+}
+export function buildCommitment(content) {
+    const canonical = stableStringify(content);
+    return { canonical, payloadHash: sha256Hex(canonical) };
+}
+// Verify that displayed content matches an on-chain payload_hash.
+export function verifyContent(content, onchainHash) {
+    const { payloadHash } = buildCommitment(content);
+    return payloadHash.toLowerCase() === onchainHash.toLowerCase();
+}

package/dist/lib/ui.js

@@ -0,0 +1,121 @@
+// Cairn CLI theme — matches the website + wallet: black-and-white terminal with a
+// single phosphor-green accent, sharp edges, a blinking cursor and a fast decode
+// "boot" reveal. Zero deps.
+//
+// clig.dev compliance:
+//   • color off when stdout/stderr isn't a TTY, NO_COLOR is set, TERM=dumb, or
+//     --no-color is passed (CAIRN_COLOR=1 forces it on for demos)
+//   • no animation unless interactive + color (CAIRN_NO_ANIM / --no-anim opt out)
+//   • the spinner (transient progress) goes to STDERR so stdout stays pipeable
+const argv = process.argv;
+const TTY = !!process.stdout.isTTY || process.env.CAIRN_COLOR === "1";
+const NO_COLOR = (!!process.env.NO_COLOR && process.env.NO_COLOR !== "") || process.env.TERM === "dumb"
+    || process.env.CAIRN_NO_COLOR === "1" || argv.includes("--no-color");
+const COLOR = (TTY || process.env.CAIRN_COLOR === "1") && !NO_COLOR;
+const TRUE = COLOR && /^(truecolor|24bit)$/.test(process.env.COLORTERM ?? "");
+const ANIM = COLOR && !!process.stdout.isTTY && !process.env.CAIRN_NO_ANIM && !argv.includes("--no-anim");
+// truecolor with a 256-color fallback, so the exact wallet/site palette renders when
+// the terminal supports it and degrades gracefully when it doesn't.
+const fg = (rgb, c256) => (s) => (COLOR ? `\x1b[${TRUE ? rgb : c256}m${s}\x1b[0m` : String(s));
+const sgr = (code) => (s) => (COLOR ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+// palette — phosphor green #6ee7a0 accent, off-white text, dim grays, soft red #ff6b6b
+const GREEN = fg("38;2;110;231;160", "38;5;114");
+const WHITE = fg("38;2;230;230;230", "97");
+const GRAY = fg("38;2;125;125;125", "38;5;245");
+const FAINT = fg("38;2;90;90;90", "38;5;240");
+const RED = fg("38;2;255;107;107", "38;5;203");
+export const c = {
+    green: GREEN, white: WHITE, gray: GRAY, faint: FAINT, red: RED,
+    dim: sgr("2"), bold: sgr("1"),
+    // legacy role names remapped to the monochrome+green theme so call sites stay put:
+    cyan: GREEN, // accents · ids · bars  → phosphor green
+    magenta: WHITE, // emphasis · rank · wordmark → bright white
+    amber: GRAY, // demo / muted → gray
+};
+const W = 64;
+const TAG = "paid-attention board · compute substrate";
+export function banner() {
+    if (!TTY)
+        return; // chrome is for humans; piped output skips it
+    console.log(`  ${c.white(c.bold("▓▒░ CAIRN"))} ${c.green("▮")}  ${c.gray(TAG)}`);
+    rule();
+}
+export function rule(label = "") {
+    if (label) {
+        const tail = Math.max(0, W - label.length - 5);
+        console.log(`${c.green("──")} ${c.white(c.bold(label))} ${c.faint("─".repeat(tail))}`);
+    }
+    else
+        console.log(c.faint("─".repeat(W)));
+}
+export function badge(source) {
+    if (source === "chain")
+        return c.green("⛓ on-chain");
+    if (source === "demo")
+        return c.gray("◆ demo");
+    if (source === "draft")
+        return c.gray("✎ draft");
+    return c.gray(source);
+}
+// proportional bar — green fill, faint track (matches the site's support bars)
+export function bar(value, max, width = 16) {
+    const frac = max > 0 ? Math.min(1, value / max) : 0;
+    const fill = Math.round(frac * width);
+    return c.green("█".repeat(fill)) + c.faint("░".repeat(Math.max(0, width - fill)));
+}
+export function csd(base) {
+    return c.green(`${(base / 1e8).toLocaleString(undefined, { maximumFractionDigits: 4 })}`) + c.gray(" CSD");
+}
+export function ok(s) { return c.green("✓ ") + s; }
+export function warn(s) { return c.gray("⚠ ") + s; }
+export function err(s) { return c.red("✗ ") + s; }
+export function key(k) { return c.gray(k); }
+export function pad(s, n) {
+    const visible = s.replace(/\x1b\[[0-9;]*m/g, "").length;
+    return s + " ".repeat(Math.max(0, n - visible));
+}
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export const isTty = TTY;
+// Phosphor braille spinner for network/async work. Writes to STDERR (clig.dev: keep
+// stdout clean for piping) and is a no-op when output isn't an interactive terminal.
+export function spinner(label) {
+    if (!ANIM)
+        return { stop: (final) => { if (final)
+                console.log(final); } };
+    const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    let i = 0;
+    const t = setInterval(() => process.stderr.write(`\r${c.green(frames[i++ % frames.length])} ${c.gray(label)} `), 80);
+    return {
+        stop: (final) => {
+            clearInterval(t);
+            process.stderr.write("\r\x1b[K");
+            if (final)
+                console.log(final);
+        },
+    };
+}
+// Fast decode-reveal of the CAIRN wordmark: scramble glyphs resolve L→R into white
+// letters with a green cursor — the site's "boot" feel. ~360ms, and only on an
+// interactive TTY (static banner otherwise, so help piped to a file isn't garbage).
+export async function bannerAnimated() {
+    if (!ANIM) {
+        banner();
+        return;
+    }
+    const word = "CAIRN";
+    const pool = "▖▗▘▙▚▛▜▝▞▟01#%/\\<>=".split("");
+    const rnd = () => pool[Math.floor(Math.random() * pool.length)];
+    for (let step = 0; step <= word.length; step++) {
+        let s = "";
+        for (let i = 0; i < word.length; i++)
+            s += i < step ? c.white(c.bold(word[i])) : c.green(rnd());
+        process.stdout.write(`\r  ${c.gray("▓▒░")} ${s} ${c.green("▋")}  ${c.gray("· " + TAG)}   `);
+        await sleep(60);
+    }
+    process.stdout.write(`\r  ${c.gray("▓▒░")} ${c.white(c.bold(word))} ${c.green("▮")}  ${c.gray("· " + TAG)}\n`);
+    rule();
+}
+export function clearScreen() {
+    if (TTY)
+        process.stdout.write("\x1b[2J\x1b[H");
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@inversealtruism/cairn-cli",
+  "version": "0.1.0",
+  "description": "Command-line client for a Cairn signal board on Compute Substrate — browse, propose, and back what to build.",
+  "type": "module",
+  "bin": { "cairn": "dist/cli.js" },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=20" },
+  "repository": { "type": "git", "url": "git+https://github.com/InverseAltruism/cairn-cli.git" },
+  "homepage": "https://cairn-substrate.com",
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "test": "tsc && node test/e2e.mjs",
+    "prepare": "tsc"
+  },
+  "keywords": ["cairn", "compute-substrate", "cli"],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}