@thebassclef/lite 1.0.0 → 1.0.1

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { version } from "./index.js";
-import { realpathSync, statSync, constants, lstatSync, mkdirSync, accessSync, unlinkSync, openSync, writeSync, closeSync, readFileSync, readdirSync, existsSync } from "node:fs";
-import { isAbsolute, resolve, dirname, join, relative, basename as basename$1 } from "node:path";
+import { realpathSync, statSync, constants, lstatSync, mkdirSync, accessSync, unlinkSync, openSync, writeSync, closeSync, readlinkSync, readFileSync, chmodSync, readdirSync, existsSync } from "node:fs";
+import { isAbsolute, resolve, dirname, join, normalize, relative, basename as basename$1 } from "node:path";
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
@@ -13,7 +13,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";
@@ -48,6 +50,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("--")) {
@@ -116,6 +128,13 @@ function isUnder(child, parent) {
   if (rel === par) return true;
   return rel.startsWith(par + "/");
 }
+function readlinkOrNull(path) {
+  try {
+    return readlinkSync(path);
+  } catch {
+    return null;
+  }
+}
 class WriteError extends Error {
   name = "WriteError";
   kind;
@@ -149,7 +168,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}`);
@@ -266,8 +290,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,
@@ -289,6 +315,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 = join(targetDir, MANIFEST_RELATIVE_PATH);
   let raw;
@@ -369,8 +404,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);
@@ -378,11 +411,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 === homedir() ? homedir() : raw;
+  try {
+    return 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 = normalize(join(home, cleaned));
+  assertContained(targetPath, home, opts.allowRoot ? "/root" : null);
+  return { scope: "user", targetPath };
+}
+function classifyProject(relPath, opts) {
+  const cleaned = normalizeRel(relPath);
+  const targetPath = normalize(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 = resolve(target);
+  const resolvedRoot = resolve(root);
+  if (resolvedTarget === resolvedRoot) return;
+  if (resolvedTarget.startsWith(resolvedRoot + "/")) return;
+  if (altRoot) {
+    const resolvedAlt = 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;
+  }
+  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: [],
@@ -392,10 +520,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);
@@ -474,10 +604,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 = join(bundleRoot, SETTINGS_SUBPATH);
+  if (!fileExists(settingsPath)) return map;
+  let parsed;
+  try {
+    parsed = JSON.parse(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 = join(bundleRoot, relPath);
   const adopterRelPath = mapAdopterPath(relPath);
-  const targetPath = join(targetDir, adopterRelPath);
+  const scopeDecision = isHookFile(relPath) ? scopeMap.get(relPath) : void 0;
+  const targetPath = scopeDecision ? scopeDecision.targetPath : join(targetDir, adopterRelPath);
+  const scope = scopeDecision ? scopeDecision.scope : "project";
   let content;
   try {
     content = readFileSync(sourcePath, "utf8");
@@ -496,7 +657,11 @@ function copyOne(relPath, bundleRoot, targetDir, options, result) {
   try {
     mkdirSafely(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) {
@@ -506,6 +671,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.`;
@@ -613,7 +780,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 = join(targetDir, MANIFEST_RELATIVE_PATH);
     if (existsSync(manifestPath)) {
       process.stderr.write(
@@ -634,18 +804,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 = join(targetDir, MANIFEST_RELATIVE_PATH);
+  if (!existsSync(manifestPath)) return "ok";
+  const version2 = readManifestShapeVersion(targetDir);
+  if (version2 !== null && version2 >= 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) {
@@ -700,10 +896,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}
@@ -745,7 +967,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;
@@ -825,7 +1047,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(
@@ -1429,12 +1651,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 {
@@ -1484,6 +1700,7 @@ Proceed?`,
   );
   const errored = copyResult.errored;
   const newManifest = {
+    schema_version: MANIFEST_SHAPE_VERSION,
     $bassclef: {
       template: "init.manifest.json",
       manifest_schema_version: "0.1.0",

package/dist/index.cjs

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const version = "1.0.0";
+const version = "1.0.1";
 exports.version = version;

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export declare const version: "1.0.0";
+export declare const version: "1.0.1";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,4 @@
-const version = "1.0.0";
+const version = "1.0.1";
 export {
   version
 };