convene-cli 1.2.0 → 1.4.0

package/dist/api.js

@@ -149,6 +149,29 @@ class ConveneApi {
     getProject(slug, timeoutMs) {
         return this.request('GET', `/projects/${encodeURIComponent(slug)}`, { timeoutMs });
     }
+    /**
+     * POST /projects/:slug/best-practices — report the adopted best-practices
+     * manifest so the dashboard can show per-project adoption (Phase 5). PURELY
+     * for observability: ALWAYS best-effort / fail-open. The shared `request`
+     * already never throws (it returns `ok:false` on a network error / timeout),
+     * so the call sites can fire-and-forget. Bounded by an explicit short timeout
+     * — onboarding / update must never slow down because the report is slow.
+     */
+    reportBestPractices(slug, manifest, timeoutMs) {
+        return this.request('POST', `/projects/${encodeURIComponent(slug)}/best-practices`, {
+            body: { manifest },
+            timeoutMs,
+        });
+    }
+    /**
+     * 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.
+     */
+    getCatalog(timeoutMs) {
+        return this.request('GET', '/catalog', { timeoutMs });
+    }
     // ── Catch-up / session-open (WP2) ──────────────────────────────────────────
     /**
      * GET /session-open — the "open already knowing the world" digest. `advance`

package/dist/cache.js

@@ -3,10 +3,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeWatchHighWater = void 0;
+exports.OVERRIDE_TTL_MS = exports.writeWatchHighWater = void 0;
 exports.readCache = readCache;
 exports.writeCache = writeCache;
 exports.ageSeconds = ageSeconds;
+exports.readCatalogVersion = readCatalogVersion;
+exports.writeCatalogVersion = writeCatalogVersion;
 exports.readSessionInstance = readSessionInstance;
 exports.mintSessionInstance = mintSessionInstance;
 exports.ensureSessionInstance = ensureSessionInstance;
@@ -20,6 +22,8 @@ exports.appendWatch = appendWatch;
 exports.readWatchSince = readWatchSince;
 exports.touchWatchHeartbeat = touchWatchHeartbeat;
 exports.watchHeartbeatAgeSec = watchHeartbeatAgeSec;
+exports.writeOverrideToken = writeOverrideToken;
+exports.readLiveOverrideToken = readLiveOverrideToken;
 /**
  * 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
@@ -63,6 +67,33 @@ function writeCache(slug, data) {
 function ageSeconds(entry) {
     return Math.max(0, Math.round((Date.now() - entry.fetchedAt) / 1000));
 }
+function catalogVersionFile() {
+    return node_path_1.default.join(config_1.CACHE_DIR, 'catalog-version.json');
+}
+/** The cached live catalog version if present AND within `ttlSec`, else null. */
+function readCatalogVersion(ttlSec) {
+    try {
+        const e = JSON.parse(node_fs_1.default.readFileSync(catalogVersionFile(), 'utf8'));
+        if (!e || typeof e.version !== 'string' || typeof e.fetchedAt !== 'number')
+            return null;
+        if ((Date.now() - e.fetchedAt) / 1000 >= ttlSec)
+            return null;
+        return e.version || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist the live catalog version (best-effort; never throws). */
+function writeCatalogVersion(version) {
+    try {
+        node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
+        node_fs_1.default.writeFileSync(catalogVersionFile(), JSON.stringify({ fetchedAt: Date.now(), version }), { mode: 0o600 });
+    }
+    catch {
+        /* best-effort */
+    }
+}
 // ── session-instance id (WP2) ────────────────────────────────────────────────
 // An opaque per-session UUID minted at SessionStart and persisted in CACHE_DIR.
 // Sent as X-Convene-Session-Instance so the server can stamp holder_instance and
@@ -296,3 +327,54 @@ function watchHeartbeatAgeSec(slug) {
         return null;
     }
 }
+// ── best-practice override token (Phase 3) ───────────────────────────────────
+// `convene override <id> --reason …` writes a short-TTL, expiry-based token that
+// `convene practice-guard <id>` honors → ALLOW. The token is purely LOCAL state
+// (the bus status post is informational/attribution, never the gate's source of
+// truth) and SESSION-SCOPED via `scoped()` so one session's override does not
+// silently lift the gate for a sibling session sharing the checkout. Keyed by
+// (slug,id). Expiry-based: honored repeatedly until it expires (the simplest
+// correct semantics — a brief, attributed window, not a single-shot counter).
+function overrideFile(slug, id) {
+    const key = `${scoped(slug)}__bp-override__${id}`.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return node_path_1.default.join(config_1.CACHE_DIR, `${key}.json`);
+}
+/** Default override window — short on purpose (a deliberate, brief bypass). */
+exports.OVERRIDE_TTL_MS = 5 * 60 * 1000;
+/** Write an expiry-based override token for (slug,id). Best-effort; throws never. */
+function writeOverrideToken(slug, id, reason, ttlMs = exports.OVERRIDE_TTL_MS) {
+    const tok = { slug, id, reason, expiresAt: Date.now() + ttlMs };
+    try {
+        node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
+        node_fs_1.default.writeFileSync(overrideFile(slug, id), JSON.stringify(tok), { mode: 0o600 });
+    }
+    catch {
+        /* best-effort; the caller still reports the in-memory token */
+    }
+    return tok;
+}
+/**
+ * Return a LIVE (unexpired) override token for (slug,id), or null. An expired or
+ * malformed token is treated as absent AND opportunistically removed so a stale
+ * file can never resurrect a gate bypass.
+ */
+function readLiveOverrideToken(slug, id) {
+    const file = overrideFile(slug, id);
+    let tok;
+    try {
+        tok = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (!tok || typeof tok.expiresAt !== 'number' || !Number.isFinite(tok.expiresAt) || Date.now() >= tok.expiresAt) {
+        try {
+            node_fs_1.default.unlinkSync(file);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        return null;
+    }
+    return tok;
+}