convene-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Hawkinson
+
+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/dist/api.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConveneApi = void 0;
+/** Thin REST client for the Convene API. Every call is bounded by a timeout. */
+const brand_1 = require("./brand");
+class ConveneApi {
+    baseUrl;
+    apiKey;
+    session;
+    tool;
+    constructor(baseUrl, apiKey, session = null, tool = null) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+        this.session = session;
+        this.tool = tool;
+    }
+    async request(method, apiPath, opts = {}) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? 10_000);
+        try {
+            const headers = { 'content-type': 'application/json' };
+            if (this.apiKey)
+                headers['authorization'] = `Bearer ${this.apiKey}`;
+            if (this.session)
+                headers['x-convene-session'] = this.session;
+            if (this.tool)
+                headers['x-convene-tool'] = this.tool;
+            if (opts.idempotencyKey)
+                headers['idempotency-key'] = opts.idempotencyKey;
+            const res = await fetch(`${this.baseUrl}${brand_1.BRAND.apiBase}${apiPath}`, {
+                method,
+                headers,
+                body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+                signal: ctrl.signal,
+            });
+            const text = await res.text();
+            let json = null;
+            try {
+                json = text ? JSON.parse(text) : null;
+            }
+            catch {
+                /* non-json */
+            }
+            return { status: res.status, ok: res.ok, json, error: res.ok ? undefined : json?.error || text };
+        }
+        catch (err) {
+            return { status: 0, ok: false, json: null, error: err?.message || 'network error' };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    validate(timeoutMs) {
+        return this.request('GET', '/projects', { timeoutMs });
+    }
+    me(timeoutMs) {
+        return this.request('GET', '/me', { timeoutMs });
+    }
+    listProjects(timeoutMs) {
+        return this.request('GET', '/projects', { timeoutMs });
+    }
+    feed(slug, q = {}, timeoutMs) {
+        const params = new URLSearchParams();
+        if (q.lookbackMin)
+            params.set('lookback_min', String(q.lookbackMin));
+        if (q.max)
+            params.set('limit', String(q.max));
+        return this.request('GET', `/projects/${encodeURIComponent(slug)}/feed?${params}`, { timeoutMs });
+    }
+    inbox(slug, timeoutMs) {
+        const p = slug ? `/projects/${encodeURIComponent(slug)}/inbox` : '/inbox';
+        return this.request('GET', p, { timeoutMs });
+    }
+    resolveRepo(repo, timeoutMs) {
+        return this.request('GET', `/projects/resolve?repo=${encodeURIComponent(repo)}`, { timeoutMs });
+    }
+    post(slug, body, idempotencyKey, timeoutMs) {
+        return this.request('POST', `/projects/${encodeURIComponent(slug)}/messages`, {
+            body,
+            idempotencyKey,
+            timeoutMs,
+        });
+    }
+    transition(id, action, body, timeoutMs) {
+        return this.request('POST', `/messages/${encodeURIComponent(id)}/${action}`, { body, timeoutMs });
+    }
+    createProject(body, timeoutMs) {
+        return this.request('POST', '/projects', { body, timeoutMs });
+    }
+    /** Redeem a join token (no bearer auth required). */
+    join(slug, body, timeoutMs) {
+        return this.request('POST', `/projects/${encodeURIComponent(slug)}/join`, { body, timeoutMs });
+    }
+    /** Self-serve: provision a brand-new global identity + key (no bearer auth). */
+    provision(body, timeoutMs) {
+        return this.request('POST', '/provision', { body, timeoutMs });
+    }
+    /** Owner: mint a self-serve join token. */
+    createJoinToken(slug, body = {}, timeoutMs) {
+        return this.request('POST', `/projects/${encodeURIComponent(slug)}/join-tokens`, { body, timeoutMs });
+    }
+    /** Owner: revoke a join token by its prefix (the first 14 chars of the raw token). */
+    revokeJoinToken(slug, prefix, timeoutMs) {
+        return this.request('DELETE', `/projects/${encodeURIComponent(slug)}/join-tokens/${encodeURIComponent(prefix)}`, { timeoutMs });
+    }
+    getProject(slug, timeoutMs) {
+        return this.request('GET', `/projects/${encodeURIComponent(slug)}`, { timeoutMs });
+    }
+}
+exports.ConveneApi = ConveneApi;

package/dist/brand.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Convene brand constants — CLI mirror of server/src/brand.ts.
+ *
+ * Single source of truth for product naming on the client side. Keep in sync
+ * with the server copy. Nothing in the CLI should hardcode the product name,
+ * key prefix, env prefix, config dir, or channel tag — reference these.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BRAND = void 0;
+exports.envName = envName;
+exports.BRAND = {
+    product: 'Convene',
+    slug: 'convene',
+    bin: 'convene',
+    domain: 'dev.convene.live',
+    baseUrl: 'https://dev.convene.live',
+    envPrefix: 'CONVENE_',
+    keyPrefix: 'cvk_',
+    configDir: '.convene',
+    channelTag: 'convene-channel',
+    apiBase: '/api/v1',
+    /** Stable marker used to find/replace the hook entry in settings.json. */
+    hookMarker: 'convene:hook',
+    /** CLAUDE.md / AGENTS.md managed-block markers. */
+    blockBegin: '<!-- convene:begin v1 -->',
+    blockEnd: '<!-- convene:end -->',
+};
+function envName(suffix) {
+    return `${exports.BRAND.envPrefix}${suffix}`;
+}

package/dist/cache.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCache = readCache;
+exports.writeCache = writeCache;
+exports.ageSeconds = ageSeconds;
+/**
+ * Tiny per-project file cache so rapid successive prompts don't each hit the
+ * network (P0-LATENCY). Short TTL; on a fetch failure the stale cache still
+ * powers a DEGRADED render (P0-FAILSAFE).
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const config_1 = require("./config");
+function cacheFile(slug) {
+    return node_path_1.default.join(config_1.CACHE_DIR, `${slug.replace(/[^a-zA-Z0-9_-]/g, '_')}.json`);
+}
+function readCache(slug) {
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(cacheFile(slug), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(slug, data) {
+    try {
+        node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
+        node_fs_1.default.writeFileSync(cacheFile(slug), JSON.stringify({ fetchedAt: Date.now(), data }), { mode: 0o600 });
+    }
+    catch {
+        /* cache is best-effort */
+    }
+}
+function ageSeconds(entry) {
+    return Math.max(0, Math.round((Date.now() - entry.fetchedAt) / 1000));
+}

package/dist/commands/auth.js

@@ -0,0 +1,151 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.login = login;
+exports.whoami = whoami;
+exports.doctor = doctor;
+/** login / whoami / doctor. */
+const node_fs_1 = __importDefault(require("node:fs"));
+const brand_1 = require("../brand");
+const api_1 = require("../api");
+const config_1 = require("../config");
+const git_1 = require("../git");
+const hook_1 = require("../hook");
+const ctx_1 = require("../ctx");
+function readStdin() {
+    try {
+        return node_fs_1.default.readFileSync(0, 'utf8').trim();
+    }
+    catch {
+        return '';
+    }
+}
+async function login(opts) {
+    const existing = (0, config_1.loadFileConfig)();
+    const baseUrl = (opts.baseUrl || existing.baseUrl || brand_1.BRAND.baseUrl).replace(/\/$/, '');
+    let apiKey = opts.apiKey;
+    if (apiKey === '-')
+        apiKey = readStdin(); // never via shell history
+    apiKey = apiKey || existing.apiKey;
+    if (!apiKey)
+        (0, ctx_1.die)('no API key — pass `--api-key -` (reads from stdin) or `--api-key <key>`');
+    const api = new api_1.ConveneApi(baseUrl, apiKey);
+    const me = await api.me(8000);
+    if (!me.ok || !me.json)
+        (0, ctx_1.die)(`key validation failed (${me.status}): ${me.error ?? 'unreachable'}`);
+    const member = me.json.member;
+    if (opts.member && opts.member !== member) {
+        process.stderr.write(`convene: note — key belongs to "${member}", ignoring --member ${opts.member}\n`);
+    }
+    (0, config_1.saveFileConfig)({ apiKey: apiKey, baseUrl, member });
+    const projects = await api.listProjects(8000);
+    const count = Array.isArray(projects.json?.projects) ? projects.json.projects.length : 0;
+    process.stdout.write(`Logged in as ${member} at ${baseUrl} (${count} project${count === 1 ? '' : 's'}).\n`);
+    process.stdout.write(`Config saved to ${config_1.CONFIG_FILE} (0600).\n`);
+}
+async function whoami() {
+    const cfg = (0, config_1.resolveConfig)();
+    if (!cfg.apiKey) {
+        process.stdout.write('Not logged in. Run `convene login`.\n');
+        return;
+    }
+    const top = (0, git_1.gitToplevel)();
+    const onBus = !!(0, config_1.loadProjectConfig)(top)?.slug;
+    const session = cfg.member && top ? (0, git_1.sessionId)(cfg.member, top) : cfg.member ? `${cfg.member}/cli` : '(unknown)';
+    let serverMember = cfg.member;
+    const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool);
+    const me = await api.me(5000);
+    if (me.ok && me.json)
+        serverMember = me.json.member;
+    process.stdout.write(`member:   ${serverMember ?? '(unknown)'}\n`);
+    process.stdout.write(`base:     ${cfg.baseUrl}\n`);
+    process.stdout.write(`tool:     ${cfg.tool}\n`);
+    process.stdout.write(`session:  ${session}\n`);
+    process.stdout.write(`this repo on the bus: ${onBus ? `yes (${(0, config_1.loadProjectConfig)(top).slug})` : 'no'}\n`);
+    process.stdout.write(`server:   ${me.ok ? 'reachable' : 'UNREACHABLE'}\n`);
+    // The API key is never printed.
+}
+async function doctor(opts) {
+    const checks = [];
+    const cfg = (0, config_1.resolveConfig)();
+    // 1. binary
+    checks.push({ name: 'binary', ok: true, detail: `convene running from ${process.argv[1] || process.execPath}` });
+    // 2. config + perms
+    const haveConfig = node_fs_1.default.existsSync(config_1.CONFIG_FILE);
+    let permsOk = true;
+    if (haveConfig && (0, config_1.isWorldReadable)(config_1.CONFIG_FILE)) {
+        permsOk = false;
+        if (opts.fix && process.platform !== 'win32') {
+            try {
+                node_fs_1.default.chmodSync(config_1.CONFIG_FILE, 0o600);
+                permsOk = true;
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    checks.push({
+        name: 'config',
+        ok: haveConfig && permsOk && !!cfg.apiKey,
+        detail: !haveConfig
+            ? 'no config — run `convene login`'
+            : !cfg.apiKey
+                ? 'no API key in config/env'
+                : permsOk
+                    ? `${config_1.CONFIG_FILE} (0600)`
+                    : `${config_1.CONFIG_FILE} is world/group-readable (run with --fix or chmod 600)`,
+    });
+    // 3. key valid
+    if (cfg.apiKey) {
+        const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey);
+        const me = await api.me(6000);
+        checks.push({
+            name: 'auth',
+            ok: me.ok,
+            detail: me.ok ? `valid key for ${me.json?.member} @ ${cfg.baseUrl}` : `key invalid/unreachable (${me.status})`,
+        });
+    }
+    else {
+        checks.push({ name: 'auth', ok: false, detail: 'skipped (no key)' });
+    }
+    // 4. git toplevel
+    const top = (0, git_1.gitToplevel)();
+    checks.push({ name: 'git', ok: !!top, detail: top ? `worktree: ${(0, git_1.worktreeBasename)(top)}` : 'not in a git repo' });
+    // 5. project on bus
+    const proj = (0, config_1.loadProjectConfig)(top);
+    checks.push({
+        name: 'project',
+        ok: !!proj?.slug,
+        detail: proj?.slug ? `bound to project "${proj.slug}"` : 'this repo is not on the bus (run `convene init`)',
+    });
+    // 6. hook registered
+    const raw = (0, hook_1.readSettingsRaw)();
+    const settings = (0, hook_1.parseSettings)(raw);
+    let hookOk = settings != null && (0, hook_1.hookIsRegistered)(settings);
+    if (!hookOk && opts.fix && settings != null) {
+        try {
+            node_fs_1.default.writeFileSync(hook_1.SETTINGS_PATH, (0, hook_1.serializeSettings)((0, hook_1.withHook)(settings)));
+            hookOk = true;
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    checks.push({
+        name: 'hook',
+        ok: hookOk,
+        detail: settings == null
+            ? `${hook_1.SETTINGS_PATH} is missing/unparseable`
+            : hookOk
+                ? 'UserPromptSubmit `convene fetch` registered'
+                : 'hook NOT registered (run `convene init` or `convene doctor --fix`)',
+    });
+    for (const c of checks) {
+        process.stdout.write(`${c.ok ? '✓' : '✗'} ${c.name.padEnd(8)} ${c.detail}\n`);
+    }
+    if (!checks.every((c) => c.ok))
+        process.exitCode = 1;
+}

package/dist/commands/fetch.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFetch = runFetch;
+/**
+ * `convene fetch` — the UserPromptSubmit hook.
+ *
+ * GUARANTEES (P0-FAILSAFE + P0-LATENCY):
+ *   - NEVER blocks or fails a prompt: any error/timeout/missing-config → exit 0.
+ *     A hard watchdog force-exits at 6s even if something hangs.
+ *   - For a repo that is ON the bus (.convene/project.json present) it ALWAYS
+ *     injects a one-line health/freshness status (ok / DEGRADED / note).
+ *   - For a repo NOT on the bus (or not a git repo) it is a silent no-op.
+ *   - A short cache TTL means rapid successive prompts don't each hit the network;
+ *     a 4s fetch timeout bounds the slow path; a failed fetch falls back to the
+ *     stale cache and renders DEGRADED (loud-but-non-blocking).
+ */
+const git_1 = require("../git");
+const config_1 = require("../config");
+const cache_1 = require("../cache");
+const api_1 = require("../api");
+const render_1 = require("../render");
+const CACHE_TTL_SEC = 3;
+const FETCH_TIMEOUT_MS = 4000;
+const WATCHDOG_MS = 6000;
+function emit(block) {
+    process.stdout.write(block + '\n');
+}
+function toRenderMessages(arr) {
+    return Array.isArray(arr) ? arr : [];
+}
+async function runFetch(opts = {}) {
+    // Absolute watchdog: under any circumstance, do not hold the prompt past 6s.
+    const watchdog = setTimeout(() => process.exit(0), WATCHDOG_MS);
+    try {
+        const top = (0, git_1.gitToplevel)();
+        if (!top)
+            return done(0); // not a git repo → silent no-op
+        const proj = (0, config_1.loadProjectConfig)(top);
+        if (!proj?.slug)
+            return done(0); // repo not on the bus → silent no-op
+        const slug = proj.slug;
+        const cfg = (0, config_1.resolveConfig)();
+        const lookback = opts.lookback ?? 60;
+        const max = opts.max ?? 20;
+        const member = cfg.member;
+        const session = member ? (0, git_1.sessionId)(member, top) : `unknown/${(0, git_1.worktreeBasename)(top)}`;
+        // On the bus but not authenticated — still inject a one-line status.
+        if (!cfg.apiKey || !member) {
+            emit((0, render_1.renderChannelBlock)({
+                slug,
+                member: member ?? 'unknown',
+                session,
+                lookbackMin: lookback,
+                openItems: [],
+                recent: [],
+                health: { state: 'note', line: 'convene: not configured — run `convene login` (coordination context unavailable)' },
+            }));
+            return done(0);
+        }
+        // Cache short-circuit for rapid successive prompts.
+        const cache = (0, cache_1.readCache)(slug);
+        if (cache && (0, cache_1.ageSeconds)(cache) < CACHE_TTL_SEC) {
+            renderData(cache.data, { slug, member, session, lookback, syncedAgoSec: (0, cache_1.ageSeconds)(cache), json: opts.json });
+            return done(0);
+        }
+        // Slow path: bounded network fetch.
+        const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool);
+        const res = await api.feed(slug, { lookbackMin: lookback, max }, FETCH_TIMEOUT_MS);
+        if (res.ok && res.json) {
+            (0, cache_1.writeCache)(slug, res.json);
+            renderData(res.json, { slug, member, session, lookback, syncedAgoSec: 0, json: opts.json });
+            return done(0);
+        }
+        // Fetch failed/timed out → DEGRADED from stale cache (or absent).
+        if (opts.json) {
+            emit(JSON.stringify({ degraded: true, error: res.error, cache: cache?.data ?? null }));
+            return done(0);
+        }
+        const staleTs = cache ? new Date(cache.fetchedAt).toISOString() : null;
+        const health = { state: 'degraded', staleTs };
+        emit((0, render_1.renderChannelBlock)({
+            slug,
+            member,
+            session,
+            lookbackMin: lookback,
+            openItems: toRenderMessages(cache?.data?.inbox ?? []),
+            recent: toRenderMessages(cache?.data?.messages ?? []),
+            health,
+        }));
+        return done(0);
+    }
+    catch {
+        // Failsafe: never let the hook break a prompt.
+        return done(0);
+    }
+    function done(code) {
+        clearTimeout(watchdog);
+        process.exit(code);
+    }
+    function renderData(data, ctx) {
+        if (ctx.json) {
+            emit(JSON.stringify(data));
+            return;
+        }
+        emit((0, render_1.renderChannelBlock)({
+            slug: ctx.slug,
+            member: ctx.member,
+            session: ctx.session,
+            lookbackMin: ctx.lookback,
+            openItems: toRenderMessages(data?.inbox ?? []),
+            recent: toRenderMessages(data?.messages ?? []),
+            health: { state: 'ok', syncedAgoSec: ctx.syncedAgoSec, openCount: Number(data?.open_for_you ?? (data?.inbox?.length ?? 0)) },
+        }));
+    }
+}

package/dist/commands/inbox.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inbox = inbox;
+/** `convene inbox` — open questions/proposals addressed to me. */
+const ctx_1 = require("../ctx");
+async function inbox(opts) {
+    const ctx = (0, ctx_1.getContext)({ project: opts.project });
+    const slug = opts.allProjects ? null : ctx.slug; // null => /inbox across all my projects
+    const res = await ctx.api.inbox(slug, 10_000);
+    if (!res.ok)
+        (0, ctx_1.die)(`inbox failed (${res.status}): ${res.error ?? 'unknown error'}`);
+    const items = res.json?.items ?? [];
+    if (opts.json) {
+        process.stdout.write(JSON.stringify(items, null, 2) + '\n');
+        return;
+    }
+    if (items.length === 0) {
+        process.stdout.write('Inbox empty — nothing open for you.\n');
+        return;
+    }
+    for (const m of items) {
+        const from = m.from_session || m.from_handle || 'unknown';
+        if (m.type === 'propose_prompt') {
+            process.stdout.write(`[${m.short_id}] PROPOSE-PROMPT from ${from}\n`);
+            if (m.body)
+                process.stdout.write(`    context: ${m.body}\n`);
+            process.stdout.write(`    prompt (UNTRUSTED — review before acting):\n`);
+            process.stdout.write(`      ${(m.prompt_text ?? '').replace(/\n/g, '\n      ')}\n`);
+            process.stdout.write(`    -> convene ack ${m.short_id}  (after surfacing to a human)\n`);
+        }
+        else {
+            process.stdout.write(`[${m.short_id}] QUESTION from ${from}: ${m.body ?? ''}\n`);
+            process.stdout.write(`    -> convene answer ${m.short_id} "<answer>"   |   convene resolve ${m.short_id}\n`);
+        }
+    }
+}