@event4u/agent-config 8.1.0 → 8.3.0

package/src/scripts/_cli/cmd_uninstall.ts

@@ -55,6 +55,7 @@
  */
 
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -62,6 +63,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as fs_atomic from '../_lib/fs_atomic.js';
 import * as installed_lock from '../_lib/installed_lock.js';
 import * as installed_tools from '../_lib/installed_tools.js';
+import { remove_managed_hooks } from '../_lib/claude_settings_hooks.js';
 import { resolve_project_root } from '../_lib/agent_settings.js';
 import { subtract_pointers } from '../_lib/json_pointers.js';
 import { PROJECT_BRIDGE_MARKERS, USER_SCOPE_PATHS } from '../install.js';
@@ -771,6 +773,26 @@ function _uninstall_global(opts: Options): number {
             removed_names.push(tool);
         }
     }
+    // Managed Claude hooks live in ~/.claude/settings.json (single-surface
+    // model) — remove exactly our entries, never user-owned ones.
+    if (tools.includes('claude-code')) {
+        const settings_path = path.join(os.homedir(), '.claude', 'settings.json');
+        if (opts.dry_run) {
+            _print(_stdout, `  · claude-code: would remove managed hooks from ${settings_path}`);
+        } else {
+            try {
+                const res = remove_managed_hooks(settings_path);
+                if (res.changed) {
+                    _print(
+                        _stdout,
+                        `  · claude-code: removed managed hooks (${res.events.join(', ')})`,
+                    );
+                }
+            } catch (e) {
+                _print(_stderr, `⚠️  claude-code: managed-hook removal skipped — ${String(e)}`);
+            }
+        }
+    }
     if (lock !== null && !opts.dry_run) {
         const remaining = (lock.tools ?? []).filter((t) => !tools.includes(t));
         const version = String((lock as unknown as AnyDict)['agent_config_version'] ?? '');
@@ -817,10 +839,29 @@ export function main(argv: string[] | null = null): number {
 
 // CLI entry guard — set process.exitCode; never call process.exit().
 const _HERE = fileURLToPath(import.meta.url);
-const _isCliEntry =
-    process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-if (_isCliEntry || process.argv[1] === _HERE) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
     try {
         process.exitCode = main(process.argv.slice(2));
     } catch (exc) {

package/src/scripts/_cli/cmd_update.ts

@@ -567,10 +567,29 @@ function _detect_installed_version(): string {
 }
 
 // CLI entry guard — set process.exitCode; never call process.exit().
-const _isCliEntry =
-    process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-if (_isCliEntry || process.argv[1] === _HERE) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
     main(process.argv.slice(2))
         .then((code) => {
             process.exitCode = code;

package/src/scripts/_cli/cmd_upgrade.ts

@@ -20,9 +20,27 @@
  *
  * 1. `npm install -g @event4u/agent-config@latest` — refresh the global binary
  *    on PATH (the binary the Claude plugin hook resolves).
- * 2. `agent-config global` (→ `install.py --global`) — refresh the global root
- *    (`~/.event4u/agent-config/`) + regenerate plugin hooks.
- * 3. If run from inside a consumer project that already has a `./agent-config`
+ * 2. `agent-config global --no-ui` (→ `install --global`) — refresh the global
+ *    root (`~/.event4u/agent-config/`) + regenerate plugin hooks. `--no-ui`
+ *    suppresses the setup-wizard auto-launch: the wizard is an onboarding
+ *    surface, not an upgrade step, and a foreground wizard server would block
+ *    the remaining upgrade steps until Ctrl-C (which then failed the run).
+ * 2b. When the Claude Code plugin (`agent-config@event4u-agent-config`) is
+ *    installed, refresh it: `claude plugin marketplace update` +
+ *    `claude plugin update` — otherwise the plugin snapshot stays pinned to
+ *    its install-time git SHA and its command surface silently rots while
+ *    the file projection moves ahead. Non-fatal: a refresh failure warns and
+ *    names the manual commands. The plugin is OPTIONAL — the file projection
+ *    is a full install on its own; no plugin → no step, no nag.
+ * 3. `agent-config settings:sync --path <file>` for every EXISTING settings
+ *    file (global `~/.event4u/agent-config/settings/.agent-settings.yml`,
+ *    then the project settings when run inside a consumer project) — additive
+ *    merge that inserts keys the new release added to the template while
+ *    preserving user lines verbatim. Runs as a subprocess of the freshly
+ *    installed binary so the NEW template is the merge source. Non-fatal:
+ *    a sync failure warns and names the manual command, never fails the
+ *    upgrade. Never creates a settings file that did not exist.
+ * 4. If run from inside a consumer project that already has a `./agent-config`
  *    wrapper, re-stamp that wrapper from the canonical template.
  *
  * Flags:
@@ -71,6 +89,9 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as installed_lock from '../_lib/installed_lock.js';
 import * as update_check from '../_lib/update_check.js';
 import * as cli_wrapper from '../_lib/cli_wrapper.js';
+import * as claude_plugin from '../_lib/claude_plugin.js';
+import { event4u_root } from '../_lib/user_global_paths.js';
+import { project_settings_path } from '../_lib/agent_settings.js';
 import { _is_source_repo } from './cmd_refresh.js';
 
 const PACKAGE_NAME = '@event4u/agent-config';
@@ -219,6 +240,170 @@ function _maybe_refresh_project_wrapper(project_root: string, out: OutSink, _err
     }
 }
 
+/**
+ * Refresh the consumer's installed `.git/hooks/pre-commit` gate after a
+ * global upgrade — but only when the hook is OURS (identified by the
+ * `pre-commit-roadmap-progress` marker) and only when run from inside a
+ * project that has it. Without this, a hook installed under an older
+ * release keeps running the old template forever (`hooks:install` without
+ * `--force` short-circuits on the marker) — the py2ts-era hooks silently
+ * no-op'd for exactly this reason. Non-fatal: a failure warns and names
+ * the manual command.
+ */
+function _maybe_refresh_git_hook(
+    project_root: string,
+    runner: (cmd: string[]) => number,
+    out: OutSink,
+    err: OutSink,
+): void {
+    const hook = path.join(project_root, '.git', 'hooks', 'pre-commit');
+    let text: string;
+    try {
+        text = fs.readFileSync(hook, 'utf-8');
+    } catch {
+        return; // no hook installed (or worktree indirection) — nothing to refresh
+    }
+    if (!text.includes('pre-commit-roadmap-progress')) {
+        return; // not our hook — never overwrite a foreign pre-commit
+    }
+    const cmd = [_agent_config_bin(), 'hooks:install', '--force'];
+    _print(out, '→ ' + cmd.join(' '));
+    let rc: number;
+    try {
+        rc = runner(cmd);
+    } catch (exc) {
+        rc = 127;
+        _print(err, `cannot run ${cmd[0]}: ${osErrorStr(exc)}`);
+    }
+    if (rc !== 0) {
+        _print(
+            err,
+            `⚠️  agent-config upgrade: pre-commit hook refresh failed (exit ${rc}) — ` +
+                'run `agent-config hooks:install --force` manually.',
+        );
+    }
+}
+
+/**
+ * Existing settings files the post-upgrade sync should bring up to the new
+ * template (additive merge — user lines preserved verbatim, only missing
+ * template keys inserted; see `sync_agent_settings.ts`).
+ *
+ * Targets, in order:
+ *  1. Global settings — `~/.event4u/agent-config/settings/.agent-settings.yml`
+ *     (the canonical wizard-written file; `EVENT4U_CONFIG_HOME` honored).
+ *  2. Project settings — the project's read-path settings file when the
+ *     upgrade runs inside a consumer project that already has one.
+ *
+ * Only files that ALREADY EXIST are returned — the sync never creates a
+ * settings file as an upgrade side effect (fresh installs get theirs from
+ * the wizard / installer).
+ */
+function _settings_sync_targets(project_root: string): string[] {
+    const targets: string[] = [];
+    const global_settings = path.join(event4u_root(), 'settings', '.agent-settings.yml');
+    if (_isFile(global_settings)) {
+        targets.push(global_settings);
+    }
+    const project_settings = project_settings_path(project_root);
+    if (project_settings !== global_settings && _isFile(project_settings)) {
+        targets.push(project_settings);
+    }
+    return targets;
+}
+
+/**
+ * Run the additive settings sync for every existing target — as a SUBPROCESS
+ * of the freshly installed binary, never in-process: after `npm install -g`
+ * the running module is still the OLD version, so an in-process merge would
+ * use the OLD template and miss exactly the new keys the upgrade shipped.
+ *
+ * Non-fatal by design: the upgrade itself already succeeded; a sync failure
+ * surfaces a warning + the manual command instead of failing the run.
+ */
+function _sync_settings_files(
+    targets: readonly string[],
+    runner: (cmd: string[]) => number,
+    out: OutSink,
+    err: OutSink,
+): void {
+    for (const target of targets) {
+        const cmd = [_agent_config_bin(), 'settings:sync', '--path', target];
+        _print(out, '→ ' + cmd.join(' '));
+        let rc: number;
+        try {
+            rc = runner(cmd);
+        } catch (exc) {
+            rc = 127;
+            _print(err, `cannot run ${cmd[0]}: ${osErrorStr(exc)}`);
+        }
+        if (rc !== 0) {
+            _print(
+                err,
+                `⚠️  agent-config upgrade: settings sync failed (exit ${rc}) for ` +
+                    `${target} — run \`agent-config settings:sync --path ${target}\` manually.`,
+            );
+        }
+    }
+}
+
+/**
+ * Refresh steps for the OPTIONAL Claude Code plugin. Non-empty only when the
+ * `claude` CLI is on PATH AND the plugin is recorded as installed — the file
+ * projection is a complete install on its own, so a missing plugin is not a
+ * gap to nag about. When present, the plugin must be refreshed alongside the
+ * global install: Claude Code pins it to the install-time git SHA, so without
+ * this step its command surface silently lags every upgrade.
+ */
+function _claude_plugin_refresh_steps(): string[][] {
+    const claude = shutilWhich('claude');
+    if (claude === null) return [];
+    if (!claude_plugin.claude_plugin_installed()) return [];
+    return [
+        [claude, 'plugin', 'marketplace', 'update', claude_plugin.CLAUDE_MARKETPLACE_NAME],
+        [
+            claude,
+            'plugin',
+            'update',
+            `${claude_plugin.CLAUDE_PLUGIN_ID}@${claude_plugin.CLAUDE_MARKETPLACE_NAME}`,
+        ],
+    ];
+}
+
+/**
+ * Run the plugin-refresh steps. Non-fatal by design (same contract as the
+ * settings sync): the upgrade itself already succeeded; a failure surfaces a
+ * warning + the manual command instead of failing the run.
+ */
+function _refresh_claude_plugin(
+    steps: readonly string[][],
+    runner: (cmd: string[]) => number,
+    out: OutSink,
+    err: OutSink,
+): void {
+    for (const cmd of steps) {
+        _print(out, '→ ' + cmd.join(' '));
+        let rc: number;
+        try {
+            rc = runner(cmd);
+        } catch (exc) {
+            rc = 127;
+            _print(err, `cannot run ${cmd[0]}: ${osErrorStr(exc)}`);
+        }
+        if (rc !== 0) {
+            _print(
+                err,
+                `⚠️  agent-config upgrade: Claude Code plugin refresh failed (exit ${rc}) — ` +
+                    `run \`${cmd.join(' ')}\` manually.`,
+            );
+            return;
+        }
+    }
+    if (steps.length > 0) {
+        _print(out, 'ℹ️  Claude Code plugin refreshed — restart Claude Code to load it.');
+    }
+}
+
 interface Args {
     check: boolean;
     dry_run: boolean;
@@ -319,37 +504,123 @@ export async function main(argv: string[] | null = null, options: MainOptions =
     }
 
     const target = `${PACKAGE_NAME}@latest`;
-    const steps: string[][] = [
-        ['npm', 'install', '-g', target],
-        [_agent_config_bin(), 'global'],
-    ];
+    const npm_cmd: string[] = ['npm', 'install', '-g', target];
+    // --no-ui: the setup wizard is an onboarding surface, not an upgrade
+    // step — its foreground server used to block the upgrade until Ctrl-C.
+    const global_cmd: string[] = [_agent_config_bin(), 'global', '--no-ui'];
+    const steps: string[][] = [npm_cmd, global_cmd];
+
+    const project_root = options.project_root ?? process.cwd();
+    const sync_targets = _settings_sync_targets(project_root);
+    const plugin_steps = _claude_plugin_refresh_steps();
 
     if (args.dry_run) {
         _print(out, 'agent-config upgrade — dry run, would execute:');
         for (const cmd of steps) {
             _print(out, '  ' + cmd.join(' '));
         }
+        for (const cmd of plugin_steps) {
+            _print(out, '  ' + cmd.join(' '));
+        }
+        for (const target of sync_targets) {
+            _print(out, '  ' + [_agent_config_bin(), 'settings:sync', '--path', target].join(' '));
+        }
         return 0;
     }
 
-    for (const cmd of steps) {
+    // Step 1 — the new package version. Nothing after makes sense without
+    // it, so this is the only hard-abort step.
+    _print(out, '→ ' + npm_cmd.join(' '));
+    const npm_rc = runner(npm_cmd);
+    if (npm_rc !== 0) {
+        _print(
+            err,
+            `❌  agent-config upgrade: step failed (exit ${npm_rc}): ` + `${npm_cmd.join(' ')}`,
+        );
+        return 1;
+    }
+
+    // Steps 2..N — independent. A failing step no longer skips the rest:
+    // the 8.2.0 failure class (aborted `global` step silently skipping the
+    // plugin refresh + settings sync) is closed by running every remaining
+    // step and reporting per-step outcomes in the summary. A failed
+    // essential step (global deploy) still exits 1 — after the others ran.
+    const failed_essential: string[] = [];
+    for (const cmd of steps.slice(1)) {
         _print(out, '→ ' + cmd.join(' '));
         const rc = runner(cmd);
         if (rc !== 0) {
+            failed_essential.push(cmd.join(' '));
             _print(
                 err,
-                `❌  agent-config upgrade: step failed (exit ${rc}): ` + `${cmd.join(' ')}`,
+                `❌  agent-config upgrade: step failed (exit ${rc}): ${cmd.join(' ')} — ` +
+                    'continuing with the remaining steps.',
             );
-            return 1;
         }
     }
 
-    _maybe_refresh_project_wrapper(options.project_root ?? process.cwd(), out, err);
+    // Refresh the OPTIONAL Claude Code plugin so its command surface tracks
+    // the upgrade — gated on the plugin actually being installed (empty step
+    // list otherwise). Deprecation window of the single-surface model: once
+    // the plugin is retired this block disappears with it.
+    _refresh_claude_plugin(plugin_steps, runner, out, err);
+
+    // Migration prompt (single-surface model): hooks were wired into
+    // ~/.claude/settings.json by the `global` step above, so an installed
+    // plugin is now a duplicate surface. Surface the one-line removal —
+    // NEVER uninstall autonomously (the plugin is a user-owned surface).
+    if (plugin_steps.length > 0) {
+        _print(
+            out,
+            'ℹ️  Claude Code marketplace plugin detected — deprecated surface. Hooks now ' +
+                'live in ~/.claude/settings.json (wired by the global step above), so the ' +
+                'plugin only duplicates skills/commands. Remove it with:\n' +
+                '    claude plugin uninstall ' +
+                `${claude_plugin.CLAUDE_PLUGIN_ID}@${claude_plugin.CLAUDE_MARKETPLACE_NAME}`,
+        );
+    }
+
+    // Bring existing settings files up to the NEW template (additive; the
+    // subprocess resolves the freshly installed binary + template).
+    _sync_settings_files(sync_targets, runner, out, err);
+
+    _maybe_refresh_project_wrapper(project_root, out, err);
+
+    // Re-stamp OUR installed .git/hooks/pre-commit from the new template
+    // (marker-guarded; foreign hooks are never touched).
+    _maybe_refresh_git_hook(project_root, runner, out, err);
+
+    // Doctor runs LAST, every time, non-fatal: its duplicate-surface and
+    // hook-wiring findings ARE the upgrade summary's health section — a
+    // mixed state (stale plugin, missing hooks) is named in the same run
+    // instead of waiting for the user to think of running doctor.
+    const doctor_cmd = [_agent_config_bin(), 'doctor'];
+    _print(out, '→ ' + doctor_cmd.join(' '));
+    const doctor_rc = runner(doctor_cmd);
+    if (doctor_rc !== 0) {
+        _print(
+            err,
+            `⚠️  agent-config doctor reported findings (exit ${doctor_rc}) — ` +
+                'see the check output above for per-item fixes.',
+        );
+    }
+
+    if (failed_essential.length > 0) {
+        _print(
+            err,
+            `❌  agent-config upgrade finished with ${failed_essential.length} failed ` +
+                `step(s):\n` +
+                failed_essential.map((c) => `    · ${c}`).join('\n') +
+                '\n   Re-run `agent-config upgrade`, or run the failed step directly. ' +
+                '`agent-config doctor` names anything left in a mixed state.',
+        );
+        return 1;
+    }
 
     _print(
         out,
-        '✅  agent-config upgraded. Run `agent-config doctor` to verify ' +
-            'PATH + plugin parity.',
+        '✅  agent-config upgraded' +
+            (doctor_rc === 0 ? ' — doctor green.' : ' — review the doctor findings above.'),
     );
     return 0;
 }
@@ -361,10 +632,29 @@ function installed_lock_is_newer(latest: string, installed: string): boolean {
 
 // --- CLI entry ---
 
-const _isCliEntry =
-    process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-if (_isCliEntry || process.argv[1] === _HERE) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
     main(process.argv.slice(2))
         .then((code) => {
             process.exitCode = code;

package/src/scripts/_cli/cmd_validate.ts

@@ -367,10 +367,29 @@ export function main(argv: string[]): number {
 
 // --- CLI entry ---
 
-const _isCliEntry =
-    process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-if (_isCliEntry || process.argv[1] === _HERE) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
     try {
         process.exitCode = main(process.argv.slice(2));
     } catch (e) {

package/src/scripts/_cli/cmd_versions.ts

@@ -476,10 +476,29 @@ export function main(argv: string[] | null = null, options: MainOptions = {}): n
 // Python: `if __name__ == "__main__": raise SystemExit(main())` (no argv slice;
 // argparse reads sys.argv[1:] inside `_parse` default).
 const _HERE = fileURLToPath(import.meta.url);
-const _isCliEntry =
-    process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-if (_isCliEntry || process.argv[1] === _HERE) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
     try {
         process.exitCode = main();
     } catch (exc) {