convene-cli 1.2.0 → 1.4.0

package/dist/commands/override.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.override = override;
+/**
+ * `convene override <id> --reason "<why>"` (Phase 3) — the attributed, short-lived
+ * bypass for a best-practice gate. Writes a LOCAL, expiry-based override token that
+ * `convene practice-guard <id>` honors → ALLOW, and best-effort posts an attributed
+ * [STATUS] to the bus so the bypass is auditable in real time.
+ *
+ * POSTURE:
+ *   - DIE-LOUD on a missing/empty --reason (an unattributed override is the whole
+ *     thing we are guarding against) and on a missing project.
+ *   - FAIL-OPEN on the BUS: the local token is the source of truth for the gate;
+ *     if the bus is unreachable we STILL write the token and WARN — an override must
+ *     never be blocked by a flaky network. The status post is attribution, not
+ *     authorization.
+ */
+const config_1 = require("../config");
+const git_1 = require("../git");
+const api_1 = require("../api");
+const cache_1 = require("../cache");
+const ctx_1 = require("../ctx");
+const NET_TIMEOUT_MS = 2500; // explicit short timeout — never the api.ts 10s default
+function fmtTtl(ms) {
+    const sec = Math.round(ms / 1000);
+    if (sec < 60)
+        return `${sec}s`;
+    const m = Math.round(sec / 60);
+    return m === 1 ? '1 minute' : `${m} minutes`;
+}
+async function override(id, opts = {}) {
+    if (!id || !id.trim())
+        (0, ctx_1.die)('override requires a practice <id> (e.g. `convene override protect-shared-files --reason "…"`)');
+    const reason = (opts.reason ?? '').trim();
+    if (!reason)
+        (0, ctx_1.die)('override requires --reason "<why>" — an unattributed override defeats the gate');
+    const top = (0, git_1.gitToplevel)();
+    const proj = (0, config_1.loadProjectConfig)(top);
+    const slug = opts.project || proj?.slug || null;
+    if (!slug)
+        (0, ctx_1.die)('no project — run inside a `convene init`-ed repo, or pass --project <slug>');
+    // 1) Write the LOCAL token first — this is what the gate honors. Source of truth.
+    const tok = (0, cache_1.writeOverrideToken)(slug, id, reason);
+    // 2) Best-effort attributed [STATUS] to the bus. FAIL-OPEN: a bus failure warns
+    //    but never blocks — the local token already stands.
+    const cfg = (0, config_1.resolveConfig)();
+    const member = cfg.member;
+    const session = member && top ? (0, git_1.sessionId)(member, top) : null;
+    let posted = false;
+    if (cfg.apiKey && session) {
+        try {
+            const instance = (0, cache_1.ensureSessionInstance)(slug);
+            const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool, instance);
+            const res = await api.post(slug, { type: 'status', body: `practice ${id} gate overridden — ${reason}` }, (0, ctx_1.uuid)(), NET_TIMEOUT_MS);
+            posted = !!res.ok;
+        }
+        catch {
+            posted = false;
+        }
+    }
+    process.stdout.write(`override active for ${id} (${fmtTtl(cache_1.OVERRIDE_TTL_MS)}) — the next edits gated by this practice will be allowed.\n`);
+    if (!posted) {
+        process.stderr.write('convene: WARNING bus unreachable — override applied locally but NOT announced to the channel.\n');
+    }
+}

package/dist/commands/practice-guard.js

@@ -0,0 +1,310 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.targetPathFromPayload = targetPathFromPayload;
+exports.isProtectedPath = isProtectedPath;
+exports.practiceGuard = practiceGuard;
+/**
+ * `convene practice-guard <id>` (Phase 3) — the LEVEL-AWARE best-practice gate.
+ * Wired as a PreToolUse `Write|Edit` hook by the catalog's settingsHook artifacts
+ * (e.g. protect-shared-files, worktree-per-session, pull-main-before-execution).
+ * This file is the verb; the WIRING is materialized by init/materialize.
+ *
+ * POSTURE = FAIL-OPEN-LOUD (P0-FAILSAFE), modeled EXACTLY on guard.ts/gate-push.ts:
+ *   - A top-level watchdog force-exits 0 at WATCHDOG_MS=4000.
+ *   - The hot path is PURELY LOCAL (manifest + git + cache) — there is NO network
+ *     call on the verdict path, so latency is bounded by local git, not a socket.
+ *   - Any error / timeout / unreadable state → exit 0 (ALLOW). NEVER die().
+ *   - exit 2 (BLOCK) ONLY on a CONFIRMED hard violation of a hook-HARD practice
+ *     (today: protect-shared-files matching a protected path). Every other
+ *     practice/level is a soft reminder on stderr (exit 0).
+ *
+ * TRUST DISCIPLINE: the verdict is computed from the adopted manifest + local
+ * git/cache state ONLY. We NEVER read or trust any message body / bus payload for
+ * a verdict — the only thing we read off the wire is nothing.
+ *
+ * The adopted LEVEL for <id> comes from loadManifest:
+ *   - not adopted, or advisory/ci/manual → exit 0 SILENTLY (the gate is inert at
+ *     these levels; CI/advisory/manual practices are not mechanically blocked).
+ *   - hook-soft → print the practice's reminder to stderr, exit 0 (ALLOW).
+ *   - hook-hard → block (exit 2) ONLY on a confirmed positive, else exit 0.
+ *
+ * OVERRIDE: a live `convene override <id> --reason …` token (short TTL, local,
+ * session-scoped) is honored → exit 0 with a one-line note.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const git_1 = require("../git");
+const config_1 = require("../config");
+const cache_1 = require("../cache");
+const catalog_1 = require("../catalog");
+const exit_1 = require("../exit");
+const WATCHDOG_MS = 4000;
+/** The Write/Edit target path out of a PreToolUse hook payload (file_path/path/notebook_path). */
+function targetPathFromPayload(raw) {
+    if (!raw)
+        return '';
+    try {
+        const j = JSON.parse(raw);
+        const ti = j?.tool_input ?? {};
+        const p = ti.file_path ?? ti.path ?? ti.notebook_path;
+        return typeof p === 'string' ? p : '';
+    }
+    catch {
+        return '';
+    }
+}
+/** Async, timeout-bounded stdin read — identical posture to guard.ts. */
+function readStdin(timeoutMs) {
+    if (process.stdin.isTTY)
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        let data = '';
+        let settled = false;
+        const finish = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            process.stdin.removeAllListeners();
+            resolve(v);
+        };
+        const timer = setTimeout(() => finish(null), timeoutMs);
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (c) => {
+            data += c;
+        });
+        process.stdin.on('end', () => finish(data));
+        process.stdin.on('error', () => finish(null));
+        process.stdin.resume();
+    });
+}
+/** Soft reminder / override note on stderr (PreToolUse surfaces stderr to the agent). */
+function note(reason) {
+    process.stderr.write(reason + '\n');
+}
+/** Hard deny reason on stderr (exit 2 surfaces this to the agent). */
+function blockReason(reason) {
+    process.stderr.write(reason + '\n');
+}
+/**
+ * A compact "why + source" suffix for a practice, drawn from the catalog. Hitting a
+ * gate is the highest-frequency moment an agent could LEARN the rationale, so every
+ * reminder/block cites the practice's `why` (the failure mode it prevents) and a
+ * `sourceUrls[0]` reference right there — turning enforcement into in-context
+ * teaching with zero new infra (the catalog is already loaded; no hot-path network).
+ * Empty when the practice or its `why` is unknown. Pure + local.
+ */
+function whySuffix(id) {
+    const p = catalog_1.CATALOG.practices.find((x) => x.id === id);
+    if (!p || !p.why)
+        return '';
+    const src = p.sourceUrls && p.sourceUrls.length > 0 ? `\n  source: ${p.sourceUrls[0]}` : '';
+    return `\n  why: ${p.why}${src}`;
+}
+/** The one-line reminder for a practice: its catalog `title` + why/source (lean). */
+function reminderFor(id) {
+    const p = catalog_1.CATALOG.practices.find((x) => x.id === id);
+    if (!p)
+        return `convene: best practice ${id} applies here.`;
+    return `convene: ${p.title} — ${p.id}.${whySuffix(id)}`;
+}
+/**
+ * DEFAULT protected paths for protect-shared-files (used when the repo has not
+ * customized a set). Returns true iff the Write/Edit target is shared/global and
+ * must not be edited by a non-owner session. Matched against the path RELATIVE to
+ * the repo toplevel so a root-config match is anchored at the root, not anywhere.
+ */
+function isProtectedPath(targetAbsOrRel, top) {
+    if (!targetAbsOrRel)
+        return false;
+    // Normalize to a repo-relative POSIX path. Resolve symlinks on BOTH sides
+    // best-effort so a /var → /private/var (macOS) or other symlinked toplevel can't
+    // make an in-repo target look external. realpath only the longest EXISTING
+    // ancestor (the leaf may not exist yet for a Write).
+    let rel = targetAbsOrRel;
+    if (node_path_1.default.isAbsolute(rel)) {
+        rel = node_path_1.default.relative(realpathBest(top), realpathBest(rel));
+    }
+    rel = rel.split(node_path_1.default.sep).join('/');
+    if (!rel || rel.startsWith('../'))
+        return false; // outside the repo → not ours to gate
+    const base = rel.split('/').pop() || rel;
+    // Lockfiles — anywhere in the tree.
+    const LOCKFILES = new Set([
+        'package-lock.json',
+        'yarn.lock',
+        'pnpm-lock.yaml',
+        'Cargo.lock',
+        'go.sum',
+        'poetry.lock',
+    ]);
+    if (LOCKFILES.has(base))
+        return true;
+    // Any path under a `migrations/` directory (at any depth).
+    if (/(^|\/)migrations\//.test(rel))
+        return true;
+    // Root-level shared config files (anchored at the repo root only).
+    const segments = rel.split('/');
+    if (segments.length === 1) {
+        if (base === 'tsconfig.json' || base === 'Dockerfile')
+            return true;
+        if (/^\.eslintrc(\..+)?$/.test(base))
+            return true;
+    }
+    return false;
+}
+/**
+ * Realpath a path, resolving symlinks on the longest EXISTING ancestor and
+ * re-appending the non-existent leaf segments. Falls back to the input on any
+ * error — a best-effort canonicalization, never a throw.
+ */
+function realpathBest(p) {
+    try {
+        return node_fs_1.default.realpathSync(p);
+    }
+    catch {
+        /* leaf may not exist yet — resolve the deepest existing ancestor */
+    }
+    let dir = p;
+    const tail = [];
+    for (let i = 0; i < 64; i++) {
+        const parent = node_path_1.default.dirname(dir);
+        if (parent === dir)
+            break; // reached the root
+        tail.unshift(node_path_1.default.basename(dir));
+        dir = parent;
+        try {
+            return node_path_1.default.join(node_fs_1.default.realpathSync(dir), ...tail);
+        }
+        catch {
+            /* keep walking up */
+        }
+    }
+    return p;
+}
+/** Resolve the adopted level for <id> from the repo manifest, or null if unadopted. */
+function adoptedLevel(top, id) {
+    const manifest = (0, config_1.loadManifest)(top);
+    if (!manifest)
+        return null;
+    const entry = manifest.practices.find((p) => p.id === id);
+    return entry ? entry.level : null;
+}
+/**
+ * The branch is CONFIRMED behind origin/main iff origin/main is NOT an ancestor of
+ * HEAD. Purely local (no fetch on the hot path — `pull-main-before-execution`
+ * deliberately does not do a slow network fetch per the spec); uses the existing
+ * tracking ref. Any uncertainty → false (no reminder), never a slow path.
+ */
+function behindOriginMain(top) {
+    try {
+        const head = (0, git_1.revParse)('HEAD', top);
+        const remote = (0, git_1.revParse)('origin/main', top) ?? (0, git_1.revParse)('origin/master', top);
+        if (!head || !remote)
+            return false;
+        if (head === remote)
+            return false;
+        // behind ⇔ remote is not an ancestor of HEAD AND there are commits we lack.
+        if ((0, git_1.isAncestor)(remote, head, top))
+            return false; // we are ahead or equal → not behind
+        const behindCount = (0, git_1.revListCount)(`${head}..${remote}`, top);
+        return (behindCount ?? 0) > 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function run(opts, id) {
+    if (!id)
+        return 0; // no practice id → nothing to gate
+    const top = (0, git_1.gitToplevel)();
+    if (!top)
+        return 0; // not a git repo → no-op
+    const proj = (0, config_1.loadProjectConfig)(top);
+    const slug = opts.project || proj?.slug || null;
+    if (!slug)
+        return 0; // not on the bus → no-op
+    const level = adoptedLevel(top, id);
+    // Unadopted, or a non-mechanical level → the gate is inert. SILENT exit 0.
+    if (level == null || level === 'advisory' || level === 'ci' || level === 'manual')
+        return 0;
+    // A live override token for (slug,id) → ALLOW with a one-line note (works at any
+    // mechanical level, including hook-hard).
+    const ovr = (0, cache_1.readLiveOverrideToken)(slug, id);
+    if (ovr) {
+        note(`convene: override active for ${id} — "${ovr.reason}" — proceeding (gate bypassed).`);
+        return 0;
+    }
+    // Read the PreToolUse payload (the Write/Edit target path).
+    const raw = opts.stdin ? await readStdin(1500) : null;
+    const target = targetPathFromPayload(raw);
+    // ── Per-practice checks ─────────────────────────────────────────────────────
+    switch (id) {
+        case 'protect-shared-files': {
+            const hit = isProtectedPath(target, top);
+            if (!hit)
+                return 0; // a normal file → allow (zero noise)
+            if (level === 'hook-hard') {
+                blockReason(`convene: BLOCKED — ${shortRel(target, top)} is a shared/global file (lockfile, migration, or root config) ` +
+                    `protected by practice protect-shared-files. Editing it across sessions reliably breaks integration. ` +
+                    `If this session OWNS this change: \`convene override protect-shared-files --reason "<why>"\`, then retry.` +
+                    whySuffix(id));
+                return 2;
+            }
+            // hook-soft → remind, allow.
+            note(`convene: ${shortRel(target, top)} is a shared/global file — protect-shared-files. ` +
+                `Only edit it if this session is the assigned owner; otherwise sequence the change.` +
+                whySuffix(id));
+            return 0;
+        }
+        case 'worktree-per-session': {
+            // hook-soft: if >1 live session shares this checkout, nudge toward a worktree
+            // (reuse the doctor signal). Best-effort; any uncertainty → no nudge.
+            const live = (0, cache_1.liveSessionCount)(slug, 15 * 60);
+            if (live > 1) {
+                note(`convene: ${live} live sessions share this checkout — worktree-per-session. ` +
+                    `Run each concurrent agent in its own worktree (\`convene worktree <branch>\`) to avoid silent clobbering.` +
+                    whySuffix(id));
+            }
+            return 0;
+        }
+        case 'pull-main-before-execution': {
+            // hook-soft, best-effort, LOCAL only (no slow fetch on the hot path).
+            if (behindOriginMain(top)) {
+                const b = (0, git_1.currentBranch)(top) ?? 'this branch';
+                note(`convene: ${b} is behind origin/main — pull-main-before-execution. ` +
+                    `Rebase onto origin/main and re-validate the plan before editing.` +
+                    whySuffix(id));
+            }
+            return 0;
+        }
+        default:
+            // plan-mode-before-edits / focused-subagents-least-privilege / any other id:
+            // a soft reminder from the catalog title. Never blocks.
+            note(reminderFor(id));
+            return 0;
+    }
+}
+/** Short, repo-relative display of a path for the reason line. */
+function shortRel(target, top) {
+    if (!target)
+        return 'this file';
+    const rel = node_path_1.default.isAbsolute(target) ? node_path_1.default.relative(top, target) : target;
+    return rel.split(node_path_1.default.sep).join('/') || target;
+}
+async function practiceGuard(id, opts = {}) {
+    let code = 0;
+    const watchdog = setTimeout(() => (0, exit_1.exitClean)(0), WATCHDOG_MS);
+    watchdog.unref();
+    try {
+        code = await run(opts, id);
+    }
+    catch {
+        code = 0; // fail-open: never block on our own error
+    }
+    clearTimeout(watchdog);
+    (0, exit_1.exitClean)(code);
+}

package/dist/commands/practices.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.practices = practices;
+/**
+ * `convene practices [id]` — the LEARN surface for the best-practices catalog.
+ *
+ * Without an id: lists every catalog practice grouped by tier, marking the ones THIS
+ * repo adopted (and at what level), so a human or agent can see what is on offer and
+ * what is active. With an id: prints that practice in depth — what it is, WHY (the
+ * failure mode it prevents), its enforcement levels, provenance, and the source URLs
+ * the practice was distilled from.
+ *
+ * The `why` and `sourceUrls` are authored on every one of the catalog's practices but
+ * were rendered nowhere — the picker shows a bare title, the materialized doc and the
+ * dashboard show the `what`/id. This command is where a repo LEARNS the rationale,
+ * before or after adopting. It deliberately lives OFF the always-loaded path (a doc
+ * imported into CLAUDE.md every turn would tax the agent — Gloaguen et al. 2026), so
+ * the heavy rationale is on-demand here, not in the hot path.
+ *
+ * Reads the bundled offline mirror (CATALOG) — network-free, instant, fail-soft. The
+ * repo manifest (loadManifest) only annotates adoption; its absence is fine (every
+ * practice then shows as available/not-adopted).
+ */
+const git_1 = require("../git");
+const config_1 = require("../config");
+const catalog_1 = require("../catalog");
+const out = (s) => process.stdout.write(s + '\n');
+/** id → adopted level, from the repo manifest. Empty (and never throws) when none. */
+function adoptedLevels() {
+    const m = new Map();
+    try {
+        const top = (0, git_1.gitToplevel)();
+        if (!top)
+            return m;
+        const manifest = (0, config_1.loadManifest)(top);
+        if (manifest)
+            for (const e of manifest.practices)
+                m.set(e.id, e.level);
+    }
+    catch {
+        /* fail-soft: no manifest annotations, list still works */
+    }
+    return m;
+}
+/** Entry point: detail view when an id is given, else the grouped list. Never throws. */
+function practices(id, _opts = {}) {
+    const adopted = adoptedLevels();
+    const wanted = (id ?? '').trim();
+    if (wanted)
+        printDetail(wanted, adopted);
+    else
+        printList(adopted);
+}
+/** The grouped list: every practice by tier, adopted ones marked with their level. */
+function printList(adopted) {
+    out(`Convene best-practices catalog v${catalog_1.CATALOG.version} — ${catalog_1.CATALOG.practices.length} practices, ` +
+        `${adopted.size} adopted in this repo.`);
+    out('Run `convene practices <id>` for the why + sources behind any one.');
+    // Pad ids to a common width so titles line up; ✓ marks an adopted practice.
+    const idWidth = Math.min(34, catalog_1.CATALOG.practices.reduce((w, p) => Math.max(w, p.id.length), 0));
+    for (const tier of catalog_1.CATALOG.tiers) {
+        const inTier = catalog_1.CATALOG.practices.filter((p) => p.tier === tier.id);
+        if (inTier.length === 0)
+            continue;
+        out('');
+        out(`${tier.name}`);
+        for (const p of inTier) {
+            const lvl = adopted.get(p.id);
+            const mark = lvl ? `✓ [${lvl}]` : '·';
+            out(`  ${mark.padEnd(13)} ${p.id.padEnd(idWidth)}  ${p.title}`);
+        }
+    }
+}
+/** The depth view for one practice: what / why / levels / provenance / sources. */
+function printDetail(id, adopted) {
+    const p = catalog_1.CATALOG.practices.find((x) => x.id === id);
+    if (!p) {
+        out(`No practice "${id}" in catalog v${catalog_1.CATALOG.version}.`);
+        const near = catalog_1.CATALOG.practices.filter((x) => x.id.includes(id) || id.includes(x.id)).slice(0, 5);
+        if (near.length) {
+            out('Did you mean:');
+            for (const n of near)
+                out(`  ${n.id}`);
+        }
+        else {
+            out('Run `convene practices` to list them all.');
+        }
+        return;
+    }
+    const lvl = adopted.get(p.id);
+    out(p.title);
+    out(`${p.id}  ·  ${p.tier} / ${p.category}  ·  v${p.version}`);
+    out(lvl ? `adopted here at: ${lvl}` : `not adopted here (suggested level: ${p.defaultLevel})`);
+    out(`enforcement levels: ${p.availableLevels.join(', ')}`);
+    if (p.productionLearned) {
+        out('provenance: production-learned at the BrightAI Opportunity Explorer');
+    }
+    out('');
+    out('WHAT');
+    out(`  ${p.what}`);
+    out('');
+    out('WHY');
+    out(`  ${p.why}`);
+    if (p.sourceUrls && p.sourceUrls.length > 0) {
+        out('');
+        out('SOURCES');
+        for (const u of p.sourceUrls)
+            out(`  - ${u}`);
+    }
+}

package/dist/commands/setup.js

@@ -31,7 +31,17 @@ async function setup(opts) {
     }
     else {
         log('This repo is not on Convene yet — onboarding it…');
-        await (0, init_1.init)({ slug: opts.slug, email: opts.email, force: opts.force, yes: opts.yes, commit: opts.commit });
+        await (0, init_1.init)({
+            slug: opts.slug,
+            email: opts.email,
+            force: opts.force,
+            yes: opts.yes,
+            commit: opts.commit,
+            tier: opts.tier,
+            practice: opts.practice,
+            allPractices: opts.allPractices,
+            noPractices: opts.noPractices,
+        });
     }
     log('');
     log('— Connected. Quick usage —');