convene-cli 1.5.1 → 1.6.0

package/dist/catalog/prompt.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.practiceBlurb = practiceBlurb;
 exports.pickPracticesInteractively = pickPracticesInteractively;
 /**
  * Interactive best-practices picker for `convene init` / `convene setup`.
@@ -16,6 +17,24 @@ exports.pickPracticesInteractively = pickPracticesInteractively;
 const promises_1 = __importDefault(require("node:readline/promises"));
 const select_1 = require("./select");
 const out = (m) => process.stdout.write(m + '\n');
+/** Truncate to ~n chars on a soft boundary, adding an ellipsis when clipped. */
+function truncate(s, n) {
+    if (s.length <= n)
+        return s;
+    return s.slice(0, n - 1).trimEnd() + '…';
+}
+/**
+ * The provenance/rationale context shown above each practice in the customizer, so
+ * a user can make an INFORMED adoption choice (feedback 52269531 — the picker used
+ * to show only a bare title). Renders the practice title, a production-learned
+ * marker (the provenance the Practice.productionLearned comment promises), and a
+ * truncated `why`. Pure + exported so it can be asserted without a TTY.
+ */
+function practiceBlurb(p) {
+    const mark = p.productionLearned ? ' ★ production-learned' : '';
+    const why = p.why ? `\n    why: ${truncate(p.why, 110)}` : '';
+    return `  ${p.title}${mark}${why}`;
+}
 /** Count of opt-in (default-ON) practices in the named tiers — for the menu labels. */
 function presetCount(catalog, preset) {
     return (0, select_1.presetSelections)(catalog, preset).length;
@@ -55,22 +74,25 @@ async function pickPracticesInteractively(catalog) {
     }
 }
 /**
- * Customize from the recommended preset: for each chosen practice show
- * `title [defaultLevel]` and accept enter=keep, 's'=skip, or a level name from
- * availableLevels. Skimmable; unknown levels re-prompt-free (keep at default).
+ * Customize from the recommended preset: for each chosen practice show its title,
+ * provenance, and a one-line `why` (via practiceBlurb), then accept enter=keep,
+ * 's'=skip, or a level name from availableLevels. Skimmable; unknown levels
+ * re-prompt-free (keep at default).
  */
 async function customize(catalog, rl) {
     const base = (0, select_1.presetSelections)(catalog, 'recommended');
     const byId = new Map(catalog.practices.map((p) => [p.id, p]));
     const result = [];
     out('');
-    out('Customize — for each: [enter] keep · [s] skip · or type a level name.');
+    out('Customize — for each: [enter] keep the suggested level · [s] skip · or type a level name.');
     for (const sel of base) {
         const p = byId.get(sel.id);
         if (!p)
             continue;
         const levels = p.availableLevels.join('/');
-        const ans = (await rl.question(`  ${p.title} [${sel.level}] (${levels}): `)).trim().toLowerCase();
+        out('');
+        out(practiceBlurb(p));
+        const ans = (await rl.question(`    [${sel.level}] (${levels}): `)).trim().toLowerCase();
         if (ans === 's' || ans === 'skip')
             continue;
         if (ans === '') {

package/dist/commands/auth.js

@@ -6,9 +6,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.login = login;
 exports.whoami = whoami;
 exports.assessLaneIdentity = assessLaneIdentity;
+exports.assessSettingsIntegrity = assessSettingsIntegrity;
 exports.doctor = doctor;
 /** login / whoami / doctor. */
 const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 const brand_1 = require("../brand");
 const api_1 = require("../api");
@@ -152,6 +154,96 @@ function assessLaneIdentity(lanes, myHandle, haveInstance, staleSec = LANE_STALE
     }
     return { name, ok: true, detail: `holding ${mine.length} lane(s), all fresh and owned by this session` };
 }
+/** Count non-overlapping occurrences of `sub` in `s`. */
+function countOccurrences(s, sub) {
+    if (!sub)
+        return 0;
+    let n = 0;
+    let i = s.indexOf(sub);
+    while (i >= 0) {
+        n++;
+        i = s.indexOf(sub, i + sub.length);
+    }
+    return n;
+}
+/**
+ * Non-destructiveness assertion (feedback 3749eac9 / dhparmele): Convene earns
+ * authority by scope + ADDITIVE merge, never by overwriting user-owned files. This
+ * check confirms that posture is intact:
+ *   - the global + project `.claude/settings.json` parse as JSON (a file Convene
+ *     would otherwise leave untouched but also could not merge into — worth flagging);
+ *   - any Convene hook coexists with user-owned hooks (additivity, not whole-object
+ *     replace) — reported as a positive note, NEVER a failure;
+ *   - the CLAUDE.md / AGENTS.md Convene marker blocks are well-formed (a balanced,
+ *     non-inverted begin/end pair) so a `--refresh-docs` re-render stays surgical.
+ * Fails (ok:false) ONLY on genuine corruption (invalid JSON / malformed markers),
+ * never on a user simply having their own hooks. Diagnostic only — no auto-repair.
+ * Exported + parameterized so it can be asserted hermetically without a TTY/network.
+ */
+function assessSettingsIntegrity(top, globalSettingsPath = hook_1.SETTINGS_PATH) {
+    const name = 'settings';
+    const problems = [];
+    const notes = [];
+    const settingsFiles = [{ label: 'global', file: globalSettingsPath }];
+    if (top)
+        settingsFiles.push({ label: 'project', file: (0, hook_1.projectSettingsPath)(top) });
+    for (const { label, file } of settingsFiles) {
+        if (!node_fs_1.default.existsSync(file))
+            continue;
+        let parsed;
+        try {
+            const raw = node_fs_1.default.readFileSync(file, 'utf8');
+            parsed = raw.trim() === '' ? {} : JSON.parse(raw);
+        }
+        catch {
+            problems.push(`${label} settings.json is not valid JSON — Convene leaves it untouched but cannot merge into it (${file})`);
+            continue;
+        }
+        if (parsed && typeof parsed === 'object' && parsed.hooks && typeof parsed.hooks === 'object') {
+            let convene = 0;
+            let foreign = 0;
+            for (const ev of Object.keys(parsed.hooks)) {
+                const groups = Array.isArray(parsed.hooks[ev]) ? parsed.hooks[ev] : [];
+                for (const g of groups) {
+                    const isConvene = Array.isArray(g?.hooks) &&
+                        g.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('convene'));
+                    if (isConvene)
+                        convene++;
+                    else
+                        foreign++;
+                }
+            }
+            if (foreign > 0)
+                notes.push(`${label}: ${foreign} user-owned hook(s) preserved alongside ${convene} Convene hook(s)`);
+        }
+    }
+    if (top) {
+        for (const fname of ['CLAUDE.md', 'AGENTS.md']) {
+            const p = node_path_1.default.join(top, fname);
+            if (!node_fs_1.default.existsSync(p))
+                continue;
+            let content;
+            try {
+                content = node_fs_1.default.readFileSync(p, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const begins = countOccurrences(content, brand_1.BRAND.blockBegin);
+            const ends = countOccurrences(content, brand_1.BRAND.blockEnd);
+            if (begins !== ends || begins > 1) {
+                problems.push(`${fname} has a malformed Convene marker block (${begins} begin / ${ends} end) — repair the markers before a refresh`);
+            }
+            else if (begins === 1 && content.indexOf(brand_1.BRAND.blockBegin) > content.indexOf(brand_1.BRAND.blockEnd)) {
+                problems.push(`${fname} Convene marker block is inverted (begin after end) — repair the markers`);
+            }
+        }
+    }
+    if (problems.length)
+        return { name, ok: false, detail: problems.join('; ') };
+    const tail = notes.length ? ` (${notes.join('; ')})` : '';
+    return { name, ok: true, detail: `settings JSON valid + marker blocks intact; Convene edits are additive${tail}` };
+}
 async function doctor(opts) {
     const checks = [];
     const cfg = (0, config_1.resolveConfig)();
@@ -228,6 +320,9 @@ async function doctor(opts) {
                 ? 'UserPromptSubmit `convene fetch` registered'
                 : 'hook NOT registered (run `convene init` or `convene doctor --fix`)',
     });
+    // 6b. settings non-destructiveness — Convene's edits stay additive + marker-scoped;
+    //     user-owned hooks/files are never clobbered. Fails only on genuine corruption.
+    checks.push(assessSettingsIntegrity(top));
     // 7. watch heartbeat — a stale/absent heartbeat means the mid-task halt watcher
     // is DOWN (so directed halts won't surface between turns). Only meaningful for a
     // repo on the bus; --fix may (re)launch `convene watch` detached.

package/dist/commands/catchup.js

@@ -25,7 +25,9 @@ const cache_1 = require("../cache");
 const api_1 = require("../api");
 const exit_1 = require("../exit");
 const render_1 = require("../render");
-const FETCH_TIMEOUT_MS = 4000;
+// Default 4000ms; overridable via CONVENE_FETCH_TIMEOUT_MS (tests drive it small for
+// deterministic, load-independent latency-budget assertions). See config.ts.
+const FETCH_TIMEOUT_MS = (0, config_1.resolveFetchTimeoutMs)();
 const WATCHDOG_MS = 6000;
 const MAX_ITEMS = 400;
 function emit(s) {

package/dist/commands/fetch.js

@@ -29,7 +29,9 @@ const render_1 = require("../render");
 const catchup_1 = require("./catchup");
 const exit_1 = require("../exit");
 const CACHE_TTL_SEC = 3;
-const FETCH_TIMEOUT_MS = 4000;
+// Default 4000ms; overridable via CONVENE_FETCH_TIMEOUT_MS (tests drive it small for
+// deterministic, load-independent latency-budget assertions). See config.ts.
+const FETCH_TIMEOUT_MS = (0, config_1.resolveFetchTimeoutMs)();
 const WATCHDOG_MS = 6000;
 /** Catalog-version cache TTL for the behind-nudge — long enough to stay off the hot path. */
 const CATALOG_VERSION_TTL_SEC = 3600;
@@ -50,8 +52,9 @@ const CATALOG_VERSION_TTL_SEC = 3600;
 // fast blip, given the bus normally answers in ~0.15s.
 /** Total network budget for the feed fetch across all attempts (== FETCH_TIMEOUT_MS). */
 const FEED_BUDGET_MS = FETCH_TIMEOUT_MS;
-/** First-attempt timeout. ~500ms under FETCH_TIMEOUT_MS, leaving room for a retry. */
-const FEED_ATTEMPT_MS = 3500;
+/** First-attempt timeout. ~500ms under FETCH_TIMEOUT_MS, leaving room for a retry.
+ *  Derived from FETCH_TIMEOUT_MS so a small env override never exceeds the budget. */
+const FEED_ATTEMPT_MS = Math.max(250, FETCH_TIMEOUT_MS - 500);
 /** A failure faster than this is treated as a transient blip worth one retry. */
 exports.FEED_FAST_FAIL_MS = 1200;
 /** Brief pause before the retry, to let a restarting task come back. */

package/dist/commands/init.js

@@ -209,7 +209,10 @@ function registerHook(noHook) {
         if (raw !== null)
             node_fs_1.default.writeFileSync(hook_1.SETTINGS_PATH + '.bak', raw);
         node_fs_1.default.writeFileSync(hook_1.SETTINGS_PATH, (0, hook_1.serializeSettings)((0, hook_1.withHook)(settings)));
-        log(`Registered UserPromptSubmit hook in ${hook_1.SETTINGS_PATH}${raw !== null ? ' (backup: settings.json.bak)' : ''}.`);
+        log(`Registered the lightweight \`convene fetch\` UserPromptSubmit hook in ${hook_1.SETTINGS_PATH}${raw !== null ? ' (backup: settings.json.bak)' : ''}.`);
+        log('  ↳ This is the ONE global write: it fires in every repo (a silent no-op off the bus) and is ' +
+            'ADDITIVE — your own hooks are left untouched. Prefer not to touch ~/.claude? Re-run with ' +
+            '`--no-hook`; the committed project `.claude/settings.json` hook still covers this repo.');
     }
     catch (err) {
         log(`Could not write settings (${err?.message}). Add this hook manually:`);

package/dist/commands/session-start.js

@@ -7,7 +7,8 @@ exports.sessionStart = sessionStart;
  * FAIL-OPEN (P0-FAILSAFE), copying the fetch.ts scaffold:
  *   - hard watchdog at 6000ms → exit 0 no matter what (SessionStart's own default
  *     timeout is 30s, which would stall a boot — we bound it ourselves);
- *   - the network GET is bounded at 4000ms;
+ *   - the network GET is bounded at FETCH_TIMEOUT_MS (default 4000ms; overridable
+ *     via CONVENE_FETCH_TIMEOUT_MS for deterministic tests);
  *   - any error / non-bus repo / DEGRADED emits NOTHING and exits 0.
  *
  * What it does on a fresh, authenticated bus repo:
@@ -26,7 +27,9 @@ const api_1 = require("../api");
 const render_1 = require("../render");
 const catchup_1 = require("./catchup");
 const exit_1 = require("../exit");
-const FETCH_TIMEOUT_MS = 4000;
+// Default 4000ms; overridable via CONVENE_FETCH_TIMEOUT_MS (tests drive it small for
+// deterministic, load-independent latency-budget assertions). See config.ts.
+const FETCH_TIMEOUT_MS = (0, config_1.resolveFetchTimeoutMs)();
 const WATCHDOG_MS = 6000;
 const MAX_ITEMS = 400;
 // Don't relaunch the watch daemon if one stamped a heartbeat this recently — a

package/dist/config.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CACHE_DIR = exports.CONFIG_FILE = exports.CONFIG_DIR = void 0;
 exports.homeBase = homeBase;
+exports.resolveFetchTimeoutMs = resolveFetchTimeoutMs;
 exports.isWorldReadable = isWorldReadable;
 exports.loadFileConfig = loadFileConfig;
 exports.loadProjectConfig = loadProjectConfig;
@@ -28,6 +29,19 @@ const brand_1 = require("./brand");
 function homeBase() {
     return process.env.CONVENE_HOME_OVERRIDE || node_os_1.default.homedir();
 }
+/**
+ * Network fetch timeout (ms) for the hook/catch-up paths. Overridable via
+ * CONVENE_FETCH_TIMEOUT_MS so the fail-open/timeout tests can drive the path
+ * deterministically with a small value instead of relying on the real 4s
+ * wall-clock — which, under full-suite serial load, collides with process-spawn
+ * + GC jitter and intermittently blows the latency-budget assertion. A garbage or
+ * non-positive value falls back to the default. Production default unchanged (4000).
+ */
+function resolveFetchTimeoutMs(fallback = 4000) {
+    const raw = process.env.CONVENE_FETCH_TIMEOUT_MS;
+    const n = raw ? Number(raw) : NaN;
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
 exports.CONFIG_DIR = node_path_1.default.join(homeBase(), brand_1.BRAND.configDir);
 exports.CONFIG_FILE = node_path_1.default.join(exports.CONFIG_DIR, 'config.json');
 exports.CACHE_DIR = node_path_1.default.join(exports.CONFIG_DIR, 'cache');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convene-cli",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Convene CLI — AI development coordination bus client + UserPromptSubmit hook. Install: npm i -g convene-cli; then `convene setup`.",
   "license": "MIT",
   "homepage": "https://dev.convene.live",