@getdial/cli 0.1.0

package/README.md

@@ -0,0 +1,19 @@
+# @getdial/cli
+
+The Dial CLI.
+
+Install via the bootstrap script:
+
+```bash
+curl -fsSL https://dial.up.railway.app/install | bash
+```
+
+Or directly from npm:
+
+```bash
+npm install -g @getdial/cli
+```
+
+Requires Node 22+.
+
+See `docs/superpowers/specs/2026-05-25-dial-cli-and-listen-service-design.md` for design.

package/dist/cli.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { runDoctor } from "./commands/doctor.js";
+import { runSignup } from "./commands/signup.js";
+import { runOnboard } from "./commands/onboard.js";
+import { runListen } from "./commands/listen/index.js";
+import { runListenInstall } from "./commands/listen/install.js";
+import { runListenUninstall } from "./commands/listen/uninstall.js";
+import { runListenStatus } from "./commands/listen/status.js";
+import { runWaitFor } from "./commands/wait-for.js";
+const program = new Command();
+program
+    .name("dial")
+    .description("Dial CLI — set up your account and run the listen service.")
+    .version("0.1.0");
+program
+    .command("doctor")
+    .description("Report state and what to do next.")
+    .option("--json", "machine-readable output")
+    .action(async (opts) => process.exit(await runDoctor({ json: !!opts.json })));
+program
+    .command("signup <email>")
+    .description("Request an email OTP for the given address.")
+    .option("--force", "overwrite any pending signup")
+    .option("--json", "machine-readable output")
+    .action(async (email, opts) => process.exit(await runSignup(email, { force: !!opts.force, json: !!opts.json })));
+program
+    .command("onboard")
+    .description("Verify the OTP and finish onboarding.")
+    .option("--verification-id <id>", "explicit verification id (falls back to local pending signup)")
+    .requiredOption("--code <code>", "6-digit OTP from your email")
+    .option("--json", "machine-readable output")
+    .action(async (opts) => process.exit(await runOnboard({ verificationId: opts.verificationId, code: opts.code, json: !!opts.json })));
+const listen = program
+    .command("listen")
+    .description("Run the listen worker (used by launchd/systemd).")
+    .action(async () => process.exit(await runListen()));
+listen
+    .command("install")
+    .description("Install the listen daemon (launchd or systemd user unit).")
+    .option("--json", "machine-readable output")
+    .action(async (opts) => process.exit(await runListenInstall({ json: !!opts.json })));
+listen
+    .command("uninstall")
+    .description("Stop and remove the listen daemon.")
+    .option("--json", "machine-readable output")
+    .action(async (opts) => process.exit(await runListenUninstall({ json: !!opts.json })));
+listen
+    .command("status")
+    .description("Report listen daemon state and last events.")
+    .option("--json", "machine-readable output")
+    .action(async (opts) => process.exit(await runListenStatus({ json: !!opts.json })));
+program
+    .command("wait-for <event-type>")
+    .description("Wait for the next matching event in the listen log (e.g. call.ended, message.received).")
+    .option("-f, --field <name=value>", "exact match on a top-level field (repeatable)", (v, prev = []) => [...prev, v], [])
+    .option("-r, --regex <name=pattern>", "regex match on a top-level field (repeatable). Pattern can be /re/flags or a bare RE.", (v, prev = []) => [...prev, v], [])
+    .option("-t, --timeout <seconds>", "timeout in seconds (default 30)", (v) => parseInt(v, 10), 30)
+    .option("--json", "machine-readable output")
+    .action(async (eventType, opts) => process.exit(await runWaitFor({
+    eventType,
+    fields: opts.field,
+    regexes: opts.regex,
+    timeoutSeconds: opts.timeout,
+    json: !!opts.json,
+})));
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(2);
+});

package/dist/commands/doctor.js

@@ -0,0 +1,95 @@
+import { readPendingSignup, readAuth } from "../lib/state.js";
+import { apiGet, baseUrl, pingBackend } from "../lib/api.js";
+import { supervisorStatus, lastEventAtFromLog } from "../lib/supervisor/index.js";
+import { paths } from "../lib/paths.js";
+const OTP_EXPIRY_MS = 10 * 60 * 1000;
+async function buildReport() {
+    const ping = await pingBackend();
+    const auth = readAuth();
+    const pending = readPendingSignup();
+    let keyValid = null;
+    if (auth?.api_key) {
+        const res = await apiGet("/api/v1/account", auth.api_key);
+        keyValid = res.ok;
+    }
+    const pendingAgeMs = pending ? Date.now() - Date.parse(pending.created_at) : null;
+    const pendingExpired = pendingAgeMs == null ? null : pendingAgeMs > OTP_EXPIRY_MS;
+    let listenState = { installed: false, running: false, last_event_at: null };
+    try {
+        const s = supervisorStatus();
+        listenState = {
+            installed: s.installed,
+            running: s.running,
+            last_event_at: lastEventAtFromLog(paths().listenLog),
+        };
+    }
+    catch {
+        // unsupported platform — leave defaults
+    }
+    let nextStep;
+    if (!auth) {
+        if (pending && pendingExpired === false)
+            nextStep = "onboard";
+        else if (pending && pendingExpired)
+            nextStep = "resend_otp";
+        else
+            nextStep = "signup";
+    }
+    else if (keyValid === false) {
+        nextStep = "signup";
+    }
+    else if (!listenState.installed || !listenState.running) {
+        nextStep = "install_listen";
+    }
+    else {
+        nextStep = "ready";
+    }
+    return {
+        cli: { version: "0.1.0", node: process.versions.node },
+        backend: { url: baseUrl(), reachable: ping.reachable, latency_ms: ping.latencyMs },
+        auth: {
+            signed_in: Boolean(auth),
+            email: auth?.email ?? null,
+            account_id: auth?.account_id ?? null,
+            api_key_present: Boolean(auth?.api_key),
+            api_key_fingerprint: auth?.api_key ? auth.api_key.slice(-4) : null,
+            key_valid: keyValid,
+        },
+        pending_otp: {
+            verification_id: pending?.verification_id ?? null,
+            age_seconds: pendingAgeMs == null ? null : Math.round(pendingAgeMs / 1000),
+            expired: pendingExpired,
+        },
+        listen: listenState,
+        next_step: nextStep,
+    };
+}
+function humanRender(r) {
+    const lines = [];
+    lines.push(`dial ${r.cli.version}  (node ${r.cli.node})`);
+    lines.push(`backend:     ${r.backend.url}  ${r.backend.reachable ? `reachable${r.backend.latency_ms != null ? ` (${r.backend.latency_ms}ms)` : ""}` : "UNREACHABLE"}`);
+    if (r.auth.signed_in) {
+        lines.push(`auth:        signed in as ${r.auth.email} (account ${r.auth.account_id}, key sk_live_***${r.auth.api_key_fingerprint})${r.auth.key_valid === false ? "  [key rejected by backend]" : ""}`);
+    }
+    else {
+        lines.push(`auth:        not signed in`);
+    }
+    if (r.pending_otp.verification_id) {
+        lines.push(`pending otp: ${r.pending_otp.age_seconds}s old${r.pending_otp.expired ? " (EXPIRED)" : ""}`);
+    }
+    else {
+        lines.push(`pending otp: none`);
+    }
+    lines.push(`listen:      ${r.listen.installed ? (r.listen.running ? "running" : "installed (stopped)") : "not installed"}${r.listen.last_event_at ? `, last event ${r.listen.last_event_at}` : ""}`);
+    lines.push("");
+    lines.push(`next: ${r.next_step}`);
+    return lines.join("\n");
+}
+export async function runDoctor(opts) {
+    const report = await buildReport();
+    if (opts.json)
+        console.log(JSON.stringify(report, null, 2));
+    else
+        console.log(humanRender(report));
+    return 0;
+}

package/dist/commands/listen/index.js

@@ -0,0 +1,29 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { readAuth } from "../../lib/state.js";
+import { startWorker } from "../../lib/pubnub.js";
+import { appendJsonl } from "../../lib/log.js";
+import { paths } from "../../lib/paths.js";
+function isSupervised() {
+    return Boolean(process.env.LAUNCHD_SOCKET || process.env.LAUNCH_DAEMON || process.env.INVOCATION_ID);
+}
+export async function runListen() {
+    const auth = readAuth();
+    if (!auth) {
+        appendJsonl(paths().listenLog, { ts: new Date().toISOString(), lifecycle: "startup", ok: false, error: "no auth.json" });
+        if (isSupervised()) {
+            await delay(30_000);
+        }
+        return 1;
+    }
+    appendJsonl(paths().listenLog, { ts: new Date().toISOString(), lifecycle: "startup", ok: true, account_id: auth.account_id });
+    const ctrl = startWorker(auth.api_key, auth.account_id);
+    const onSignal = async (sig) => {
+        appendJsonl(paths().listenLog, { ts: new Date().toISOString(), lifecycle: "shutdown", signal: sig });
+        await ctrl.stop();
+    };
+    process.on("SIGTERM", onSignal);
+    process.on("SIGINT", onSignal);
+    await ctrl.whenStopped;
+    const code = process.exitCode;
+    return typeof code === "number" ? code : 0;
+}

package/dist/commands/listen/install.js

@@ -0,0 +1,35 @@
+import { readAuth } from "../../lib/state.js";
+import { installSupervised } from "../../lib/supervisor/index.js";
+function resolveDialPath() {
+    return process.env.DIAL_BIN_OVERRIDE ?? process.argv[1] ?? "dial";
+}
+export async function runListenInstall(opts) {
+    const auth = readAuth();
+    if (!auth) {
+        if (opts.json)
+            console.log(JSON.stringify({ ok: false, code: "not_signed_in" }));
+        else
+            console.error("Not signed in. Run `dial signup` and `dial onboard` first.");
+        return 1;
+    }
+    try {
+        const result = installSupervised(resolveDialPath());
+        if (opts.json)
+            console.log(JSON.stringify({ ok: true, changed: result.changed, unit_path: result.unitPath, warnings: result.warnings }));
+        else {
+            console.log(`listen service installed${result.changed ? "" : " (no change)"}.`);
+            console.log(`  unit: ${result.unitPath}`);
+            for (const w of result.warnings)
+                console.log(`  ! ${w}`);
+        }
+        return 0;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (opts.json)
+            console.log(JSON.stringify({ ok: false, code: "install_failed", error: msg }));
+        else
+            console.error(`listen install failed: ${msg}`);
+        return 2;
+    }
+}

package/dist/commands/listen/status.js

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+import { lastEventAtFromLog, supervisorStatus } from "../../lib/supervisor/index.js";
+import { paths } from "../../lib/paths.js";
+export async function runListenStatus(opts) {
+    const s = supervisorStatus();
+    const lastEventAt = lastEventAtFromLog(paths().listenLog);
+    let lastEvents = [];
+    try {
+        const raw = readFileSync(paths().listenLog, "utf8");
+        const lines = raw.trim().split("\n").filter(Boolean);
+        lastEvents = lines.slice(-5).map((l) => { try {
+            return JSON.parse(l);
+        }
+        catch {
+            return l;
+        } });
+    }
+    catch { /* ignore */ }
+    const out = {
+        installed: s.installed,
+        running: s.running,
+        pid: s.pid,
+        unit_path: s.unitPath,
+        last_event_at: lastEventAt,
+        last_events: lastEvents,
+    };
+    if (opts.json)
+        console.log(JSON.stringify(out, null, 2));
+    else {
+        console.log(`installed:     ${out.installed}`);
+        console.log(`running:       ${out.running}`);
+        console.log(`pid:           ${out.pid ?? "-"}`);
+        console.log(`unit:          ${out.unit_path}`);
+        console.log(`last event at: ${out.last_event_at ?? "-"}`);
+    }
+    return 0;
+}

package/dist/commands/listen/uninstall.js

@@ -0,0 +1,19 @@
+import { uninstallSupervised } from "../../lib/supervisor/index.js";
+export async function runListenUninstall(opts) {
+    try {
+        uninstallSupervised();
+        if (opts.json)
+            console.log(JSON.stringify({ ok: true }));
+        else
+            console.log("listen service uninstalled.");
+        return 0;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (opts.json)
+            console.log(JSON.stringify({ ok: false, error: msg }));
+        else
+            console.error(`listen uninstall failed: ${msg}`);
+        return 2;
+    }
+}

package/dist/commands/onboard.js

@@ -0,0 +1,77 @@
+import { readPendingSignup, clearPendingSignup, writeAuth } from "../lib/state.js";
+import { apiPost } from "../lib/api.js";
+export async function runOnboard(opts) {
+    let verificationId = opts.verificationId;
+    let email = null;
+    if (!verificationId) {
+        const pending = readPendingSignup();
+        if (!pending) {
+            if (opts.json)
+                console.log(JSON.stringify({ ok: false, code: "no_pending_signup" }));
+            else
+                console.error("No pending signup. Run `dial signup <email>` first, or pass --verification-id.");
+            return 1;
+        }
+        verificationId = pending.verification_id;
+        email = pending.email;
+    }
+    const res = await apiPost("/api/v1/auth/verify", { verification_id: verificationId, code: opts.code });
+    if (!res.ok) {
+        if (opts.json)
+            console.log(JSON.stringify({ ok: false, code: "verify_failed", status: res.status, error: res.error }));
+        else
+            console.error(`onboard failed: ${res.error}`);
+        return res.status === 401 ? 1 : 2;
+    }
+    const apiKey = res.data.api_key ?? null;
+    if (!apiKey || !res.data.account_id) {
+        if (opts.json)
+            console.log(JSON.stringify({ ok: false, code: "missing_api_key", error: "backend returned no api_key" }));
+        else
+            console.error("onboard failed: backend returned no api_key");
+        return 2;
+    }
+    writeAuth({
+        api_key: apiKey,
+        account_id: res.data.account_id,
+        email: email ?? "",
+        phone_number: res.data.phone_number ?? null,
+        phone_number_id: res.data.phone_number_id ?? null,
+    });
+    clearPendingSignup();
+    let listenStatus = { installed: false, warnings: [], error: null };
+    try {
+        const { installSupervised } = await import("../lib/supervisor/index.js");
+        const dialPath = process.env.DIAL_BIN_OVERRIDE ?? process.argv[1] ?? "dial";
+        const result = installSupervised(dialPath);
+        listenStatus = { installed: true, warnings: result.warnings, error: null };
+    }
+    catch (err) {
+        listenStatus = { installed: false, warnings: [], error: err instanceof Error ? err.message : String(err) };
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            api_key: apiKey,
+            account_id: res.data.account_id,
+            phone_number: res.data.phone_number ?? null,
+            phone_number_id: res.data.phone_number_id ?? null,
+            listen: listenStatus,
+        }));
+    }
+    else {
+        console.log("onboarded.");
+        console.log(`  api key:      ${apiKey}   (save this — shown once)`);
+        if (res.data.phone_number)
+            console.log(`  phone number: ${res.data.phone_number}`);
+        if (listenStatus.installed) {
+            console.log(`  listen:       installed and running (logs: ~/.local/state/dial/listen.log)`);
+            for (const w of listenStatus.warnings)
+                console.log(`                ! ${w}`);
+        }
+        else {
+            console.log(`  listen:       NOT installed (${listenStatus.error}). Run \`dial listen install\` manually.`);
+        }
+    }
+    return 0;
+}

package/dist/commands/signup.js

@@ -0,0 +1,36 @@
+import { readPendingSignup, writePendingSignup } from "../lib/state.js";
+import { apiPost } from "../lib/api.js";
+const PENDING_FRESH_MS = 10 * 60 * 1000;
+export async function runSignup(email, opts) {
+    const existing = readPendingSignup();
+    if (existing && !opts.force) {
+        const age = Date.now() - Date.parse(existing.created_at);
+        if (Number.isFinite(age) && age < PENDING_FRESH_MS) {
+            const ageS = Math.round(age / 1000);
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: false, code: "pending_exists", verification_id: existing.verification_id, email: existing.email, age_seconds: ageS }));
+            }
+            else {
+                console.error(`A pending OTP for ${existing.email} is still fresh (${ageS}s old). Use \`dial onboard --code <code>\` or re-run with --force to start a new one.`);
+            }
+            return 3;
+        }
+    }
+    const res = await apiPost("/api/v1/auth/signup", { email });
+    if (!res.ok) {
+        if (opts.json)
+            console.log(JSON.stringify({ ok: false, code: "signup_failed", status: res.status, error: res.error }));
+        else
+            console.error(`signup failed: ${res.error}`);
+        return 2;
+    }
+    writePendingSignup({ verification_id: res.data.verification_id, email, created_at: new Date().toISOString() });
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, verification_id: res.data.verification_id, email }));
+    }
+    else {
+        console.log(`OTP sent to ${email}.`);
+        console.log(`Run \`dial onboard --code <code>\` once you have it (verification_id is stored locally).`);
+    }
+    return 0;
+}

package/dist/commands/wait-for.js

@@ -0,0 +1,119 @@
+import { closeSync, existsSync, openSync, readFileSync, readSync, statSync } from "node:fs";
+import { paths } from "../lib/paths.js";
+import { supervisorStatus } from "../lib/supervisor/index.js";
+import { matches, parseFieldArg, parseRegexArg } from "../lib/event-filter.js";
+const POLL_INTERVAL_MS = 200;
+export async function runWaitFor(opts) {
+    const status = supervisorStatus();
+    if (!status.installed || !status.running) {
+        const hint = !status.installed
+            ? "Run `dial listen install` (or rerun `dial onboard`)."
+            : "It's installed but not running. Reinstall with `dial listen install` to restart it.";
+        if (opts.json) {
+            console.log(JSON.stringify({
+                ok: false,
+                reason: "listen_not_running",
+                installed: status.installed,
+                running: status.running,
+                pid: status.pid,
+                unit_path: status.unitPath,
+            }));
+        }
+        else {
+            console.error(`listen daemon is not running (installed=${status.installed}, running=${status.running}). ${hint}`);
+        }
+        return 3;
+    }
+    const spec = {
+        eventType: opts.eventType,
+        fields: opts.fields.map(parseFieldArg),
+        regexes: opts.regexes.map(parseRegexArg),
+    };
+    const file = paths().listenLog;
+    const startPos = currentSize(file);
+    const deadline = Date.now() + opts.timeoutSeconds * 1000;
+    let pos = startPos;
+    while (Date.now() < deadline) {
+        const size = currentSize(file);
+        if (size < pos)
+            pos = 0; // log rotated
+        if (size > pos) {
+            const chunk = readRange(file, pos, size - pos);
+            pos = size;
+            for (const { line, obj } of parseLines(chunk)) {
+                if (obj && matches(obj, spec)) {
+                    process.stdout.write(line + "\n");
+                    return 0;
+                }
+            }
+        }
+        await sleep(POLL_INTERVAL_MS);
+    }
+    const fallback = findLatestMatchInFile(file, spec);
+    if (fallback) {
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: false, timeout: true, source: "log", event: fallback.obj }));
+        }
+        else {
+            console.error(`timed out after ${opts.timeoutSeconds}s; latest matching entry in log:`);
+            process.stdout.write(fallback.line + "\n");
+        }
+        return 1;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: false, timeout: true, source: null, event: null }));
+    }
+    else {
+        console.error(`timed out after ${opts.timeoutSeconds}s; no matching ${opts.eventType} entry in log.`);
+    }
+    return 2;
+}
+function currentSize(file) {
+    try {
+        return statSync(file).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function readRange(file, offset, length) {
+    const fd = openSync(file, "r");
+    try {
+        const buf = Buffer.alloc(length);
+        readSync(fd, buf, 0, length, offset);
+        return buf.toString("utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function parseLines(chunk) {
+    return chunk.split("\n").filter(Boolean).map((line) => {
+        try {
+            return { line, obj: JSON.parse(line) };
+        }
+        catch {
+            return { line, obj: null };
+        }
+    });
+}
+function findLatestMatchInFile(file, spec) {
+    if (!existsSync(file))
+        return null;
+    const raw = readFileSync(file, "utf8");
+    const lines = raw.split("\n").filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            const obj = JSON.parse(lines[i]);
+            if (matches(obj, spec))
+                return { line: lines[i], obj };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/lib/api.js

@@ -0,0 +1,51 @@
+import { request } from "undici";
+import { logger } from "./log.js";
+const DEFAULT_BASE = "https://dial.up.railway.app";
+export function baseUrl() {
+    return process.env.DIAL_API_URL ?? DEFAULT_BASE;
+}
+export async function apiPost(path, body, apiKey) {
+    return apiRequest("POST", path, body, apiKey);
+}
+export async function apiGet(path, apiKey) {
+    return apiRequest("GET", path, undefined, apiKey);
+}
+async function apiRequest(method, path, body, apiKey) {
+    const url = `${baseUrl()}${path}`;
+    const headers = { "content-type": "application/json" };
+    if (apiKey)
+        headers.authorization = `Bearer ${apiKey}`;
+    try {
+        const res = await request(url, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const text = await res.body.text();
+        let parsed = null;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch { /* keep raw */ }
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+            return { ok: true, status: res.statusCode, data: parsed };
+        }
+        const errMsg = parsed?.error ?? text ?? `HTTP ${res.statusCode}`;
+        return { ok: false, status: res.statusCode, error: errMsg };
+    }
+    catch (err) {
+        return { ok: false, status: 0, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+export async function pingBackend() {
+    const start = Date.now();
+    try {
+        const res = await request(`${baseUrl()}/`, { method: "GET" });
+        await res.body.dump();
+        return { reachable: res.statusCode < 500, latencyMs: Date.now() - start };
+    }
+    catch (err) {
+        logger.warn({ err, url: baseUrl() }, "backend unreachable");
+        return { reachable: false, latencyMs: null };
+    }
+}

package/dist/lib/event-filter.js

@@ -0,0 +1,33 @@
+export function parseFieldArg(input) {
+    const eq = input.indexOf("=");
+    if (eq < 1)
+        throw new Error(`invalid --field "${input}": expected name=value`);
+    return { name: input.slice(0, eq), value: input.slice(eq + 1) };
+}
+export function parseRegexArg(input) {
+    const eq = input.indexOf("=");
+    if (eq < 1)
+        throw new Error(`invalid --regex "${input}": expected name=pattern`);
+    const name = input.slice(0, eq);
+    const raw = input.slice(eq + 1);
+    // Support /pattern/flags as well as bare pattern.
+    const m = /^\/(.+)\/([gimsuy]*)$/.exec(raw);
+    const regex = m ? new RegExp(m[1], m[2]) : new RegExp(raw);
+    return { name, regex };
+}
+export function matches(obj, spec) {
+    if (!obj || typeof obj !== "object")
+        return false;
+    const record = obj;
+    if (record.type !== spec.eventType)
+        return false;
+    for (const f of spec.fields) {
+        if (String(record[f.name] ?? "") !== f.value)
+            return false;
+    }
+    for (const r of spec.regexes) {
+        if (!r.regex.test(String(record[r.name] ?? "")))
+            return false;
+    }
+    return true;
+}

package/dist/lib/log.js

@@ -0,0 +1,34 @@
+import { appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import pino from "pino";
+export function appendJsonl(file, obj) {
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, JSON.stringify(obj) + "\n");
+}
+export const logger = pino({
+    level: process.env.DIAL_LOG_LEVEL ?? "warn",
+    base: { name: "dial-cli" },
+}, pino.transport({
+    target: "pino-pretty",
+    options: {
+        destination: 2, // stderr
+        colorize: true,
+        translateTime: "SYS:HH:MM:ss.l",
+        ignore: "pid,hostname,name",
+    },
+}));
+export function rotateIfLarge(file, maxBytes) {
+    let size = 0;
+    try {
+        size = statSync(file).size;
+    }
+    catch {
+        return;
+    }
+    if (size <= maxBytes)
+        return;
+    const raw = readFileSync(file, "utf8");
+    const lines = raw.split("\n").filter(Boolean);
+    const keep = lines.slice(Math.floor(lines.length / 2));
+    writeFileSync(file, keep.join("\n") + "\n");
+}

package/dist/lib/paths.js

@@ -0,0 +1,24 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function paths() {
+    const home = process.env.HOME ?? homedir();
+    const configHome = process.env.XDG_CONFIG_HOME ?? join(home, ".config");
+    const dataHome = process.env.XDG_DATA_HOME ?? join(home, ".local", "share");
+    const stateHome = process.env.XDG_STATE_HOME ?? join(home, ".local", "state");
+    const configDir = join(configHome, "dial");
+    const dataDir = join(dataHome, "dial");
+    const stateDir = join(stateHome, "dial");
+    return {
+        configDir,
+        dataDir,
+        stateDir,
+        configFile: join(configDir, "config.json"),
+        authFile: join(dataDir, "auth.json"),
+        pendingSignupFile: join(dataDir, "pending-signup.json"),
+        listenLog: join(stateDir, "listen.log"),
+        listenOutLog: join(stateDir, "listen.out.log"),
+        listenErrLog: join(stateDir, "listen.err.log"),
+        listenPid: join(stateDir, "listen.pid"),
+        cliLog: join(stateDir, "cli.log"),
+    };
+}

package/dist/lib/pubnub.js

@@ -0,0 +1,103 @@
+import PubNub from "pubnub";
+import { apiPost } from "./api.js";
+import { appendJsonl, rotateIfLarge } from "./log.js";
+import { paths } from "./paths.js";
+const MAX_LOG_BYTES = 10 * 1024 * 1024;
+const SUBSCRIBE_PATH = "/api/v1/listen/subscribe";
+const REFRESH_FAILURES_BEFORE_EXIT = 3;
+export async function fetchSubscribeCreds(apiKey) {
+    const res = await apiPost(SUBSCRIBE_PATH, {}, apiKey);
+    if (!res.ok)
+        throw new Error(`subscribe failed: ${res.error} (status ${res.status})`);
+    return res.data;
+}
+export function startWorker(apiKey, accountId) {
+    const logFile = paths().listenLog;
+    let pn = null;
+    let refreshTimer = null;
+    let stopped = false;
+    let consecutiveFailures = 0;
+    let resolveStopped;
+    const whenStopped = new Promise((r) => { resolveStopped = r; });
+    function logLine(obj) {
+        rotateIfLarge(logFile, MAX_LOG_BYTES);
+        appendJsonl(logFile, obj);
+    }
+    async function refresh(creds) {
+        try {
+            const next = await fetchSubscribeCreds(apiKey);
+            pn?.setToken(next.token);
+            consecutiveFailures = 0;
+            logLine({ ts: new Date().toISOString(), lifecycle: "token_refresh", ok: true });
+            scheduleRefresh(next);
+        }
+        catch (err) {
+            consecutiveFailures += 1;
+            logLine({ ts: new Date().toISOString(), lifecycle: "token_refresh", ok: false, error: err instanceof Error ? err.message : String(err), consecutive_failures: consecutiveFailures });
+            if (consecutiveFailures >= REFRESH_FAILURES_BEFORE_EXIT) {
+                logLine({ ts: new Date().toISOString(), lifecycle: "shutdown", reason: "refresh_failures_exceeded" });
+                await stop();
+                process.exitCode = 1;
+                return;
+            }
+            const backoff = Math.min(60, Math.pow(2, consecutiveFailures)) * 1000;
+            refreshTimer = setTimeout(() => refresh(creds), backoff);
+        }
+    }
+    function scheduleRefresh(creds) {
+        const ms = Math.max(60, Math.floor(creds.ttl_seconds / 2)) * 1000;
+        refreshTimer = setTimeout(() => refresh(creds), ms);
+    }
+    async function stop() {
+        if (stopped)
+            return whenStopped;
+        stopped = true;
+        if (refreshTimer)
+            clearTimeout(refreshTimer);
+        try {
+            pn?.unsubscribeAll();
+        }
+        catch (err) {
+            logLine({ ts: new Date().toISOString(), lifecycle: "shutdown_error", phase: "unsubscribeAll", error: err instanceof Error ? err.message : String(err), stack: err instanceof Error ? err.stack : null });
+        }
+        try {
+            pn?.destroy?.();
+        }
+        catch (err) {
+            logLine({ ts: new Date().toISOString(), lifecycle: "shutdown_error", phase: "destroy", error: err instanceof Error ? err.message : String(err), stack: err instanceof Error ? err.stack : null });
+        }
+        resolveStopped();
+        return whenStopped;
+    }
+    (async () => {
+        let creds;
+        try {
+            creds = await fetchSubscribeCreds(apiKey);
+        }
+        catch (err) {
+            logLine({ ts: new Date().toISOString(), lifecycle: "startup", ok: false, error: err instanceof Error ? err.message : String(err) });
+            process.exitCode = 1;
+            resolveStopped();
+            return;
+        }
+        pn = new PubNub({
+            subscribeKey: creds.subscribe_key,
+            userId: `dial-cli-${accountId}`,
+            ssl: true,
+            authKey: creds.token,
+        });
+        pn.setToken(creds.token);
+        pn.addListener({
+            message: (ev) => {
+                logLine({ ts: new Date().toISOString(), ...ev.message });
+            },
+            status: (s) => {
+                logLine({ ts: new Date().toISOString(), lifecycle: "status", category: s.category, operation: s.operation ?? null });
+            },
+        });
+        pn.subscribe({ channels: [creds.channel] });
+        logLine({ ts: new Date().toISOString(), lifecycle: "subscribed", channel: creds.channel });
+        scheduleRefresh(creds);
+    })();
+    return { stop, whenStopped };
+}

package/dist/lib/state.js

@@ -0,0 +1,95 @@
+import { mkdirSync, readFileSync, writeFileSync, unlinkSync, statSync, chmodSync } from "node:fs";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { paths } from "./paths.js";
+import { logger } from "./log.js";
+export const AuthSchema = z.object({
+    api_key: z.string(),
+    account_id: z.string(),
+    email: z.string(),
+    phone_number: z.string().nullable(),
+    phone_number_id: z.string().nullable(),
+});
+export const PendingSignupSchema = z.object({
+    verification_id: z.string(),
+    email: z.string(),
+    created_at: z.string(),
+});
+const CHMOD_UNSUPPORTED_CODES = new Set(["ENOTSUP", "EOPNOTSUPP", "EPERM"]);
+function ensureDir(path) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(dirname(path), 0o700);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code && CHMOD_UNSUPPORTED_CODES.has(code)) {
+            logger.warn({ err, code, path: dirname(path) }, "chmod 0700 unsupported, continuing");
+            return;
+        }
+        throw err;
+    }
+}
+function readSecure(path, schema) {
+    let stat;
+    try {
+        stat = statSync(path);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    const mode = stat.mode & 0o777;
+    if (mode & 0o077) {
+        throw new Error(`${path} has insecure permissions (mode ${mode.toString(8)})`);
+    }
+    const raw = readFileSync(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        logger.warn({ err, path }, "failed to parse state file");
+        return null;
+    }
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+        logger.warn({ path, issues: result.error.issues }, "state file did not match expected schema");
+        return null;
+    }
+    return result.data;
+}
+function writeSecure(path, data) {
+    ensureDir(path);
+    writeFileSync(path, JSON.stringify(data, null, 2), { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+export function readAuth() {
+    return readSecure(paths().authFile, AuthSchema);
+}
+export function writeAuth(auth) {
+    writeSecure(paths().authFile, auth);
+}
+function unlinkIfExists(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+}
+export function clearAuth() {
+    unlinkIfExists(paths().authFile);
+}
+export function readPendingSignup() {
+    return readSecure(paths().pendingSignupFile, PendingSignupSchema);
+}
+export function writePendingSignup(p) {
+    writeSecure(paths().pendingSignupFile, p);
+}
+export function clearPendingSignup() {
+    unlinkIfExists(paths().pendingSignupFile);
+}

package/dist/lib/supervisor/index.js

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { userInfo } from "node:os";
+import { paths } from "../paths.js";
+import { logger } from "../log.js";
+import { LAUNCHD_LABEL, launchctlBootoutSilent, launchctlLoad, launchctlStatus, launchctlUnload, launchdPlistPath, renderLaunchdPlist, writeLaunchdPlist } from "./launchd.js";
+import { lingerEnabled, renderSystemdUnit, systemctlDisable, systemctlEnableAndStart, systemctlStatus, systemdUnitPath, writeSystemdUnit } from "./systemd.js";
+export function currentPlatform() {
+    if (process.platform === "darwin")
+        return "darwin";
+    if (process.platform === "linux")
+        return "linux";
+    throw new Error(`Unsupported platform: ${process.platform} (macOS and Linux only)`);
+}
+export function installSupervised(programPath) {
+    const platform = currentPlatform();
+    const p = paths();
+    if (platform === "darwin") {
+        const xml = renderLaunchdPlist({
+            label: LAUNCHD_LABEL,
+            programPath,
+            stdoutPath: p.listenOutLog,
+            stderrPath: p.listenErrLog,
+        });
+        const { path, changed } = writeLaunchdPlist(xml);
+        if (changed) {
+            // Boot the prior service out (if any) without deleting the freshly written plist.
+            launchctlBootoutSilent();
+        }
+        launchctlLoad(path);
+        return { changed, warnings: [], unitPath: path };
+    }
+    else {
+        const unit = renderSystemdUnit({ programPath });
+        const { path, changed } = writeSystemdUnit(unit);
+        systemctlEnableAndStart();
+        const warnings = [];
+        if (!lingerEnabled(userInfo().username)) {
+            warnings.push("Run `loginctl enable-linger $USER` so the listen service survives logout.");
+        }
+        return { changed, warnings, unitPath: path };
+    }
+}
+export function uninstallSupervised() {
+    const platform = currentPlatform();
+    if (platform === "darwin") {
+        launchctlUnload(launchdPlistPath());
+    }
+    else {
+        systemctlDisable();
+    }
+}
+export function supervisorStatus() {
+    const platform = currentPlatform();
+    if (platform === "darwin") {
+        const path = launchdPlistPath();
+        const installed = existsSync(path);
+        const s = launchctlStatus();
+        return { installed, running: s.running, pid: s.pid, unitPath: path };
+    }
+    else {
+        const path = systemdUnitPath();
+        const installed = existsSync(path);
+        const s = systemctlStatus();
+        return { installed, running: s.running, pid: s.pid, unitPath: path };
+    }
+}
+export function lastEventAtFromLog(file) {
+    let buf;
+    try {
+        if (!statSync(file).isFile())
+            return null;
+        buf = readFileSync(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    const lines = buf.trim().split("\n").filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        let obj;
+        try {
+            obj = JSON.parse(lines[i]);
+        }
+        catch (err) {
+            logger.warn({ err, file, lineIndex: i }, "skipping malformed JSONL line in listen log");
+            continue;
+        }
+        const t = obj.occurred_at ?? obj.ts;
+        if (t)
+            return t;
+    }
+    return null;
+}

package/dist/lib/supervisor/launchd.js

@@ -0,0 +1,145 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { logger } from "../log.js";
+function isLaunchctlNotFound(err) {
+    const stderr = err.stderr;
+    const text = stderr ? stderr.toString() : "";
+    return /No such process|could not find specified service|not loaded/i.test(text);
+}
+function isEnoent(err) {
+    return err.code === "ENOENT";
+}
+// Coerce Buffer fields on Error objects to strings so pino doesn't dump raw byte arrays.
+function redactBuffers(err) {
+    if (!err || typeof err !== "object")
+        return err;
+    const e = err;
+    const redacted = { ...e };
+    for (const k of ["stderr", "stdout", "output"]) {
+        const v = e[k];
+        if (Buffer.isBuffer(v))
+            redacted[k] = v.toString().trim();
+        else if (Array.isArray(v))
+            redacted[k] = v.map((x) => (Buffer.isBuffer(x) ? x.toString().trim() : x));
+    }
+    return redacted;
+}
+export const LAUNCHD_LABEL = "ai.getdial.listen";
+export function launchdPlistPath() {
+    return join(homedir(), "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+}
+export function renderLaunchdPlist(params) {
+    // The dial script uses `#!/usr/bin/env node`. launchd starts with a minimal PATH,
+    // so we must prepend the directory of the currently running node (e.g. nvm's bin dir)
+    // so the shebang can resolve. Falls back to /usr/local/bin which is where Homebrew puts node.
+    const nodeDir = dirname(process.execPath);
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${params.label}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${params.programPath}</string>
+    <string>listen</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${params.stdoutPath}</string>
+  <key>StandardErrorPath</key>
+  <string>${params.stderrPath}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${nodeDir}:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+export function writeLaunchdPlist(contents) {
+    const path = launchdPlistPath();
+    mkdirSync(join(homedir(), "Library", "LaunchAgents"), { recursive: true });
+    const prior = existsSync(path) ? readFileSync(path, "utf8") : null;
+    if (prior === contents)
+        return { path, changed: false };
+    writeFileSync(path, contents);
+    return { path, changed: true };
+}
+export function launchctlBootoutSilent() {
+    const uid = process.getuid?.() ?? 0;
+    try {
+        execFileSync("launchctl", ["bootout", `gui/${uid}/${LAUNCHD_LABEL}`], { stdio: "pipe" });
+    }
+    catch {
+        // Best-effort cleanup before install: launchctl bootout exits non-zero with
+        // ambiguous "Boot-out failed: 5: Input/output error" when nothing is loaded.
+        // We can't reliably distinguish "not loaded" from real errors, and any real
+        // problem will surface on the next bootstrap. Ignore.
+    }
+}
+export function launchctlLoad(plistPath) {
+    const uid = process.getuid?.() ?? 0;
+    try {
+        execFileSync("launchctl", ["bootstrap", `gui/${uid}`, plistPath], { stdio: "pipe" });
+        return;
+    }
+    catch (bootstrapErr) {
+        logger.warn({ err: redactBuffers(bootstrapErr) }, "launchctl bootstrap failed, falling back to legacy load");
+    }
+    // launchctl load -w prints "Load failed: ..." to stderr but exits 0,
+    // so we must inspect stderr ourselves to detect the failure.
+    const r = spawnSync("launchctl", ["load", "-w", plistPath], { encoding: "utf8" });
+    const stderr = (r.stderr ?? "").trim();
+    if (r.error)
+        throw r.error;
+    if (r.status !== 0 || /Load failed|error/i.test(stderr)) {
+        throw new Error(`launchctl load -w ${plistPath} failed: ${stderr || `exit ${r.status}`}`);
+    }
+}
+export function launchctlUnload(plistPath) {
+    const uid = process.getuid?.() ?? 0;
+    try {
+        execFileSync("launchctl", ["bootout", `gui/${uid}/${LAUNCHD_LABEL}`], { stdio: "pipe" });
+    }
+    catch (err) {
+        if (!isLaunchctlNotFound(err)) {
+            // bootout missing on older macOS — try legacy unload before giving up
+            try {
+                execFileSync("launchctl", ["unload", plistPath], { stdio: "pipe" });
+            }
+            catch (unloadErr) {
+                if (!isLaunchctlNotFound(unloadErr))
+                    throw unloadErr;
+            }
+        }
+    }
+    try {
+        unlinkSync(plistPath);
+    }
+    catch (err) {
+        if (!isEnoent(err))
+            throw err;
+    }
+}
+export function launchctlStatus() {
+    try {
+        const out = execFileSync("launchctl", ["list"], { stdio: ["ignore", "pipe", "ignore"] }).toString();
+        const line = out.split("\n").find((l) => l.endsWith(`\t${LAUNCHD_LABEL}`) || l.endsWith(` ${LAUNCHD_LABEL}`));
+        if (!line)
+            return { running: false, pid: null };
+        const cols = line.split(/\s+/);
+        const pid = parseInt(cols[0], 10);
+        return { running: Number.isFinite(pid) && pid > 0, pid: Number.isFinite(pid) && pid > 0 ? pid : null };
+    }
+    catch (err) {
+        logger.warn({ err: redactBuffers(err) }, "launchctl list failed");
+        return { running: false, pid: null };
+    }
+}

package/dist/lib/supervisor/systemd.js

@@ -0,0 +1,90 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { logger } from "../log.js";
+function isSystemctlNotLoaded(err) {
+    const stderr = err.stderr;
+    const text = stderr ? stderr.toString() : "";
+    return /not loaded|does not exist|Unit .* not found/i.test(text);
+}
+function isEnoent(err) {
+    return err.code === "ENOENT";
+}
+export const SYSTEMD_UNIT_NAME = "dial-listen.service";
+export function systemdUnitPath() {
+    return join(homedir(), ".config", "systemd", "user", SYSTEMD_UNIT_NAME);
+}
+export function renderSystemdUnit(params) {
+    // systemd user units start with a minimal PATH; include node's bin dir so
+    // dial's `#!/usr/bin/env node` shebang resolves.
+    const nodeDir = dirname(process.execPath);
+    return `[Unit]
+Description=Dial listen service
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+Environment="PATH=${nodeDir}:/usr/local/bin:/usr/bin:/bin"
+ExecStart=${params.programPath} listen
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+`;
+}
+export function writeSystemdUnit(contents) {
+    const path = systemdUnitPath();
+    mkdirSync(join(homedir(), ".config", "systemd", "user"), { recursive: true });
+    const prior = existsSync(path) ? readFileSync(path, "utf8") : null;
+    if (prior === contents)
+        return { path, changed: false };
+    writeFileSync(path, contents);
+    return { path, changed: true };
+}
+export function systemctlEnableAndStart() {
+    execFileSync("systemctl", ["--user", "daemon-reload"], { stdio: "pipe" });
+    execFileSync("systemctl", ["--user", "enable", "--now", SYSTEMD_UNIT_NAME], { stdio: "pipe" });
+}
+export function systemctlDisable() {
+    try {
+        execFileSync("systemctl", ["--user", "disable", "--now", SYSTEMD_UNIT_NAME], { stdio: "pipe" });
+    }
+    catch (err) {
+        if (!isSystemctlNotLoaded(err))
+            throw err;
+    }
+    try {
+        unlinkSync(systemdUnitPath());
+    }
+    catch (err) {
+        if (!isEnoent(err))
+            throw err;
+    }
+    execFileSync("systemctl", ["--user", "daemon-reload"], { stdio: "pipe" });
+}
+export function systemctlStatus() {
+    try {
+        const out = execFileSync("systemctl", ["--user", "show", SYSTEMD_UNIT_NAME, "--property=ActiveState,MainPID"], { stdio: ["ignore", "pipe", "ignore"] }).toString();
+        const active = /ActiveState=active/.test(out);
+        const m = out.match(/MainPID=(\d+)/);
+        const pid = m ? parseInt(m[1], 10) : 0;
+        return { running: active, pid: active && pid > 0 ? pid : null };
+    }
+    catch (err) {
+        logger.warn({ err }, "systemctl show failed");
+        return { running: false, pid: null };
+    }
+}
+export function lingerEnabled(user) {
+    try {
+        const out = execFileSync("loginctl", ["show-user", user, "--property=Linger"], { stdio: ["ignore", "pipe", "ignore"] }).toString();
+        return /Linger=yes/.test(out);
+    }
+    catch (err) {
+        logger.warn({ err, user }, "loginctl show-user failed; assuming linger disabled");
+        return false;
+    }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@getdial/cli",
+  "version": "0.1.0",
+  "description": "Dial CLI — install, sign up, and run the local listen service.",
+  "license": "MIT",
+  "bin": {
+    "dial": "./dist/cli.js"
+  },
+  "preferGlobal": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "node --import tsx --test",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "pubnub": "^11.0.1",
+    "undici": "^8.3.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.22.3",
+    "typescript": "^5.6.0"
+  }
+}