bc-pkg 1.0.0 → 1.0.1

package/README.md

@@ -1,163 +1,65 @@
 # bc-pkg
 
-Run [babashka](https://babashka.org) (`bb`) without installing anything first.
-On its first invocation this package downloads a pinned babashka binary **and**
-an Eclipse Temurin JDK into a shared user cache, then forwards every argument
-to `bb`.
+`bc-pkg` creates or reuses a BigConfig CLI in the current directory, then
+forwards your command to that CLI.
+
+The npm package and the PyPI package expose the same behavior. The target
+package can be implemented in Clojure, TypeScript, or Python; `bc-pkg` infers
+that language from the pinned GitHub content.
 
 ## Usage
 
 ```sh
-npx bc-pkg@latest tasks                       # -> bb tasks
-npx bc-pkg@latest <args...>                   # -> bb <args...>
-npx bc-pkg@latest <owner>/<project> <args...> # bootstrap/validate bb.edn, then -> bb <args...>
+npx bc-pkg <owner/repo@ref> package validate
+npx bc-pkg package validate
 ```
 
-The npm package is unscoped `bc-pkg` and exposes a single `bc-pkg` bin. All
-other arguments (including flags) are passed through verbatim, and `bb` runs in
-your current working directory, so it picks up the local `bb.edn`. If
-the first argument has the shape `owner/project`, it is consumed as repo
-identity and never forwarded to `bb`: it bootstraps a missing `bb.edn` or
-validates the existing `bb.edn`'s top-level `:repo`.
-
-## What happens on first run
-
-1. The host OS/CPU are resolved to the matching babashka release asset and
-   Adoptium API parameters.
-2. babashka is downloaded from its GitHub releases and cached.
-3. A Temurin JDK is downloaded from the Adoptium API and cached.
-4. On Linux, `git` is installed via the system package manager if it is not on
-   `PATH`.
-5. If a `<owner>/<project>` slug is the first argument, it is consumed; it
-   bootstraps a missing `bb.edn` or validates an existing `bb.edn`'s `:repo`.
-6. `bb` is launched with `JAVA_HOME` / `PATH` pointing at the cached JDK (and
-   the cached `bb`, so nested `bb` calls work) — the environment change applies
-   **only** to the `bb` subprocess.
-
-Subsequent runs reuse the cache and start immediately.
-
-## git (Linux only)
-
-On Linux, if `git` is not on `PATH`, it is installed via the system package
-manager (`apt-get`, `dnf`, `yum`, `zypper`, `pacman`, or `apk`), using `sudo`
-when not running as root. This is **skipped** when git is already present, and
-is a **no-op on macOS/Windows**. Unlike babashka/JDK, this modifies the system
-and may prompt for a sudo password; in non-interactive environments without
-passwordless sudo it will fail with an actionable message — pre-install git to
-avoid this entirely.
-
-## bb.edn bootstrap (optional)
-
-If the current directory has **no `bb.edn`** and the first argument has the
-shape `owner/project`, that repo's `bb.edn` is downloaded (pinned to its
-default branch's latest commit), top-level `:repo "owner/project"` is ensured,
-and the repo itself is added to `:deps` as
-`io.github.<owner>/<project> {:git/sha "<sha>"}`. The edit is done with
-`borkdude/rewrite-edn`, so existing comments and formatting are preserved.
-The slug is consumed; remaining arguments are forwarded to `bb`.
-
-If a `bb.edn` already exists, the same slug is still consumed and compared
-exactly with top-level `:repo`. The slug may be omitted when `bb.edn` exists.
-
-Any dependency using `:local/root` (in `:deps` or a task's `:extra-deps`) is
-removed first, since those paths don't exist once the file is downloaded.
-Valid Maven/git deps are kept.
-
-- Skipped if no slug is given and no `bb.edn` needs to be created.
-- Fatal error, when a slug is supplied, if an existing `bb.edn` is invalid,
-  lacks `:repo`, or has a different `:repo`.
-- Fatal error if the repo is missing/inaccessible, has no `bb.edn`, or its
-  `bb.edn` declares a different `:repo`.
-- Set `GITHUB_TOKEN` for private repos or to avoid GitHub's unauthenticated
-  API rate limit.
+`ref` can be a branch name or a full 40-character commit SHA:
 
 ```sh
-npx bc-pkg@latest my-org/shared-tasks tasks
+npx bc-pkg bigconfig-ai/once@typescript package validate
+npx bc-pkg bigconfig-ai/once@2f4e8c0d0b4c4b8f0c3a9f6e2a1b5c7d8e9f0123 package validate
 ```
 
-## Cache location
-
-A single shared directory, reused across all projects:
-
-| Platform      | Path                                         |
-| ------------- | -------------------------------------------- |
-| macOS / Linux | `$XDG_CACHE_HOME` or `~/.cache` → `bc-pkg/` |
-| Windows       | `%LOCALAPPDATA%` → `bc-pkg/`           |
-
-Delete that directory to force a clean reinstall.
-
-## Configuration
-
-| Env var               | Default    | Effect                                          |
-| --------------------- | ---------- | ----------------------------------------------- |
-| `BB_VERSION`          | `1.12.196` | babashka release version to install             |
-| `JDK_VERSION`         | `21`       | Temurin feature version (e.g. `17`, `21`, `25`) |
-| `GITHUB_TOKEN`        | _(unset)_  | Used for the bb.edn bootstrap (private repos / higher API rate limit) |
-| `REWRITE_EDN_VERSION` | `0.5.9`    | `borkdude/rewrite-edn` version used to edit the `bb.edn` |
+On the first run, `bc-pkg` resolves the ref to a full SHA and pins it. Later
+runs omit `<owner/repo@ref>` and keep using the pinned SHA.
 
-## Supported platforms
+## What is created
 
-macOS arm64, macOS x64, Linux x64, Linux arm64, Windows x64.
+The launcher copies the target package's root `run` file into the current
+directory and writes language-native metadata:
 
-Notes:
+| Target language | Manifest | Runtime command |
+| --- | --- | --- |
+| Clojure | `deps.edn` | `bb run ...` |
+| TypeScript | `package.json` | `node run ...` |
+| Python | `pyproject.toml` | `uv run python run ...` |
 
-- Linux x64 uses babashka's glibc build (may not run on musl distros such as
-  Alpine). Linux arm64 uses babashka's static build, which runs on both glibc
-  and musl.
-- Extraction uses the system `tar` (present on macOS, Linux, and Windows
-  10+); Windows falls back to PowerShell `Expand-Archive` for `.zip` if `tar`
-  is unavailable.
+For Clojure targets, a small `bb.edn` runtime dependency file is also written so
+Babashka can load the pinned Git dependency.
 
-## Development Docker image
+If the directory is already initialized for a different repo/ref/SHA, `bc-pkg`
+exits with an error instead of updating it implicitly.
 
-This repository also includes a `Dockerfile` and `bb.edn` tasks for a
-throwaway development shell. The former Makefile workflow now lives in
-`bb.edn`. The image is based on Ubuntu 24.04 and installs Node.js, the pi
-coding agent, Claude, `ripgrep`, `fd`, and `sudo`. Requires Docker. Commands
-below assume `bb` is on `PATH`; use `node bin/bc-pkg.js <task>` to exercise the
-local launcher instead.
+## Requirements
 
-If these tasks are bootstrapped into an empty directory by passing
-`bigconfig-ai/bc-pkg` as the first argument, the missing `Dockerfile` is
-downloaded into that directory from the same pinned GitHub SHA as the
-bootstrapped `bb.edn`:
+- npm launcher: Node.js >= 18.
+- TypeScript target packages: Node.js and npm must already be installed.
+- Python target packages: Python and `uv` must already be installed.
+- Clojure target packages: `bc-pkg` downloads pinned Babashka and Temurin JDK
+  versions into a shared user cache and checks/installs `git` on Linux.
 
-```sh
-mkdir empty && cd empty
-npx bc-pkg@latest bigconfig-ai/bc-pkg shell
-```
+## Environment
 
-```sh
-bb tasks                 # list repository tasks
-bb build                 # build bc-pkg:dev
-bb build --no-cache      # rebuild without Docker layer cache
-bb shell                 # build, create a generated home, then open bash
-bb shell --skip-build    # reuse the existing image
-```
+| Variable | Effect |
+| --- | --- |
+| `GITHUB_TOKEN` | Used for private GitHub repos or higher API rate limits. |
+| `BB_VERSION` | Override the Babashka version for Clojure targets. |
+| `JDK_VERSION` | Override the Temurin JDK feature version for Clojure targets. |
 
-`bb shell` creates a writable host directory under `homes/<random-name>` and
-mounts it at `/home/developer` in the container. Before starting Docker it
-copies `~/.pi/agent/auth.json` and `~/.pi/agent/settings.json` into that
-generated home when those files exist; missing files are skipped. Use
-`--project-subdir PATH` to mount a specific host directory instead, and
-`bb homes` / `bb clean --all` to list or remove generated homes.
-
-Common options are available as flags or environment variables:
-
-| Option / env | Default | Effect |
-| ------------ | ------- | ------ |
-| `--image` / `IMAGE` | `bc-pkg` | Docker image name |
-| `--tag` / `TAG` | `dev` | Docker image tag |
-| `--node-major` / `NODE_MAJOR` | `24` | Node.js major version build arg |
-| `--no-cache` | `false` | Pass `--no-cache` to `docker build` |
-| `--workdir` / `WORKDIR` | `/home/developer` | Container working directory |
-| `--name` / `DOCKER_STYLE_RANDOM_NAME` | random | Container hostname and generated home name |
-| `--project-subdir` / `PROJECT_SUBDIR` | `homes/<name>` | Host directory mounted into the container |
-| `--docker-run-arg ARG` | _(none)_ | Extra `docker run` argument; repeat as needed |
-| `--dry-run` | `false` | Print commands without executing them |
-
-Run `bb options` for the full option list.
+## Cache
 
-## Requirements
+Babashka and JDK downloads are shared across projects under:
 
-Node.js >= 18.
+- macOS/Linux: `$XDG_CACHE_HOME/bc-pkg` or `~/.cache/bc-pkg`
+- Windows: `%LOCALAPPDATA%/bc-pkg`

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,403 @@ 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 <args...>\n\nExamples:\n  npx bc-pkg bigconfig-ai/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]}` };
+}
+
+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;
+}
+
+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'),
+  ]);
+
+  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(`${spec.slug}@${sha.slice(0, 7)} has no deps.edn, package.json, or pyproject.toml`);
+  }
+  if (found.length > 1) {
+    fail(`${spec.slug}@${sha.slice(0, 7)} is ambiguous; found ${found.join(', ')} manifests`);
+  }
+
+  if (found[0] === 'typescript') {
+    const pkg = parseJson(packageJsonText, 'package.json');
+    if (!pkg.name) fail(`${spec.slug}@${sha.slice(0, 7)} package.json has no name`);
+    return { language: 'typescript', packageName: pkg.name };
+  }
+  if (found[0] === 'python') {
+    const packageName = parsePyProjectName(pyprojectText);
+    if (!packageName) fail(`${spec.slug}@${sha.slice(0, 7)} pyproject.toml has no [project].name`);
+    return { language: 'python', packageName };
+  }
+  return { language: 'clojure', packageName: `io.github.${spec.owner}/${spec.repo}` };
+}
+
+// --- 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'),
+    manifest: file,
+  };
+}
+
+function metadataFromDepsEdn(file) {
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, 'utf8');
+  if (!text.includes(':bigconfig/repo')) 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',
+    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.repo || !meta.ref || !meta.sha || !meta.language) {
+    fail(`Incomplete BigConfig metadata in ${meta.manifest}`);
+  }
+  return meta;
+}
+
+function validateExistingMetadata(meta, spec, sha) {
+  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 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);
+}
+
+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}`);
+}
+
+// --- target dependency setup and execution -------------------------------
+
+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);
+    }
+    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,
+  };
+}
+
+async function restoreRunIfMissing(meta) {
+  const runPath = path.join(process.cwd(), meta.run || 'run');
+  if (fs.existsSync(runPath)) 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 +427,7 @@ function resolvePlatform() {
     jdkOs = 'windows';
     archiveExt = 'zip';
   } else {
-    throw new Error(`Unsupported OS: ${plat}`);
+    fail(`Unsupported OS: ${plat}`);
   }
 
   let bbArch;
@@ -59,17 +439,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 +458,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 +475,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 +495,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 +529,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 +552,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 +570,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 +580,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 +590,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 +626,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 +639,36 @@ 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}")`);
-    }
-    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`);
+// --- main ----------------------------------------------------------------
 
-  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();
+async function main(argv) {
+  let args = [...argv];
+  let spec = args.length ? parseSpec(args[0]) : null;
+  if (spec) args = args.slice(1);
 
-  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})`
-      );
-    }
-    if (!fs.existsSync(target)) {
-      throw new Error('rewrite-edn step did not produce a bb.edn');
+  let meta = readMetadata();
+  if (spec) {
+    const sha = await resolveRef(spec);
+    if (meta) {
+      validateExistingMetadata(meta, spec, sha);
+    } else {
+      meta = await initialize(spec, sha);
     }
-    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 +679,14 @@ if (require.main === module) {
   });
 }
 
-// Exported for tests / inspection.
 module.exports = {
+  parseSpec,
+  resolveRef,
+  detectTarget,
+  readMetadata,
+  validateExistingMetadata,
   resolvePlatform,
   cacheRoot,
   findJavaHome,
   ensureGit,
-  validateBbEdnRepo,
-  ensureBbEdn,
 };

package/package.json

@@ -1,15 +1,15 @@
 {
-    "name": "bc-pkg",
-    "version": "1.0.0",
-    "description": "Bootstrap and run babashka (bb): installs babashka and a Temurin JDK on first use if missing, then forwards all arguments to bb.",
-    "bin": {
-        "bc-pkg": "bin/bc-pkg.js"
-    },
-    "files": ["bin/", "README.md"],
-    "engines": {
-        "node": ">=18"
-    },
-    "keywords": ["babashka", "bb", "clojure", "jdk", "cli"],
-    "license": "MIT",
-    "type": "commonjs"
+  "name": "bc-pkg",
+  "version": "1.0.1",
+  "description": "Create and run a BigConfig CLI from a language-specific GitHub package.",
+  "bin": {
+    "bc-pkg": "bin/bc-pkg.js"
+  },
+  "files": ["bin/", "README.md"],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["bigconfig", "cli", "launcher", "clojure", "typescript", "python"],
+  "license": "MIT",
+  "type": "commonjs"
 }