@claude-code-hooks/cli 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-code-hooks/cli",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Wizard CLI to set up and manage @claude-code-hooks packages for Claude Code.",
   "license": "MIT",
   "homepage": "https://github.com/beefiker/claude-code-hooks/tree/main/packages/cli",

package/src/cli.js

@@ -2,11 +2,15 @@
 
 import process from 'node:process';
 import readline from 'node:readline';
-import fs from 'node:fs/promises';
 import path from 'node:path';
+import fs from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 import {
-  intro,
   outro,
   select,
   multiselect,
@@ -28,8 +32,6 @@ import {
   configPathForScope,
   readJsonIfExists,
   writeJson,
-  CONFIG_FILENAME,
-  configFilePath,
   readProjectConfig,
   writeProjectConfig,
   removeLegacyClaudeSoundHooks,
@@ -47,8 +49,6 @@ if (detectLanguage() !== 'en') {
   });
 }
 
-import { buildSettingsSnippet } from './snippet.js';
-
 // In-workspace imports (when running from monorepo) and normal Node resolution
 // (when installed from npm) both resolve these packages.
 import { planInteractiveSetup as planSecuritySetup } from '@claude-code-hooks/security/src/plan.js';
@@ -61,6 +61,51 @@ function dieCancelled(msg) {
   process.exit(0);
 }
 
+function showWelcome() {
+  let version = '';
+  try {
+    const pkg = require(path.join(__dirname, '..', 'package.json'));
+    version = pkg.version ? ` v${pkg.version}` : '';
+  } catch {
+    // ignore
+  }
+
+  const width = 48;
+  const pad = '\n';
+  const particles = ['·', '•', '✦', '✧', '◦', '▪', 'º', '∗'];
+  const colors = [pc.blue, pc.cyan, pc.yellow, pc.magenta, pc.green];
+
+  const particleLine = (seed) => {
+    const len = width - 2;
+    let s = '  ';
+    for (let i = 0; i < len; i++) {
+      const show =
+        ((i * 17 + seed) % 5 === 0) ||
+        ((i * 13 + seed + 3) % 6 === 0) ||
+        ((i * 11 + seed + 1) % 4 === 0) ||
+        ((i * 19 + seed + 5) % 7 === 0);
+      s += show ? colors[(i + seed) % colors.length](particles[(i + seed) % particles.length]) : ' ';
+    }
+    return s + '\n';
+  };
+
+  const icon = pc.blue('◆');
+  const line = `  ${pc.blue('═')}${pc.cyan('═'.repeat(width - 4))}${pc.blue('═')}`;
+  const lineBottom = `  ${pc.yellow('═')}${pc.magenta('═'.repeat(width - 4))}${pc.yellow('═')}`;
+
+  process.stdout.write(pad);
+  process.stdout.write(particleLine(0));
+  process.stdout.write(line + pad);
+  process.stdout.write(pad);
+  process.stdout.write(`  ${icon}  ${pc.blue(pc.bold(t('cli.welcomeTitle')))}${version ? pc.gray(version) : ''}\n`);
+  process.stdout.write(pad);
+  process.stdout.write(`  ${pc.brightCyan('Customize Claude Code with zero dependencies')}\n`);
+  process.stdout.write(pad);
+  process.stdout.write(lineBottom + pad);
+  process.stdout.write(particleLine(5));
+  process.stdout.write(pad);
+}
+
 /**
  * Run a prompt with Backspace = go back. When Backspace is pressed, aborts and returns
  * { wentBack: true }. ESC still exits. Caller must handle wentBack by continuing the loop.
@@ -90,6 +135,47 @@ function usage(exitCode = 0) {
   process.exit(exitCode);
 }
 
+const GITIGNORE_LOCAL_ENTRY = '.claude/settings.local.json';
+
+/**
+ * Returns true if the trimmed gitignore line would cause settings.local.json to be ignored.
+ */
+function wouldIgnoreLocalSettings(line) {
+  const t = line.replace(/#.*$/, '').trim();
+  if (!t) return false;
+  if (t === GITIGNORE_LOCAL_ENTRY || t === '**/' + GITIGNORE_LOCAL_ENTRY) return true;
+  if (t === '.claude/' || t === '.claude' || t === '**/.claude/' || t === '**/.claude') return true;
+  if (t === '.claude/*' || t === '.claude/**' || t.includes('**/.claude')) return true;
+  if (t.includes('settings.local.json')) return true;
+  return false;
+}
+
+/**
+ * Ensures .gitignore in projectDir contains an entry to ignore settings.local.json.
+ * Called when user selects project (local) so their per-developer settings stay untracked.
+ * Never throws: catches all errors to avoid crashing the CLI.
+ */
+async function ensureGitignoreLocalEntry(projectDir) {
+  try {
+    const gitignorePath = path.join(projectDir, '.gitignore');
+    let content = '';
+    try {
+      content = await fs.readFile(gitignorePath, 'utf-8');
+    } catch (err) {
+      if (err?.code !== 'ENOENT') return;
+    }
+
+    const lines = content.split(/\r?\n/);
+    if (lines.some(wouldIgnoreLocalSettings)) return;
+
+    const needsNewline = content.length > 0 && !content.endsWith('\n');
+    const block = '\n# claude-code-hooks: per-developer local settings\n' + GITIGNORE_LOCAL_ENTRY + '\n';
+    await fs.appendFile(gitignorePath, (needsNewline ? '\n' : '') + block);
+  } catch {
+    // EACCES, EPERM, ENOSPC, etc. — don't crash CLI; settings were already written
+  }
+}
+
 async function ensureProjectOnlyConfig(projectDir, selected, perPackageConfig) {
   const cfgRes = await readProjectConfig(projectDir);
   const rawCfg = cfgRes.ok ? { ...(cfgRes.value || {}) } : {};
@@ -107,19 +193,6 @@ async function ensureProjectOnlyConfig(projectDir, selected, perPackageConfig) {
   return out;
 }
 
-async function maybeWriteSnippet(projectDir, snippetObj) {
-  const ok = await confirm({
-    message: t('cli.writeSnippet'),
-    initialValue: false
-  });
-  if (isCancel(ok)) return;
-  if (!ok) return;
-
-  const filePath = path.join(projectDir, 'claude-code-hooks.snippet.json');
-  await fs.writeFile(filePath, JSON.stringify(snippetObj, null, 2) + '\n');
-  note(filePath, t('cli.wroteSnippet'));
-}
-
 async function main() {
   const args = process.argv.slice(2);
   if (args.includes('-h') || args.includes('--help')) usage(0);
@@ -132,10 +205,13 @@ async function main() {
 
   const projectDir = process.cwd();
 
-  intro('claude-code-hooks');
-  note(t('cli.navHint'), t('cli.navTitle'));
+  showWelcome();
+
+  /** Build step header: "Step N/5 — <title> (ESC exit · Backspace back)" */
+  const stepHeader = (n, title) =>
+    pc.dim(t('cli.stepHeader', { n, title, suffix: t('cli.stepHeaderSuffix') }));
 
-  // ── Step 1–3: action, target, packages (Backspace = go to previous step) ──
+  // ── Step 1–5: action, target, packages, configure, review (Backspace = go to previous step) ──
   let action;
   let target;
   let selected;
@@ -153,7 +229,7 @@ async function main() {
   while (true) {
     if (step === 1) {
       action = await select({
-        message: `${pc.dim(t('cli.stepFormat', { n: 1 }))}  ${t('cli.step1ChooseAction')}`,
+        message: stepHeader(1, t('cli.step1ChooseAction')),
         options: [
           { value: 'setup', label: t('cli.actionSetup') },
           { value: 'uninstall', label: t('cli.actionUninstall') },
@@ -168,10 +244,11 @@ async function main() {
       const targetCtrl = new AbortController();
       const { result: targetResult, wentBack: targetBack } = await withBackspaceBack(targetCtrl, () =>
         select({
-          message: `${pc.dim(t('cli.stepFormat', { n: 2 }))}  ${t('cli.step2ChooseTarget')}`,
+          message: stepHeader(2, t('cli.step2ChooseTarget')),
           options: [
             { value: 'global', label: t('cli.targetGlobal') },
-            { value: 'projectOnly', label: t('cli.targetProjectOnly').replace(CONFIG_FILENAME, pc.bold(CONFIG_FILENAME)) }
+            { value: 'project', label: t('common.scopeProject') },
+            { value: 'projectLocal', label: t('common.scopeProjectLocal') }
           ],
           signal: targetCtrl.signal
         })
@@ -189,7 +266,7 @@ async function main() {
       const pkgsCtrl = new AbortController();
       const { result: pkgsResult, wentBack: pkgsBack } = await withBackspaceBack(pkgsCtrl, () =>
         multiselect({
-          message: `${pc.dim(t('cli.stepFormat', { n: 3 }))}  ${t('cli.step3SelectPackages')}`,
+          message: stepHeader(3, t('cli.step3SelectPackages')),
           options: packageOptions,
           required: true,
           validate: (v) => (!v || v.length === 0) ? t('common.selectAtLeastOne') : true,
@@ -208,7 +285,7 @@ async function main() {
     if (step === 4) {
       const proceedCtrl = new AbortController();
       const { result: proceedResult, wentBack: proceedBack } = await withBackspaceBack(proceedCtrl, () =>
-        confirm({ message: t('cli.configureNow'), initialValue: true, signal: proceedCtrl.signal })
+        confirm({ message: stepHeader(4, t('cli.configureNow')), initialValue: true, active: t('common.yes'), inactive: t('common.no'), signal: proceedCtrl.signal })
       );
       if (proceedBack) {
         step = 3;
@@ -239,7 +316,7 @@ async function main() {
         .map(
           (k) => {
             const desc = pc.dim(packageDescs[k] || '');
-            const label = highlightKey === k ? pc.cyan(pc.bold(k)) : pc.bold(k);
+            const label = highlightKey === k ? pc.blue(pc.bold(k)) : pc.bold(k);
             return `${label}: ${desc}`;
           }
         )
@@ -247,29 +324,27 @@ async function main() {
 
     // ── Step 4/5: configure (highlight current package) ──
     if (selected.includes('security')) {
-      note(formatPackageList('security'), `${pc.dim(t('cli.stepFormat', { n: 4 }))}  ${t('cli.step4Configure')}`);
+      note(formatPackageList('security'), stepHeader(4, t('cli.step4Configure')));
       perPackage.security = await planSecuritySetup({ action, projectDir, ui: 'umbrella' });
     }
     if (selected.includes('secrets')) {
-      note(formatPackageList('secrets'), `${pc.dim(t('cli.stepFormat', { n: 4 }))}  ${t('cli.step4Configure')}`);
+      note(formatPackageList('secrets'), stepHeader(4, t('cli.step4Configure')));
       perPackage.secrets = await planSecretsSetup({ action, projectDir, ui: 'umbrella' });
     }
     if (selected.includes('sound')) {
-      note(formatPackageList('sound'), `${pc.dim(t('cli.stepFormat', { n: 4 }))}  ${t('cli.step4Configure')}`);
+      note(formatPackageList('sound'), stepHeader(4, t('cli.step4Configure')));
       perPackage.sound = await planSoundSetup({ action, projectDir, ui: 'umbrella' });
     }
     if (selected.includes('notification')) {
-      note(formatPackageList('notification'), `${pc.dim(t('cli.stepFormat', { n: 4 }))}  ${t('cli.step4Configure')}`);
+      note(formatPackageList('notification'), stepHeader(4, t('cli.step4Configure')));
       perPackage.notification = await planNotificationSetup({ action, projectDir, ui: 'umbrella' });
     }
 
     // ── Step 5/5: review ──
     const files = [];
     if (target === 'global') files.push(configPathForScope('global', projectDir));
-    if (target === 'projectOnly') {
-      files.push(path.join(projectDir, CONFIG_FILENAME));
-      files.push(path.join(projectDir, 'claude-code-hooks.snippet.json (optional)'));
-    }
+    if (target === 'project') files.push(configPathForScope('project', projectDir));
+    if (target === 'projectLocal') files.push(configPathForScope('projectLocal', projectDir));
 
     function summarizePlan(key, plan) {
       if (!plan) return `${key}: ${t('cli.summarySkipped')}`;
@@ -283,10 +358,15 @@ async function main() {
 
     note(
       [
-        `${pc.dim(t('cli.stepFormat', { n: 5 }))}  ${t('cli.step5Review')}`,
+        stepHeader(5, t('cli.step5Review')),
         '',
-        `${t('cli.reviewAction')}: ${pc.bold(action)}`,
-        `${t('cli.reviewTarget')}: ${pc.bold(target === 'global' ? t('cli.reviewTargetGlobal') : t('cli.reviewTargetProjectOnly'))}`,
+        `${pc.bold(t('cli.reviewSectionActionTarget'))}`,
+        `  ${t('cli.reviewAction')}: ${pc.bold(action)}`,
+        `  ${t('cli.reviewTarget')}: ${pc.bold(
+          target === 'global' ? t('cli.reviewTargetGlobal') :
+          target === 'project' ? t('cli.reviewTargetProject') :
+          t('cli.reviewTargetProjectLocal')
+        )}`,
         '',
         `${pc.bold(t('cli.reviewPackages'))}`,
         ...selected.map((k) => `  - ${summarizePlan(k, perPackage[k])}`),
@@ -297,10 +377,10 @@ async function main() {
       t('cli.step5Review')
     );
 
-    const applyCtrl = new AbortController();
+      const applyCtrl = new AbortController();
     const { result: applyResult, wentBack: applyBack } = await withBackspaceBack(applyCtrl, () =>
       select({
-        message: t('cli.applyChanges'),
+        message: stepHeader(5, t('cli.applyChanges')),
         options: [
           { value: 'yes', label: t('cli.applyYes') },
           { value: 'cancel', label: t('cli.applyCancel') }
@@ -317,66 +397,42 @@ async function main() {
     break;
   }
 
-  if (target === 'projectOnly') {
-    // Write project config
-    const s = spinner();
-    s.start(t('cli.writingProjectConfig'));
-
-    // perPackage.*.projectConfigSection is shaped for claude-code-hooks.config.json sections.
-    const projectCfg = await ensureProjectOnlyConfig(projectDir, selected, {
-      security: perPackage.security?.projectConfigSection,
-      secrets: perPackage.secrets?.projectConfigSection,
-      sound: perPackage.sound?.projectConfigSection,
-      notification: perPackage.notification?.projectConfigSection
-    });
-
-    // Print snippet for user to paste into global settings.
-    const snippetObj = buildSettingsSnippet({
-      projectDir,
-      selected,
-      packagePlans: {
-        security: perPackage.security,
-        secrets: perPackage.secrets,
-        sound: perPackage.sound,
-        notification: perPackage.notification
-      }
-    });
-
-    s.stop(t('cli.done'));
-
-    note(JSON.stringify(snippetObj, null, 2), t('cli.pasteSnippet'));
-    await maybeWriteSnippet(projectDir, snippetObj);
-
-    outro(`${t('cli.projectConfigWritten')}: ${pc.bold(configFilePath(projectDir))}`);
-    return;
-  }
+  // Global / project / projectLocal apply: read settings.json, apply transforms, write once.
+  const settingsPath = configPathForScope(target, projectDir);
+  const pkgLabels = {
+    security: t('cli.pkgSecurity'),
+    secrets: t('cli.pkgSecrets'),
+    sound: t('cli.pkgSound'),
+    notification: t('cli.pkgNotification')
+  };
+  const s = spinner();
+  s.start(t('cli.applyingChanges'));
 
-  // Global apply: read settings.json, apply transforms, write once.
-  const settingsPath = configPathForScope('global', projectDir);
   const res = await readJsonIfExists(settingsPath);
   if (!res.ok) {
+    s.stop(t('cli.done'));
     cancel(t('cli.couldNotReadJson', { path: settingsPath }));
     process.exit(1);
   }
-
   let settings = res.value;
 
-  const s = spinner();
-  s.start(t('cli.applyingChanges'));
-
   for (const key of selected) {
     const plan = perPackage[key];
     if (!plan) continue;
+    const pkgName = pkgLabels[key] ?? key;
+    s.message(t('cli.applyStepApplyPackage', { packageName: pkgName }));
     settings = await plan.applyToSettings(settings);
   }
 
-  // Remove legacy claude-sound hooks (from old standalone package) to avoid duplicates
+  s.message(t('cli.applyStepWriteSettings'));
   settings = removeLegacyClaudeSoundHooks(settings);
-
   await writeJson(settingsPath, settings);
+  if (target === 'projectLocal') {
+    await ensureGitignoreLocalEntry(projectDir);
+  }
 
-  // Update project config only on setup.
   if (action === 'setup') {
+    s.message(t('cli.applyStepWriteProjectConfig'));
     await ensureProjectOnlyConfig(projectDir, selected, {
       security: perPackage.security?.projectConfigSection,
       secrets: perPackage.secrets?.projectConfigSection,
@@ -384,9 +440,27 @@ async function main() {
       notification: perPackage.notification?.projectConfigSection
     });
   }
+  s.stop('');
+
+  // Build contextual completion note
+  const traits = [];
+  if (selected.includes('security') || selected.includes('secrets')) traits.push(t('cli.doneTraitSafer'));
+  if (selected.includes('sound')) traits.push(t('cli.doneTraitLouder'));
+  if (selected.includes('notification')) traits.push(t('cli.doneTraitAttentive'));
+
+  const lines = [];
+  lines.push(`${t('cli.saved')}: ${pc.cyan(settingsPath)}`);
+  lines.push(`${t('cli.reviewPackages')}: ${selected.map((k) => pc.green(pkgLabels[k] ?? k)).join(', ')}`);
+
+  if (traits.length > 0) {
+    const joined = traits.length === 1
+      ? traits[0]
+      : traits.slice(0, -1).join(', ') + ' & ' + traits[traits.length - 1];
+    lines.push('');
+    lines.push(pc.bold(t('cli.doneWithTraits', { traits: joined })));
+  }
 
-  s.stop(t('cli.done'));
-  outro(`${t('cli.saved')}: ${pc.bold(settingsPath)}`);
+  note(lines.join('\n'), t('cli.doneNoteTitle'));
 }
 
 main().catch((err) => {

package/src/snippet.js

@@ -1,29 +0,0 @@
-import path from 'node:path';
-
-// This file generates a snippet the user can paste into ~/.claude/settings.json.
-// We keep it simple: a "hooks" object with managed hook handlers.
-
-export function buildSettingsSnippet({ projectDir, selected, packagePlans }) {
-  const hooks = {};
-
-  for (const key of selected) {
-    const plan = packagePlans[key];
-    if (!plan) continue;
-
-    // plan.snippetHooks is: { [eventName]: [ { matcher, hooks:[{type,command,async,timeout}]} ] }
-    for (const [eventName, groups] of Object.entries(plan.snippetHooks || {})) {
-      if (!Array.isArray(groups) || groups.length === 0) continue;
-      const existing = Array.isArray(hooks[eventName]) ? hooks[eventName] : [];
-      hooks[eventName] = [...existing, ...groups];
-    }
-  }
-
-  // Include a comment-like pointer to project config path (JSON doesn't support comments, so we use a metadata key).
-  const cfgPath = path.join(projectDir, 'claude-code-hooks.config.json');
-
-  return {
-    "__generated_by": "@claude-code-hooks/cli",
-    "__project_config": cfgPath,
-    hooks
-  };
-}