@thebassclef/lite 1.0.0 → 1.0.1

package/dist/cli.cjs

@@ -36,7 +36,9 @@ const DEFAULTS$2 = {
   verbose: false,
   allowRoot: false,
   allowAnyDir: false,
-  dir: void 0
+  dir: void 0,
+  yes: false,
+  json: false
 };
 let ArgvError$1 = class ArgvError extends Error {
   name = "ArgvError";
@@ -71,6 +73,16 @@ function parseInitArgs(argv) {
       i += 1;
       continue;
     }
+    if (token === "--yes") {
+      out.yes = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--json") {
+      out.json = true;
+      i += 1;
+      continue;
+    }
     if (token === "--dir") {
       const value = argv[i + 1];
       if (value === void 0 || value.startsWith("--")) {
@@ -139,6 +151,13 @@ function isUnder(child, parent) {
   if (rel === par) return true;
   return rel.startsWith(par + "/");
 }
+function readlinkOrNull(path) {
+  try {
+    return node_fs.readlinkSync(path);
+  } catch {
+    return null;
+  }
+}
 class WriteError extends Error {
   name = "WriteError";
   kind;
@@ -172,7 +191,12 @@ function writeSafely(path, content, opts = {}) {
     else throw new WriteError("Unknown", `cannot stat ${path}: ${err.code ?? "unknown"}`);
   }
   if (existing === "symlink") {
-    throw new WriteError("SymlinkRefused", `refusing to follow symlink at target path: ${path}`);
+    const target = readlinkOrNull(path);
+    const targetClause = target ? ` (points to: ${target})` : "";
+    throw new WriteError(
+      "SymlinkRefused",
+      `refusing to follow symlink at target path: ${path}${targetClause}. Delete or move the symlink and rerun bassclef init.`
+    );
   }
   if (existing !== "none" && !opts.force) {
     throw new WriteError("AlreadyExists", `file already exists (pass --force to overwrite): ${path}`);
@@ -289,8 +313,10 @@ function substrateConfigMdTemplate(pkgVersion) {
   ].join("\n");
 }
 const MANIFEST_SCHEMA_VERSION = "0.1.0";
+const MANIFEST_SHAPE_VERSION = 2;
 function manifestTemplate(input) {
   const value = {
+    schema_version: MANIFEST_SHAPE_VERSION,
     $bassclef: {
       template: "init.manifest.json",
       manifest_schema_version: MANIFEST_SCHEMA_VERSION,
@@ -312,6 +338,15 @@ class ManifestReadError extends Error {
     this.kind = kind;
   }
 }
+function readManifestShapeVersion(targetDir) {
+  try {
+    const parsed = readManifest(targetDir);
+    if (typeof parsed.schema_version === "number") return parsed.schema_version;
+    return null;
+  } catch {
+    return null;
+  }
+}
 function readManifest(targetDir) {
   const path = node_path.join(targetDir, MANIFEST_RELATIVE_PATH);
   let raw;
@@ -392,8 +427,6 @@ async function computeConfigHashes(targetDir, paths) {
   }
   return out;
 }
-const EXPECTED_WIRING_SCHEMA_MAJOR = 2;
-const WIRING_MANIFEST_RELATIVE = "standards/bassclef-wiring-manifest.json";
 class CopyFailure extends Error {
   constructor(kind, message) {
     super(message);
@@ -401,11 +434,106 @@ class CopyFailure extends Error {
     this.name = "CopyFailure";
   }
 }
+function resolveHome(opts) {
+  const raw = process.env.HOME;
+  if (raw === void 0 || raw === "") {
+    throw new CopyFailure(
+      "EnvironmentIncomplete",
+      "HOME environment variable is unset. bassclef init needs HOME set to resolve user-scope hook targets. Set HOME to your home directory and rerun."
+    );
+  }
+  if (raw === "/root" && !opts.allowRoot) {
+    throw new CopyFailure(
+      "SudoBypassRefused",
+      "HOME resolves to /root — sudo bypass detected. Routing user-scope hooks to /root breaks the adopter maintenance model. Run bassclef init without sudo, or pass --allow-root if this is intentional."
+    );
+  }
+  const canonical = raw === node_os.homedir() ? node_os.homedir() : raw;
+  try {
+    return node_fs.realpathSync(canonical);
+  } catch {
+    return canonical.endsWith("/") ? canonical.slice(0, -1) : canonical;
+  }
+}
+const PREFIX_HOME = "$HOME/";
+const PREFIX_PROJECT = "$CLAUDE_PROJECT_DIR/";
+function classify$1(hook, opts) {
+  const cmd = hook.command;
+  if (typeof cmd !== "string" || cmd.length === 0) {
+    throw new CopyFailure(
+      "UnknownScopePrefix",
+      "Hook command is empty. settings.json must supply a non-empty command string."
+    );
+  }
+  if (cmd.startsWith(PREFIX_HOME)) {
+    return classifyUser(cmd.slice(PREFIX_HOME.length), opts);
+  }
+  if (cmd.startsWith(PREFIX_PROJECT)) {
+    return classifyProject(cmd.slice(PREFIX_PROJECT.length), opts);
+  }
+  throw new CopyFailure(
+    "UnknownScopePrefix",
+    `Hook command "${cmd}" uses an unknown scope prefix. cli 1.0.1 handles "$HOME/..." and "$CLAUDE_PROJECT_DIR/..." only. Upgrade cli to a version that supports this prefix.`
+  );
+}
+function classifyUser(relPath, opts) {
+  const home = resolveHome({ allowRoot: opts.allowRoot });
+  const cleaned = normalizeRel(relPath);
+  const targetPath = node_path.normalize(node_path.join(home, cleaned));
+  assertContained(targetPath, home, opts.allowRoot ? "/root" : null);
+  return { scope: "user", targetPath };
+}
+function classifyProject(relPath, opts) {
+  const cleaned = normalizeRel(relPath);
+  const targetPath = node_path.normalize(node_path.join(opts.targetDir, cleaned));
+  assertContained(targetPath, opts.targetDir);
+  return { scope: "project", targetPath };
+}
+function normalizeRel(rel) {
+  return rel.replace(/\/{2,}/g, "/");
+}
+function assertContained(target, root, altRoot) {
+  const resolvedTarget = node_path.resolve(target);
+  const resolvedRoot = node_path.resolve(root);
+  if (resolvedTarget === resolvedRoot) return;
+  if (resolvedTarget.startsWith(resolvedRoot + "/")) return;
+  if (altRoot) {
+    const resolvedAlt = node_path.resolve(altRoot);
+    if (resolvedTarget === resolvedAlt) return;
+    if (resolvedTarget.startsWith(resolvedAlt + "/")) return;
+  }
+  throw new CopyFailure(
+    "PathTraversalRefused",
+    `Hook target "${target}" escapes ${root}. settings.json commands must resolve inside the declared scope root. If this is a bassclef-upstream bundle defect, file at sunj-labs/bassclef-upstream.`
+  );
+}
+const HOOK_EXECUTABLE_MODE = 493;
+function setExecutable(targetPath) {
+  if (process.platform === "win32") {
+    process.stderr.write(
+      `bassclef init: executable bit not applicable on this OS (${targetPath}). Claude Code will still invoke the hook if a POSIX shell layer is present.
+`
+    );
+    return;
+  }
+  node_fs.chmodSync(targetPath, HOOK_EXECUTABLE_MODE);
+}
+const HOOKS_SUBPATH = ".claude/hooks/";
+const SETTINGS_SUBPATH = ".claude/settings.json";
+const CONFIG_FILES = [
+  ".claude/settings.json",
+  "substrate.config.md",
+  "substrate.secrets.md"
+];
+const CURRENT_ENTRY_COUNT = 149;
+const EXPECTED_WIRING_SCHEMA_MAJOR = 2;
+const WIRING_MANIFEST_RELATIVE = "standards/bassclef-wiring-manifest.json";
 function copySubstrate(targetDir, options = {}) {
   const bundleRoot = resolveBundleRoot(options.bundleRoot);
   const manifest = readWiringManifest(bundleRoot);
   const result = {
     copied: [],
+    copiedEntries: [],
     refused: [],
     errored: [],
     erroredMessages: [],
@@ -415,10 +543,12 @@ function copySubstrate(targetDir, options = {}) {
   if (options.dryRun) result.wouldCopy = [];
   const files = walkDistTree(bundleRoot);
   const groups = groupByTopDirectory(files);
+  const bundleHookRelPaths = new Set(files.filter(isHookFile));
+  const scopeMap = buildScopeMap(bundleRoot, targetDir, options, bundleHookRelPaths);
   for (const [directory, groupFiles] of groups) {
     let completedInGroup = 0;
     for (const relPath of groupFiles) {
-      const outcome = copyOne(relPath, bundleRoot, targetDir, options, result);
+      const outcome = copyOne(relPath, bundleRoot, targetDir, options, result, scopeMap);
       if (outcome !== "skipped") completedInGroup += 1;
     }
     if (options.onProgress) options.onProgress(directory, completedInGroup);
@@ -497,10 +627,41 @@ function mapAdopterPath(relPath) {
   if (relPath === GITIGNORE_BUNDLE_NAME) return GITIGNORE_ADOPTER_NAME;
   return relPath;
 }
-function copyOne(relPath, bundleRoot, targetDir, options, result) {
+function buildScopeMap(bundleRoot, targetDir, options, bundleHookRelPaths) {
+  const map = /* @__PURE__ */ new Map();
+  const settingsPath = node_path.join(bundleRoot, SETTINGS_SUBPATH);
+  if (!fileExists(settingsPath)) return map;
+  let parsed;
+  try {
+    parsed = JSON.parse(node_fs.readFileSync(settingsPath, "utf8"));
+  } catch {
+    return map;
+  }
+  const allowRoot = options.allowRoot ?? false;
+  for (const eventBlocks of Object.values(parsed.hooks ?? {})) {
+    for (const block of eventBlocks) {
+      for (const entry of block.hooks ?? []) {
+        const cmd = entry.command;
+        if (typeof cmd !== "string" || cmd.length === 0) continue;
+        if (!cmd.startsWith("$")) continue;
+        const decision = classify$1({ command: cmd }, { targetDir, allowRoot });
+        const relSource = cmd.replace(/^\$HOME\//, "").replace(/^\$CLAUDE_PROJECT_DIR\//, "").replace(/\/{2,}/g, "/");
+        if (!bundleHookRelPaths.has(relSource)) continue;
+        map.set(relSource, decision);
+      }
+    }
+  }
+  return map;
+}
+function isHookFile(relPath) {
+  return relPath.startsWith(HOOKS_SUBPATH) && relPath.endsWith(".sh");
+}
+function copyOne(relPath, bundleRoot, targetDir, options, result, scopeMap) {
   const sourcePath = node_path.join(bundleRoot, relPath);
   const adopterRelPath = mapAdopterPath(relPath);
-  const targetPath = node_path.join(targetDir, adopterRelPath);
+  const scopeDecision = isHookFile(relPath) ? scopeMap.get(relPath) : void 0;
+  const targetPath = scopeDecision ? scopeDecision.targetPath : node_path.join(targetDir, adopterRelPath);
+  const scope = scopeDecision ? scopeDecision.scope : "project";
   let content;
   try {
     content = node_fs.readFileSync(sourcePath, "utf8");
@@ -519,7 +680,11 @@ function copyOne(relPath, bundleRoot, targetDir, options, result) {
   try {
     mkdirSafely(node_path.dirname(targetPath));
     writeSafely(targetPath, outputContent, { force: options.force ?? false });
+    if (isHookFile(relPath)) {
+      setExecutable(targetPath);
+    }
     result.copied.push(adopterRelPath);
+    result.copiedEntries.push({ path: adopterRelPath, scope });
     return "copied";
   } catch (e) {
     if (e instanceof WriteError) {
@@ -529,6 +694,8 @@ function copyOne(relPath, bundleRoot, targetDir, options, result) {
       }
       if (e.kind === "SymlinkRefused") {
         result.refused.push(adopterRelPath);
+        process.stderr.write(`bassclef init: ${e.message}
+`);
         return "refused";
       }
       const message = `${adopterRelPath} — write failed (${e.kind}): ${e.message}. Check the target directory exists and is writable, then rerun.`;
@@ -636,7 +803,10 @@ function runInit(argv) {
     }
     throw e;
   }
-  if (!args.force && !args.dryRun) {
+  const advisoryOutcome = maybeEmitUpgradeAdvisory(targetDir, args.yes);
+  if (advisoryOutcome === "refused") return 1;
+  const upgradeApproved = advisoryOutcome === "upgrade-approved";
+  if (!args.force && !args.dryRun && !upgradeApproved) {
     const manifestPath = node_path.join(targetDir, MANIFEST_RELATIVE_PATH);
     if (node_fs.existsSync(manifestPath)) {
       process.stderr.write(
@@ -657,18 +827,44 @@ function runInit(argv) {
   ];
   if (args.dryRun) {
     runDryRun$1(plans);
-    return dispatchSubstrateCopy(targetDir, args.force, args.verbose, true);
+    return dispatchSubstrateCopy(targetDir, args.force || upgradeApproved, args.verbose, true, args.allowRoot, args.json);
+  }
+  return runReal$1(plans, args.force || upgradeApproved, args.verbose, targetDir, args.allowRoot, args.json);
+}
+function maybeEmitUpgradeAdvisory(targetDir, yes) {
+  const manifestPath = node_path.join(targetDir, MANIFEST_RELATIVE_PATH);
+  if (!node_fs.existsSync(manifestPath)) return "ok";
+  const version = readManifestShapeVersion(targetDir);
+  if (version !== null && version >= 2) return "ok";
+  process.stdout.write(
+    `bassclef init: cli 1.0.1 introduces user-scope hook installation at ~/${HOOKS_SUBPATH}. cli 1.0.0 did not write there.
+`
+  );
+  if (yes) return "upgrade-approved";
+  process.stdout.write("bassclef init: continue? (y/N) ");
+  const answer = readOneLineFromStdin();
+  if (answer === "" || answer === "y" || answer === "Y") return "upgrade-approved";
+  process.stdout.write("bassclef init: aborted by adopter.\n");
+  return "refused";
+}
+function readOneLineFromStdin() {
+  try {
+    const buf = Buffer.alloc(256);
+    const n = require("node:fs").readSync(0, buf, 0, 256, null);
+    return n > 0 ? buf.slice(0, n).toString("utf8").trim() : "";
+  } catch {
+    return "";
   }
-  return runReal$1(plans, args.force, args.verbose, targetDir);
 }
-function dispatchSubstrateCopy(targetDir, force, verbose, dryRun) {
+function dispatchSubstrateCopy(targetDir, force, verbose, dryRun, allowRoot, json) {
   const substitute = makePlaceholderTransform(targetDir);
   let result;
   try {
     result = copySubstrate(targetDir, {
       force,
       dryRun,
-      transform: substitute
+      transform: substitute,
+      allowRoot
     });
   } catch (e) {
     if (e instanceof CopyFailure) {
@@ -723,10 +919,36 @@ function dispatchSubstrateCopy(targetDir, force, verbose, dryRun) {
     `bassclef init: ${grandTotal} files total (1 config + ${result.copied.length} substrate).
 `
   );
-  process.stdout.write(
-    `bassclef init: ${result.hookCount} hooks armed (${RESOLVED_TIER} tier).
-`
+  const copiedHookEntries = result.copiedEntries.filter(
+    (e) => e.path.startsWith(HOOKS_SUBPATH) && e.path.endsWith(".sh")
   );
+  const copiedCount = copiedHookEntries.length;
+  const declaredCount = result.hookCount;
+  const failedCount = result.refused.length + result.errored.length;
+  const userScope = copiedHookEntries.filter((e) => e.scope === "user").length;
+  const projectScope = copiedHookEntries.filter((e) => e.scope === "project").length;
+  const scopeSuffix = userScope + projectScope > 0 ? ` ${projectScope} in <repo>/${HOOKS_SUBPATH.replace(/\/$/, "")}, ${userScope} in ~/${HOOKS_SUBPATH.replace(/\/$/, "")}.` : "";
+  if (failedCount > 0) {
+    process.stdout.write(
+      `bassclef init: Installed ${copiedCount} of ${declaredCount} hooks (${RESOLVED_TIER} tier).${scopeSuffix} ${failedCount} failed — see errors above. Rerun bassclef init to retry.
+`
+    );
+  } else {
+    process.stdout.write(
+      `bassclef init: Installed ${copiedCount} of ${declaredCount} hooks (${RESOLVED_TIER} tier).${scopeSuffix}
+`
+    );
+  }
+  if (json) {
+    const report = {
+      copied: copiedCount,
+      declared: declaredCount,
+      failed: failedCount,
+      scope_counts: { user: userScope, project: projectScope },
+      tier: RESOLVED_TIER
+    };
+    process.stderr.write(JSON.stringify(report) + "\n");
+  }
   if (verbose && result.erroredMessages) {
     for (const msg of result.erroredMessages) {
       process.stderr.write(`  substrate: ${msg}
@@ -768,7 +990,7 @@ function runDryRun$1(plans) {
   }
   return 0;
 }
-function runReal$1(plans, force, verbose, targetDir) {
+function runReal$1(plans, force, verbose, targetDir, allowRoot, json) {
   const results = [];
   let anyRefused = false;
   let anyError = false;
@@ -848,7 +1070,7 @@ function runReal$1(plans, force, verbose, targetDir) {
     process.stdout.write(`bassclef init: ${created} config files created, ${unchanged} unchanged.
 `);
   }
-  const walkerExit = dispatchSubstrateCopy(targetDir, force, verbose, false);
+  const walkerExit = dispatchSubstrateCopy(targetDir, force, verbose, false, allowRoot, json);
   writeManifest(targetDir, results);
   if (walkerExit === 0) {
     process.stdout.write(
@@ -1452,12 +1674,6 @@ async function confirm(question, opts = {}) {
     rl.close();
   }
 }
-const CONFIG_FILES = [
-  ".claude/settings.json",
-  "substrate.config.md",
-  "substrate.secrets.md"
-];
-const CURRENT_ENTRY_COUNT = 149;
 async function detectAdopterState(targetDir) {
   let manifest;
   try {
@@ -1507,6 +1723,7 @@ Proceed?`,
   );
   const errored = copyResult.errored;
   const newManifest = {
+    schema_version: MANIFEST_SHAPE_VERSION,
     $bassclef: {
       template: "init.manifest.json",
       manifest_schema_version: "0.1.0",