bc-pkg 1.0.0 → 1.0.2

package/bin/bc-pkg.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 'use strict';
 
-// bc-pkg — bootstraps babashka + a Temurin JDK on first use, then
-// forwards all arguments to `bb`. Single-file launcher, no build step.
+// bc-pkg — creates/reuses a BigConfig CLI in the current directory and runs it.
+// The target package can be implemented in Clojure, TypeScript, or Python. The
+// target language is inferred from the package's pinned GitHub content.
 
 const fs = require('fs');
 const os = require('os');
@@ -11,24 +12,659 @@ const { spawn, spawnSync } = require('child_process');
 const { Readable } = require('stream');
 const { pipeline } = require('stream/promises');
 
-// Pinned, known-good versions. Overridable via env.
 const DEFAULT_BB_VERSION = process.env.BB_VERSION || '1.12.196';
 const DEFAULT_JDK_VERSION = process.env.JDK_VERSION || '21';
-const REWRITE_EDN_VERSION = process.env.REWRITE_EDN_VERSION || '0.5.9';
-
 const TAG = '[bc-pkg]';
+const FULL_SHA_RE = /^[0-9a-fA-F]{40}$/;
+const SPEC_RE = /^([^/\s@]+)\/([^/\s@]+)@([^\s]+)$/;
 
 function log(msg) {
-  // stderr so stdout stays clean for bb's own output.
   process.stderr.write(`${TAG} ${msg}\n`);
 }
 
-// --- Platform resolution -------------------------------------------------
+function fail(msg) {
+  throw new Error(msg);
+}
+
+function usage() {
+  return `Usage:\n  bc-pkg <owner/repo@ref> <args...>\n  bc-pkg <local-path> <args...>\n  bc-pkg <args...>\n\nExamples:\n  npx bc-pkg bigconfig-ai/once@typescript package validate\n  npx bc-pkg ../once/typescript package validate\n  npx bc-pkg package validate`;
+}
+
+// --- generic process helpers -------------------------------------------
+
+function commandWorks(cmd, args = ['--version']) {
+  const r = spawnSync(cmd, args, { stdio: 'ignore' });
+  return !r.error && r.status === 0;
+}
+
+function binExists(cmd) {
+  return !spawnSync(cmd, ['--version'], { stdio: 'ignore' }).error;
+}
+
+function runCommand(cmd, args, options = {}) {
+  const child = spawn(cmd, args, {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+    env: process.env,
+    ...options,
+  });
+
+  const forward = (sig) => {
+    try {
+      child.kill(sig);
+    } catch {
+      // child already gone
+    }
+  };
+  process.on('SIGINT', forward);
+  process.on('SIGTERM', forward);
+
+  return new Promise((resolve) => {
+    child.on('error', (err) => {
+      log(`failed to start ${cmd}: ${err.message}`);
+      resolve(127);
+    });
+    child.on('exit', (code, signal) => {
+      resolve(signal ? 1 : code == null ? 1 : code);
+    });
+  });
+}
+
+function whichPython() {
+  if (commandWorks('python3')) return 'python3';
+  if (commandWorks('python')) return 'python';
+  return null;
+}
+
+function requireCommand(cmd, installHint) {
+  if (!commandWorks(cmd)) {
+    fail(`${cmd} is required but was not found on PATH.${installHint ? `\n  ${installHint}` : ''}`);
+  }
+}
+
+// --- GitHub --------------------------------------------------------------
+
+function parseSpec(arg) {
+  const m = arg && arg.match(SPEC_RE);
+  if (!m) return null;
+  return { owner: m[1], repo: m[2], ref: m[3], slug: `${m[1]}/${m[2]}` };
+}
+
+// A normal local path: leading slash, dot-slash, or tilde. Bare names with no
+// path prefix are treated as forwarded args, not local targets.
+function isLocalSpec(arg) {
+  if (!arg) return false;
+  if (arg === '.' || arg === '..') return true;
+  if (arg.startsWith('/') || arg.startsWith('~') || arg.startsWith('./') || arg.startsWith('../')) return true;
+  if (process.platform === 'win32') {
+    if (arg.startsWith('.\\') || arg.startsWith('..\\') || arg.startsWith('\\')) return true;
+    if (/^[A-Za-z]:[\\/]/.test(arg)) return true;
+  }
+  return false;
+}
+
+function parseLocalSpec(arg) {
+  let p = arg;
+  if (p === '~' || p.startsWith('~/') || p.startsWith('~\\')) {
+    p = path.join(os.homedir(), p.slice(1));
+  }
+  const abs = path.resolve(process.cwd(), p);
+  let resolved;
+  try {
+    resolved = fs.realpathSync(abs);
+  } catch {
+    fail(`local path ${JSON.stringify(arg)} is not a directory (${abs})`);
+  }
+  if (!fs.statSync(resolved).isDirectory()) {
+    fail(`local path ${JSON.stringify(arg)} is not a directory (${resolved})`);
+  }
+  return { path: resolved, name: path.basename(resolved) };
+}
+
+function ghHeaders(accept) {
+  const headers = {
+    'user-agent': 'bc-pkg',
+    accept: accept || 'application/vnd.github+json',
+    'x-github-api-version': '2022-11-28',
+  };
+  if (process.env.GITHUB_TOKEN) {
+    headers.authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+  }
+  return headers;
+}
+
+async function ghFetch(url, accept) {
+  return fetch(url, { headers: ghHeaders(accept), redirect: 'follow' });
+}
+
+async function resolveRef(spec) {
+  if (FULL_SHA_RE.test(spec.ref)) {
+    return spec.ref.toLowerCase();
+  }
+  const url = `https://api.github.com/repos/${spec.owner}/${spec.repo}/commits/${encodeURIComponent(spec.ref)}`;
+  const res = await ghFetch(url);
+  if (res.status === 404) {
+    fail(`${spec.slug}@${spec.ref} not found or not accessible (set GITHUB_TOKEN for private repos)`);
+  }
+  if (!res.ok) {
+    fail(`GitHub API error ${res.status} resolving ${spec.slug}@${spec.ref}`);
+  }
+  const data = await res.json();
+  if (!data || !data.sha) fail(`${spec.slug}@${spec.ref} did not resolve to a commit`);
+  return String(data.sha).toLowerCase();
+}
+
+async function fetchFile(spec, sha, filePath, { required = false } = {}) {
+  const url = `https://api.github.com/repos/${spec.owner}/${spec.repo}/contents/${filePath}?ref=${sha}`;
+  const res = await ghFetch(url, 'application/vnd.github.raw');
+  if (res.status === 404) {
+    if (required) fail(`${spec.slug}@${sha.slice(0, 7)} has no ${filePath}`);
+    return null;
+  }
+  if (!res.ok) {
+    fail(`GitHub API error ${res.status} fetching ${filePath} from ${spec.slug}@${sha.slice(0, 7)}`);
+  }
+  return await res.text();
+}
+
+function parseJson(text, label) {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    fail(`Invalid JSON in ${label}: ${err.message}`);
+  }
+}
+
+function parsePyProjectName(text) {
+  const project = sectionText(text, 'project');
+  const m = project && project.match(/^\s*name\s*=\s*["']([^"']+)["']/m);
+  return m ? m[1] : null;
+}
+
+function sectionText(text, name) {
+  const re = new RegExp(`^\\s*\\[${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\]\\s*$`, 'm');
+  const m = re.exec(text);
+  if (!m) return null;
+  const start = m.index + m[0].length;
+  const rest = text.slice(start);
+  const next = /^\s*\[[^\]]+\]\s*$/m.exec(rest);
+  return next ? rest.slice(0, next.index) : rest;
+}
+
+function detectTargetFromManifests(label, depsEdn, packageJsonText, pyprojectText, clojureCoord) {
+  const found = [];
+  if (depsEdn != null) found.push('clojure');
+  if (packageJsonText != null) found.push('typescript');
+  if (pyprojectText != null) found.push('python');
+  if (found.length === 0) {
+    fail(`${label} has no deps.edn, package.json, or pyproject.toml`);
+  }
+  if (found.length > 1) {
+    fail(`${label} is ambiguous; found ${found.join(', ')} manifests`);
+  }
+
+  if (found[0] === 'typescript') {
+    const pkg = parseJson(packageJsonText, 'package.json');
+    if (!pkg.name) fail(`${label} package.json has no name`);
+    return { language: 'typescript', packageName: pkg.name };
+  }
+  if (found[0] === 'python') {
+    const packageName = parsePyProjectName(pyprojectText);
+    if (!packageName) fail(`${label} pyproject.toml has no [project].name`);
+    return { language: 'python', packageName };
+  }
+  return { language: 'clojure', packageName: clojureCoord };
+}
+
+async function detectTarget(spec, sha) {
+  const [depsEdn, packageJsonText, pyprojectText] = await Promise.all([
+    fetchFile(spec, sha, 'deps.edn'),
+    fetchFile(spec, sha, 'package.json'),
+    fetchFile(spec, sha, 'pyproject.toml'),
+  ]);
+  return detectTargetFromManifests(
+    `${spec.slug}@${sha.slice(0, 7)}`,
+    depsEdn,
+    packageJsonText,
+    pyprojectText,
+    `io.github.${spec.owner}/${spec.repo}`,
+  );
+}
+
+function readLocalFile(local, filePath, { required = false } = {}) {
+  const f = path.join(local.path, filePath);
+  if (!fs.existsSync(f) || !fs.statSync(f).isFile()) {
+    if (required) fail(`${local.path} has no ${filePath}`);
+    return null;
+  }
+  return fs.readFileSync(f, 'utf8');
+}
+
+function detectTargetLocal(local) {
+  return detectTargetFromManifests(
+    local.path,
+    readLocalFile(local, 'deps.edn'),
+    readLocalFile(local, 'package.json'),
+    readLocalFile(local, 'pyproject.toml'),
+    `local/${local.name}`,
+  );
+}
+
+// --- native metadata -----------------------------------------------------
+
+function metadataFromPackageJson(file) {
+  if (!fs.existsSync(file)) return null;
+  const pkg = parseJson(fs.readFileSync(file, 'utf8'), file);
+  if (!pkg.bigconfig) return null;
+  return { ...pkg.bigconfig, language: pkg.bigconfig.language || 'typescript', manifest: file };
+}
+
+function metadataFromPyproject(file) {
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, 'utf8');
+  const sec = sectionText(text, 'tool.bigconfig');
+  if (!sec) return null;
+  const get = (key) => {
+    const m = sec.match(new RegExp(`^\\s*${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*=\\s*["']([^"']+)["']`, 'm'));
+    return m ? m[1] : undefined;
+  };
+  return {
+    repo: get('repo'),
+    ref: get('ref'),
+    sha: get('sha'),
+    language: get('language') || 'python',
+    run: get('run') || 'run',
+    packageName: get('package-name'),
+    local: /^\s*local\s*=\s*true\s*$/m.test(sec),
+    path: get('path'),
+    manifest: file,
+  };
+}
+
+function metadataFromDepsEdn(file) {
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, 'utf8');
+  if (!text.includes(':bigconfig/repo') && !text.includes(':bigconfig/path')) return null;
+  const get = (key) => {
+    const m = text.match(new RegExp(`:${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s+"([^"]+)"`));
+    return m ? m[1] : undefined;
+  };
+  return {
+    repo: get('bigconfig/repo'),
+    ref: get('bigconfig/ref'),
+    sha: get('bigconfig/sha'),
+    language: get('bigconfig/language') || 'clojure',
+    run: get('bigconfig/run') || 'run',
+    local: get('bigconfig/local') === 'true',
+    path: get('bigconfig/path'),
+    manifest: file,
+  };
+}
+
+function readMetadata(cwd = process.cwd()) {
+  const metas = [
+    metadataFromDepsEdn(path.join(cwd, 'deps.edn')),
+    metadataFromPackageJson(path.join(cwd, 'package.json')),
+    metadataFromPyproject(path.join(cwd, 'pyproject.toml')),
+  ].filter(Boolean);
+  if (metas.length > 1) {
+    fail('Multiple BigConfig metadata files found; keep only one of deps.edn, package.json, or pyproject.toml initialized for bc-pkg.');
+  }
+  if (metas.length === 0) return null;
+  const meta = metas[0];
+  if (meta.local) {
+    if (!meta.path || !meta.language) fail(`Incomplete BigConfig metadata in ${meta.manifest}`);
+  } else if (!meta.repo || !meta.ref || !meta.sha || !meta.language) {
+    fail(`Incomplete BigConfig metadata in ${meta.manifest}`);
+  }
+  return meta;
+}
+
+function validateExistingMetadata(meta, spec, sha) {
+  if (meta.local) {
+    fail('Current directory is initialized for a local BigConfig package; refusing to switch to a GitHub package.');
+  }
+  const expectedRepo = spec.slug;
+  const problems = [];
+  if (meta.repo !== expectedRepo) problems.push(`repo ${JSON.stringify(meta.repo)} != ${JSON.stringify(expectedRepo)}`);
+  if (meta.ref !== spec.ref) problems.push(`ref ${JSON.stringify(meta.ref)} != ${JSON.stringify(spec.ref)}`);
+  if (String(meta.sha).toLowerCase() !== sha.toLowerCase()) problems.push(`sha ${meta.sha} != ${sha}`);
+  if (problems.length) {
+    fail(`Current directory is already initialized for a different BigConfig package:\n  ${problems.join('\n  ')}`);
+  }
+}
+
+function validateExistingLocalMetadata(meta, local) {
+  if (!meta.local) {
+    fail('Current directory is initialized for a GitHub BigConfig package; refusing to switch to a local package.');
+  }
+  let existing = null;
+  if (meta.path) {
+    try {
+      existing = fs.realpathSync(meta.path);
+    } catch {
+      existing = path.resolve(meta.path);
+    }
+  }
+  if (existing !== local.path) {
+    fail(`Current directory is already initialized for a different local BigConfig package:\n  path ${JSON.stringify(meta.path)} != ${JSON.stringify(local.path)}`);
+  }
+}
+
+function quoteToml(s) {
+  return JSON.stringify(String(s));
+}
+
+function writeRunFile(text) {
+  const target = path.join(process.cwd(), 'run');
+  fs.writeFileSync(target, text);
+  if (process.platform !== 'win32') fs.chmodSync(target, 0o755);
+}
+
+// Local targets symlink the run file so edits to the local package flow through;
+// copy as a fallback where symlinks are unavailable.
+function linkRunFile(source) {
+  const target = path.join(process.cwd(), 'run');
+  try {
+    fs.lstatSync(target);
+    fs.rmSync(target, { force: true });
+  } catch {
+    // nothing to remove
+  }
+  try {
+    fs.symlinkSync(source, target);
+  } catch {
+    fs.copyFileSync(source, target);
+    if (process.platform !== 'win32') fs.chmodSync(target, 0o755);
+  }
+}
+
+function clojureCoord(spec) {
+  return `io.github.${spec.owner}/${spec.repo}`;
+}
+
+function writeClojureManifest(spec, sha, target) {
+  const coord = clojureCoord(spec);
+  const gitUrl = `https://github.com/${spec.owner}/${spec.repo}.git`;
+  const deps = `{:deps {${coord} {:git/url "${gitUrl}"\n                           :git/sha "${sha}"}}\n :bigconfig/repo "${spec.slug}"\n :bigconfig/ref "${spec.ref}"\n :bigconfig/sha "${sha}"\n :bigconfig/language "clojure"\n :bigconfig/run "run"}\n`;
+  fs.writeFileSync(path.join(process.cwd(), 'deps.edn'), deps);
+
+  // Babashka script execution reads bb.edn, not deps.edn. Metadata remains in
+  // deps.edn per the launcher contract; bb.edn is the runtime dependency file.
+  const bb = `{:deps {${coord} {:git/url "${gitUrl}"\n                           :git/sha "${sha}"}}}\n`;
+  fs.writeFileSync(path.join(process.cwd(), 'bb.edn'), bb);
+}
+
+function writeTypeScriptManifest(spec, sha, target) {
+  const file = path.join(process.cwd(), 'package.json');
+  let pkg = {};
+  if (fs.existsSync(file)) {
+    pkg = parseJson(fs.readFileSync(file, 'utf8'), file);
+    if (pkg.bigconfig) validateExistingMetadata(pkg.bigconfig, spec, sha);
+  }
+  pkg.type = pkg.type || 'module';
+  pkg.scripts = { ...(pkg.scripts || {}), run: 'node run' };
+  pkg.dependencies = { ...(pkg.dependencies || {}) };
+  pkg.dependencies[target.packageName] = `github:${spec.owner}/${spec.repo}#${sha}`;
+  pkg.bigconfig = {
+    repo: spec.slug,
+    ref: spec.ref,
+    sha,
+    language: 'typescript',
+    run: 'run',
+    packageName: target.packageName,
+  };
+  fs.writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+function writePythonManifest(spec, sha, target) {
+  const file = path.join(process.cwd(), 'pyproject.toml');
+  if (fs.existsSync(file)) {
+    const existing = metadataFromPyproject(file);
+    if (!existing) {
+      fail('pyproject.toml already exists and is not initialized for bc-pkg; refusing to rewrite it.');
+    }
+    validateExistingMetadata(existing, spec, sha);
+  }
+  const dep = `${target.packageName} @ git+https://github.com/${spec.owner}/${spec.repo}.git@${sha}`;
+  const text = `[project]\nname = "bigconfig-cli"\nversion = "0.1.0"\nrequires-python = ">=3.12"\ndependencies = [\n  ${quoteToml(dep)},\n]\n\n[tool.bigconfig]\nrepo = ${quoteToml(spec.slug)}\nref = ${quoteToml(spec.ref)}\nsha = ${quoteToml(sha)}\nlanguage = "python"\nrun = "run"\npackage-name = ${quoteToml(target.packageName)}\n`;
+  fs.writeFileSync(file, text);
+}
+
+function writeNativeManifest(spec, sha, target) {
+  if (target.language === 'clojure') return writeClojureManifest(spec, sha, target);
+  if (target.language === 'typescript') return writeTypeScriptManifest(spec, sha, target);
+  if (target.language === 'python') return writePythonManifest(spec, sha, target);
+  fail(`Unsupported language: ${target.language}`);
+}
+
+// --- local (live) manifests ----------------------------------------------
+
+function writeClojureManifestLocal(local, target) {
+  const coord = target.packageName || `local/${local.name}`;
+  const p = local.path;
+  const deps = `{:deps {${coord} {:local/root "${p}"}}\n :bigconfig/local "true"\n :bigconfig/path "${p}"\n :bigconfig/language "clojure"\n :bigconfig/run "run"}\n`;
+  fs.writeFileSync(path.join(process.cwd(), 'deps.edn'), deps);
+
+  // Babashka reads bb.edn; metadata stays in deps.edn per the launcher contract.
+  const bb = `{:deps {${coord} {:local/root "${p}"}}}\n`;
+  fs.writeFileSync(path.join(process.cwd(), 'bb.edn'), bb);
+}
+
+function writeTypeScriptManifestLocal(local, target) {
+  const file = path.join(process.cwd(), 'package.json');
+  let pkg = {};
+  if (fs.existsSync(file)) {
+    pkg = parseJson(fs.readFileSync(file, 'utf8'), file);
+    if (pkg.bigconfig) validateExistingLocalMetadata(metadataFromPackageJson(file), local);
+  }
+  const packageName = target.packageName || local.name;
+  pkg.type = pkg.type || 'module';
+  pkg.scripts = { ...(pkg.scripts || {}), run: 'node run' };
+  pkg.dependencies = { ...(pkg.dependencies || {}) };
+  pkg.dependencies[packageName] = `file:${local.path}`;
+  pkg.bigconfig = {
+    local: true,
+    path: local.path,
+    language: 'typescript',
+    run: 'run',
+    packageName,
+  };
+  fs.writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+function writePythonManifestLocal(local, target) {
+  const file = path.join(process.cwd(), 'pyproject.toml');
+  if (fs.existsSync(file)) {
+    const existing = metadataFromPyproject(file);
+    if (!existing) {
+      fail('pyproject.toml already exists and is not initialized for bc-pkg; refusing to rewrite it.');
+    }
+    validateExistingLocalMetadata(existing, local);
+  }
+  const packageName = target.packageName || local.name;
+  const text = `[project]\nname = "bigconfig-cli"\nversion = "0.1.0"\nrequires-python = ">=3.12"\ndependencies = [\n  ${quoteToml(packageName)},\n]\n\n[tool.uv.sources]\n${quoteToml(packageName)} = { path = ${quoteToml(local.path)}, editable = true }\n\n[tool.bigconfig]\nlocal = true\npath = ${quoteToml(local.path)}\nlanguage = "python"\nrun = "run"\npackage-name = ${quoteToml(packageName)}\n`;
+  fs.writeFileSync(file, text);
+}
+
+function writeNativeManifestLocal(local, target) {
+  if (target.language === 'clojure') return writeClojureManifestLocal(local, target);
+  if (target.language === 'typescript') return writeTypeScriptManifestLocal(local, target);
+  if (target.language === 'python') return writePythonManifestLocal(local, target);
+  fail(`Unsupported language: ${target.language}`);
+}
+
+// --- target dependency setup and execution -------------------------------
+
+function pythonSitePackagesDirs() {
+  const venv = path.join(process.cwd(), '.venv');
+  const candidates = [path.join(venv, 'Lib', 'site-packages')];
+  for (const libName of ['lib', 'lib64']) {
+    const libDir = path.join(venv, libName);
+    let entries = [];
+    try {
+      entries = fs.readdirSync(libDir);
+    } catch {
+      entries = [];
+    }
+    for (const e of entries.sort()) {
+      if (e.startsWith('python')) candidates.push(path.join(libDir, e, 'site-packages'));
+    }
+  }
+  const seen = new Set();
+  const result = [];
+  for (const c of candidates) {
+    if (seen.has(c)) continue;
+    seen.add(c);
+    try {
+      if (fs.statSync(c).isDirectory()) result.push(c);
+    } catch {
+      // not present
+    }
+  }
+  return result;
+}
+
+// Python wheels install templates as top-level package data under
+// site-packages/resources; BigConfig's renderer resolves them from ./resources.
+// For editable local installs the source tree is used instead (resources live
+// under <path>/src/resources or <path>/resources, never in site-packages).
+function exposePythonResources(meta) {
+  const target = path.join(process.cwd(), 'resources');
+  try {
+    if (fs.statSync(target)) return;
+  } catch {
+    // not present; continue
+  }
+  try {
+    if (fs.lstatSync(target)) fs.rmSync(target, { force: true, recursive: true });
+  } catch {
+    // nothing to remove (e.g. broken symlink already gone)
+  }
+  const candidates = [];
+  if (meta && meta.local && meta.path) {
+    candidates.push(path.join(meta.path, 'src', 'resources'), path.join(meta.path, 'resources'));
+  }
+  for (const site of pythonSitePackagesDirs()) candidates.push(path.join(site, 'resources'));
+  let source = null;
+  for (const c of candidates) {
+    try {
+      if (fs.statSync(c).isDirectory()) {
+        source = c;
+        break;
+      }
+    } catch {
+      // not a dir
+    }
+  }
+  if (!source) return;
+  try {
+    fs.symlinkSync(source, target, 'dir');
+  } catch {
+    fs.cpSync(source, target, { recursive: true });
+  }
+}
+
+async function ensureTargetDeps(meta) {
+  if (meta.language === 'typescript') {
+    requireCommand('node', 'Install Node.js and try again.');
+    requireCommand('npm', 'Install npm and try again.');
+    if (!fs.existsSync(path.join(process.cwd(), 'node_modules'))) {
+      log('Installing TypeScript target dependencies with npm install...');
+      const code = await runCommand('npm', ['install']);
+      if (code !== 0) process.exit(code);
+    }
+    return;
+  }
+  if (meta.language === 'python') {
+    const py = whichPython();
+    if (!py) fail('python3 or python is required but was not found on PATH.');
+    requireCommand('uv', 'Install uv and try again.');
+    if (!fs.existsSync(path.join(process.cwd(), '.venv'))) {
+      log('Installing Python target dependencies with uv sync...');
+      const code = await runCommand('uv', ['sync']);
+      if (code !== 0) process.exit(code);
+    }
+    exposePythonResources(meta);
+    return;
+  }
+}
+
+async function runTarget(meta, args) {
+  if (meta.language === 'typescript') {
+    await ensureTargetDeps(meta);
+    return await runCommand('node', ['run', ...args]);
+  }
+  if (meta.language === 'python') {
+    await ensureTargetDeps(meta);
+    return await runCommand('uv', ['run', 'python', meta.run || 'run', ...args]);
+  }
+  if (meta.language === 'clojure') {
+    const p = resolvePlatform();
+    const bbPath = await ensureBabashka(p);
+    const javaHome = await ensureJdk(p);
+    ensureGit();
+    return await runBb(bbPath, ['run', ...args], javaHome);
+  }
+  fail(`Unsupported language: ${meta.language}`);
+}
+
+async function initialize(spec, sha) {
+  const target = await detectTarget(spec, sha);
+  const runText = await fetchFile(spec, sha, 'run', { required: true });
+  writeRunFile(runText);
+  writeNativeManifest(spec, sha, target);
+  return {
+    repo: spec.slug,
+    ref: spec.ref,
+    sha,
+    language: target.language,
+    run: 'run',
+    packageName: target.packageName,
+  };
+}
+
+function initializeLocal(local) {
+  if (local.path === fs.realpathSync(process.cwd())) {
+    fail("local path is the current directory; run bc-pkg from a separate directory so it does not overwrite the package's own manifest.");
+  }
+  const target = detectTargetLocal(local);
+  const runSource = path.join(local.path, 'run');
+  if (!fs.existsSync(runSource) || !fs.statSync(runSource).isFile()) fail(`${local.path} has no run`);
+  linkRunFile(runSource);
+  writeNativeManifestLocal(local, target);
+  return {
+    repo: null,
+    ref: null,
+    sha: null,
+    language: target.language,
+    run: 'run',
+    packageName: target.packageName,
+    local: true,
+    path: local.path,
+  };
+}
+
+async function restoreRunIfMissing(meta) {
+  const runPath = path.join(process.cwd(), meta.run || 'run');
+  if (fs.existsSync(runPath)) return;
+  if (meta.local) {
+    const source = path.join(meta.path, meta.run || 'run');
+    if (!fs.existsSync(source)) fail(`${meta.path} has no ${meta.run || 'run'}`);
+    linkRunFile(source);
+    return;
+  }
+  const [owner, repo] = meta.repo.split('/');
+  const spec = { owner, repo, slug: meta.repo, ref: meta.ref };
+  const runText = await fetchFile(spec, meta.sha, 'run', { required: true });
+  writeRunFile(runText);
+}
+
+// --- Babashka/JDK bootstrap for Clojure targets --------------------------
 
-// Maps the host OS/arch to babashka release asset + Adoptium API parameters.
 function resolvePlatform() {
-  const plat = process.platform; // 'darwin' | 'linux' | 'win32'
-  const arch = process.arch; // 'arm64' | 'x64'
+  const plat = process.platform;
+  const arch = process.arch;
   const exeSuffix = plat === 'win32' ? '.exe' : '';
 
   let bbOs;
@@ -47,7 +683,7 @@ function resolvePlatform() {
     jdkOs = 'windows';
     archiveExt = 'zip';
   } else {
-    throw new Error(`Unsupported OS: ${plat}`);
+    fail(`Unsupported OS: ${plat}`);
   }
 
   let bbArch;
@@ -59,17 +695,11 @@ function resolvePlatform() {
     bbArch = 'amd64';
     jdkArch = 'x64';
   } else {
-    throw new Error(`Unsupported CPU architecture: ${arch}`);
+    fail(`Unsupported CPU architecture: ${arch}`);
   }
 
-  // babashka ships only a *static* (musl) build for Linux arm64 — there is no
-  // dynamic linux-aarch64 asset. The static build also runs on glibc.
-  const bbArchToken =
-    plat === 'linux' && arch === 'arm64' ? 'aarch64-static' : bbArch;
-
-  if (plat === 'win32' && arch === 'arm64') {
-    throw new Error('babashka has no prebuilt Windows arm64 binary');
-  }
+  const bbArchToken = plat === 'linux' && arch === 'arm64' ? 'aarch64-static' : bbArch;
+  if (plat === 'win32' && arch === 'arm64') fail('babashka has no prebuilt Windows arm64 binary');
 
   return {
     exeSuffix,
@@ -84,22 +714,16 @@ function resolvePlatform() {
 }
 
 function cacheRoot() {
-  const base =
-    process.platform === 'win32'
-      ? process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local')
-      : process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  const base = process.platform === 'win32'
+    ? process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local')
+    : process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
   return path.join(base, 'bc-pkg');
 }
 
-// --- Filesystem helpers --------------------------------------------------
-
 function rmrf(target) {
   fs.rmSync(target, { recursive: true, force: true });
 }
 
-// Runs `install(tmpDir)` into a private temp dir, then atomically renames it
-// into place. Concurrent first-runs race on the rename; the loser is discarded
-// so the final dir is never left half-written.
 async function installOnce(finalDir, install) {
   if (fs.existsSync(finalDir)) return;
   const tmp = `${finalDir}.tmp-${process.pid}-${Date.now()}`;
@@ -107,7 +731,7 @@ async function installOnce(finalDir, install) {
   try {
     await install(tmp);
     if (fs.existsSync(finalDir)) {
-      rmrf(tmp); // another process won the race
+      rmrf(tmp);
       return;
     }
     fs.mkdirSync(path.dirname(finalDir), { recursive: true });
@@ -127,52 +751,28 @@ async function installOnce(finalDir, install) {
 }
 
 async function download(url, destFile) {
-  const res = await fetch(url, {
-    redirect: 'follow',
-    headers: { 'user-agent': 'bc-pkg' },
-  });
+  const res = await fetch(url, { redirect: 'follow', headers: { 'user-agent': 'bc-pkg' } });
   if (!res.ok || !res.body) {
-    throw new Error(
-      `Download failed (HTTP ${res.status} ${res.statusText})\n  ${url}`
-    );
+    fail(`Download failed (HTTP ${res.status} ${res.statusText})\n  ${url}`);
   }
   await fs.promises.mkdir(path.dirname(destFile), { recursive: true });
   await pipeline(Readable.fromWeb(res.body), fs.createWriteStream(destFile));
 }
 
-// Extracts .tar.gz / .zip. System `tar` (GNU on Linux, bsdtar on macOS &
-// Windows 10+) auto-detects gzip and handles zip; PowerShell is a Windows
-// fallback when `tar` is absent.
 function extract(archive, destDir) {
   fs.mkdirSync(destDir, { recursive: true });
-  let r = spawnSync('tar', ['-xf', archive, '-C', destDir], {
-    stdio: ['ignore', 'inherit', 'inherit'],
-  });
+  let r = spawnSync('tar', ['-xf', archive, '-C', destDir], { stdio: ['ignore', 'inherit', 'inherit'] });
   if (r.error && r.error.code === 'ENOENT') {
     if (process.platform === 'win32' && archive.endsWith('.zip')) {
-      r = spawnSync(
-        'powershell',
-        [
-          '-NoProfile',
-          '-Command',
-          `Expand-Archive -LiteralPath '${archive}' -DestinationPath '${destDir}' -Force`,
-        ],
-        { stdio: ['ignore', 'inherit', 'inherit'] }
-      );
-      if (r.status !== 0) {
-        throw new Error(`Failed to extract ${archive} (PowerShell fallback)`);
-      }
+      r = spawnSync('powershell', ['-NoProfile', '-Command', `Expand-Archive -LiteralPath '${archive}' -DestinationPath '${destDir}' -Force`], { stdio: ['ignore', 'inherit', 'inherit'] });
+      if (r.status !== 0) fail(`Failed to extract ${archive} (PowerShell fallback)`);
       return;
     }
-    throw new Error(`'tar' not found on PATH; cannot extract ${archive}`);
-  }
-  if (r.status !== 0) {
-    throw new Error(`Failed to extract ${archive} (tar exit ${r.status})`);
+    fail(`'tar' not found on PATH; cannot extract ${archive}`);
   }
+  if (r.status !== 0) fail(`Failed to extract ${archive} (tar exit ${r.status})`);
 }
 
-// Locates JAVA_HOME inside an extracted JDK. Layout differs per OS
-// (linux: <root>/bin/java, macOS: <root>/Contents/Home/bin/java).
 function findJavaHome(root, exeSuffix) {
   const javaRel = path.join('bin', `java${exeSuffix}`);
   const stack = [root];
@@ -185,15 +785,11 @@ function findJavaHome(root, exeSuffix) {
     } catch {
       continue;
     }
-    for (const e of entries) {
-      if (e.isDirectory()) stack.push(path.join(dir, e.name));
-    }
+    for (const e of entries) if (e.isDirectory()) stack.push(path.join(dir, e.name));
   }
   return null;
 }
 
-// --- Bootstrap steps -----------------------------------------------------
-
 async function ensureBabashka(p) {
   const version = DEFAULT_BB_VERSION;
   const finalDir = path.join(cacheRoot(), 'bb', version);
@@ -212,23 +808,13 @@ async function ensureBabashka(p) {
     extract(archive, tmp);
     fs.unlinkSync(archive);
     const exe = path.join(tmp, `bb${p.exeSuffix}`);
-    if (!fs.existsSync(exe)) {
-      throw new Error('babashka binary not found after extraction');
-    }
+    if (!fs.existsSync(exe)) fail('babashka binary not found after extraction');
     if (process.platform !== 'win32') fs.chmodSync(exe, 0o755);
   });
 
-  if (!fs.existsSync(bbPath)) {
-    throw new Error(
-      `babashka cache looks corrupt; remove ${finalDir} and retry`
-    );
-  }
+  if (!fs.existsSync(bbPath)) fail(`babashka cache looks corrupt; remove ${finalDir} and retry`);
   if (process.platform !== 'win32') {
-    try {
-      fs.chmodSync(bbPath, 0o755);
-    } catch {
-      /* already executable */
-    }
+    try { fs.chmodSync(bbPath, 0o755); } catch {}
   }
   return bbPath;
 }
@@ -240,9 +826,7 @@ async function ensureJdk(p) {
 
   await installOnce(finalDir, async (tmp) => {
     const archive = path.join(tmp, p.jdkArchiveName);
-    const url =
-      `https://api.adoptium.net/v3/binary/latest/${feature}/ga/` +
-      `${p.jdkOs}/${p.jdkArch}/jdk/hotspot/normal/eclipse`;
+    const url = `https://api.adoptium.net/v3/binary/latest/${feature}/ga/${p.jdkOs}/${p.jdkArch}/jdk/hotspot/normal/eclipse`;
     log(`Installing Temurin JDK ${feature} (set JDK_VERSION to override)...`);
     try {
       await download(url, archive);
@@ -252,8 +836,7 @@ async function ensureJdk(p) {
     extract(archive, tmp);
     fs.unlinkSync(archive);
     const home = findJavaHome(tmp, p.exeSuffix);
-    if (!home) throw new Error('could not locate java in extracted JDK');
-    // Path relative to tmp stays valid after tmp is renamed to finalDir.
+    if (!home) fail('could not locate java in extracted JDK');
     fs.writeFileSync(path.join(tmp, '.javahome'), path.relative(tmp, home));
   });
 
@@ -263,75 +846,33 @@ async function ensureJdk(p) {
   } catch {
     javaHome = null;
   }
-  if (
-    !javaHome ||
-    !fs.existsSync(path.join(javaHome, 'bin', `java${p.exeSuffix}`))
-  ) {
+  if (!javaHome || !fs.existsSync(path.join(javaHome, 'bin', `java${p.exeSuffix}`))) {
     javaHome = findJavaHome(finalDir, p.exeSuffix);
   }
-  if (!javaHome) {
-    throw new Error(`JDK cache looks corrupt; remove ${finalDir} and retry`);
-  }
+  if (!javaHome) fail(`JDK cache looks corrupt; remove ${finalDir} and retry`);
   return javaHome;
 }
 
-// --- git (Linux only) ----------------------------------------------------
-
-function commandWorks(cmd, args) {
-  const r = spawnSync(cmd, args, { stdio: 'ignore' });
-  return !r.error && r.status === 0;
-}
-
-// ENOENT sets r.error; any exit code otherwise means the binary exists.
-function binExists(cmd) {
-  return !spawnSync(cmd, ['--version'], { stdio: 'ignore' }).error;
-}
-
-// On Linux, install git via the system package manager if it is missing.
-// Skipped when git is already on PATH; a no-op on macOS/Windows.
 function ensureGit() {
   if (process.platform !== 'linux') return;
   if (commandWorks('git', ['--version'])) return;
 
-  const isRoot =
-    typeof process.getuid === 'function' && process.getuid() === 0;
+  const isRoot = typeof process.getuid === 'function' && process.getuid() === 0;
   const sudo = isRoot ? [] : binExists('sudo') ? ['sudo'] : null;
   if (sudo === null) {
-    throw new Error(
-      'git is missing and cannot be installed: not running as root and ' +
-        '`sudo` is unavailable.\n' +
-        '  Install git manually (e.g. `apt-get install git`) and re-run.'
-    );
+    fail('git is missing and cannot be installed: not running as root and `sudo` is unavailable.\n  Install git manually and re-run.');
   }
 
-  // First match wins; `soft` lists step indexes allowed to fail (e.g.
-  // `apt-get update`, which is non-fatal if package lists already exist).
   const managers = [
-    {
-      bin: 'apt-get',
-      steps: [
-        ['apt-get', 'update', '-y'],
-        ['apt-get', 'install', '-y', 'git'],
-      ],
-      soft: [0],
-    },
+    { bin: 'apt-get', steps: [['apt-get', 'update', '-y'], ['apt-get', 'install', '-y', 'git']], soft: [0] },
     { bin: 'dnf', steps: [['dnf', 'install', '-y', 'git']] },
     { bin: 'yum', steps: [['yum', 'install', '-y', 'git']] },
-    {
-      bin: 'zypper',
-      steps: [['zypper', '--non-interactive', 'install', 'git']],
-    },
+    { bin: 'zypper', steps: [['zypper', '--non-interactive', 'install', 'git']] },
     { bin: 'pacman', steps: [['pacman', '-S', '--noconfirm', 'git']] },
     { bin: 'apk', steps: [['apk', 'add', '--no-cache', 'git']] },
   ];
   const pm = managers.find((m) => binExists(m.bin));
-  if (!pm) {
-    throw new Error(
-      'git is missing and no supported package manager ' +
-        '(apt-get/dnf/yum/zypper/pacman/apk) was found.\n' +
-        '  Install git manually and re-run.'
-    );
-  }
+  if (!pm) fail('git is missing and no supported package manager was found. Install git manually and re-run.');
 
   log(`Installing git via ${pm.bin}${sudo.length ? ' (sudo)' : ''}...`);
   const env = { ...process.env, DEBIAN_FRONTEND: 'noninteractive' };
@@ -341,18 +882,12 @@ function ensureGit() {
     const ok = !r.error && r.status === 0;
     if (!ok && !(pm.soft && pm.soft.includes(i))) {
       const why = r.error ? r.error.code : `exit ${r.status}`;
-      throw new Error(`git install failed: \`${argv.join(' ')}\` (${why}).`);
+      fail(`git install failed: \`${argv.join(' ')}\` (${why}).`);
     }
   });
-
-  if (!commandWorks('git', ['--version'])) {
-    throw new Error('git still not available after the install attempt.');
-  }
+  if (!commandWorks('git', ['--version'])) fail('git still not available after the install attempt.');
 }
 
-// --- bb.edn bootstrap ----------------------------------------------------
-
-// Env augmented so spawned processes find the cached JDK and bb; nothing system-wide.
 function bbEnv(javaHome, bbPath, extraEnv = {}) {
   const env = { ...process.env, ...extraEnv };
   const pathEntries = [];
@@ -360,293 +895,44 @@ function bbEnv(javaHome, bbPath, extraEnv = {}) {
     env.JAVA_HOME = javaHome;
     pathEntries.push(path.join(javaHome, 'bin'));
   }
-  if (bbPath) {
-    pathEntries.push(path.dirname(bbPath));
-  }
-  if (pathEntries.length) {
-    env.PATH = pathEntries.join(path.delimiter) + path.delimiter + (env.PATH || '');
-  }
+  if (bbPath) pathEntries.push(path.dirname(bbPath));
+  if (pathEntries.length) env.PATH = pathEntries.join(path.delimiter) + path.delimiter + (env.PATH || '');
   return env;
 }
 
-function ghFetch(url, accept) {
-  const headers = {
-    'user-agent': 'bc-pkg',
-    accept: accept || 'application/vnd.github+json',
-    'x-github-api-version': '2022-11-28',
-  };
-  if (process.env.GITHUB_TOKEN) {
-    headers.authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
-  }
-  return fetch(url, { headers, redirect: 'follow' });
-}
-
-// Reads/edits the EDN with borkdude/rewrite-edn so comments & formatting of
-// untouched nodes survive. Params are passed via env to avoid quoting issues.
-const REWRITE_SCRIPT = `(require '[babashka.deps :as deps])
-(deps/add-deps {:deps {'borkdude/rewrite-edn {:mvn/version (System/getenv "BBEDN_REWRITE_VERSION")}}})
-(require '[borkdude.rewrite-edn :as r])
-
-(defn fail! [msg]
-  (binding [*out* *err*]
-    (println msg))
-  (System/exit 1))
-
-(defn local-root? [coord]
-  (and (map? coord) (contains? coord :local/root)))
-
-;; Drop every entry whose effective coord (sexpr respects #_ discard) is a
-;; map containing :local/root. Returns the (possibly unchanged) map node.
-(defn strip-local-root [m-node]
-  (if (nil? m-node)
-    m-node
-    (let [m (r/sexpr m-node)]
-      (reduce (fn [acc k]
-                (if (local-root? (get m k)) (r/dissoc acc k) acc))
-              m-node
-              (keys m)))))
-
-(let [in    (System/getenv "BBEDN_IN")
-      out   (System/getenv "BBEDN_OUT")
-      owner (System/getenv "BBEDN_OWNER")
-      proj  (System/getenv "BBEDN_PROJECT")
-      sha   (System/getenv "BBEDN_SHA")
-      repo  (System/getenv "BBEDN_REPO")
-      dep   (symbol (str "io.github." owner) proj)
-      nodes (r/parse-string (slurp in))
-      data  (r/sexpr nodes)
-      existing-repo (if (and (map? data) (contains? data :repo))
-                      (:repo data)
-                      ::missing)
-      _validate-map (when-not (map? data)
-                      (fail! "Downloaded bb.edn must contain a top-level EDN map"))
-      _validate-repo (when (and (not= ::missing existing-repo)
-                                (not= existing-repo repo))
-                       (fail! (str "Downloaded bb.edn :repo " (pr-str existing-repo)
-                                   " does not match CLI repo " (pr-str repo))))
-      nodes (if (= ::missing existing-repo) (r/assoc nodes :repo repo) nodes)
-      ;; 1. strip :local/root from top-level :deps
-      nodes (if (r/get nodes :deps)
-              (r/update nodes :deps strip-local-root)
-              nodes)
-      ;; 2. strip :local/root from each task's :extra-deps
-      tasks (some-> (r/get nodes :tasks) r/sexpr)
-      nodes (reduce (fn [acc tk]
-                      (let [tv (get tasks tk)]
-                        (if (and (map? tv) (map? (:extra-deps tv)))
-                          (r/update-in acc [:tasks tk :extra-deps] strip-local-root)
-                          acc)))
-                    nodes
-                    (keys tasks))
-      ;; 3. ensure :deps exists, then inject the repo as a git dep
-      nodes (if (nil? (r/get nodes :deps)) (r/assoc nodes :deps {}) nodes)
-      nodes (r/assoc-in nodes [:deps dep] {:git/sha sha})]
-  (spit out (str nodes)))
-`;
-
-const VALIDATE_REPO_SCRIPT = `(require '[clojure.edn :as edn])
-
-(defn fail! [msg]
-  (binding [*out* *err*]
-    (println msg))
-  (System/exit 1))
-
-(let [target    (System/getenv "BBEDN_TARGET")
-      cli-repo  (System/getenv "BBEDN_REPO")
-      data      (try
-                  (edn/read-string (slurp target))
-                  (catch Exception e
-                    (fail! (str "Invalid bb.edn: " (.getMessage e)))))
-      has-repo? (and (map? data) (contains? data :repo))
-      file-repo (when has-repo? (:repo data))]
-  (when-not (map? data)
-    (fail! "Invalid bb.edn: expected top-level EDN map"))
-  (when-not has-repo?
-    (fail! (str "bb.edn exists but does not contain :repo; omit the CLI repo or add :repo "
-                (pr-str cli-repo))))
-  (when-not (= file-repo cli-repo)
-    (fail! (str "bb.edn :repo " (pr-str file-repo)
-                " does not match CLI repo " (pr-str cli-repo)))))
-`;
-
-// Regex for the "owner/project" slug shape. Anchored, no slashes/spaces/@
-// inside either segment. When present as the first argument, it is consumed as
-// repo identity and never forwarded to bb.
-const REPO_SLUG_RE = /^([^/\s@]+)\/([^/\s@]+)$/;
-
-function validateBbEdnRepo(bbPath, javaHome, target, repo) {
-  const targetPath = path.resolve(target);
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'bb-edn-validate-'));
-  try {
-    const script = path.join(tmp, 'validate-repo.clj');
-    fs.writeFileSync(script, VALIDATE_REPO_SCRIPT);
-    const r = spawnSync(bbPath, [script], {
-      stdio: ['ignore', 'pipe', 'pipe'],
-      encoding: 'utf8',
-      cwd: tmp,
-      env: bbEnv(javaHome, bbPath, {
-        BBEDN_TARGET: targetPath,
-        BBEDN_REPO: repo,
-      }),
-    });
-    if (r.error || r.status !== 0) {
-      const details = [r.stderr, r.stdout]
-        .filter(Boolean)
-        .map((s) => s.trim())
-        .filter(Boolean)
-        .join('\n');
-      const why = r.error ? r.error.message : `exit ${r.status}`;
-      throw new Error(details || `bb.edn repo validation failed (${why})`);
-    }
-  } finally {
-    rmrf(tmp);
-  }
+function runBb(bbPath, args, javaHome, extraEnv = {}) {
+  return runCommand(bbPath, args, { env: bbEnv(javaHome, bbPath, extraEnv) });
 }
 
-// If bb.edn exists and a CLI repo was provided, validate its top-level :repo.
-// Otherwise, when cwd has no bb.edn and `repo` is "owner/project", fetch that
-// repo's bb.edn (pinned to its default-branch HEAD), inject top-level :repo,
-// and add the repo itself as an io.github git dep.
-async function ensureBbEdn(bbPath, javaHome, repo) {
-  let owner = null;
-  let project = null;
-  let slug = null;
-  if (repo) {
-    const m = repo.match(REPO_SLUG_RE);
-    if (!m) {
-      throw new Error(`repo must be "owner/project" (got "${repo}")`);
+// --- main ----------------------------------------------------------------
+
+async function main(argv) {
+  let args = [...argv];
+  const first = args.length ? args[0] : null;
+  const localSpec = first != null && isLocalSpec(first) ? parseLocalSpec(first) : null;
+  const spec = localSpec ? null : first ? parseSpec(first) : null;
+  if (localSpec || spec) args = args.slice(1);
+
+  let meta = readMetadata();
+  if (localSpec) {
+    if (meta) {
+      validateExistingLocalMetadata(meta, localSpec);
+    } else {
+      meta = initializeLocal(localSpec);
     }
-    owner = m[1];
-    project = m[2];
-    slug = `${owner}/${project}`;
-  }
-
-  const target = path.join(process.cwd(), 'bb.edn');
-  if (fs.existsSync(target)) {
-    if (repo) validateBbEdnRepo(bbPath, javaHome, target, slug);
-    return null;
-  }
-  if (!repo) return null; // step disabled — proceed straight to bb
-
-  const api = `https://api.github.com/repos/${owner}/${project}`;
-
-  const cr = await ghFetch(`${api}/commits?per_page=1`);
-  if (cr.status === 404) {
-    throw new Error(
-      `${slug} not found or not accessible ` +
-        `(set GITHUB_TOKEN for private repos)`
-    );
-  }
-  if (!cr.ok) {
-    throw new Error(`GitHub API error ${cr.status} resolving ${slug}`);
-  }
-  const commits = await cr.json();
-  const sha = Array.isArray(commits) && commits[0] && commits[0].sha;
-  if (!sha) throw new Error(`${slug} has no commits`);
-
-  const fr = await ghFetch(
-    `${api}/contents/bb.edn?ref=${sha}`,
-    'application/vnd.github.raw'
-  );
-  if (fr.status === 404) {
-    throw new Error(`${slug} (at ${sha.slice(0, 7)}) has no bb.edn`);
-  }
-  if (!fr.ok) {
-    throw new Error(`GitHub API error ${fr.status} fetching bb.edn from ${slug}`);
-  }
-  const ednText = await fr.text();
-
-  log(`Bootstrapping bb.edn from ${slug}@${sha.slice(0, 7)}...`);
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'bb-edn-'));
-  try {
-    const inFile = path.join(tmp, 'in.edn');
-    const script = path.join(tmp, 'rewrite.clj');
-    fs.writeFileSync(inFile, ednText);
-    fs.writeFileSync(script, REWRITE_SCRIPT);
-    const env = bbEnv(javaHome, bbPath);
-    Object.assign(env, {
-      BBEDN_IN: inFile,
-      BBEDN_OUT: target,
-      BBEDN_OWNER: owner,
-      BBEDN_PROJECT: project,
-      BBEDN_REPO: slug,
-      BBEDN_SHA: sha,
-      BBEDN_REWRITE_VERSION: REWRITE_EDN_VERSION,
-    });
-    const r = spawnSync(bbPath, [script], {
-      stdio: ['ignore', 'pipe', 'pipe'],
-      encoding: 'utf8',
-      cwd: tmp,
-      env,
-    });
-    if (r.error || r.status !== 0) {
-      const details = [r.stderr, r.stdout]
-        .filter(Boolean)
-        .map((s) => s.trim())
-        .filter(Boolean)
-        .join('\n');
-      const why = r.error ? r.error.message : `exit ${r.status}`;
-      throw new Error(
-        details || `failed to write bb.edn via rewrite-edn (${why})`
-      );
+  } else if (spec) {
+    const sha = await resolveRef(spec);
+    if (meta) {
+      validateExistingMetadata(meta, spec, sha);
+    } else {
+      meta = await initialize(spec, sha);
     }
-    if (!fs.existsSync(target)) {
-      throw new Error('rewrite-edn step did not produce a bb.edn');
-    }
-    return { owner, project, sha };
-  } finally {
-    rmrf(tmp);
+  } else if (!meta) {
+    fail(`No BigConfig CLI is initialized in this directory.\n\n${usage()}`);
   }
-}
-
-// --- Run bb --------------------------------------------------------------
-
-function runBb(bbPath, args, javaHome, extraEnv = {}) {
-  const env = bbEnv(javaHome, bbPath, extraEnv);
-
-  const child = spawn(bbPath, args, {
-    stdio: 'inherit',
-    cwd: process.cwd(),
-    env,
-  });
-
-  const forward = (sig) => {
-    try {
-      child.kill(sig);
-    } catch {
-      /* child already gone */
-    }
-  };
-  process.on('SIGINT', forward);
-  process.on('SIGTERM', forward);
-
-  return new Promise((resolve) => {
-    child.on('error', (err) => {
-      log(`failed to start bb: ${err.message}`);
-      resolve(127);
-    });
-    child.on('exit', (code, signal) => {
-      resolve(signal ? 1 : code == null ? 1 : code);
-    });
-  });
-}
 
-async function main(args) {
-  const p = resolvePlatform();
-  // Consume the first positional argument as repo identity whenever it has
-  // the shape "owner/project". It is never forwarded to bb: with no bb.edn it
-  // bootstraps one, and with an existing bb.edn it validates top-level :repo.
-  let repo = null;
-  if (args.length && REPO_SLUG_RE.test(args[0])) {
-    repo = args[0];
-    args = args.slice(1);
-  }
-  const bbPath = await ensureBabashka(p);
-  const javaHome = await ensureJdk(p);
-  ensureGit();
-  const bootstrapped = await ensureBbEdn(bbPath, javaHome, repo);
-  const extraEnv = bootstrapped ? { BB_BOOTSTRAP_SHA: bootstrapped.sha } : {};
-  const code = await runBb(bbPath, args, javaHome, extraEnv);
+  await restoreRunIfMissing(meta);
+  const code = await runTarget(meta, args);
   process.exit(code);
 }
 
@@ -657,12 +943,18 @@ if (require.main === module) {
   });
 }
 
-// Exported for tests / inspection.
 module.exports = {
+  parseSpec,
+  isLocalSpec,
+  parseLocalSpec,
+  resolveRef,
+  detectTarget,
+  detectTargetLocal,
+  readMetadata,
+  validateExistingMetadata,
+  validateExistingLocalMetadata,
   resolvePlatform,
   cacheRoot,
   findJavaHome,
   ensureGit,
-  validateBbEdnRepo,
-  ensureBbEdn,
 };