@thebassclef/lite 0.0.1 → 0.1.0

package/dist/cli.cjs

@@ -0,0 +1,1610 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+const index = require("./index.cjs");
+const node_fs = require("node:fs");
+const node_path = require("node:path");
+const node_os = require("node:os");
+const node_crypto = require("node:crypto");
+const node_url = require("node:url");
+const node_module = require("node:module");
+const promises = require("node:readline/promises");
+const node_process = require("node:process");
+var _documentCurrentScript = typeof document !== "undefined" ? document.currentScript : null;
+const DEFAULTS$2 = {
+  force: false,
+  dryRun: false,
+  verbose: false,
+  allowRoot: false,
+  allowAnyDir: false,
+  dir: void 0
+};
+let ArgvError$1 = class ArgvError extends Error {
+  name = "ArgvError";
+};
+function parseInitArgs(argv) {
+  const out = { ...DEFAULTS$2 };
+  let i = 0;
+  while (i < argv.length) {
+    const token = argv[i];
+    if (token === "--force") {
+      out.force = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--dry-run") {
+      out.dryRun = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--verbose") {
+      out.verbose = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--allow-root") {
+      out.allowRoot = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--allow-any-dir") {
+      out.allowAnyDir = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--dir") {
+      const value = argv[i + 1];
+      if (value === void 0 || value.startsWith("--")) {
+        throw new ArgvError$1("--dir requires a value");
+      }
+      out.dir = value;
+      i += 2;
+      continue;
+    }
+    if (token.startsWith("--dir=")) {
+      out.dir = token.slice("--dir=".length);
+      i += 1;
+      continue;
+    }
+    if (token.startsWith("--")) {
+      throw new ArgvError$1(`unknown flag: ${token}`);
+    }
+    throw new ArgvError$1(`unexpected argument: ${token}`);
+  }
+  return out;
+}
+class ResolveError extends Error {
+  name = "ResolveError";
+}
+function resolveTargetDir(input) {
+  const raw = input.cliArg ?? input.cwd;
+  const beforeReal = node_path.isAbsolute(raw) ? raw : node_path.resolve(input.cwd, raw);
+  let canonical;
+  try {
+    canonical = node_fs.realpathSync(beforeReal);
+  } catch (e) {
+    const err = e;
+    if (err.code === "ENOENT") {
+      throw new ResolveError(`target directory does not exist: ${beforeReal}`);
+    }
+    throw new ResolveError(`cannot resolve target directory: ${beforeReal} (${err.code ?? "unknown"})`);
+  }
+  if (!input.allowAnyDir) {
+    const home = node_os.homedir();
+    if (!isUnder(canonical, home)) {
+      throw new ResolveError(
+        `target directory is not under your home directory (${home}). Pass --allow-any-dir if this is intentional.`
+      );
+    }
+    if (typeof process.getuid === "function") {
+      const uid = process.getuid();
+      let stat;
+      try {
+        stat = node_fs.statSync(canonical);
+      } catch (e) {
+        const err = e;
+        throw new ResolveError(`cannot stat target directory (${err.code ?? "unknown"}): ${canonical}`);
+      }
+      if (stat.uid !== uid) {
+        throw new ResolveError(
+          `target directory is not owned by the current user. Pass --allow-any-dir if this is intentional.`
+        );
+      }
+    }
+  }
+  return canonical;
+}
+function isUnder(child, parent) {
+  const rel = node_path.resolve(child);
+  const par = node_path.resolve(parent);
+  if (rel === par) return true;
+  return rel.startsWith(par + "/");
+}
+class WriteError extends Error {
+  name = "WriteError";
+  kind;
+  constructor(kind, message) {
+    super(message);
+    this.kind = kind;
+  }
+}
+const FLAGS_CREATE = node_fs.constants.O_CREAT | node_fs.constants.O_EXCL | node_fs.constants.O_NOFOLLOW | node_fs.constants.O_WRONLY;
+function writeSafely(path, content, opts = {}) {
+  const parent = node_path.dirname(path);
+  try {
+    node_fs.accessSync(parent, node_fs.constants.F_OK);
+  } catch {
+    throw new WriteError("ParentMissing", `parent directory does not exist: ${parent}`);
+  }
+  try {
+    node_fs.accessSync(parent, node_fs.constants.W_OK);
+  } catch {
+    throw new WriteError("ParentNotWritable", `parent directory is not writable: ${parent}`);
+  }
+  let existing;
+  try {
+    const st = node_fs.lstatSync(path);
+    if (st.isSymbolicLink()) existing = "symlink";
+    else if (st.isFile()) existing = "regular";
+    else existing = "other";
+  } catch (e) {
+    const err = e;
+    if (err.code === "ENOENT") existing = "none";
+    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}`);
+  }
+  if (existing !== "none" && !opts.force) {
+    throw new WriteError("AlreadyExists", `file already exists (pass --force to overwrite): ${path}`);
+  }
+  if (existing !== "none" && opts.force) {
+    try {
+      node_fs.unlinkSync(path);
+    } catch (e) {
+      const err = e;
+      if (err.code !== "ENOENT") {
+        throw new WriteError("Unknown", `cannot remove existing entry at ${path}: ${err.code ?? "unknown"}`);
+      }
+    }
+  }
+  let fd;
+  const mode = opts.mode ?? 420;
+  try {
+    fd = node_fs.openSync(path, FLAGS_CREATE, mode);
+  } catch (e) {
+    const err = e;
+    if (err.code === "EEXIST") {
+      throw new WriteError("AlreadyExists", `file appeared during write (race): ${path}`);
+    }
+    if (err.code === "ELOOP" || err.code === "EMLINK" || err.code === "ENOTSUP") {
+      throw new WriteError("SymlinkRefused", `refusing to follow symlink at target path: ${path}`);
+    }
+    throw new WriteError("Unknown", `cannot open ${path}: ${err.code ?? "unknown"}`);
+  }
+  try {
+    node_fs.writeSync(fd, content);
+  } finally {
+    node_fs.closeSync(fd);
+  }
+}
+function mkdirSafely(path) {
+  try {
+    const st = node_fs.lstatSync(path);
+    if (st.isSymbolicLink()) {
+      throw new WriteError("SymlinkRefused", `refusing to create over symlink: ${path}`);
+    }
+    if (st.isDirectory()) {
+      return;
+    }
+    throw new WriteError("AlreadyExists", `cannot create directory: non-directory entry exists at ${path}`);
+  } catch (e) {
+    if (e instanceof WriteError) throw e;
+    const err = e;
+    if (err.code !== "ENOENT") {
+      throw new WriteError("Unknown", `cannot stat ${path}: ${err.code ?? "unknown"}`);
+    }
+  }
+  try {
+    node_fs.mkdirSync(path, { recursive: true, mode: 493 });
+  } catch (e) {
+    const err = e;
+    if (err.code === "EACCES" || err.code === "EPERM") {
+      throw new WriteError("ParentNotWritable", `cannot create directory (permission): ${path}`);
+    }
+    throw new WriteError("Unknown", `cannot create directory: ${path} (${err.code ?? "unknown"})`);
+  }
+}
+function hashContent(content) {
+  let normalized = content;
+  if (normalized.charCodeAt(0) === 65279) {
+    normalized = normalized.slice(1);
+  }
+  normalized = normalized.replace(/\r\n/g, "\n");
+  return node_crypto.createHash("sha256").update(normalized, "utf8").digest("hex");
+}
+const SETTINGS_TEMPLATE_VERSION = "0.0.1";
+function settingsJsonTemplate(pkgVersion) {
+  const value = {
+    $bassclef: {
+      template: "settings.json",
+      template_version: SETTINGS_TEMPLATE_VERSION,
+      generated_by: "@thebassclef/core",
+      generated_by_version: pkgVersion
+    },
+    permissions: {
+      additionalDirectories: []
+    },
+    hooks: {}
+  };
+  return JSON.stringify(value, null, 2) + "\n";
+}
+const SUBSTRATE_CONFIG_TEMPLATE_VERSION = "0.0.1";
+function substrateConfigMdTemplate(pkgVersion) {
+  return [
+    "---",
+    `bassclef_template: substrate.config.md`,
+    `bassclef_template_version: ${SUBSTRATE_CONFIG_TEMPLATE_VERSION}`,
+    `generated_by: "@thebassclef/core"`,
+    `generated_by_version: "${pkgVersion}"`,
+    "---",
+    "",
+    "# substrate.config.md",
+    "",
+    "## Configuration",
+    "gating: operator-gated",
+    "execution_mode: sequential",
+    "",
+    "## Active agents",
+    "agents: Shaper, PM, Designer, Architect, Builder, Reviewer, Deployer, Closer",
+    "",
+    "## Phases",
+    "phases: [Inception, Elaboration, Construction, Transition]",
+    "",
+    "## Iteration planning",
+    "iterations: informal",
+    "",
+    "## Risk register",
+    "risk-register: no",
+    "",
+    "## Budget",
+    "budget:",
+    "  session_ceiling:",
+    "  iteration_ceiling:",
+    "",
+    "## Hosting platform",
+    "# Leave `none` unless this project deploys a web UI.",
+    "# Enum: amplify | ec2-tailscale | vercel | netlify | cloudflare-pages | none",
+    "hosting_platform: none",
+    "",
+    "## Deploy targets",
+    "deploy_targets:",
+    "  local: true",
+    "  staging: false",
+    "  prod: false",
+    ""
+  ].join("\n");
+}
+const MANIFEST_SCHEMA_VERSION = "0.1.0";
+function manifestTemplate(input) {
+  const value = {
+    $bassclef: {
+      template: "init.manifest.json",
+      manifest_schema_version: MANIFEST_SCHEMA_VERSION,
+      generated_by: "@thebassclef/core",
+      generated_by_version: input.pkgVersion
+    },
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    target_dir: input.targetDir,
+    files: input.files
+  };
+  return JSON.stringify(value, null, 2) + "\n";
+}
+const MANIFEST_RELATIVE_PATH = ".bassclef/init.manifest.json";
+class ManifestReadError extends Error {
+  name = "ManifestReadError";
+  kind;
+  constructor(kind, message) {
+    super(message);
+    this.kind = kind;
+  }
+}
+function readManifest(targetDir) {
+  const path = node_path.join(targetDir, MANIFEST_RELATIVE_PATH);
+  let raw;
+  try {
+    raw = node_fs.readFileSync(path, "utf8");
+  } catch (e) {
+    const err = e;
+    if (err.code === "ENOENT") {
+      throw new ManifestReadError(
+        "Missing",
+        `not initialized — no manifest at ${path}. Run \`bassclef init\` (or \`bassclef init --force\` if managed files already exist).`
+      );
+    }
+    throw new ManifestReadError("Malformed", `cannot read manifest at ${path}: ${err.code ?? "unknown"}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new ManifestReadError(
+      "Malformed",
+      `manifest is not valid JSON at ${path}. Repair it by hand or run \`bassclef init --force\` to re-baseline.`
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || !("$bassclef" in parsed) || typeof parsed.$bassclef !== "object" || parsed.$bassclef === null) {
+    throw new ManifestReadError(
+      "Malformed",
+      `manifest is missing the $bassclef block at ${path}. Repair or re-baseline via \`bassclef init --force\`.`
+    );
+  }
+  const marker = parsed.$bassclef;
+  const schema = marker.manifest_schema_version;
+  if (typeof schema !== "string") {
+    throw new ManifestReadError(
+      "Malformed",
+      `manifest lacks a $bassclef.manifest_schema_version field at ${path}.`
+    );
+  }
+  if (compareSchemaVersion(schema, MANIFEST_SCHEMA_VERSION) > 0) {
+    throw new ManifestReadError(
+      "SchemaTooNew",
+      `manifest schema version ${schema} is newer than this package understands (${MANIFEST_SCHEMA_VERSION}). Upgrade @thebassclef/core.`
+    );
+  }
+  const obj = parsed;
+  if (!Array.isArray(obj.files)) {
+    throw new ManifestReadError("Malformed", `manifest.files is not an array at ${path}.`);
+  }
+  return parsed;
+}
+function writeManifest$1(targetDir, manifest) {
+  const path = node_path.join(targetDir, MANIFEST_RELATIVE_PATH);
+  const body = JSON.stringify(manifest, null, 2) + "\n";
+  mkdirSafely(node_path.dirname(path));
+  writeSafely(path, body, { force: true });
+}
+function compareSchemaVersion(a, b) {
+  const A = a.split(".").map((x) => parseInt(x, 10));
+  const B = b.split(".").map((x) => parseInt(x, 10));
+  for (let i = 0; i < Math.max(A.length, B.length); i++) {
+    const av = A[i] ?? 0;
+    const bv = B[i] ?? 0;
+    if (av !== bv) return av - bv;
+  }
+  return 0;
+}
+async function computeConfigHashes(targetDir, paths) {
+  const { readFileSync: read } = await import("node:fs");
+  const { createHash } = await import("node:crypto");
+  const { existsSync } = await import("node:fs");
+  const out = {};
+  for (const rel of paths) {
+    const abs = node_path.join(targetDir, rel);
+    if (!existsSync(abs)) continue;
+    const raw = read(abs, "utf8");
+    const normalized = raw.replace(/\r\n/g, "\n");
+    out[rel] = createHash("sha256").update(normalized, "utf8").digest("hex");
+  }
+  return out;
+}
+const SUBSTRATE_ROOT = "substrate";
+const CONFIG_FILES = [
+  ".claude/settings.json",
+  "substrate.config.md",
+  "substrate.secrets.md"
+];
+const CURRENT_ENTRY_COUNT = 149;
+function copySubstrate(targetDir, options = {}) {
+  const bundleRoot = resolveBundleRoot(options.bundleRoot);
+  const manifest = loadBundledManifest(bundleRoot);
+  const result = {
+    copied: [],
+    refused: [],
+    errored: [],
+    erroredMessages: []
+  };
+  if (options.dryRun) result.wouldCopy = [];
+  const groups = groupByTopDirectory(manifest.entries);
+  for (const [directory, entries] of groups) {
+    let completedInGroup = 0;
+    for (const entry of entries) {
+      const outcome = copyOne(entry, bundleRoot, targetDir, options, result);
+      if (outcome !== "skipped") completedInGroup += 1;
+    }
+    if (options.onProgress) options.onProgress(directory, completedInGroup);
+  }
+  return result;
+}
+function copyOne(entry, bundleRoot, targetDir, options, result) {
+  const sourcePath = node_path.join(bundleRoot, entry.path);
+  const targetPath = node_path.join(targetDir, entry.path);
+  let content;
+  try {
+    content = node_fs.readFileSync(sourcePath, "utf8");
+  } catch (e) {
+    const err = e;
+    const message = `${entry.path} — cannot read bundled source (${err.code ?? "unknown"}). Reinstall @thebassclef/core to restore the bundle.`;
+    result.errored.push(entry.path);
+    result.erroredMessages?.push(message);
+    return "errored";
+  }
+  const declaredHash = stripHashPrefix(entry.content_hash);
+  const actualHash = sha256Hex(content);
+  if (declaredHash !== actualHash) {
+    const message = `${entry.path} — bundled content hash does not match the manifest. Reinstall @thebassclef/core to repair the bundle, then rerun bassclef init --force.`;
+    result.errored.push(entry.path);
+    result.erroredMessages?.push(message);
+    return "errored";
+  }
+  if (options.dryRun) {
+    result.wouldCopy?.push(entry.path);
+    return "wouldCopy";
+  }
+  try {
+    mkdirSafely(node_path.dirname(targetPath));
+    writeSafely(targetPath, content, { force: options.force ?? false });
+    result.copied.push(entry.path);
+    return "copied";
+  } catch (e) {
+    if (e instanceof WriteError) {
+      if (e.kind === "AlreadyExists") {
+        result.refused.push(entry.path);
+        return "refused";
+      }
+      if (e.kind === "SymlinkRefused") {
+        result.refused.push(entry.path);
+        return "refused";
+      }
+      const message = `${entry.path} — write failed (${e.kind}): ${e.message}. Check the target directory exists and is writable, then rerun.`;
+      result.errored.push(entry.path);
+      result.erroredMessages?.push(message);
+      return "errored";
+    }
+    throw e;
+  }
+}
+function loadBundledManifest(bundleRoot) {
+  const manifestPath = node_path.join(bundleRoot, ".bassclef", "lite-manifest.json");
+  const raw = node_fs.readFileSync(manifestPath, "utf8");
+  const parsed = JSON.parse(raw);
+  if (!Array.isArray(parsed.entries)) {
+    throw new Error(
+      `bundled manifest at ${manifestPath} has no entries[] array. Reinstall @thebassclef/core to restore the bundle.`
+    );
+  }
+  return parsed;
+}
+function resolveBundleRoot(explicit) {
+  if (explicit && explicit.length > 0) return node_path.resolve(explicit);
+  const thisFile = node_url.fileURLToPath(typeof document === "undefined" ? require("url").pathToFileURL(__filename).href : _documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === "SCRIPT" && _documentCurrentScript.src || new URL("cli.cjs", document.baseURI).href);
+  let dir = node_path.dirname(thisFile);
+  for (let i = 0; i < 5; i += 1) {
+    try {
+      node_fs.readFileSync(node_path.join(dir, "package.json"), "utf8");
+      return node_path.join(dir, SUBSTRATE_ROOT);
+    } catch {
+      const parent = node_path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  const require$1 = node_module.createRequire(typeof document === "undefined" ? require("url").pathToFileURL(__filename).href : _documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === "SCRIPT" && _documentCurrentScript.src || new URL("cli.cjs", document.baseURI).href);
+  const pkgJsonPath = require$1.resolve("@thebassclef/core/package.json");
+  const pkgRoot = node_path.dirname(pkgJsonPath);
+  return node_path.join(pkgRoot, SUBSTRATE_ROOT);
+}
+function groupByTopDirectory(entries) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const parts = entry.path.split("/");
+    const top = parts.length >= 2 ? parts.slice(0, 2).join("/") : parts[0] ?? "";
+    if (!groups.has(top)) groups.set(top, []);
+    groups.get(top).push(entry);
+  }
+  return groups;
+}
+function stripHashPrefix(value) {
+  const prefix = "sha256:";
+  return value.startsWith(prefix) ? value.slice(prefix.length) : value;
+}
+function sha256Hex(content) {
+  return node_crypto.createHash("sha256").update(content).digest("hex");
+}
+function runInit(argv) {
+  let args;
+  try {
+    args = parseInitArgs(argv);
+  } catch (e) {
+    if (e instanceof ArgvError$1) {
+      process.stderr.write(`bassclef init: ${e.message}
+`);
+      process.stderr.write(usage$2());
+      return 3;
+    }
+    throw e;
+  }
+  const currentUid = typeof process.getuid === "function" ? process.getuid() : void 0;
+  if (shouldRefuseRoot(currentUid, args.allowRoot)) {
+    process.stderr.write(
+      "bassclef init: refusing to run as root. Pass --allow-root if this is intentional.\n"
+    );
+    return 1;
+  }
+  let targetDir;
+  try {
+    targetDir = resolveTargetDir({
+      cwd: process.cwd(),
+      cliArg: args.dir,
+      allowAnyDir: args.allowAnyDir
+    });
+  } catch (e) {
+    if (e instanceof ResolveError) {
+      process.stderr.write(`bassclef init: ${e.message}
+`);
+      return 1;
+    }
+    throw e;
+  }
+  if (!args.force && !args.dryRun) {
+    const manifestPath = node_path.join(targetDir, MANIFEST_RELATIVE_PATH);
+    if (node_fs.existsSync(manifestPath)) {
+      process.stderr.write(
+        "bassclef init: already initialized (manifest exists). Run `bassclef sync` to apply updates, or `bassclef init --force` to re-baseline.\n"
+      );
+      return 1;
+    }
+  }
+  const plans = [
+    {
+      label: "settings.json",
+      relativePath: ".claude/settings.json",
+      fullPath: node_path.join(targetDir, ".claude", "settings.json"),
+      content: settingsJsonTemplate(index.version),
+      templateName: "settings.json",
+      templateVersion: SETTINGS_TEMPLATE_VERSION
+    },
+    {
+      label: "substrate.config.md",
+      relativePath: "substrate.config.md",
+      fullPath: node_path.join(targetDir, "substrate.config.md"),
+      content: substrateConfigMdTemplate(index.version),
+      templateName: "substrate.config.md",
+      templateVersion: SUBSTRATE_CONFIG_TEMPLATE_VERSION
+    }
+  ];
+  if (args.dryRun) {
+    return runDryRun$1(plans);
+  }
+  const exitCode = runReal$1(plans, args.force, args.verbose, targetDir);
+  if (exitCode === 0) {
+    dispatchSubstrateCopy(targetDir, args.force, args.verbose);
+  }
+  return exitCode;
+}
+function dispatchSubstrateCopy(targetDir, force, verbose) {
+  let result;
+  try {
+    result = copySubstrate(targetDir, { force });
+  } catch (e) {
+    const err = e;
+    process.stderr.write(
+      `bassclef init: substrate copy failed — ${err.message}
+  cause: the installed @thebassclef/core package is missing the bundled substrate manifest.
+  fix: reinstall with \`npm install -g @thebassclef/core@latest --force\`.
+       If the reinstall does not help, file an issue at
+       https://github.com/sunj-labs/bassclef-cli/issues with your package version.
+`
+    );
+    process.exit(2);
+  }
+  if (result.copied.length === 0 && result.refused.length === 0 && result.errored.length === 0) {
+    return;
+  }
+  const groupCounts = /* @__PURE__ */ new Map();
+  for (const path of result.copied) {
+    const parts2 = path.split("/");
+    const top = parts2.length >= 2 ? parts2.slice(0, 2).join("/") : parts2[0] ?? "";
+    groupCounts.set(top, (groupCounts.get(top) ?? 0) + 1);
+  }
+  for (const [directory, count] of groupCounts) {
+    process.stdout.write(`  ${directory}: ${count} files copied
+`);
+  }
+  const parts = [];
+  if (result.copied.length > 0) parts.push(`${result.copied.length} substrate files copied`);
+  if (result.refused.length > 0) parts.push(`${result.refused.length} refused`);
+  if (result.errored.length > 0) parts.push(`${result.errored.length} error(s)`);
+  process.stdout.write(`bassclef init: ${parts.join(", ")}.
+`);
+  if (verbose && result.erroredMessages) {
+    for (const msg of result.erroredMessages) {
+      process.stderr.write(`  substrate: ${msg}
+`);
+    }
+  }
+}
+function runDryRun$1(plans) {
+  for (const p of plans) {
+    let planned;
+    let extra = "";
+    if (!node_fs.existsSync(p.fullPath)) {
+      planned = "would create";
+    } else {
+      try {
+        const st = node_fs.lstatSync(p.fullPath);
+        if (st.isSymbolicLink()) {
+          planned = "would refuse";
+          extra = " (symlink at target)";
+        } else {
+          planned = "would skip";
+          extra = " (already exists — use --force)";
+        }
+      } catch {
+        planned = "would skip";
+      }
+    }
+    process.stdout.write(`  ${planned.padEnd(14)} ${p.fullPath}${extra}
+`);
+  }
+  return 0;
+}
+function runReal$1(plans, force, verbose, targetDir) {
+  const results = [];
+  let anyRefused = false;
+  let anyError = false;
+  for (const p of plans) {
+    const parent = node_path.dirname(p.fullPath);
+    try {
+      mkdirSafely(parent);
+    } catch (e) {
+      if (e instanceof WriteError) {
+        results.push({ plan: p, outcome: "error", message: e.message });
+        anyError = true;
+        continue;
+      }
+      throw e;
+    }
+    try {
+      writeSafely(p.fullPath, p.content, { force });
+      results.push({ plan: p, outcome: "created" });
+    } catch (e) {
+      if (e instanceof WriteError) {
+        if (e.kind === "AlreadyExists") {
+          results.push({ plan: p, outcome: "unchanged" });
+          anyRefused = true;
+          continue;
+        }
+        if (e.kind === "SymlinkRefused") {
+          results.push({ plan: p, outcome: "refused", message: e.message });
+          anyError = true;
+          continue;
+        }
+        results.push({ plan: p, outcome: "error", message: e.message });
+        anyError = true;
+        continue;
+      }
+      throw e;
+    }
+  }
+  const created = results.filter((r) => r.outcome === "created").length;
+  const unchanged = results.filter((r) => r.outcome === "unchanged").length;
+  const errored = results.filter((r) => r.outcome === "error");
+  const refused = results.filter((r) => r.outcome === "refused").length;
+  if (verbose) {
+    for (const r of results) {
+      let label;
+      if (r.outcome === "error") label = `error (${r.message ?? "unknown"})`;
+      else if (r.outcome === "refused") label = "refused";
+      else label = r.outcome;
+      process.stdout.write(`  ${label.padEnd(10)} ${r.plan.fullPath}
+`);
+    }
+  }
+  for (const r of errored) {
+    const tag = r.outcome === "refused" ? "refused" : "error";
+    process.stderr.write(`bassclef init: ${tag}: ${r.message ?? "write failed"}: ${r.plan.fullPath}
+`);
+  }
+  writeManifest(targetDir, results);
+  if (anyError) {
+    const parts = [];
+    if (created > 0) parts.push(`${created} created`);
+    if (unchanged > 0) parts.push(`${unchanged} unchanged`);
+    if (refused > 0) parts.push(`${refused} refused`);
+    const otherErrors = errored.length - refused;
+    if (otherErrors > 0) parts.push(`${otherErrors} error(s)`);
+    process.stderr.write(`bassclef init: ${parts.join(", ")}.
+`);
+    return 2;
+  }
+  if (created === 0 && unchanged === plans.length) {
+    process.stdout.write("bassclef init: already initialized. No changes.\n");
+    return 0;
+  }
+  if (anyRefused && created > 0) {
+    process.stdout.write(
+      `bassclef init: ${created} created, ${unchanged} unchanged. Pass --force to overwrite.
+`
+    );
+    process.stdout.write(
+      `bassclef init: your substrate lives under .claude/. Add .claude/ to .gitignore if you have not.
+`
+    );
+    return 0;
+  }
+  process.stdout.write(`bassclef init: ${created} created, ${unchanged} unchanged.
+`);
+  process.stdout.write(
+    `bassclef init: your substrate lives under .claude/. Add .claude/ to .gitignore if you have not.
+`
+  );
+  return 0;
+}
+function shouldRefuseRoot(currentUid, allowRoot) {
+  if (currentUid === void 0) return false;
+  if (currentUid !== 0) return false;
+  return !allowRoot;
+}
+function writeManifest(targetDir, results) {
+  const entries = results.map((r) => {
+    const entry = {
+      path: r.plan.relativePath,
+      template: r.plan.templateName,
+      template_version: r.plan.templateVersion,
+      outcome: r.outcome
+    };
+    if (r.outcome === "created") {
+      entry.content_hash_sha256 = hashContent(r.plan.content);
+      entry.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    }
+    return entry;
+  });
+  const manifestDir = node_path.join(targetDir, ".bassclef");
+  const manifestPath = node_path.join(manifestDir, "init.manifest.json");
+  const content = manifestTemplate({
+    pkgVersion: index.version,
+    targetDir,
+    files: entries
+  });
+  try {
+    mkdirSafely(manifestDir);
+    writeSafely(manifestPath, content, { force: true });
+  } catch {
+  }
+}
+function usage$2() {
+  return [
+    "",
+    "Usage:",
+    "  bassclef init [options]",
+    "",
+    "Options:",
+    "  --dir <path>       Target directory. Default: current working directory.",
+    "  --force            Overwrite existing files. Default: refuse.",
+    "  --dry-run          Print what would happen; write nothing.",
+    "  --allow-root       Allow running as root. Default: refuse.",
+    "  --allow-any-dir    Allow --dir outside your home directory. Default: refuse.",
+    "  --verbose          Print per-file result.",
+    "",
+    "Files written under <target>:",
+    "  .claude/settings.json          Claude Code settings (minimal, opt-in blocks)",
+    "  substrate.config.md            Bassclef project manifest",
+    "  .bassclef/init.manifest.json   Record of what init wrote (used by sync)",
+    ""
+  ].join("\n");
+}
+const DEFAULTS$1 = {
+  force: false,
+  replaceEdits: false,
+  dryRun: false,
+  diff: false,
+  verbose: false,
+  allowRoot: false,
+  allowAnyDir: false,
+  dir: void 0
+};
+class SyncArgvError extends Error {
+  name = "SyncArgvError";
+}
+function parseSyncArgs(argv) {
+  const out = { ...DEFAULTS$1 };
+  let i = 0;
+  while (i < argv.length) {
+    const token = argv[i];
+    if (token === "--force") {
+      out.force = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--replace-edits") {
+      out.replaceEdits = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--dry-run") {
+      out.dryRun = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--diff") {
+      out.diff = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--verbose") {
+      out.verbose = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--allow-root") {
+      out.allowRoot = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--allow-any-dir") {
+      out.allowAnyDir = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--dir") {
+      const value = argv[i + 1];
+      if (value === void 0 || value.startsWith("--")) {
+        throw new SyncArgvError("--dir requires a value");
+      }
+      out.dir = value;
+      i += 2;
+      continue;
+    }
+    if (token.startsWith("--dir=")) {
+      out.dir = token.slice("--dir=".length);
+      i += 1;
+      continue;
+    }
+    if (token.startsWith("--")) {
+      throw new SyncArgvError(`unknown flag: ${token}`);
+    }
+    throw new SyncArgvError(`unexpected argument: ${token}`);
+  }
+  return out;
+}
+const TEMPLATES = [
+  {
+    templateName: "settings.json",
+    currentVersion: SETTINGS_TEMPLATE_VERSION,
+    render: settingsJsonTemplate,
+    hasMarker: (c) => c.includes('"$bassclef"')
+  },
+  {
+    templateName: "substrate.config.md",
+    currentVersion: SUBSTRATE_CONFIG_TEMPLATE_VERSION,
+    render: substrateConfigMdTemplate,
+    hasMarker: (c) => c.includes("bassclef_template:")
+  }
+];
+function runSync(argv) {
+  let args;
+  try {
+    args = parseSyncArgs(argv);
+  } catch (e) {
+    if (e instanceof SyncArgvError) {
+      process.stderr.write(`bassclef sync: ${e.message}
+`);
+      process.stderr.write(usage$1());
+      return 3;
+    }
+    throw e;
+  }
+  const currentUid = typeof process.getuid === "function" ? process.getuid() : void 0;
+  if (shouldRefuseRoot(currentUid, args.allowRoot)) {
+    process.stderr.write(
+      "bassclef sync: refusing to run as root. Pass --allow-root if this is intentional.\n"
+    );
+    return 1;
+  }
+  let targetDir;
+  try {
+    targetDir = resolveTargetDir({
+      cwd: process.cwd(),
+      cliArg: args.dir,
+      allowAnyDir: args.allowAnyDir
+    });
+  } catch (e) {
+    if (e instanceof ResolveError) {
+      process.stderr.write(`bassclef sync: ${e.message}
+`);
+      return 1;
+    }
+    throw e;
+  }
+  let manifest;
+  try {
+    manifest = readManifest(targetDir);
+  } catch (e) {
+    if (e instanceof ManifestReadError) {
+      process.stderr.write(`bassclef sync: ${e.message}
+`);
+      if (e.kind === "SchemaTooNew") return 4;
+      return 1;
+    }
+    throw e;
+  }
+  const decisions = manifest.files.map(
+    (entry) => classify(entry, targetDir, args)
+  );
+  if (args.dryRun) {
+    return runDryRun(decisions, args.diff);
+  }
+  return runReal(decisions, targetDir, manifest, args.verbose);
+}
+function classify(entry, targetDir, args) {
+  const fullPath = node_path.join(targetDir, entry.path);
+  const spec = TEMPLATES.find((t) => t.templateName === entry.template);
+  if (spec === void 0) {
+    return {
+      entry,
+      fullPath,
+      spec: void 0,
+      case: { kind: "Current" },
+      // unknown template — treat as no-op with a note
+      action: "no-op",
+      refusalReason: `unknown template: ${entry.template}`
+    };
+  }
+  if (!node_fs.existsSync(fullPath)) {
+    const canRestore = args.force && args.replaceEdits;
+    return {
+      entry,
+      fullPath,
+      spec,
+      case: { kind: "Deleted" },
+      action: canRestore ? "update" : "refuse",
+      refusalReason: canRestore ? void 0 : `${entry.path} — you have deleted this file since init. Sync will not recreate it without both --force and --replace-edits.`,
+      nextStep: canRestore ? void 0 : "bassclef sync --force --replace-edits"
+    };
+  }
+  let currentContent;
+  try {
+    currentContent = node_fs.readFileSync(fullPath, "utf8");
+  } catch (e) {
+    const err = e;
+    return {
+      entry,
+      fullPath,
+      spec,
+      case: { kind: "Edited", manifestUpdatedAt: entry.updated_at, currentMtime: "unknown" },
+      action: "refuse",
+      refusalReason: `${entry.path} — cannot read (${err.code ?? "unknown"}).`
+    };
+  }
+  if (!spec.hasMarker(currentContent)) {
+    return {
+      entry,
+      fullPath,
+      spec,
+      case: { kind: "NoMarker" },
+      action: "refuse",
+      refusalReason: `${entry.path} — file is not managed by bassclef (no $bassclef marker). Sync will not overwrite it.`
+    };
+  }
+  if (entry.content_hash_sha256 === void 0) {
+    return {
+      entry,
+      fullPath,
+      spec,
+      case: { kind: "UnknownHash" },
+      action: "refuse",
+      refusalReason: `${entry.path} — manifest lacks content hash. This can happen on manifests written before content-hash tracking. Repair via \`bassclef init --force\` (drops any adopter edits) or add the current hash by hand.`,
+      nextStep: "bassclef init --force"
+    };
+  }
+  const currentHash = hashContent(currentContent);
+  const templateOutput = spec.render(index.version);
+  const templateOutputHash = hashContent(templateOutput);
+  const currentTemplateVersion = spec.currentVersion;
+  const versionOutdated = currentTemplateVersion !== entry.template_version;
+  const adopterEdited = currentHash !== entry.content_hash_sha256;
+  const wouldChange = templateOutputHash !== currentHash;
+  if (!wouldChange) {
+    return { entry, fullPath, spec, case: { kind: "Current" }, action: "no-op" };
+  }
+  if (adopterEdited) {
+    const mtime = safeMtimeIso(fullPath);
+    const versionNote = versionOutdated ? `
+  a template update is also pending: ${entry.template_version} → ${currentTemplateVersion}` : "";
+    return {
+      entry,
+      fullPath,
+      spec,
+      case: {
+        kind: "Edited",
+        manifestUpdatedAt: entry.updated_at,
+        currentMtime: mtime
+      },
+      action: args.replaceEdits ? "update" : "refuse",
+      refusalReason: args.replaceEdits ? void 0 : `${entry.path} — content differs from what init/sync last recorded.
+  either you edited the file, or a prior sync did not finish.
+  last sync recorded:  ${entry.updated_at ?? "(unknown)"}
+  file mtime is now:   ${mtime}` + versionNote + `
+Run \`bassclef sync --diff\` to see the change.
+Run \`bassclef sync --replace-edits\` to replace your edits.`,
+      nextStep: args.replaceEdits ? void 0 : "bassclef sync --replace-edits"
+    };
+  }
+  if (versionOutdated) {
+    return {
+      entry,
+      fullPath,
+      spec,
+      case: {
+        kind: "NeedsUpdate",
+        fromVersion: entry.template_version,
+        toVersion: currentTemplateVersion
+      },
+      action: args.force ? "update" : "refuse",
+      refusalReason: args.force ? void 0 : `${entry.path} — update available (template ${entry.template_version} → ${currentTemplateVersion}). Run \`bassclef sync --force\` to apply.`,
+      nextStep: args.force ? void 0 : "bassclef sync --force"
+    };
+  }
+  return { entry, fullPath, spec, case: { kind: "Current" }, action: "no-op" };
+}
+function safeMtimeIso(path) {
+  try {
+    return node_fs.statSync(path).mtime.toISOString();
+  } catch {
+    return "unknown";
+  }
+}
+function runDryRun(decisions, showDiff) {
+  let anyChange = false;
+  for (const d of decisions) {
+    const label = describeCase(d.case);
+    process.stdout.write(`  ${label.padEnd(18)} ${d.entry.path}
+`);
+    if (d.action === "update" || d.action === "refuse") anyChange = true;
+    if (showDiff && d.spec !== void 0 && d.case.kind !== "Current") {
+      process.stdout.write(`      template current: ${d.spec.currentVersion}
+`);
+      process.stdout.write(`      manifest recorded: ${d.entry.template_version}
+`);
+    }
+  }
+  if (!anyChange) {
+    process.stdout.write("bassclef sync: all up to date.\n");
+  }
+  return 0;
+}
+function runReal(decisions, targetDir, manifest, verbose) {
+  let updated = 0;
+  let refused = 0;
+  let errors = 0;
+  let noChange = 0;
+  for (const d of decisions) {
+    if (d.action === "no-op") {
+      noChange += 1;
+      continue;
+    }
+    if (d.action === "refuse") {
+      refused += 1;
+      process.stderr.write(`bassclef sync: refused: ${d.refusalReason ?? d.entry.path}
+`);
+      continue;
+    }
+    if (d.spec === void 0) {
+      noChange += 1;
+      continue;
+    }
+    const newContent = d.spec.render(index.version);
+    const newHash = hashContent(newContent);
+    const parent = d.fullPath.substring(0, d.fullPath.lastIndexOf("/"));
+    let preservedMode = 420;
+    try {
+      preservedMode = node_fs.lstatSync(d.fullPath).mode & 511;
+    } catch {
+    }
+    try {
+      mkdirSafely(parent);
+      writeSafely(d.fullPath, newContent, { force: true, mode: preservedMode });
+    } catch (e) {
+      errors += 1;
+      const msg = e instanceof WriteError ? e.message : e.message;
+      process.stderr.write(`bassclef sync: write failed: ${d.entry.path}: ${msg}
+`);
+      continue;
+    }
+    updateManifestEntry(manifest, d.entry.path, {
+      content_hash_sha256: newHash,
+      template_version: d.spec.currentVersion,
+      updated_at: (/* @__PURE__ */ new Date()).toISOString(),
+      outcome: "updated"
+    });
+    try {
+      writeManifest$1(targetDir, manifest);
+    } catch (e) {
+      errors += 1;
+      process.stderr.write(`bassclef sync: manifest update failed after writing ${d.entry.path}: ${e.message}
+`);
+      continue;
+    }
+    updated += 1;
+    process.stdout.write(`  updated  ${d.entry.path}
+`);
+  }
+  emitL2Output(decisions, verbose);
+  const parts = [];
+  if (updated > 0) parts.push(`${updated} updated`);
+  if (noChange > 0) parts.push(`${noChange} up to date`);
+  if (refused > 0) parts.push(`${refused} refused`);
+  if (errors > 0) parts.push(`${errors} error(s)`);
+  if (parts.length === 0) parts.push("nothing to do");
+  const summary = parts.join(", ");
+  if (errors > 0) {
+    process.stderr.write(`bassclef sync: ${summary}.
+`);
+    return 2;
+  }
+  if (refused > 0) {
+    process.stderr.write(`bassclef sync: ${summary}.
+`);
+    return 1;
+  }
+  process.stdout.write(`bassclef sync: ${summary}.
+`);
+  return 0;
+}
+function emitL2Output(decisions, verbose) {
+  if (decisions.length === 0) return;
+  if (verbose) {
+    for (const d of decisions) {
+      const status = describeCase(d.case);
+      process.stdout.write(`  ${d.entry.path}: ${status}
+`);
+    }
+    return;
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (const d of decisions) {
+    const parts = d.entry.path.split("/");
+    const top = parts.length >= 2 ? parts.slice(0, 2).join("/") : parts[0] ?? "";
+    const status = describeCase(d.case);
+    let group = groups.get(top);
+    if (group === void 0) {
+      group = { count: 0, statuses: /* @__PURE__ */ new Map() };
+      groups.set(top, group);
+    }
+    group.count += 1;
+    group.statuses.set(status, (group.statuses.get(status) ?? 0) + 1);
+  }
+  for (const [directory, group] of groups) {
+    let statusSummary;
+    if (group.statuses.size === 1) {
+      statusSummary = Array.from(group.statuses.keys())[0];
+    } else {
+      const bits = [];
+      for (const [status, count] of group.statuses) {
+        bits.push(`${count} ${status}`);
+      }
+      statusSummary = bits.join(", ");
+    }
+    const files = group.count === 1 ? "file" : "files";
+    process.stdout.write(`  ${directory}: ${group.count} ${files} (${statusSummary})
+`);
+  }
+}
+function updateManifestEntry(manifest, path, patch) {
+  const idx = manifest.files.findIndex((f) => f.path === path);
+  if (idx < 0) {
+    manifest.files.push({
+      path,
+      template: patch.template ?? path,
+      template_version: patch.template_version ?? "0.0.1",
+      outcome: "updated",
+      ...patch
+    });
+    return;
+  }
+  manifest.files[idx] = { ...manifest.files[idx], ...patch };
+}
+function describeCase(c) {
+  switch (c.kind) {
+    case "Current":
+      return "up to date";
+    case "NeedsUpdate":
+      return `update ${c.fromVersion}→${c.toVersion}`;
+    case "Edited":
+      return "edited by you";
+    case "Deleted":
+      return "deleted by you";
+    case "NoMarker":
+      return "no marker";
+    case "UnknownHash":
+      return "no hash in manifest";
+  }
+}
+function usage$1() {
+  return [
+    "",
+    "Usage:",
+    "  bassclef sync [options]",
+    "",
+    "Options:",
+    "  --dir <path>       Target directory. Default: current working directory.",
+    "  --force            Apply available template updates. Default: refuse.",
+    "  --replace-edits    Replace files you have edited. Default: refuse.",
+    "  --dry-run          Print per-file status; write nothing.",
+    "  --diff             Show template version change per file (--dry-run friendly).",
+    "  --allow-root       Allow running as root. Default: refuse.",
+    "  --allow-any-dir    Allow --dir outside your home directory. Default: refuse.",
+    "  --verbose          Print per-file result.",
+    "",
+    "Sync reads .bassclef/init.manifest.json in the target directory.",
+    "It updates only files listed in the manifest that carry the $bassclef marker.",
+    ""
+  ].join("\n");
+}
+const DEFAULTS = {
+  dryRun: false,
+  verbose: false,
+  yes: false,
+  allowRoot: false,
+  allowAnyDir: false,
+  dir: void 0
+};
+class ArgvError2 extends Error {
+  name = "ArgvError";
+}
+function parseMigrateArgs(argv) {
+  const out = { ...DEFAULTS };
+  let i = 0;
+  while (i < argv.length) {
+    const token = argv[i];
+    if (token === "--dry-run") {
+      out.dryRun = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--verbose") {
+      out.verbose = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--yes") {
+      out.yes = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--allow-root") {
+      out.allowRoot = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--allow-any-dir") {
+      out.allowAnyDir = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--dir") {
+      const value = argv[i + 1];
+      if (value === void 0 || value.startsWith("--")) {
+        throw new ArgvError2("--dir requires a value");
+      }
+      out.dir = value;
+      i += 2;
+      continue;
+    }
+    if (token.startsWith("--dir=")) {
+      out.dir = token.slice("--dir=".length);
+      i += 1;
+      continue;
+    }
+    if (token.startsWith("--")) {
+      throw new ArgvError2(`unknown flag: ${token}`);
+    }
+    throw new ArgvError2(`unexpected argument: ${token}`);
+  }
+  return out;
+}
+async function confirm(question, opts = {}) {
+  const { defaultNo = true, ttyOverride = null } = opts;
+  if (ttyOverride === "yes") return true;
+  if (ttyOverride === "no") return false;
+  if (!node_process.stdin.isTTY) {
+    node_process.stderr.write(
+      `bassclef: no terminal detected; declining prompt.
+         Run with --yes for non-interactive mode.
+`
+    );
+    return false;
+  }
+  const rl = promises.createInterface({ input: node_process.stdin, output: node_process.stdout });
+  try {
+    const suffix = defaultNo ? " [y/N] " : " [Y/n] ";
+    const answer = (await rl.question(question + suffix)).trim().toLowerCase();
+    if (answer === "") return !defaultNo;
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+async function detectAdopterState(targetDir) {
+  let manifest;
+  try {
+    manifest = readManifest(targetDir);
+  } catch (e) {
+    if (e instanceof ManifestReadError) {
+      if (e.kind === "Missing") return "no-manifest";
+      return { kind: "error", message: e.message };
+    }
+    throw e;
+  }
+  const isLegacy = manifest.files.length === 3;
+  const schemaLegacy = manifest.$bassclef.manifest_schema_version.startsWith("0.0.");
+  if (isLegacy || schemaLegacy) return "legacy-3-entry";
+  if (manifest.files.length === CURRENT_ENTRY_COUNT) return "current";
+  return {
+    kind: "unknown",
+    message: `manifest has ${manifest.files.length} entries; expected 3 (legacy) or ${CURRENT_ENTRY_COUNT} (current)`
+  };
+}
+async function runPathA(targetDir, _existingManifest, args, opts = {}) {
+  const configHashes = await computeConfigHashes(targetDir, [...CONFIG_FILES]);
+  const ttyOverride = args.yes ? "yes" : null;
+  const proceed = await confirm(
+    `Ready to migrate to 0.1.0. Adds substrate files; preserves ${Object.keys(configHashes).length} existing config files.
+Proceed?`,
+    { defaultNo: true, ttyOverride }
+  );
+  if (!proceed) {
+    process.stdout.write("bassclef migrate: aborted. No files changed.\n");
+    return { added: [], preserved: [], refused: [], errored: [], exitCode: 0 };
+  }
+  if (args.dryRun) {
+    process.stdout.write(
+      `bassclef migrate: dry-run — would add substrate files; would preserve ${Object.keys(configHashes).length} config files.
+`
+    );
+    return { added: [], preserved: Object.keys(configHashes), refused: [], errored: [], exitCode: 0 };
+  }
+  const copyResult = copySubstrate(targetDir, { force: false, bundleRoot: opts.bundleRoot });
+  const added = copyResult.copied;
+  const preserved = copyResult.refused.filter(
+    (p) => CONFIG_FILES.includes(p)
+  );
+  const refused = copyResult.refused.filter(
+    (p) => !CONFIG_FILES.includes(p)
+  );
+  const errored = copyResult.errored;
+  const newManifest = {
+    $bassclef: {
+      template: "init.manifest.json",
+      manifest_schema_version: "0.1.0",
+      generated_by: "@thebassclef/core",
+      generated_by_version: index.version
+    },
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    target_dir: targetDir,
+    files: [
+      ...added.map((path) => ({
+        path,
+        template: basename(path),
+        template_version: "0.1.0",
+        outcome: "created"
+      })),
+      ...preserved.map((path) => ({
+        path,
+        template: basename(path),
+        template_version: "0.1.0",
+        content_hash_sha256: configHashes[path],
+        outcome: "unchanged"
+      }))
+    ]
+  };
+  writeManifest$1(targetDir, newManifest);
+  const parts = [
+    `${added.length} added`,
+    `${preserved.length} preserved with existing content`,
+    ...refused.length > 0 ? [`${refused.length} refused`] : [],
+    ...errored.length > 0 ? [`${errored.length} errored`] : []
+  ];
+  process.stdout.write(`bassclef migrate: ${parts.join("; ")}.
+`);
+  process.stdout.write(
+    `bassclef migrate: your substrate lives under .claude/. Add .claude/ to .gitignore if you have not.
+`
+  );
+  const exitCode = errored.length > 0 ? 1 : refused.length > 0 ? 2 : 0;
+  return { added, preserved, refused, errored, exitCode };
+}
+async function runPathB(targetDir, args) {
+  process.stdout.write(
+    `bassclef migrate: no prior manifest detected. Running full init for ${CURRENT_ENTRY_COUNT} files.
+`
+  );
+  const initArgv = [];
+  if (args.dir) initArgv.push("--dir", args.dir);
+  if (args.dryRun) initArgv.push("--dry-run");
+  if (args.verbose) initArgv.push("--verbose");
+  if (args.allowRoot) initArgv.push("--allow-root");
+  if (args.allowAnyDir) initArgv.push("--allow-any-dir");
+  initArgv.push("--force");
+  const exitCode = runInit(initArgv);
+  if (exitCode === 0) {
+    process.stdout.write(
+      `bassclef migrate: your substrate lives under .claude/. Add .claude/ to .gitignore if you have not.
+`
+    );
+  }
+  return {
+    added: exitCode === 0 ? Array(CURRENT_ENTRY_COUNT).fill("(via init)") : [],
+    preserved: [],
+    refused: [],
+    errored: [],
+    exitCode
+  };
+}
+function basename(path) {
+  const parts = path.split("/");
+  return parts[parts.length - 1] ?? path;
+}
+function usage() {
+  return `bassclef migrate — upgrade adopter substrate to the current shape
+
+Usage:
+  bassclef migrate [options]
+
+Options:
+  --dry-run          Preview the shape without writing anything
+  --verbose          Print one line per file (not just the summary)
+  --yes              Skip the interactive confirmation prompt (CI + scripts)
+  --allow-root       Allow running as root
+  --allow-any-dir    Allow a target outside the current user's home
+  --dir <path>       Target directory (defaults to current working dir)
+  --help             Print this message
+
+Two upgrade paths run automatically based on adopter state:
+  0.0.2 legacy install → Path A: adds 146 substrate files; preserves
+                         the 3 edited config files via SHA-256 hash
+  0.0.1 name-reservation → Path B: full init for all 149 files
+
+Exit codes:
+  0  success (files landed, or already at current shape, or user aborted)
+  1  argv error, root check failed, or manifest could not be read
+  2  one or more per-file writes refused (symlink, parent not writable)
+  4  manifest schema version newer than this migrate knows about
+  5  adopter state does not match 0.0.x or 0.1.0 — reinstall @thebassclef/core
+`;
+}
+async function runMigrate(argv) {
+  let args;
+  try {
+    args = parseMigrateArgs(argv);
+  } catch (e) {
+    if (e instanceof ArgvError2) {
+      process.stderr.write(`bassclef migrate: ${e.message}
+`);
+      return 1;
+    }
+    throw e;
+  }
+  const uid = typeof process.getuid === "function" ? process.getuid() : void 0;
+  if (shouldRefuseRoot(uid, args.allowRoot)) {
+    process.stderr.write(
+      `bassclef migrate: refusing to run as root. Pass --allow-root to override, or run as the project owner.
+`
+    );
+    return 1;
+  }
+  const targetDir = args.dir ?? process.cwd();
+  const state = await detectAdopterState(targetDir);
+  if (state === "current") {
+    process.stdout.write("bassclef migrate: already at 0.1.0 shape. Nothing to migrate.\n");
+    return 0;
+  }
+  if (state === "no-manifest") {
+    const result = await runPathB(targetDir, args);
+    return result.exitCode;
+  }
+  if (state === "legacy-3-entry") {
+    const manifest = readManifest(targetDir);
+    const result = await runPathA(targetDir, manifest, args);
+    return result.exitCode;
+  }
+  if (state.kind === "unknown") {
+    process.stderr.write(
+      `bassclef migrate: adopter state does not match 0.0.x or 0.1.0. Reinstall @thebassclef/core then rerun. (${state.message})
+`
+    );
+    return 5;
+  }
+  if (state.kind === "error") {
+    process.stderr.write(`bassclef migrate: ${state.message}
+`);
+    if (state.message.includes("newer than this package")) return 4;
+    return 1;
+  }
+  return 1;
+}
+const USAGE = `bassclef — install and upgrade bassclef in your project
+
+Usage:
+  bassclef init [options]    Write bassclef config into a project directory
+  bassclef sync [options]    Update bassclef-managed files in place
+  bassclef migrate [options] Upgrade adopter substrate to the current shape
+  bassclef --version         Print the running version
+  bassclef --help            Print this message
+
+Run \`bassclef init --help\` for init options + the safety defaults.
+Run \`bassclef sync --help\` for sync options + the update semantics.
+Run \`bassclef migrate --help\` for migrate options + the upgrade paths.
+
+Version: ${index.version}
+Docs:    https://github.com/sunj-labs/bassclef-cli
+`;
+async function main(argv) {
+  const first = argv[0];
+  if (first === void 0 || first === "--help" || first === "-h" || first === "help") {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (first === "--version" || first === "-v" || first === "version") {
+    process.stdout.write(`${index.version}
+`);
+    return 0;
+  }
+  if (first === "init") {
+    const rest = argv.slice(1);
+    if (rest.includes("--help") || rest.includes("-h")) {
+      process.stdout.write(usage$2());
+      return 0;
+    }
+    return runInit(rest);
+  }
+  if (first === "sync") {
+    const rest = argv.slice(1);
+    if (rest.includes("--help") || rest.includes("-h")) {
+      process.stdout.write(usage$1());
+      return 0;
+    }
+    return runSync(rest);
+  }
+  if (first === "migrate") {
+    const rest = argv.slice(1);
+    if (rest.includes("--help") || rest.includes("-h")) {
+      process.stdout.write(usage());
+      return 0;
+    }
+    return await runMigrate(rest);
+  }
+  process.stderr.write(
+    `bassclef: unknown command '${first}'
+
+` + USAGE
+  );
+  return 3;
+}
+main(process.argv.slice(2)).then((exitCode) => process.exit(exitCode)).catch((err) => {
+  process.stderr.write(`bassclef: ${err.message ?? String(err)}
+`);
+  process.exit(1);
+});