convene-cli 1.1.1 → 1.3.0

package/dist/git.js

@@ -22,6 +22,11 @@ exports.isAncestor = isAncestor;
 exports.gitFetch = gitFetch;
 exports.gitHooksDir = gitHooksDir;
 exports.gitConfigSetLocal = gitConfigSetLocal;
+exports.gitConfigUnsetLocal = gitConfigUnsetLocal;
+exports.pathIsTracked = pathIsTracked;
+exports.hasStagedChanges = hasStagedChanges;
+exports.gitAddPaths = gitAddPaths;
+exports.gitCommit = gitCommit;
 exports.gitPathIsIgnored = gitPathIsIgnored;
 /** Cross-platform git helpers. No shell strings — spawn git directly (P0-XPLAT). */
 const node_child_process_1 = require("node:child_process");
@@ -251,6 +256,74 @@ function gitConfigSetLocal(key, value, cwd = process.cwd()) {
         return false;
     }
 }
+/**
+ * Unset a repo-local git config value. Idempotent: git exits 5 when the key is
+ * absent, which we treat as success (the desired end-state is "unset").
+ */
+function gitConfigUnsetLocal(key, cwd = process.cwd()) {
+    try {
+        const r = (0, node_child_process_1.spawnSync)('git', ['config', '--local', '--unset', key], { cwd, timeout: 2500 });
+        return r.status === 0 || r.status === 5;
+    }
+    catch {
+        return false;
+    }
+}
+/** Is `relPath` tracked by git at the current index/HEAD? (a deleted-but-staged path still counts). */
+function pathIsTracked(relPath, cwd = process.cwd()) {
+    try {
+        const r = (0, node_child_process_1.spawnSync)('git', ['ls-files', '--error-unmatch', '--', relPath], { cwd, timeout: 2500 });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** True iff there are staged changes in the index (git diff --cached exits 1 when so). */
+function hasStagedChanges(cwd = process.cwd()) {
+    try {
+        const r = (0, node_child_process_1.spawnSync)('git', ['diff', '--cached', '--quiet'], { cwd, timeout: 2500 });
+        return r.status === 1;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Stage ONLY the given pathspecs (adds, modifications, AND deletions via -A), never
+ * a blanket `git add -A` of the whole tree — so an onboarding/off-board commit can
+ * never sweep in unrelated work. Returns true on success.
+ */
+function gitAddPaths(paths, cwd = process.cwd()) {
+    if (paths.length === 0)
+        return true;
+    try {
+        const r = (0, node_child_process_1.spawnSync)('git', ['add', '-A', '--', ...paths], { cwd, timeout: 5000 });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Commit ONLY the given pathspecs (`git commit -m <msg> -- <paths>`), leaving any
+ * other staged changes untouched — the isolated-commit guarantee. Returns the short
+ * SHA on success. Pass an empty `paths` to commit the current index as-is.
+ */
+function gitCommit(message, paths = [], cwd = process.cwd()) {
+    try {
+        const args = ['commit', '-m', message];
+        if (paths.length)
+            args.push('--', ...paths);
+        const r = (0, node_child_process_1.spawnSync)('git', args, { cwd, encoding: 'utf8', timeout: 5000 });
+        if (r.status !== 0)
+            return { ok: false };
+        return { ok: true, sha: shortSha('HEAD', cwd) ?? undefined };
+    }
+    catch {
+        return { ok: false };
+    }
+}
 /**
  * True iff `relPath` is ignored by git (any .gitignore / info/exclude / global
  * core.excludesfile). `check-ignore -q` exits 0 when ignored, 1 when not, 128 on

package/dist/githook.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GITHOOK_MARKER_V1 = exports.GITHOOK_MARKER = exports.GITHOOKS_DIR = void 0;
 exports.prePushScript = prePushScript;
 exports.installGitHooks = installGitHooks;
+exports.uninstallGitHooks = uninstallGitHooks;
 /**
  * Committed git pre-push hook installer — the tool-agnostic half of "enforce bus
  * posting". Unlike the Claude-only `convene fetch` UserPromptSubmit hook (hook.ts),
@@ -152,3 +153,39 @@ function installGitHooks(top) {
         return { status: 'error', message: err?.message || 'unknown error' };
     }
 }
+/**
+ * Inverse of installGitHooks (off-board). Removes `.githooks/pre-push` ONLY if it
+ * still carries our marker (never clobbers a hook someone else placed there), drops
+ * the `.githooks` dir if it empties, and unsets `core.hooksPath` ONLY when it points
+ * at our `.githooks` (a foreign hooks path is left exactly as-is). Never throws.
+ */
+function uninstallGitHooks(top) {
+    try {
+        const dir = node_path_1.default.join(top, exports.GITHOOKS_DIR);
+        const hookFile = node_path_1.default.join(dir, 'pre-push');
+        const hooksPath = (0, git_1.gitConfigGet)('core.hooksPath', top);
+        const current = node_fs_1.default.existsSync(hookFile) ? node_fs_1.default.readFileSync(hookFile, 'utf8') : null;
+        if (current !== null && !isOurHook(current)) {
+            return { status: 'skipped-foreign' };
+        }
+        let removed = false;
+        if (current !== null) {
+            node_fs_1.default.rmSync(hookFile, { force: true });
+            removed = true;
+            try {
+                if (node_fs_1.default.readdirSync(dir).length === 0)
+                    node_fs_1.default.rmdirSync(dir);
+            }
+            catch {
+                /* dir not empty or gone — fine */
+            }
+        }
+        // Only relinquish hook dispatch if WE are the ones pointing it at .githooks.
+        if (hooksPath === exports.GITHOOKS_DIR)
+            (0, git_1.gitConfigUnsetLocal)('core.hooksPath', top);
+        return { status: removed ? 'removed' : 'absent' };
+    }
+    catch (err) {
+        return { status: 'error', message: err?.message || 'unknown error' };
+    }
+}

package/dist/hook.js

@@ -14,6 +14,9 @@ exports.genericHookIsRegistered = genericHookIsRegistered;
 exports.withGenericHook = withGenericHook;
 exports.ensureHook = ensureHook;
 exports.ensureHookRegistered = ensureHookRegistered;
+exports.isConveneHookCommand = isConveneHookCommand;
+exports.withoutConveneHooks = withoutConveneHooks;
+exports.settingsIsEmpty = settingsIsEmpty;
 exports.projectSettingsPath = projectSettingsPath;
 exports.ensureProjectHookRegistered = ensureProjectHookRegistered;
 /**
@@ -188,6 +191,59 @@ function ensureHookRegistered() {
         return 'manual';
     }
 }
+// ── Hook removal (off-board / rollback) ───────────────────────────────────────
+// The inverse of withHook/withGenericHook. Every hook convene init writes invokes
+// the `convene` binary (`convene fetch`, `convene session-start`, `convene guard`,
+// `convene gate-push …`), so a single predicate identifies all of them — no need to
+// enumerate the WP13 table here. A foreign hook that merely shells out to something
+// else is never matched.
+/** A hook command is convene-authored iff it invokes the `convene` binary. */
+function isConveneHookCommand(command) {
+    return typeof command === 'string' && /^convene(\s|$)/.test(command.trim());
+}
+/**
+ * Return a new settings object (deep-clone) with every convene-authored hook
+ * removed, pruning emptied groups and emptied event arrays (and the `hooks` key
+ * itself if it ends up empty). `removed` reports whether anything was stripped.
+ * Foreign hooks and all other settings keys are preserved untouched.
+ */
+function withoutConveneHooks(settings) {
+    const next = settings ? JSON.parse(JSON.stringify(settings)) : {};
+    let removed = false;
+    const hooks = next.hooks;
+    if (hooks && typeof hooks === 'object') {
+        for (const event of Object.keys(hooks)) {
+            const groups = hooks[event];
+            if (!Array.isArray(groups))
+                continue;
+            const kept = [];
+            for (const g of groups) {
+                if (g && Array.isArray(g.hooks)) {
+                    const before = g.hooks.length;
+                    g.hooks = g.hooks.filter((h) => !isConveneHookCommand(h?.command));
+                    if (g.hooks.length !== before)
+                        removed = true;
+                    if (g.hooks.length > 0)
+                        kept.push(g); // drop a group whose hooks are all ours
+                }
+                else {
+                    kept.push(g);
+                }
+            }
+            if (kept.length > 0)
+                hooks[event] = kept;
+            else
+                delete hooks[event];
+        }
+        if (Object.keys(hooks).length === 0)
+            delete next.hooks;
+    }
+    return { settings: next, removed };
+}
+/** A settings object with no keys at all — safe to delete the file rather than write `{}`. */
+function settingsIsEmpty(settings) {
+    return !settings || Object.keys(settings).length === 0;
+}
 /** The repo's COMMITTED, shared project settings file (vs settings.local.json, which is personal/gitignored). */
 function projectSettingsPath(toplevel) {
     return node_path_1.default.join(toplevel, '.claude', 'settings.json');

package/dist/index.js

@@ -45,6 +45,7 @@ const post = __importStar(require("./commands/post"));
 const inbox_1 = require("./commands/inbox");
 const auth_1 = require("./commands/auth");
 const init_1 = require("./commands/init");
+const offboard_1 = require("./commands/offboard");
 const join_1 = require("./commands/join");
 const setup_1 = require("./commands/setup");
 const migrate_1 = require("./commands/migrate");
@@ -56,14 +57,27 @@ 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 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)')
@@ -141,6 +155,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)')
@@ -200,7 +226,8 @@ program.command('resolve <id>').description('resolve a question').action((id) =>
 program
     .command('inbox')
     .description('open questions/proposals addressed to you')
-    .option('--all-projects', 'across all your projects')
+    .option('--all-projects', 'across all your projects (deliberate cross-project view)')
+    .option('--force', 'allow --all-projects even from a repo that is not on Convene')
     .option('--project <slug>')
     .option('--json')
     .action((opts) => (0, inbox_1.inbox)(opts));
@@ -228,9 +255,24 @@ program
     .option('--no-agent-rules', 'do not write Cursor/Cline/Gemini/Aider rule files (Claude/Codex via AGENTS.md still work)')
     .option('--no-mcp', 'do not write MCP client configs (.cursor/mcp.json, .vscode/mcp.json, .codex/config.toml, Gemini)')
     .option('--force', 'commit a join token even if the repo looks public (overrides the guard)')
-    .option('--yes', 'non-interactive')
+    .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')
+    .description('cleanly remove this repo from Convene — the inverse of init (one isolated commit)')
+    .option('--yes', 'confirm non-interactively (required for agents/CI)')
+    .option('--remove-global', 'also remove the SHARED per-machine ~/.claude fetch hook (only if this is your last Convene repo)')
+    .option('--revoke-token', 'also revoke the committed join token server-side (owner-only)')
+    .option('--no-commit', 'do not create the isolated off-board commit')
+    .option('--dry-run', 'print what would change; touch nothing')
+    .action((opts) => (0, offboard_1.offboard)(opts));
 program
     .command('worktree <branch>')
     .description('create an isolated git worktree for a parallel session (one checkout per agent)')
@@ -249,7 +291,13 @@ program
     .option('--slug <slug>', 'project slug (defaults to the repo name / .convene/project.json)')
     .option('--email <email>', 'email for first-run self-provision (defaults to git user.email)')
     .option('--force', 'commit a join token even if the repo looks public')
-    .action((opts) => (0, setup_1.setup)(opts));
+    .option('--yes', 'confirm onboarding non-interactively (required for agents/CI)')
+    .option('--commit', 'commit ONLY the convene files as one isolated commit')
+    .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')
@@ -268,6 +316,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/dist/protocol.js

@@ -88,6 +88,18 @@ propose next-prompts to one another.
 
 Project: \`${slug}\` · Dashboard: ${baseUrl}/p/${slug}
 
+## Onboarding & off-boarding (a deliberate human action)
+Connecting a repo to Convene — or removing it — is a deliberate choice, never an agent
+side-effect. Onboard with \`convene setup\` (it auto-detects new-repo vs already-onboarded); an
+agent / CI run must pass \`--yes\` to confirm intent, and \`--commit\` lands the footprint as one
+isolated commit (never bundled into other work). Onboarding also **verifies your server-side
+membership before writing anything**, so a repo can't end up half-connected (local hooks that
+403 every prompt). Private repos are first-class: each repo is its OWN project, scoped to the
+members you add — the join token is committed into private repos by design. Remove a repo with
+\`convene off-board\`: it strips only convene-managed content (keeping yours), deletes the files
+convene created, unsets the hook path, and commits the removal in one shot. The per-machine
+identity in \`~/.convene/config.json\` is shared across repos and is left intact.
+
 ## Identity
 - **Member** — a durable identity (e.g. \`${'alex'}\`), human or agent.
 - **Session** — a tag \`<member>/<worktree-basename>\`, with a short \`#<id>\` suffix
@@ -205,6 +217,8 @@ convene answer <id> "<answer>"
 convene ack <id> | convene resolve <id> | convene accept <id> | convene decline <id>
 convene lanes | convene lane claim <lane> | convene lane release <lane> | convene deploy
 convene catchup | convene inbox
+convene setup [--yes] [--commit]   # onboard/connect this repo (deliberate; --yes for agents/CI)
+convene off-board [--yes] [--revoke-token] [--dry-run]   # cleanly remove this repo (inverse of init)
 \`\`\`
 `;
 }

package/package.json

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