convene-cli 1.13.0 → 1.13.1

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convene-cli",
-  "version": "1.13.0",
+  "version": "1.13.1",
   "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",