convene-cli 1.13.0 → 1.13.2

package/dist/api.js

@@ -207,9 +207,11 @@ class ConveneApi {
     }
     /**
      * GET /catalog — the canonical best-practices catalog (PUBLIC, no tenant data).
-     * The CLI prefers this live read but is fully fail-soft: on any non-ok / network
-     * error the caller falls back to the bundled offline mirror. Bounded by a short
-     * timeout — never the 10s default.
+     * The server returns a release ENVELOPE `{ version, contentHash, catalog }`; the
+     * actual Catalog lives under `.catalog` (loadCatalog unwraps it). The CLI prefers
+     * this live read but is fully fail-soft: on any non-ok / network error the caller
+     * falls back to the bundled offline mirror. Bounded by a short timeout — never
+     * the 10s default.
      */
     getCatalog(timeoutMs) {
         return this.request('GET', '/catalog', { timeoutMs });

package/dist/catalog/index.js

@@ -6,16 +6,26 @@ const catalog_generated_1 = require("./catalog.generated");
 Object.defineProperty(exports, "CATALOG", { enumerable: true, get: function () { return catalog_generated_1.CATALOG; } });
 Object.defineProperty(exports, "CATALOG_VERSION", { enumerable: true, get: function () { return catalog_generated_1.CATALOG_VERSION; } });
 /**
- * Load the catalog, preferring the live server copy when `api` is given. Any
- * failure (no client, non-ok status, network error, empty body) silently falls
- * back to the bundled mirror — this never throws.
+ * Load the catalog, preferring the live server copy when `api` is given. Unwraps
+ * the server's release envelope ({ version, contentHash, catalog }) and tolerates
+ * a bare Catalog for back-compat. Any failure (no client, non-ok status, network
+ * error, empty/malformed body) silently falls back to the bundled mirror — this
+ * never throws.
  */
 async function loadCatalog(api, timeoutMs = 5_000) {
     if (api) {
         try {
             const res = await api.getCatalog(timeoutMs);
-            if (res.ok && res.json && Array.isArray(res.json.practices) && res.json.version) {
-                return { catalog: res.json, source: 'live' };
+            // The server wraps the catalog in a release envelope
+            // ({ version, contentHash, catalog }); the Catalog (with `practices`) lives
+            // one level down under `.catalog`. Unwrap that, but also tolerate a bare
+            // Catalog for back-compat with a differently-shaped/older server. VALIDATE
+            // the UNWRAPPED object — the envelope's top-level `version` matches a bare
+            // Catalog's, so guarding on the inner `practices` is what tells them apart.
+            const body = res.json;
+            const cat = body && 'catalog' in body ? body.catalog : body;
+            if (res.ok && cat && Array.isArray(cat.practices) && typeof cat.version === 'string') {
+                return { catalog: cat, source: 'live' };
             }
         }
         catch {

package/dist/catalog/manifest.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.semverLt = semverLt;
 exports.bumpClass = bumpClass;
 exports.compareToCatalog = compareToCatalog;
+exports.catalogBehindLine = catalogBehindLine;
+exports.bestPracticesFreshnessLine = bestPracticesFreshnessLine;
 /**
  * Strict SemVer less-than over the dotted numeric core (pre-release/build
  * metadata ignored — the catalog uses plain X.Y.Z). Missing components read as
@@ -69,3 +71,31 @@ function compareToCatalog(manifest, catalog) {
         unknownIds,
     };
 }
+/**
+ * The canonical "your repo trails the catalog" nudge, shared by `convene doctor`
+ * and the `convene fetch` channel nudge so the SAME sentence ALWAYS means the
+ * same thing: `serverVersion` is the SERVER-published catalog version
+ * (authoritative), `repoVersion` is what this repo adopted. Never call this with
+ * a bundled-mirror version — a stale binary's bundled version is not "available"
+ * on the server (see `bestPracticesFreshnessLine`'s offline branch for that).
+ */
+function catalogBehindLine(serverVersion, repoVersion) {
+    return `server catalog v${serverVersion} available (repo adopted v${repoVersion}) — run \`convene update\``;
+}
+/**
+ * The `convene doctor` best-practices freshness line, given a catalog comparison
+ * and WHERE the catalog came from. Server-truthful by construction: it only makes
+ * an "available"/"up to date" claim when the comparison was against the LIVE
+ * server catalog. When the server was unreachable the comparison is against the
+ * bundled mirror baked into this binary — which may trail OR lead the server — so
+ * it refuses to claim either and just states both versions + that the server is
+ * unknown. Pure (no stdout/network) so it unit-tests directly.
+ */
+function bestPracticesFreshnessLine(cmp, source) {
+    if (source === 'live') {
+        return cmp.behind
+            ? catalogBehindLine(cmp.catalogVersion, cmp.repoVersion)
+            : `best practices up to date with server catalog v${cmp.repoVersion}`;
+    }
+    return `bundled catalog v${cmp.catalogVersion} (offline — server version unknown) vs repo adopted v${cmp.repoVersion}`;
+}

package/dist/commands/auth.js

@@ -636,22 +636,35 @@ async function doctor(opts) {
     for (const c of checks) {
         process.stdout.write(`${c.ok ? '✓' : '✗'} ${c.name.padEnd(8)} ${c.detail}\n`);
     }
-    // Best practices (local-only, advisory): adopted-practice inventory + whether
-    // the repo trails the catalog. Fail-soft — never throws and never alters the
-    // doctor exit code.
-    reportBestPractices(top, proj?.slug ?? null);
+    // Best practices (advisory): adopted-practice inventory + whether the repo
+    // trails the catalog. Fail-soft — never throws and never alters the doctor exit
+    // code. Resolve the catalog SERVER-TRUTHFULLY first (prefer the live published
+    // catalog, fall back to the bundled mirror) — the same `loadCatalog` resolver
+    // `convene update` uses — so the "available" line reflects what the SERVER
+    // publishes, not the version baked into this binary. doctor is already async +
+    // already does network I/O (api.me above), so a live fetch here costs nothing
+    // extra; loadCatalog is fail-soft and tags its source, so an unreachable server
+    // simply yields the bundled mirror, labelled honestly as offline.
+    const { catalog: bpCatalog, source: bpSource } = await (0, catalog_1.loadCatalog)(cfg.apiKey ? new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey) : null);
+    reportBestPractices(top, proj?.slug ?? null, bpCatalog, bpSource);
     if (!checks.every((c) => c.ok))
         process.exitCode = 1;
 }
 /**
- * Print doctor's "Best practices" section. Local-only this phase: reads the repo
- * manifest and diffs it against the bundled catalog. Purely informational — it
- * never throws (a malformed manifest is swallowed) and never sets the exit code.
- *   - manifest present → catalog freshness line + each adopted practice + unknowns.
+ * Print doctor's "Best practices" section. Diffs the repo manifest against the
+ * RESOLVED catalog (`catalog`/`source` come from loadCatalog — live-preferred,
+ * bundled fallback). Purely informational — it never throws (a malformed manifest
+ * is swallowed) and never sets the exit code.
+ *   - manifest present → server-truthful freshness line + each adopted practice + unknowns.
  *   - on the bus but no manifest → a single nudge to adopt some.
  *   - not on the bus → nothing.
+ * The freshness wording is server-truthful: an "available"/"up to date" claim is
+ * made only when `source === 'live'`; an unreachable server yields the honest
+ * "bundled catalog … (offline — server version unknown)" line (see
+ * `bestPracticesFreshnessLine`). The same `catalogBehindLine` phrasing is shared
+ * with the `convene fetch` nudge so the sentence never means two different things.
  */
-function reportBestPractices(top, slug) {
+function reportBestPractices(top, slug, catalog, source) {
     try {
         const manifest = (0, config_1.loadManifest)(top);
         if (!manifest) {
@@ -660,10 +673,8 @@ function reportBestPractices(top, slug) {
             }
             return;
         }
-        const cmp = (0, manifest_1.compareToCatalog)(manifest, catalog_1.CATALOG);
-        process.stdout.write(cmp.behind
-            ? `· catalog v${cmp.catalogVersion} available (repo on v${cmp.repoVersion}) — run \`convene update\`\n`
-            : `· best practices up to date at v${cmp.repoVersion}\n`);
+        const cmp = (0, manifest_1.compareToCatalog)(manifest, catalog);
+        process.stdout.write(`· ${(0, manifest_1.bestPracticesFreshnessLine)(cmp, source)}\n`);
         for (const p of cmp.adopted) {
             const flag = p.outdated ? ` (outdated → v${p.catalogVersion})` : '';
             process.stdout.write(`    ${p.id} @ ${p.manifestVersion} [${p.level}]${flag}\n`);

package/dist/commands/fetch.js

@@ -105,7 +105,10 @@ function catalogBehindNudge(top) {
             return null;
         if (!(0, manifest_1.semverLt)(manifest.catalogVersion, live))
             return null;
-        return `convene: best-practices catalog v${live} available (repo on v${manifest.catalogVersion}) — run \`convene update\``;
+        // Shared phrasing with `convene doctor` — `live` is the SERVER version (the
+        // cache is populated from api.getCatalog), so the "server catalog vX" wording
+        // is accurate here and means the SAME thing in both surfaces.
+        return `convene: ${(0, manifest_1.catalogBehindLine)(live, manifest.catalogVersion)}`;
     }
     catch {
         return null;

package/dist/commands/gate-push.js

@@ -129,7 +129,23 @@ function loudOpen(systemMessage) {
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 async function run(opts) {
-    const top = (0, git_1.gitToplevel)();
+    // Read the PreToolUse / pre-push payload ONCE up front. stdin can only be read
+    // once, so everything downstream reuses `payloadRaw`. For the Claude Code
+    // PreToolUse path we need it to resolve the directory the push ACTUALLY runs in
+    // BEFORE resolving the repo — a release is routinely pushed from a SEPARATE
+    // worktree, and gating the SESSION-ROOT checkout instead false-blocks it (bug
+    // deff9ab9).
+    const payloadRaw = opts.stdin ? await readStdin(1500) : null;
+    const trimmed = (payloadRaw ?? '').trim();
+    const isHookPayload = trimmed.startsWith('{');
+    // Effective push directory: the PreToolUse `cwd` (reflects a persisted `cd`)
+    // overridden by a leading in-command `cd`; process.cwd() otherwise — which is
+    // also correct for the real git pre-push hook, where cwd already IS the pushed
+    // worktree.
+    const pushCwd = isHookPayload
+        ? (0, guard_1.resolvePushCwd)(payloadRaw, (0, guard_1.commandFromPayload)(payloadRaw))
+        : { dir: process.cwd(), indeterminate: false };
+    const top = (0, git_1.gitToplevel)(pushCwd.dir);
     if (!top)
         return 0; // not a git repo → no-op
     const cwd = top;
@@ -143,15 +159,14 @@ async function run(opts) {
     // Determine the ref(s) being pushed.
     let refs;
     if (opts.stdin) {
-        const stdin = await readStdin(1500);
-        const trimmed = (stdin ?? '').trim();
-        if (trimmed.startsWith('{')) {
+        if (isHookPayload) {
             // Claude Code PreToolUse/PostToolUse payload (JSON). Gate ONLY a real
             // `git push` — classify the command with the SAME anchored classifier as
             // `guard`, so an ordinary Bash command (even one whose ARGS contain
             // "deploy"/"release"/a ref name) is a zero-network no-op and NEVER claims a
-            // lane. A bare `git push` (no refspec) falls back to the current branch.
-            const cls = (0, guard_1.classifyCommand)((0, guard_1.commandFromPayload)(stdin));
+            // lane. A bare `git push` (no refspec) falls back to the current branch (of
+            // the RESOLVED push worktree).
+            const cls = (0, guard_1.classifyCommand)((0, guard_1.commandFromPayload)(payloadRaw));
             if (cls.kind === 'push') {
                 const cb = (0, git_1.currentBranch)(cwd);
                 refs = cls.refs.length ? cls.refs : cb ? [`refs/heads/${cb}`] : [];
@@ -162,7 +177,7 @@ async function run(opts) {
         }
         else {
             // git pre-push hook context: real refspecs arrive on stdin.
-            refs = stdin ? parseRefsFromStdin(stdin) : [];
+            refs = payloadRaw ? parseRefsFromStdin(payloadRaw) : [];
             if (!refs.length) {
                 const b = (0, git_1.currentBranch)(cwd);
                 refs = b ? [`refs/heads/${b}`] : [];
@@ -280,13 +295,26 @@ async function run(opts) {
     }
     // 200 → we hold the lane (claimed fresh or self-reclaimed). Now the COMPAT gate.
     const compat = await compatP;
-    if (compat.behind) {
-        // Behind HEAD after a fresh fetch → CONFIRMED positive → release + hard block.
+    if (compat.behind && !pushCwd.indeterminate) {
+        // Behind HEAD after a fresh fetch, against the RESOLVED push worktree →
+        // CONFIRMED positive → release + hard block.
         await api.laneRelease(slug, lane, NET_TIMEOUT_MS).catch(() => undefined);
         blockReason(`convene: BLOCKED — HEAD is behind origin/${ref.replace(/^refs\/heads\//, '')} after fetch. ` +
             `Run \`git pull --rebase\` then push again.`);
         return 2;
     }
+    if (compat.behind && pushCwd.indeterminate) {
+        // A dynamic in-command `cd` meant we could NOT resolve the pushed worktree, so
+        // this "behind" verdict may have come from an unrelated checkout. The lane IS
+        // held (the claim succeeded); keep it and ALLOW — degrade only the LOCAL
+        // freshness check to fail-open-loud rather than risk a false block (bug
+        // deff9ab9). NOTE: the committed git pre-push hook only RE-gates freshness when
+        // `convene.blockingPush` is enabled (it otherwise just posts a status), so this
+        // is a genuine skip of the freshness check, not a deferral to another gate.
+        loudOpen(`convene: deploy lane ${lane} claimed; could not resolve the push worktree from the ` +
+            `command, so the behind-HEAD freshness check was SKIPPED — proceeding UNGATED on freshness. ` +
+            `Confirm the branch is current before relying on this deploy.`);
+    }
     // Also honor a directed halt even when the lane was free (defense in depth).
     const halt = await directedHaltFor(api, slug, ref);
     if (halt) {

package/dist/commands/guard.js

@@ -1,8 +1,13 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.classifyPushRefs = classifyPushRefs;
 exports.classifyCommand = classifyCommand;
 exports.commandFromPayload = commandFromPayload;
+exports.cwdFromPayload = cwdFromPayload;
+exports.resolvePushCwd = resolvePushCwd;
 exports.guard = guard;
 /**
  * `convene guard` (WP9) — the PreToolUse halt+lane gate for Bash commands. Wired
@@ -30,6 +35,7 @@ exports.guard = guard;
  *   (b) a CONFIRMED held lane for a DEPLOY command (different instance).
  * A SOFT held-lane conflict (foreign live lane, no directed halt) → 'ask'.
  */
+const node_path_1 = __importDefault(require("node:path"));
 const git_1 = require("../git");
 const config_1 = require("../config");
 const cache_1 = require("../cache");
@@ -167,6 +173,123 @@ function commandFromPayload(raw) {
         return '';
     }
 }
+/**
+ * Pull the top-level `cwd` (the directory the tool will run in) out of a Claude
+ * Code PreToolUse payload, or null if absent/unparseable. Claude Code stamps this
+ * with the session's CURRENT working directory, which already reflects any `cd`
+ * that PERSISTED from a prior Bash call (within the project / additional dirs).
+ */
+function cwdFromPayload(raw) {
+    if (!raw)
+        return null;
+    try {
+        const j = JSON.parse(raw);
+        const c = j?.cwd;
+        return typeof c === 'string' && c.trim() ? c.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isPush(w) {
+    return w[0] === 'git' && w[1] === 'push';
+}
+/**
+ * Resolve a `cd`/`pushd` target to an absolute dir against `from`, or report it
+ * unresolvable. Strips cd option flags (`--`, `-L`, `-P`, …); rejects `-` (OLDPWD)
+ * and any dynamic/quoted/glob/`~`/escaped path — only a single literal path is safe.
+ */
+function resolveCdTarget(args, from) {
+    let rest = args;
+    while (rest.length && (rest[0] === '--' || /^-[A-Za-z]+$/.test(rest[0])))
+        rest = rest.slice(1);
+    const target = rest[0];
+    if (!target || target === '-' || rest.length > 1 || /[$*?`"'~\\]/.test(target))
+        return null;
+    return node_path_1.default.isAbsolute(target) ? target : node_path_1.default.resolve(from, target);
+}
+/**
+ * Resolve the directory a gated `git push` will run in, for the PreToolUse gate.
+ *
+ * The base is the PreToolUse payload's `cwd` (the session's current dir, already
+ * reflecting a PERSISTED `cd`), falling back to `process.cwd()` — which is also
+ * the right answer for the real git pre-push hook path, where the process cwd IS
+ * the pushed worktree. But the hook fires BEFORE the command runs, so a `cd`
+ * performed INSIDE the gated command — `(cd ../repo-release; git push origin main)`
+ * or `cd ../wt && git push` — is NOT yet reflected in `cwd`. We therefore also walk
+ * the command and apply a leading `cd`/`pushd` that precedes the push.
+ *
+ * Shell-faithful enough for the real cases: a `(` opens a SUBSHELL scope (a `cd`
+ * inside it that `)` closes BEFORE the push does not persist — `(cd X); git push`
+ * runs in the base, `(cd X; git push)` runs in X); a `cd` whose `||`/pipe RHS IS
+ * the push does not apply (the push then runs in the base); anything we cannot
+ * resolve statically (a `$var`/glob/quoted target, a bare `popd`, an over-long
+ * command) flags `indeterminate` so the caller degrades to fail-open-loud rather
+ * than trusting a guessed dir.
+ *
+ * Why this matters (bug deff9ab9): a release is routinely pushed from a SEPARATE
+ * git worktree — the one-worktree-per-session pattern Convene itself recommends.
+ * Resolving the repo from the SESSION-ROOT checkout instead of the pushed worktree
+ * made the behind-HEAD gate compare against a stale, unrelated HEAD and false-block
+ * the push.
+ */
+function resolvePushCwd(raw, command, fallback = process.cwd()) {
+    const base = cwdFromPayload(raw) ?? fallback;
+    const cmd = (command ?? '').trim();
+    if (!cmd)
+        return { dir: base, indeterminate: false };
+    // An absurdly long command is pathological (and could waste work pre-watchdog) —
+    // do not try to parse it; fail-open on the local freshness check.
+    if (cmd.length > 8192)
+        return { dir: base, indeterminate: true };
+    // Split on shell connectors, KEEPING them. `||` must precede `|` in the
+    // alternation so a single pipe never shadows it.
+    const parts = cmd.split(/(\s*&&\s*|\s*\|\|\s*|\s*;\s*|\s*\|\s*|\n)/);
+    const segs = [];
+    for (let i = 0; i < parts.length; i += 2) {
+        const rawSeg = parts[i] ?? '';
+        const open = (rawSeg.match(/^\s*\(+/)?.[0].match(/\(/g) || []).length;
+        const close = (rawSeg.match(/\)+\s*$/)?.[0].match(/\)/g) || []).length;
+        const seg = rawSeg.replace(/^[\s(]+/, '').replace(/[\s)]+$/, '');
+        const words = seg.split(/\s+/).filter(Boolean);
+        let k = 0;
+        while (k < words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[k]) || /^(sudo|command|exec|time|env)$/.test(words[k])))
+            k++;
+        segs.push({ open, close, words: words.slice(k), conn: (parts[i + 1] ?? '').trim() });
+    }
+    let dir = base;
+    let indeterminate = false;
+    const scope = []; // saved dirs at each OPEN `(` — restored when it `)` closes
+    for (let idx = 0; idx < segs.length; idx++) {
+        const s = segs[idx];
+        for (let o = 0; o < s.open; o++)
+            scope.push(dir); // enter subshell(s)
+        const w = s.words;
+        if (isPush(w))
+            break; // reached the push — `dir` is its cwd (still inside any open subshell)
+        if (w[0] === 'cd' || w[0] === 'pushd') {
+            // A pipe RHS, or a `||` RHS that IS the push, means the push does NOT run in
+            // this cd's dir (cd in a pipe is a subshell; `cd X || git push` only pushes
+            // when the cd FAILED) — leave the dir untouched. A `cd X || handler; … push`
+            // still applies (its success persists to the later push).
+            const pushIsRhs = (s.conn === '||' || s.conn === '|') && isPush(segs[idx + 1]?.words ?? []);
+            if (s.conn !== '|' && !pushIsRhs) {
+                const resolved = resolveCdTarget(w.slice(1), dir);
+                if (resolved === null)
+                    indeterminate = true;
+                else
+                    dir = resolved;
+            }
+        }
+        else if (w[0] === 'popd') {
+            indeterminate = true; // we do not model the pushd/popd stack
+        }
+        for (let c = 0; c < s.close; c++)
+            if (scope.length)
+                dir = scope.pop(); // exit subshell(s)
+    }
+    return { dir, indeterminate };
+}
 function emitJson(obj) {
     process.stdout.write(JSON.stringify(obj) + '\n');
 }

package/package.json

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