convene-cli 1.2.0 → 1.4.0

package/dist/commands/update.js

@@ -0,0 +1,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.update = update;
+exports.runUpdate = runUpdate;
+/**
+ * `convene update` — Phase 4: check for + apply best-practices catalog updates.
+ *
+ * The repo's manifest (.convene/project.json schema 2) pins the (practice, version,
+ * level) triples it materialized against some catalog release. This command diffs
+ * that against the LIVE catalog (GET /catalog, falling back to the bundled mirror)
+ * and, on --apply, RE-MATERIALIZES the adopted practices at their CURRENT levels to
+ * the live versions — then rewrites the manifest.
+ *
+ * HARD SAFETY RAILS (the whole point of this verb):
+ *   - MAJOR-bump practices are SKIPPED unless --force (a major bump may change
+ *     behavior/enforcement; the human re-reads and re-adopts deliberately).
+ *   - DRIFTED practices (a human hand-edited the region) are SKIPPED unless --force
+ *     — update never silently overwrites a local edit.
+ *   - NEVER git add / commit / push. Changes land in the working tree; the user
+ *     reviews with `git diff` and commits.
+ *   - --auto-patch limits an UNATTENDED apply to patch-only bumps (minor/major are
+ *     left for a human even without drift).
+ *
+ * Fail-soft throughout: offline → bundled catalog; a malformed manifest or any
+ * unexpected error prints a clear note and exits non-fatally for the dry run.
+ */
+const config_1 = require("../config");
+const git_1 = require("../git");
+const api_1 = require("../api");
+const catalog_1 = require("../catalog");
+const report_1 = require("../catalog/report");
+const manifest_1 = require("../catalog/manifest");
+const materialize_1 = require("../catalog/materialize");
+const ctx_1 = require("../ctx");
+const log = (m) => process.stdout.write(m + '\n');
+/** A practice has an actual bump available to take (patch/minor/major). */
+function hasBump(row) {
+    return row.status === 'patch' || row.status === 'minor' || row.status === 'major';
+}
+/** Skipped only because it is locally edited (drift) and not forced. */
+function skipForDrift(row, opts) {
+    return hasBump(row) && row.drifted && !opts.force;
+}
+/** Skipped only because it is a major bump (and not drift-skipped) and not forced. */
+function skipForMajor(row, opts) {
+    return row.status === 'major' && !skipForDrift(row, opts) && !opts.force;
+}
+/** Skipped only because --auto-patch excludes a (non-drift, non-major) minor bump. */
+function skipForPatchGate(row, opts) {
+    return Boolean(opts.autoPatch) && row.status === 'minor' && !row.drifted && !opts.force;
+}
+/** Will this practice actually be re-materialized on apply, given the safety rails? */
+function isApplicable(row, opts) {
+    if (!hasBump(row))
+        return false; // up-to-date / removed-from-catalog → leave alone
+    if (skipForDrift(row, opts))
+        return false;
+    if (skipForMajor(row, opts))
+        return false;
+    if (skipForPatchGate(row, opts))
+        return false;
+    return true;
+}
+/** Right-pad to a fixed width for the dry-run table. */
+function pad(s, n) {
+    return s.length >= n ? s : s + ' '.repeat(n - s.length);
+}
+async function update(opts = {}) {
+    const top = (0, git_1.gitToplevel)();
+    if (!top)
+        (0, ctx_1.die)('not a git repository — run `convene update` inside a repo');
+    const manifest = (0, config_1.loadManifest)(top);
+    if (!manifest) {
+        log('· no best practices adopted — nothing to update. Run `convene init` to choose some.');
+        return;
+    }
+    // Live catalog (fail-soft → bundled). Build an authed client only if we have a
+    // key; loadCatalog itself falls back on any failure, so this never blocks.
+    const cfg = (0, config_1.resolveConfig)();
+    const api = cfg.apiKey && cfg.member ? new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, (0, git_1.sessionId)(cfg.member, top), cfg.tool) : null;
+    const { catalog, source } = await (0, catalog_1.loadCatalog)(api);
+    await runUpdate(top, manifest, catalog, source, opts);
+}
+/**
+ * Core of `convene update`, with the resolved (top, manifest, catalog) already in
+ * hand — the seam tests drive with a synthetic catalog (no fs/network resolution).
+ * Pure orchestration: dry-run reporting OR re-materialize + manifest rewrite. Never
+ * git-adds/commits. `source` only flavors the dry-run header.
+ */
+async function runUpdate(top, manifest, catalog, source, opts) {
+    const rows = classify(manifest, catalog, top);
+    const cmp = (0, manifest_1.compareToCatalog)(manifest, catalog);
+    if (!opts.apply) {
+        printDryRun(rows, cmp.repoVersion, catalog.version, source, opts);
+        return;
+    }
+    await applyUpdate(top, manifest, catalog, rows, opts);
+}
+/** Build the per-practice rows: status vs. the live catalog + drift flags. */
+function classify(manifest, catalog, top) {
+    const byId = new Map(catalog.practices.map((p) => [p.id, p]));
+    const drifted = new Set((0, materialize_1.detectDrift)(top, manifest));
+    return manifest.practices.map((entry) => {
+        const cat = byId.get(entry.id);
+        if (!cat) {
+            return {
+                id: entry.id,
+                level: entry.level,
+                manifestVersion: entry.version,
+                catalogVersion: null,
+                status: 'removed-from-catalog',
+                drifted: drifted.has(entry.id),
+            };
+        }
+        const bump = (0, manifest_1.bumpClass)(entry.version, cat.version);
+        const status = bump === 'none' ? 'up-to-date' : bump;
+        return {
+            id: entry.id,
+            level: entry.level,
+            manifestVersion: entry.version,
+            catalogVersion: cat.version,
+            status,
+            drifted: drifted.has(entry.id),
+        };
+    });
+}
+function printDryRun(rows, repoVersion, catalogVersion, source, opts) {
+    const behind = repoVersion !== catalogVersion;
+    log(behind
+        ? `Catalog update available: repo on v${repoVersion} → catalog v${catalogVersion}${source === 'bundled' ? ' (bundled — offline)' : ''}`
+        : `Best practices up to date at catalog v${repoVersion}${source === 'bundled' ? ' (bundled — offline)' : ''}`);
+    log('');
+    const idW = Math.max(8, ...rows.map((r) => r.id.length));
+    log(`  ${pad('practice', idW)}  ${pad('level', 9)}  ${pad('version', 18)}  change`);
+    for (const r of rows) {
+        const to = r.catalogVersion ?? '—';
+        const verCol = `${r.manifestVersion} → ${to}`;
+        let change;
+        switch (r.status) {
+            case 'up-to-date':
+                change = 'up to date';
+                break;
+            case 'removed-from-catalog':
+                change = 'removed from catalog (kept; update can\'t take it)';
+                break;
+            default:
+                change = `${r.status} bump`;
+        }
+        const drift = r.drifted ? '  [EDITED LOCALLY]' : '';
+        log(`  ${pad(r.id, idW)}  ${pad(r.level, 9)}  ${pad(verCol, 18)}  ${change}${drift}`);
+    }
+    log('');
+    const applicable = rows.filter((r) => isApplicable(r, opts));
+    const skippedMajor = rows.filter((r) => skipForMajor(r, opts));
+    const skippedDrift = rows.filter((r) => skipForDrift(r, opts));
+    const skippedPatchGate = rows.filter((r) => skipForPatchGate(r, opts));
+    if (applicable.length === 0 && skippedMajor.length === 0 && skippedDrift.length === 0 && skippedPatchGate.length === 0) {
+        log('Nothing to apply.');
+        return;
+    }
+    if (applicable.length) {
+        log(`${applicable.length} practice(s) would update on \`convene update --apply\`.`);
+    }
+    reportSkips(skippedMajor, skippedDrift, skippedPatchGate);
+    log('');
+    log('Next: `convene update --apply` (review with `git diff` and commit yourself — Convene never commits).');
+}
+async function applyUpdate(top, manifest, catalog, rows, opts) {
+    const byId = new Map(catalog.practices.map((p) => [p.id, p]));
+    const toUpdate = rows.filter((r) => isApplicable(r, opts));
+    const skippedMajor = rows.filter((r) => skipForMajor(r, opts));
+    const skippedDrift = rows.filter((r) => skipForDrift(r, opts));
+    const skippedPatchGate = rows.filter((r) => skipForPatchGate(r, opts));
+    const takeIds = new Set(toUpdate.map((r) => r.id));
+    if (takeIds.size === 0) {
+        log('Nothing applied — no practice was eligible.');
+        reportSkips(skippedMajor, skippedDrift, skippedPatchGate);
+        reportRemoved(rows);
+        return;
+    }
+    // PRESERVE skipped (drifted / major / patch-gated) sections byte-for-byte: snapshot
+    // their on-disk blocks BEFORE re-materializing, then splice them back afterward so
+    // a human edit or a deliberately-deferred major is never touched. (A REMOVED-from-
+    // catalog practice has no bump and isn't skipped here — it simply isn't re-rendered
+    // and its on-disk block + manifest entry both carry forward unchanged.)
+    const skippedIds = new Set([...skippedMajor, ...skippedDrift, ...skippedPatchGate].map((r) => r.id));
+    const allBlocks = (0, materialize_1.extractPracticeBlocks)(top);
+    const preserve = new Map();
+    for (const id of skippedIds) {
+        const b = allBlocks.get(id);
+        if (b)
+            preserve.set(id, b);
+    }
+    // Re-materialize every adopted practice STILL IN THE CATALOG and NOT skipped, each
+    // at its CURRENT level. This advances taken practices to the live catalog body and
+    // refreshes their enforcement artifacts (idempotent merges), while leaving the
+    // skipped + removed practices out of this render pass. `slug` is unused by the doc
+    // renderer — pass ''.
+    const renderSelections = manifest.practices
+        .filter((e) => byId.has(e.id) && !skippedIds.has(e.id))
+        .map((e) => ({ id: e.id, level: e.level }));
+    const reMaterialized = (0, materialize_1.materializePractices)(top, '', renderSelections, catalog);
+    // Splice the preserved skipped blocks back into the freshly-written doc so the
+    // managed doc stays a single coherent artifact with every adopted section present.
+    (0, materialize_1.splicePreservedBlocks)(top, preserve);
+    // Build the next manifest: fresh entry for each re-materialized practice; the
+    // verbatim OLD entry for everyone else (skipped, up-to-date, removed) — preserving
+    // their version + hash so a skipped/edited region is never re-flagged as drift.
+    const freshById = new Map(reMaterialized.map((e) => [e.id, e]));
+    const nextPractices = manifest.practices.map((old) => freshById.get(old.id) ?? old);
+    const nextManifest = {
+        catalogVersion: catalog.version,
+        channel: manifest.channel,
+        practices: nextPractices,
+    };
+    (0, config_1.writeManifest)(top, nextManifest);
+    // Phase 5: report the freshly-rewritten manifest so the dashboard's adoption
+    // view tracks the update. Best-effort, fail-OPEN, fire-and-forget — `--apply`
+    // never fails/slows because the report failed; skipped silently with no api key.
+    const slug = opts.project || (0, config_1.loadProjectConfig)(top)?.slug;
+    if (slug)
+        await (0, report_1.reportManifest)(top, slug, nextManifest);
+    log(`✓ updated ${takeIds.size} practice(s); manifest catalog version → v${catalog.version}.`);
+    for (const r of toUpdate) {
+        log(`    ${r.id}: v${r.manifestVersion} → v${r.catalogVersion} [${r.level}]`);
+    }
+    reportSkips(skippedMajor, skippedDrift, skippedPatchGate);
+    reportRemoved(rows);
+    log('');
+    log('Changes are in your working tree only. Review with `git diff` and commit yourself — Convene never commits.');
+}
+/** Note any adopted practices the catalog no longer ships — kept, never auto-dropped. */
+function reportRemoved(rows) {
+    const removed = rows.filter((r) => r.status === 'removed-from-catalog');
+    if (removed.length) {
+        log(`  ${removed.length} practice(s) removed from the catalog — kept as-is (update can't take them): ${removed.map((r) => r.id).join(', ')}`);
+    }
+}
+function reportSkips(skippedMajor, skippedDrift, skippedPatchGate) {
+    if (skippedMajor.length) {
+        log(`  skipped ${skippedMajor.length} MAJOR bump(s) (re-run with --force to take): ${skippedMajor.map((r) => r.id).join(', ')}`);
+    }
+    if (skippedDrift.length) {
+        log(`  skipped ${skippedDrift.length} locally-EDITED practice(s) (your edits preserved; --force to overwrite): ${skippedDrift.map((r) => r.id).join(', ')}`);
+    }
+    if (skippedPatchGate.length) {
+        log(`  skipped ${skippedPatchGate.length} minor/major bump(s) under --auto-patch (run \`convene update --apply\` without --auto-patch): ${skippedPatchGate.map((r) => r.id).join(', ')}`);
+    }
+}

package/dist/config.js

@@ -12,6 +12,8 @@ exports.resolveConfig = resolveConfig;
 exports.ensureConfigDir = ensureConfigDir;
 exports.saveFileConfig = saveFileConfig;
 exports.writeProjectConfig = writeProjectConfig;
+exports.loadManifest = loadManifest;
+exports.writeManifest = writeManifest;
 /**
  * Config resolution with precedence:
  *   env (CONVENE_API_KEY, CONVENE_BASE_URL, CONVENE_MEMBER, ...)
@@ -96,6 +98,22 @@ function writeProjectConfig(toplevel, cfg) {
     const dir = node_path_1.default.join(toplevel, '.convene');
     node_fs_1.default.mkdirSync(dir, { recursive: true });
     const file = node_path_1.default.join(dir, 'project.json');
-    node_fs_1.default.writeFileSync(file, JSON.stringify({ schema: 1, ...cfg }, null, 2) + '\n');
+    // schema 2 ONLY once a best-practices manifest is present; plain onboarding
+    // stays at schema 1 (byte-identical to pre-catalog output).
+    const schema = cfg.bestPractices ? 2 : 1;
+    node_fs_1.default.writeFileSync(file, JSON.stringify({ schema, ...cfg }, null, 2) + '\n');
     return file;
 }
+/** The adopted best-practices manifest for a repo, or null if none/absent. */
+function loadManifest(toplevel) {
+    return loadProjectConfig(toplevel)?.bestPractices ?? null;
+}
+/**
+ * Merge a best-practices manifest into the repo's project.json, preserving
+ * slug/displayName/joinToken and bumping it to schema 2. Round-trip safe.
+ */
+function writeManifest(toplevel, manifest) {
+    const existing = loadProjectConfig(toplevel) ?? {};
+    const { schema: _schema, ...rest } = existing;
+    return writeProjectConfig(toplevel, { ...rest, bestPractices: manifest });
+}

package/dist/index.js

@@ -57,14 +57,28 @@ const lane_1 = require("./commands/lane");
 const deploy_1 = require("./commands/deploy");
 const guard_1 = require("./commands/guard");
 const gate_push_1 = require("./commands/gate-push");
+const practice_guard_1 = require("./commands/practice-guard");
+const override_1 = require("./commands/override");
 const watch_1 = require("./commands/watch");
 const explain_1 = require("./commands/explain");
+const practices_1 = require("./commands/practices");
+const update_1 = require("./commands/update");
 const program = new commander_1.Command();
 // Read the version from package.json so `convene --version` always tracks the
 // published version (npm includes package.json in the tarball). dist/index.js
 // sits one level below package.json; in dev (tsx) src/index.ts does too.
 const { version } = JSON.parse((0, fs_1.readFileSync)((0, path_1.resolve)(__dirname, '../package.json'), 'utf8'));
 program.name(brand_1.BRAND.bin).description('Convene — AI development coordination bus').version(version);
+/**
+ * Commander maps `--no-practices` to `practices: false`; the catalog selection logic
+ * reads `noPractices`. Translate it (leaving every other option untouched) so init /
+ * setup see the field they expect.
+ */
+function withPracticeOpts(opts) {
+    if (opts.practices === false)
+        opts.noPractices = true;
+    return opts;
+}
 program
     .command('login')
     .description('authenticate and save config (0600)')
@@ -142,6 +156,18 @@ program
     .option('--dry-run', 'classify + report; do not gate or hit the network for the verdict')
     .option('--project <slug>')
     .action((opts) => (0, gate_push_1.gatePush)(opts));
+program
+    .command('practice-guard <id>')
+    .description('PreToolUse/Stop hook: level-aware best-practice gate (fail-open-loud)')
+    .option('--stdin', 'read the PreToolUse JSON payload from stdin')
+    .option('--project <slug>')
+    .action((id, opts) => (0, practice_guard_1.practiceGuard)(id, opts));
+program
+    .command('override <id>')
+    .description('grant a short-lived, attributed bypass for a best-practice gate')
+    .option('--reason <text>', 'why the gate is being overridden (required; attributed to the bus)')
+    .option('--project <slug>')
+    .action((id, opts) => (0, override_1.override)(id, opts));
 program
     .command('watch')
     .description('SessionStart-launched detached long-poll for directed halts (fail-open, self-healing)')
@@ -210,6 +236,10 @@ program
     .command('explain [question]')
     .description('ask how Convene itself works (protocol, lanes, halts, privacy, …) — fail-soft, public')
     .action((question) => (0, explain_1.explain)(question));
+program
+    .command('practices [id]')
+    .description('learn the best practices: list adopted + available, or pass an id for the why + sources')
+    .action((id) => (0, practices_1.practices)(id));
 program
     .command('suggest <text>')
     .description('send a feature request / bug report / feedback into Convene')
@@ -233,7 +263,11 @@ program
     .option('--yes', 'confirm onboarding non-interactively (required for agents/CI)')
     .option('--commit', 'commit ONLY the convene files as one isolated commit (never `git add -A`)')
     .option('--offline', 'write local files only (no API calls)')
-    .action((opts) => (0, init_1.init)(opts));
+    .option('--tier <names>', 'best practices: comma-separated tiers to adopt (essentials,recommended,advanced)')
+    .option('--practice <id[=level]>', 'best practice to adopt (id or id=level; repeatable)', (v, acc) => (acc.push(v), acc), [])
+    .option('--all-practices', 'adopt every catalog best practice at its default level')
+    .option('--no-practices', 'adopt no best practices (skip the catalog + interactive picker)')
+    .action((opts) => (0, init_1.init)(withPracticeOpts(opts)));
 program
     .command('off-board')
     .alias('offboard')
@@ -264,7 +298,11 @@ program
     .option('--force', 'commit a join token even if the repo looks public')
     .option('--yes', 'confirm onboarding non-interactively (required for agents/CI)')
     .option('--commit', 'commit ONLY the convene files as one isolated commit')
-    .action((opts) => (0, setup_1.setup)(opts));
+    .option('--tier <names>', 'best practices: comma-separated tiers to adopt (essentials,recommended,advanced)')
+    .option('--practice <id[=level]>', 'best practice to adopt (id or id=level; repeatable)', (v, acc) => (acc.push(v), acc), [])
+    .option('--all-practices', 'adopt every catalog best practice at its default level')
+    .option('--no-practices', 'adopt no best practices (skip the catalog + interactive picker)')
+    .action((opts) => (0, setup_1.setup)(withPracticeOpts(opts)));
 program
     .command('join')
     .description('self-provision: redeem a project join token for your own key + hook')
@@ -283,6 +321,14 @@ program
     .option('--yes')
     .option('--offline')
     .action((opts) => (0, migrate_1.migrate)(opts));
+program
+    .command('update')
+    .description('check for + apply best-practices catalog updates (review in your working tree; never auto-commits)')
+    .option('--apply', 're-materialize adopted practices to the live catalog (default: dry run)')
+    .option('--auto-patch', 'limit an unattended --apply to patch-only bumps')
+    .option('--force', 're-materialize MAJOR bumps and locally-edited (drifted) practices too')
+    .option('--project <slug>', 'project slug (defaults to .convene/project.json)')
+    .action((opts) => (0, update_1.update)(opts));
 program.command('doctor').description('diagnose setup').option('--fix', 'attempt safe fixes').action((opts) => (0, auth_1.doctor)(opts));
 program.parseAsync(process.argv).catch((err) => {
     process.stderr.write(`convene: ${err?.message || err}\n`);

package/package.json

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