convene-cli 1.4.1 → 1.4.3

package/dist/commands/init.js

@@ -8,6 +8,7 @@ exports.upsertMarkerBlock = upsertMarkerBlock;
 exports.removeMarkerBlock = removeMarkerBlock;
 exports.removeGitignoreGuard = removeGitignoreGuard;
 exports.removeTomlBlock = removeTomlBlock;
+exports.refreshDocs = refreshDocs;
 exports.init = init;
 /**
  * `convene init` — one-command repo onboarding. IDEMPOTENT + merge-safe
@@ -520,10 +521,111 @@ async function adoptBestPractices(top, slug, opts) {
             log('· reported adoption to the dashboard');
     }
 }
+/**
+ * Re-render the managed COORDINATION blocks (CLAUDE.md + AGENTS.md) at the current
+ * template. Pure per file (P0-IDEMPOTENT). The two blocks intentionally diverge:
+ * CLAUDE.md (conveneBlock) omits the manual-deploy line (its PreToolUse hook gates
+ * deploys); AGENTS.md (conveneAgentsBlock) adds it for tools with no in-time gate.
+ * upsertMarkerBlock preserves everything OUTSIDE the markers.
+ */
+function writeCoordinationBlocks(top, slug, member, baseUrl) {
+    const fileBlocks = [
+        ['CLAUDE.md', (0, protocol_1.conveneBlock)(slug, member, baseUrl)],
+        ['AGENTS.md', (0, protocol_1.conveneAgentsBlock)(slug, member, baseUrl)],
+    ];
+    for (const [fname, block] of fileBlocks) {
+        const file = node_path_1.default.join(top, fname);
+        const old = node_fs_1.default.existsSync(file) ? node_fs_1.default.readFileSync(file, 'utf8') : '';
+        const result = writeIfChanged(file, upsertMarkerBlock(old, block));
+        const note = result === 'created'
+            ? 'created — Convene block added'
+            : result === 'updated'
+                ? 'merged — your content preserved'
+                : 'unchanged';
+        log(`${result === 'unchanged' ? '·' : '✓'} ${fname} (${note})`);
+    }
+}
+/**
+ * Stage + commit ONLY the convene files (CONVENE_PATHS) as one isolated commit —
+ * never `git add -A`, so convene changes are never bundled into unrelated work.
+ * Shared by `convene init --commit` and `convene init --refresh-docs --commit`.
+ */
+function commitConveneFiles(top, message, label) {
+    const paths = exports.CONVENE_PATHS.filter((p) => node_fs_1.default.existsSync(node_path_1.default.join(top, p)));
+    if (!paths.length)
+        return;
+    // Decide up front whether anything under the managed paths is actually pending
+    // (staged/unstaged/untracked). This makes `--commit` deterministic and TRANSPARENT:
+    // a clean re-render says "already up to date" instead of a vague no-op, and a tree
+    // dirtied by an EARLIER `--refresh-docs` (without `--commit`) still gets committed
+    // — the gotcha that previously left changes stranded.
+    const pending = (0, git_1.gitPendingPaths)(paths, top);
+    if (!pending.length) {
+        log(`· ${label}: managed files already committed — nothing to commit.`);
+        return;
+    }
+    if (!(0, git_1.gitAddPaths)(paths, top)) {
+        log('⚠ could not stage the convene files — commit them manually.');
+        return;
+    }
+    const res = (0, git_1.gitCommit)(message, paths, top);
+    if (res.ok) {
+        log(`✓ committed ${label} as one isolated commit${res.sha ? ` (${res.sha})` : ''} — ${pending.length} convene file(s) staged, nothing else.`);
+    }
+    else {
+        // pending changes existed but the commit did not land — never silent.
+        log(`⚠ ${pending.length} convene file(s) are staged but the commit did not land — commit them manually (\`git commit\`).`);
+    }
+}
+/**
+ * `convene init --refresh-docs` — re-render the managed DOC surfaces (CLAUDE.md +
+ * AGENTS.md coordination blocks, the cross-agent rule files, and the MCP client
+ * configs) at the CURRENT CLI template, for a repo that is ALREADY on Convene.
+ *
+ * This is the propagation path init/setup lacked: `convene setup` on an already-
+ * onboarded repo only re-confirms identity, so improvements to the block templates
+ * (e.g. the connect-line in protocol.ts) never reached existing repos. Refresh fixes
+ * that with NO network/identity work — every template is a pure function of
+ * (slug, member, baseUrl), all read from local config — so it is byte-idempotent.
+ * Best-practice CONTENT is intentionally NOT touched here (that is `convene update`'s
+ * job: versioned + consented), and CONVENE_PROTOCOL.md is left as-is (write-if-absent
+ * / hand-enrichable), same as init.
+ */
+async function refreshDocs(opts) {
+    const top = (0, git_1.gitToplevel)();
+    if (!top)
+        (0, ctx_1.die)('not a git repository — run `convene init --refresh-docs` inside a repo');
+    const existing = (0, config_1.loadProjectConfig)(top);
+    if (!existing?.slug) {
+        (0, ctx_1.die)('this repo is not on Convene yet — run `convene setup` first; `--refresh-docs` only re-renders an already-onboarded repo.');
+    }
+    const cfg = (0, config_1.resolveConfig)();
+    const slug = existing.slug;
+    const member = cfg.member;
+    const baseUrl = cfg.baseUrl;
+    const skipAgentRules = opts.noAgentRules === true || opts.agentRules === false;
+    const skipMcp = opts.noMcp === true || opts.mcp === false;
+    log(`Refreshing Convene managed blocks for "${slug}" at the current template (no identity/network changes)…`);
+    writeCoordinationBlocks(top, slug, member, baseUrl);
+    if (!skipAgentRules)
+        writeAgentRules(top, slug, member, baseUrl);
+    if (!skipMcp)
+        writeMcpConfigs(top, baseUrl);
+    if (opts.commit)
+        commitConveneFiles(top, 'Refresh Convene managed blocks to current template', 'the refresh');
+    log('');
+    log('Done — managed blocks re-rendered. Your content outside the convene markers is untouched.');
+    log('(Best-practice content is managed separately — run `convene update` to take catalog changes.)');
+}
 async function init(opts) {
     const top = (0, git_1.gitToplevel)();
     if (!top)
         (0, ctx_1.die)('not a git repository — run `convene init` inside a repo');
+    // `--refresh-docs` is a re-render of an already-onboarded repo's managed blocks —
+    // not onboarding. It needs no consent gate / identity / network, so short-circuit
+    // here, before all of that.
+    if (opts.refreshDocs)
+        return refreshDocs(opts);
     // Consent gate: onboarding writes a footprint and registers per-prompt hooks — it
     // must be a DELIBERATE choice, never an accidental side-effect. A human at a
     // terminal (TTY) confirms simply by running it; an agent / CI (no TTY) must pass
@@ -658,21 +760,7 @@ async function init(opts) {
     //    gates deploys), AGENTS.md uses conveneAgentsBlock (adds the explicit
     //    `convene deploy` line for tools with no in-time gate). Each is PURE, so a
     //    re-run is byte-identical per file (P0-IDEMPOTENT).
-    const fileBlocks = [
-        ['CLAUDE.md', (0, protocol_1.conveneBlock)(slug, member, baseUrl)],
-        ['AGENTS.md', (0, protocol_1.conveneAgentsBlock)(slug, member, baseUrl)],
-    ];
-    for (const [fname, block] of fileBlocks) {
-        const file = node_path_1.default.join(top, fname);
-        const old = node_fs_1.default.existsSync(file) ? node_fs_1.default.readFileSync(file, 'utf8') : '';
-        const result = writeIfChanged(file, upsertMarkerBlock(old, block));
-        const note = result === 'created'
-            ? 'created — Convene block added'
-            : result === 'updated'
-                ? 'merged — your content preserved'
-                : 'unchanged';
-        log(`${result === 'unchanged' ? '·' : '✓'} ${fname} (${note})`);
-    }
+    writeCoordinationBlocks(top, slug, member, baseUrl);
     // 6. portable protocol doc — write only if ABSENT (mirrors the memory-seed
     //    pattern). The doc is hand-enrichable; unconditionally overwriting it with
     //    the generated stub would clobber any teammate's expanded protocol spec.
@@ -750,19 +838,8 @@ async function init(opts) {
     // 8a. optional isolated commit — stage ONLY the convene files (never `git add -A`),
     //     so onboarding can never be bundled into unrelated work (the VAcontractorCo
     //     entangled-commit failure). Off by default; `--commit` opts in.
-    if (opts.commit) {
-        const paths = exports.CONVENE_PATHS.filter((p) => node_fs_1.default.existsSync(node_path_1.default.join(top, p)));
-        if (paths.length && (0, git_1.gitAddPaths)(paths, top)) {
-            const res = (0, git_1.gitCommit)('Onboard onto Convene coordination bus', paths, top);
-            if (res.ok)
-                log(`✓ committed onboarding as one isolated commit${res.sha ? ` (${res.sha})` : ''} — only the convene files were staged.`);
-            else
-                log('· nothing committed (no staged changes).');
-        }
-        else if (paths.length) {
-            log('⚠ could not stage the convene files — commit them manually.');
-        }
-    }
+    if (opts.commit)
+        commitConveneFiles(top, 'Onboard onto Convene coordination bus', 'onboarding');
     // 9. teammate one-liner
     log('');
     log(`Done. Project "${slug}" — dashboard: ${baseUrl}/p/${slug}`);

package/dist/git.js

@@ -26,6 +26,7 @@ exports.gitConfigUnsetLocal = gitConfigUnsetLocal;
 exports.pathIsTracked = pathIsTracked;
 exports.hasStagedChanges = hasStagedChanges;
 exports.gitAddPaths = gitAddPaths;
+exports.gitPendingPaths = gitPendingPaths;
 exports.gitCommit = gitCommit;
 exports.gitPathIsIgnored = gitPathIsIgnored;
 /** Cross-platform git helpers. No shell strings — spawn git directly (P0-XPLAT). */
@@ -305,6 +306,30 @@ function gitAddPaths(paths, cwd = process.cwd()) {
         return false;
     }
 }
+/**
+ * The subset of `paths` that have PENDING changes (staged, unstaged, or untracked),
+ * via `git status --porcelain -- <paths>`. Lets a caller decide whether there is
+ * anything to commit BEFORE running `git commit` — so an isolated-commit helper can
+ * say "already up to date" plainly instead of relying on a non-zero `git commit`
+ * exit. Returns [] on any error / clean tree (never throws).
+ */
+function gitPendingPaths(paths, cwd = process.cwd()) {
+    if (paths.length === 0)
+        return [];
+    try {
+        const r = (0, node_child_process_1.spawnSync)('git', ['status', '--porcelain', '--', ...paths], { cwd, encoding: 'utf8', timeout: 5000 });
+        if (r.status !== 0 || !r.stdout)
+            return [];
+        // Porcelain v1 line: "XY <path>"; we only need the count/names, not the status.
+        return r.stdout
+            .split('\n')
+            .map((l) => l.slice(3).trim())
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * Commit ONLY the given pathspecs (`git commit -m <msg> -- <paths>`), leaving any
  * other staged changes untouched — the isolated-commit guarantee. Returns the short

package/dist/index.js

@@ -263,6 +263,7 @@ 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)')
+    .option('--refresh-docs', 're-render the managed CLAUDE.md/AGENTS.md blocks + agent rules + MCP configs at the current template (already-onboarded repos; no identity/network changes)')
     .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')

package/dist/protocol.js

@@ -31,7 +31,7 @@ function block(flavor, slug, member, baseUrl) {
         `This repo is on **Convene** — a tool-agnostic AI development coordination bus — as project \`${slug}\`.`,
         `Dashboard: ${baseUrl}/p/${slug}`,
         '',
-        `> **Not connected on this machine?** Paste this one line into your Claude Code **or** Codex session: *"Connect me to Convene for this repo: run \`npm i -g convene-cli@latest\`, then \`convene setup\` and follow the prompts, then \`convene doctor\`."* — or run those yourself, or fetch ${baseUrl}/start and follow it. One time per machine; both tools are then wired automatically.`,
+        `> **Asked to get set up / "up and running" with Convene on this machine?** Run these three: \`npm i -g convene-cli@latest\` → \`convene setup\` (follow the prompts) → \`convene doctor\`. One time per machine; wires Claude Code **and** Codex. Already connected? \`convene doctor\` confirms it. Detail: ${baseUrl}/start.`,
         '',
         'Each turn you get a `<convene-channel>` block — a health line, open items addressed to you, and',
         'recent activity. (Claude Code injects it via the `convene fetch` UserPromptSubmit hook; with other',

package/package.json

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