1tube 0.1.46 → 0.1.47

package/README.md

@@ -62,25 +62,57 @@ npx 1tube package --functions supabase/functions --in dist --out fw.1tube --sign
 This replaces local-source invocations such as
 `deno run -A ../1tube/src/cli.ts ...` in downstream CI pipelines.
 
-### Passing deno flags through the launcher
+### One launcher, one path
 
-Arguments before a standalone `--` are 1tube CLI args; everything **after** `--`
-is forwarded verbatim to `deno run` (inserted before the entrypoint). This lets
-the launcher fully replace a project's bespoke `deno run … src/server.ts`
-command — including project-level deno flags like `--config`, `--env-file`,
-`--node-modules-dir` and `--no-lock`:
+There is a single launcher (`src/launch.ts`): the npm bin, the deno tasks, and
+host projects all funnel through it, and `serve` **always** spawns the gateway
+as a child `deno run`. That child process is what lets the launcher reconcile
+the lockfile with your installed dependencies _before_ Deno resolves any npm
+specifier — and fully reload it when a dependency changes (see below).
+
+The launcher recognizes its own flags and forwards everything else to the
+gateway, so it fully replaces a bespoke `deno run … src/server.ts` line — no
+`--` split needed:
 
 ```bash
 npx 1tube serve --functions ./supabase/functions --dev --hmr \
-  -- --no-lock --env-file=.env --config ./supabase/functions/deno.json --node-modules-dir=false
+  --config ./supabase/functions/deno.json --env-file=.env --node-modules-dir=false
 ```
 
-- If your passthrough includes its own `--config`, the launcher does **not** add
-  1tube's bundled `deno.json` — your import map wins (the gateway's own sources
-  use fully-qualified `npm:`/`jsr:` specifiers, so they resolve regardless).
+Launcher flags: `--lock <path>` (managed lockfile, default
+`<cwd>/.1tube/deno.lock`), `--no-lock`, `--refresh-lock`, `--config <path>`,
+`--env-file[=<path>]` (repeatable), `--minimum-dependency-age <n>`,
+`--node-modules-dir <v>`, `--no-pin`, `--no-dep-watch`. Anything after a `--`
+is forwarded verbatim to the gateway.
+
+- If you don't pass `--config`, the launcher falls back to 1tube's bundled
+  `deno.json`; the gateway's own sources use fully-qualified `npm:`/`jsr:`
+  specifiers, so they resolve either way.
 - Prefer keeping the command line clean? Set the same flags in
-  `1TUBE_DENO_ARGS` (space-separated) instead of after `--`. CLI passthrough
-  takes precedence on any duplicate flag.
+  `1TUBE_DENO_ARGS` (space-separated); they're appended to the launcher args.
+
+### Dependency pinning & live reload
+
+The edge runtime runs with `--node-modules-dir=false`, so Deno resolves npm
+specifiers from its own cache + lockfile, not from `node_modules`. An import map
+that maps a dependency with an **unconstrained** specifier (`npm:1tube/edge`,
+i.e. `@*`) is satisfied by _any_ locked version — so bumping that dependency in
+`package.json` would silently never reach the edge runtime, and the gateway
+could end up a different version than the edge surface its functions import.
+
+The launcher closes this gap: before spawning the gateway it rewrites every
+unconstrained `npm:` specifier in your `--config` import map to the **exact
+version installed in `node_modules`** (the source of truth your package manager
+controls), writing the result to `<.1tube>/deno.gen.json`. Now the specifier's
+version tracks the installed dependency, so Deno's native lockfile auto-update
+recomputes just that entry — every already-pinned dependency keeps its locked
+version (and the warm-boot speed a lockfile buys).
+
+While serving, the launcher watches your deno config and each pinned
+dependency's `package.json`. When an install or a config edit changes the
+effective version set, it prints `dependency change detected — reloading
+gateway` and fully restarts the gateway so Deno re-resolves. Disable with
+`--no-pin` / `--no-dep-watch`.
 
 ### Minimum dependency age
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "1tube",
-  "version": "0.1.46",
+  "version": "0.1.47",
   "private": false,
   "description": "Self-hosted Supabase Edge Functions gateway for Deno, plus an ESLint plugin for consumers",
   "license": "MIT",
@@ -55,7 +55,7 @@
     "serve": "deno task serve",
     "build:edge": "deno run -A npm:typescript@latest/tsc --target ES2022 --module ESNext --moduleResolution Bundler --declaration --outDir dist src/edge.ts src/edge-caller.ts src/warmup-client.ts",
     "prepack": "bun run build:edge",
-    "typecheck": "deno check src/server.ts src/cli.ts src/edge.ts src/edge-caller.ts src/warmup-client.ts eslint-plugin.js",
+    "typecheck": "deno check src/server.ts src/cli.ts src/launch.ts src/edge.ts src/edge-caller.ts src/warmup-client.ts eslint-plugin.js",
     "check": "deno cache --allow-scripts=npm:protobufjs src/server.ts",
     "smoke:bin": "node ./scripts/npm-cli.js --version",
     "prepublishOnly": "bun run build:edge && bun run typecheck && bun run check && bun run smoke:bin"

package/scripts/npm-cli.js

@@ -1,113 +1,49 @@
 #!/usr/bin/env node
 
+/**
+ * `1tube` npm bin — a tiny Node shim that locates Deno and runs the single
+ * launcher (`src/launch.ts`). All argument handling, the managed lockfile,
+ * dependency pinning, minimum-dependency-age, and live reload live in the
+ * launcher itself, so this shim stays trivial: find deno, forward argv, wire
+ * up signals + exit code.
+ *
+ * Machines using this need Deno on PATH (or set `DENO_BIN`). Arguments are
+ * forwarded verbatim — the launcher recognizes its own flags (`--lock`,
+ * `--config`, `--env-file`, `--node-modules-dir`, `--minimum-dependency-age`,
+ * `--no-lock`, `--no-pin`, `--no-dep-watch`, …) and forwards everything else
+ * to the gateway. `1TUBE_DENO_ARGS` (space-separated) is appended for projects
+ * that prefer to keep flags out of the command line.
+ */
+
 import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const denoConfig = resolve(packageRoot, "deno.json");
-const cliEntrypoint = resolve(packageRoot, "src", "cli.ts");
+const launcherEntrypoint = resolve(packageRoot, "src", "launch.ts");
 const denoBin = process.env.DENO_BIN || "deno";
 
-// Arg model
-// ---------
-// Everything BEFORE a standalone `--` is a 1tube CLI argument (forwarded
-// after the entrypoint). Everything AFTER `--` is a raw `deno run` flag,
-// inserted BEFORE the entrypoint — so this launcher can fully replace a
-// hand-rolled `deno run … src/server.ts` line:
-//
-//   1tube serve --functions ./supabase/functions --dev --hmr \
-//     -- --no-lock --env-file=.env --config ./supabase/functions/deno.json --node-modules-dir=false
-//
-// Projects that would rather not thread flags through the command line
-// can set `1TUBE_DENO_ARGS` instead (same flags, space-separated).
-const rawArgs = process.argv.slice(2);
-const sepIndex = rawArgs.indexOf("--");
-const tubeArgs = sepIndex === -1 ? rawArgs : rawArgs.slice(0, sepIndex);
-const cliDenoArgs = sepIndex === -1 ? [] : rawArgs.slice(sepIndex + 1);
-
-// CLI passthrough is appended last so it wins on any duplicate flag
-// (Deno applies last-one-wins for repeated flags).
-const denoPassthrough = [
+// The launcher needs no import map or lockfile of its own (it imports only
+// node: builtins + relative source), and it owns the gateway child's lock,
+// config and npm-config — so the outer `deno run` stays minimal and fast.
+const denoArgs = [
+  "run",
+  "--quiet",
+  "-A",
+  "--node-modules-dir=false",
+  launcherEntrypoint,
   ...tokenizeArgs(
     process.env.ONETUBE_DENO_ARGS ?? process.env["1TUBE_DENO_ARGS"] ?? "",
   ),
-  ...cliDenoArgs,
+  ...process.argv.slice(2),
 ];
 
-// Default to --help only when the user gave us nothing at all; if they
-// supplied deno flags but no 1tube subcommand, let cli.ts fall through to
-// its default `serve` path.
-const forwardedTubeArgs = tubeArgs.length === 0 && denoPassthrough.length === 0
-  ? ["--help"]
-  : tubeArgs;
-
-// 1tube ships its own deno.json (import map for the gateway's jsr:/npm:
-// dependencies). Only inject it when the project didn't supply its own
-// --config — a Supabase project points --config at
-// supabase/functions/deno.json so its function workers resolve the
-// project's bare specifiers. The gateway's own sources use fully
-// qualified npm:/jsr: specifiers, so they resolve without our config.
-const userSuppliedConfig = denoPassthrough.some((a) =>
-  a === "--config" || a === "-c" ||
-  a.startsWith("--config=") || a.startsWith("-c=")
-);
-
-// Managed lockfile
-// ----------------
-// A lockfile is what makes a big functions project boot fast: without one
-// (`--no-lock`) Deno re-solves the entire npm/jsr version graph from
-// scratch on every start, and a 100-function project pays that as a
-// multi-second floor every boot. People reach for `--no-lock` to dodge
-// "the lock went stale when I bumped a dep" pain — but in dev Deno's
-// lockfile is ADDITIVE and non-frozen: a changed dependency is appended
-// without error. So the right default is a lockfile we own, not none.
-//
-// We point `--lock` at `.1tube/deno.lock` — a gateway-owned scratch path
-// (already gitignored alongside `.1tube/logs.db`) so it never adds git
-// churn and never collides with a project's own committed `deno.lock`.
-// We never pass `--frozen`, so dep changes self-heal. `1TUBE_REFRESH_LOCK=1`
-// drops the managed lock for a clean rebuild. Any explicit `--lock`,
-// `--no-lock`, or `--frozen` the user passes wins — we don't second-guess.
-const managedLock = resolveManagedLock(denoPassthrough);
-
-const denoArgs = ["run", "--quiet", "-A"];
-if (!userSuppliedConfig) denoArgs.push("--config", denoConfig);
-if (managedLock) denoArgs.push("--lock", managedLock);
-denoArgs.push(...denoPassthrough, cliEntrypoint, ...forwardedTubeArgs);
-
-// Deno 2.9 enables a 24h "minimum dependency age" by default, which makes
-// a function that pins a freshly published npm version fail to resolve in
-// local dev ("…newer than the specified minimum dependency date"). This
-// setting cannot be changed from inside the process (Deno snapshots npm
-// config at startup), so the launcher is the place to neutralize it.
-//
-// NPM_CONFIG_MIN_RELEASE_AGE is the LOWEST explicit tier in Deno's
-// precedence chain (CLI flag > deno.json > .npmrc > this env var > the
-// 24h built-in default). Setting it to 0 cancels ONLY the built-in
-// default — any .npmrc `min-release-age`, deno.json `minimumDependencyAge`,
-// or `--minimum-dependency-age` the project sets still wins. We never
-// override a value the user already exported.
-const childEnv = { ...process.env };
-if (
-  childEnv.NPM_CONFIG_MIN_RELEASE_AGE === undefined &&
-  childEnv.npm_config_min_release_age === undefined
-) {
-  childEnv.NPM_CONFIG_MIN_RELEASE_AGE = "0";
-}
-// Let the gateway print which lockfile is in effect (it can't read its own
-// process's `--lock` flag back out of Deno).
-if (managedLock) childEnv.ONETUBE_LOCK = managedLock;
-
 // Resolve the real deno binary up front. Node ≥18.20 refuses to spawn a
-// `.cmd`/`.bat` shim without a shell, but spawning a real `.exe` (or a
-// bare binary on POSIX) with `shell:false` lets Node escape arguments
-// properly — important now that we forward arbitrary deno flags, some of
-// which carry paths with spaces (`--config "C:\My Project\deno.json"`).
-// We only fall back to a shell when we must (a `.cmd`/`.bat` shim, or we
-// couldn't locate the binary on a Windows PATH at all).
+// `.cmd`/`.bat` shim without a shell, but spawning a real `.exe` (or a bare
+// binary on POSIX) with `shell:false` lets Node escape arguments properly —
+// important since we forward arbitrary flags, some carrying paths with spaces.
 const resolvedDeno = resolveExecutable(denoBin);
 const needsShell = resolvedDeno
   ? /\.(cmd|bat)$/i.test(resolvedDeno)
@@ -116,26 +52,17 @@ const spawnBin = resolvedDeno ?? denoBin;
 
 let child;
 if (needsShell) {
-  // A `.cmd`/`.bat` shim (the npm-installed deno) — or an unresolved name
-  // on Windows — must go through a shell. We pass a single, manually
-  // quoted command string instead of an args array so that (a) paths
-  // with spaces survive and (b) we sidestep Node's DEP0190 "args are not
-  // escaped" deprecation, which fires only for the shell-plus-array form.
   const command = [spawnBin, ...denoArgs].map(quoteForCmd).join(" ");
   child = spawn(command, {
     stdio: "inherit",
     shell: true,
     windowsHide: false,
-    env: childEnv,
   });
 } else {
-  // Real executable (deno.exe / a POSIX binary): no shell, so Node
-  // escapes each argument for us.
   child = spawn(spawnBin, denoArgs, {
     stdio: "inherit",
     shell: false,
     windowsHide: false,
-    env: childEnv,
   });
 }
 
@@ -164,64 +91,10 @@ child.on("exit", (code, signal) => {
   process.exit(code ?? 1);
 });
 
-/**
- * Decide whether to inject a 1tube-managed lockfile, and where.
- *
- * Returns the absolute lock path to pass to `--lock`, or null when the
- * caller already made an explicit locking choice (`--lock`, `--no-lock`,
- * or `--frozen`) — in which case we stay out of the way entirely.
- *
- * The managed lock lives at `<cwd>/.1tube/deno.lock`: a scratch path that
- * 1tube already owns and gitignores, so enabling it adds no git churn and
- * never clashes with a project's own committed `deno.lock`.
- *
- * @param {string[]} passthrough  Raw deno flags being forwarded to `deno run`.
- * @returns {string | null}
- */
-function resolveManagedLock(passthrough) {
-  const explicit = passthrough.some((a) =>
-    a === "--lock" || a.startsWith("--lock=") ||
-    a === "--no-lock" || a.startsWith("--no-lock=") ||
-    a === "--frozen" || a.startsWith("--frozen=")
-  );
-  if (explicit) return null;
-
-  const dir = join(process.cwd(), ".1tube");
-  const lockPath = join(dir, "deno.lock");
-  try {
-    mkdirSync(dir, { recursive: true });
-  } catch {
-    // If we can't create the scratch dir, fall back to no managed lock
-    // rather than crash the launcher.
-    return null;
-  }
-
-  // `1TUBE_REFRESH_LOCK=1` forces a clean rebuild by dropping the managed
-  // lock; Deno then re-derives it from the current deps on this boot.
-  if (truthy(process.env.ONETUBE_REFRESH_LOCK ?? process.env["1TUBE_REFRESH_LOCK"])) {
-    try {
-      rmSync(lockPath, { force: true });
-    } catch {
-      // Best-effort.
-    }
-  }
-  return lockPath;
-}
-
-/**
- * Loose truthiness for env-var flags: "1", "true", "yes", "on" (any case).
- *
- * @param {string | undefined} v
- * @returns {boolean}
- */
-function truthy(v) {
-  return v !== undefined && /^(1|true|yes|on)$/i.test(v.trim());
-}
-
 /**
  * Split a flag string into argv tokens, honoring single/double quotes so
- * values with spaces (`--env-file="my env.env"`) survive. Good enough for
- * a dev-time convenience var — not a full shell parser.
+ * values with spaces (`--env-file="my env.env"`) survive. Good enough for a
+ * dev-time convenience var — not a full shell parser.
  *
  * @param {string} s
  * @returns {string[]}
@@ -238,14 +111,13 @@ function tokenizeArgs(s) {
 
 /**
  * Locate an executable on PATH (honoring PATHEXT on Windows). Returns an
- * absolute path, or null when the name can't be resolved — in which case
- * the caller hands the bare name to spawn and lets the OS/shell try.
+ * absolute path, or null when the name can't be resolved — in which case the
+ * caller hands the bare name to spawn and lets the OS/shell try.
  *
  * @param {string} bin
  * @returns {string | null}
  */
 function resolveExecutable(bin) {
-  // An explicit path (absolute or containing a separator) is used as-is.
   if (isAbsolute(bin) || bin.includes("/") || bin.includes("\\")) {
     return existsSync(bin) ? bin : null;
   }
@@ -264,9 +136,9 @@ function resolveExecutable(bin) {
 }
 
 /**
- * Quote a single argument for cmd.exe. Leaves simple tokens untouched to
- * avoid over-quoting; wraps anything with whitespace or shell
- * metacharacters in double quotes, doubling any embedded quotes.
+ * Quote a single argument for cmd.exe. Leaves simple tokens untouched to avoid
+ * over-quoting; wraps anything with whitespace or shell metacharacters in
+ * double quotes, doubling any embedded quotes.
  *
  * @param {string} arg
  * @returns {string}

package/src/cli/dep-pin.ts

@@ -0,0 +1,126 @@
+/**
+ * Dependency pinning for the Deno edge runtime.
+ *
+ * The problem this solves
+ * =======================
+ * 1tube's edge functions run under Deno with `--node-modules-dir=false`, so
+ * Deno resolves npm specifiers from its OWN cache + lockfile, NOT from the
+ * host project's `node_modules`. The import map a Supabase-style project ships
+ * commonly maps 1tube's surface with an *unconstrained* specifier:
+ *
+ *     "1tube/edge": "npm:1tube/edge"        // === npm:1tube@*
+ *
+ * `@*` is satisfied by ANY version. So once the lockfile pins, say,
+ * `1tube@0.1.43`, bumping the npm dependency (and `node_modules/1tube`) to
+ * `0.1.46` changes nothing for the edge runtime: the old pin still satisfies
+ * `*`, Deno never re-resolves, and the gateway (loaded from `node_modules`,
+ * now 0.1.46) ends up serving a *different* version of the edge surface than
+ * the functions import (still 0.1.43) — e.g. a missing export at boot.
+ *
+ * Deno's native lockfile auto-update is correct and fast, but it only triggers
+ * when a specifier's *version requirement* actually changes. Unconstrained
+ * specifiers never change, so they "stick" forever.
+ *
+ * The fix
+ * =======
+ * Before launching the gateway, rewrite every unconstrained `npm:` specifier
+ * in the import map to the EXACT version installed in the host's
+ * `node_modules` (the single source of truth the user controls via their
+ * package manager). `npm:1tube/edge` → `npm:1tube@0.1.46/edge`. Now the
+ * specifier version tracks the installed dependency, so bumping the dep makes
+ * Deno's native lock auto-update recompute that one entry — while every
+ * already-pinned dependency is left untouched, preserving lockfile
+ * reproducibility and warm-boot performance.
+ *
+ * This module is the pure, IO-free core (parsing + reconciliation) so it can
+ * be unit-tested; the file IO + process spawn live in `src/launch.ts`.
+ */
+
+/** A parsed `npm:` import-map specifier. */
+export interface NpmSpecifier {
+  /** Package name, including scope (e.g. `1tube`, `@supabase/server`). */
+  name: string;
+  /**
+   * Version requirement as written (e.g. `0.1.46`, `^1`, `4.4.3`), or
+   * `undefined` when the specifier is unconstrained (`npm:name` / `@*`).
+   */
+  version?: string;
+  /** Subpath including the leading slash (e.g. `/edge`), or `""`. */
+  subpath: string;
+}
+
+// `npm:` body grammar: (@scope/)?name (@version)? (/subpath)?
+//   group 1 — name: scoped `@scope/name` or bare `name` (no `@` or `/` inside)
+//   group 2 — `@version` (everything up to the next `/`)
+//   group 3 — `/subpath`
+const NPM_BODY_RE = /^(@[^/@]+\/[^/@]+|[^/@]+)(@[^/]+)?(\/.*)?$/;
+
+/**
+ * Parse an import-map value into its npm parts, or `null` when it is not an
+ * `npm:` specifier (e.g. `jsr:`, `https:`, `./local.ts`).
+ */
+export function parseNpmSpecifier(value: string): NpmSpecifier | null {
+  if (!value.startsWith("npm:")) return null;
+  const body = value.slice(4);
+  const m = NPM_BODY_RE.exec(body);
+  if (!m) return null;
+  return {
+    name: m[1],
+    version: m[2] ? m[2].slice(1) : undefined,
+    subpath: m[3] ?? "",
+  };
+}
+
+/** A single applied pin, for human-facing logging. */
+export interface AppliedPin {
+  name: string;
+  version: string;
+}
+
+export interface ReconcileResult {
+  /** The rewritten import map (a new object; input is not mutated). */
+  imports: Record<string, string>;
+  /** Distinct packages that were pinned, in first-seen order. */
+  pins: AppliedPin[];
+  /** True when at least one entry was rewritten. */
+  changed: boolean;
+}
+
+/**
+ * Rewrite every UNCONSTRAINED `npm:` specifier to the installed version
+ * reported by `resolveVersion`. Constrained specifiers (those that already
+ * carry a version/range) are left exactly as-is — Deno's native lock handling
+ * already tracks those correctly. Non-npm specifiers pass through untouched.
+ *
+ * `resolveVersion` returns `undefined` when the package is not installed (or
+ * has no readable version), in which case the specifier is left unchanged
+ * rather than guessed.
+ */
+export function reconcileImports(
+  imports: Record<string, string>,
+  resolveVersion: (pkg: string) => string | undefined,
+): ReconcileResult {
+  const out: Record<string, string> = {};
+  const pins: AppliedPin[] = [];
+  const seen = new Set<string>();
+  let changed = false;
+
+  for (const [key, value] of Object.entries(imports)) {
+    const spec = parseNpmSpecifier(value);
+    if (spec && spec.version === undefined) {
+      const version = resolveVersion(spec.name);
+      if (version) {
+        out[key] = `npm:${spec.name}@${version}${spec.subpath}`;
+        changed = true;
+        if (!seen.has(spec.name)) {
+          seen.add(spec.name);
+          pins.push({ name: spec.name, version });
+        }
+        continue;
+      }
+    }
+    out[key] = value;
+  }
+
+  return { imports: out, pins, changed };
+}

package/src/cli.ts

@@ -1,51 +1,12 @@
 /**
- * 1tube CLI entry point.
+ * 1tube CLI entry point (compatibility alias).
  *
- * Dispatches between the lightweight subcommands (`build`, `--help`,
- * `--version`) and the default `serve` path (which loads the full
- * gateway machinery via dynamic import).
- *
- * Subcommand modules are imported lazily so a CI box running
- * `1tube build` never pays the gateway's static-import cost (Hono,
- * registry, supervisor, every middleware, …) — and conversely, the
- * serve hot path doesn't drag in esbuild's typings just because the
- * build command exists.
- *
- * `Deno.args` is readonly so we cannot strip a leading `serve` token
- * to forward only the tail. Instead, the gateway's `parseArgs` already
- * silently ignores unknown positional tokens — so a literal `serve`
- * passed in the args list just no-ops, which is exactly what we want.
+ * The real dispatcher + serve orchestrator lives in `./launch.ts` — this file
+ * exists only so existing references to `src/cli.ts` (downstream CI, the npm
+ * bin's historical entrypoint, docs) keep working. There is a single launcher
+ * implementation; this just forwards to it.
  */
 
-const arg0 = Deno.args[0];
-
-if (arg0 === "build") {
-  const { runBuild } = await import("./cli/build.ts");
-  const code = await runBuild(Deno.args.slice(1));
-  Deno.exit(code);
-} else if (arg0 === "package") {
-  const { runPackage } = await import("./cli/package.ts");
-  const code = await runPackage(Deno.args.slice(1));
-  Deno.exit(code);
-} else if (arg0 === "--version" || arg0 === "-v") {
-  const { VERSION } = await import("./version.ts");
-  console.log(VERSION);
-  Deno.exit(0);
-} else if (arg0 === "--help" || arg0 === "-h") {
-  console.log(`Usage: 1tube <command> [options]
-
-Commands:
-  serve       Run the gateway (default when no command given)
-  build       Bundle functions for a target (--target workerd|vercel)
-  package     Build and/or wrap dist/ into a signed .1tube firmware payload
-  --version   Print version and exit
-  --help      Print this help
+import { run } from "./launch.ts";
 
-Run \`1tube <command> --help\` for command-specific options.
-`);
-  Deno.exit(0);
-} else {
-  // Default path — load the gateway. Dynamic import so the heavy
-  // graph is only resolved after the dispatch decision above.
-  await import("./server.ts");
-}
+await run(Deno.args);

package/src/launch.ts

@@ -0,0 +1,677 @@
+/**
+ * 1tube launcher — the single entry point for running and building 1tube.
+ *
+ * This is the one and only launcher: the npm `1tube` bin, the repo's deno
+ * tasks, and host projects all funnel through here. There is no second
+ * "in-process" serve path — `serve` always spawns the gateway as a child
+ * `deno run`, which is what lets the launcher reconcile the lockfile with the
+ * host's installed dependencies BEFORE the runtime resolves any npm specifier,
+ * and fully reload it when a dependency changes while running.
+ *
+ * Dispatch
+ * ========
+ *   build      → cli/build.ts   (bundle for workerd/vercel)
+ *   package    → cli/package.ts (sign a firmware payload)
+ *   --version  → print version
+ *   --help     → usage
+ *   <else>     → serve (the gateway)            ← default, may be spelled `serve`
+ *
+ * Why a spawning launcher (the dependency story)
+ * ==============================================
+ * The edge runtime uses `--node-modules-dir=false`, so Deno resolves npm
+ * specifiers from its own cache + lockfile, never from `node_modules`. A host
+ * import map commonly maps 1tube with an UNCONSTRAINED specifier
+ * (`npm:1tube/edge`, i.e. `@*`), and `@*` is satisfied by ANY version — so
+ * once the lock pins, say, `1tube@0.1.43`, bumping the dependency in
+ * `package.json` + `node_modules` silently changes nothing for the edge
+ * runtime, and the gateway (loaded from `node_modules`) can end up a different
+ * version than the edge surface its functions import.
+ *
+ * The launcher fixes this by rewriting every unconstrained `npm:` specifier to
+ * the EXACT version installed in `node_modules` (the source of truth the user
+ * controls via their package manager) and pointing the gateway at the
+ * resulting generated config. Because the specifier's version now tracks the
+ * installed dependency, Deno's NATIVE lockfile auto-update recomputes just
+ * that entry on the next run — every already-pinned dependency is left alone,
+ * so the lock keeps its reproducibility and warm-boot speed.
+ *
+ * Live reload
+ * ===========
+ * While serving, the launcher watches the host's deno config and the
+ * `package.json` of every pinned dependency. When an install or a config edit
+ * changes the effective dependency set, it prints a notice and fully reloads
+ * the gateway (kill + respawn) so Deno re-resolves against the new versions.
+ */
+
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { type AppliedPin, reconcileImports } from "./cli/dep-pin.ts";
+
+// ---------------------------------------------------------------------------
+// Top-level dispatch
+// ---------------------------------------------------------------------------
+
+export async function run(argv: readonly string[]): Promise<void> {
+  const arg0 = argv[0];
+  if (arg0 === "build") {
+    const { runBuild } = await import("./cli/build.ts");
+    Deno.exit(await runBuild(argv.slice(1)));
+  }
+  if (arg0 === "package") {
+    const { runPackage } = await import("./cli/package.ts");
+    Deno.exit(await runPackage(argv.slice(1)));
+  }
+  if (arg0 === "--version" || arg0 === "-v") {
+    const { VERSION } = await import("./version.ts");
+    console.log(VERSION);
+    Deno.exit(0);
+  }
+  if (arg0 === "--help" || arg0 === "-h") {
+    printHelp();
+    Deno.exit(0);
+  }
+  // Default: serve. A literal `serve` token is accepted and dropped.
+  const serveArgv = arg0 === "serve" ? argv.slice(1) : argv;
+  await runServe(parseServeArgs(serveArgv));
+}
+
+function printHelp(): void {
+  console.log(`Usage: 1tube <command> [options]
+
+Commands:
+  serve       Run the gateway (default when no command given)
+  build       Bundle functions for a target (--target workerd|vercel)
+  package     Build and/or wrap dist/ into a signed .1tube firmware payload
+  --version   Print version and exit
+  --help      Print this help
+
+Serve options (everything else is forwarded to the gateway):
+  --lock <path>                 Managed lockfile (default <cwd>/.1tube/deno.lock)
+  --no-lock                     Run without a lockfile
+  --refresh-lock                Drop the managed lock for a clean re-resolve
+  --config <path>               Host deno.json[c] (its import map is reconciled)
+  --env-file[=<path>]           Env file forwarded to the gateway (repeatable)
+  --minimum-dependency-age <n>  Forwarded to the gateway's deno run
+  --node-modules-dir <v>        Forwarded to the gateway (default false)
+  --no-pin                      Don't pin unconstrained npm specifiers
+  --no-dep-watch                Don't live-reload on dependency changes
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Serve argument parsing
+// ---------------------------------------------------------------------------
+
+interface ServeArgs {
+  lock?: string;
+  noLock: boolean;
+  refreshLock: boolean;
+  config?: string;
+  envFiles: string[];
+  minimumDependencyAge?: string;
+  nodeModulesDir: string;
+  serverOverride?: string;
+  pin: boolean;
+  depWatch: boolean;
+  forwarded: string[];
+}
+
+const VALUE_FLAGS = new Set([
+  "--lock",
+  "--config",
+  "--env-file",
+  "--minimum-dependency-age",
+  "--node-modules-dir",
+  "--server",
+]);
+
+function parseServeArgs(argv: readonly string[]): ServeArgs {
+  const out: ServeArgs = {
+    noLock: false,
+    refreshLock: false,
+    envFiles: [],
+    nodeModulesDir: "false",
+    pin: true,
+    depWatch: true,
+    forwarded: [],
+  };
+  let passthroughOnly = false;
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (passthroughOnly) {
+      out.forwarded.push(tok);
+      continue;
+    }
+    if (tok === "--") {
+      passthroughOnly = true;
+      continue;
+    }
+    if (tok === "--no-lock") {
+      out.noLock = true;
+      continue;
+    }
+    if (tok === "--refresh-lock") {
+      out.refreshLock = true;
+      continue;
+    }
+    if (tok === "--no-pin") {
+      out.pin = false;
+      continue;
+    }
+    if (tok === "--no-dep-watch") {
+      out.depWatch = false;
+      continue;
+    }
+    const eq = tok.indexOf("=");
+    const flag = tok.startsWith("--") && eq !== -1 ? tok.slice(0, eq) : tok;
+    if (VALUE_FLAGS.has(flag)) {
+      const value = eq !== -1 ? tok.slice(eq + 1) : argv[++i];
+      if (value === undefined) continue;
+      switch (flag) {
+        case "--lock":
+          out.lock = value;
+          break;
+        case "--config":
+          out.config = value;
+          break;
+        case "--env-file":
+          out.envFiles.push(value);
+          break;
+        case "--minimum-dependency-age":
+          out.minimumDependencyAge = value;
+          break;
+        case "--node-modules-dir":
+          out.nodeModulesDir = value;
+          break;
+        case "--server":
+          out.serverOverride = value;
+          break;
+      }
+      continue;
+    }
+    out.forwarded.push(tok);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// JSONC (deno.jsonc) tolerant parse — mirrors the gateway's own stripper.
+// ---------------------------------------------------------------------------
+
+function stripJsonc(text: string): string {
+  let out = "";
+  let inString = false;
+  let quote = "";
+  let escaped = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    const next = text[i + 1];
+    if (inString) {
+      out += ch;
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === quote) inString = false;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = true;
+      quote = ch;
+      out += ch;
+      continue;
+    }
+    if (ch === "/" && next === "/") {
+      while (i < text.length && text[i] !== "\n") i++;
+      out += "\n";
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      i += 2;
+      while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++;
+      i++;
+      continue;
+    }
+    out += ch;
+  }
+  return out.replace(/,\s*([}\]])/g, "$1");
+}
+
+// ---------------------------------------------------------------------------
+// Installed-version resolution (the package manager is the source of truth)
+// ---------------------------------------------------------------------------
+
+/**
+ * Locate the `package.json` of `pkg` in the nearest `node_modules`, walking up
+ * from each start dir. Returns the path so the watcher can subscribe to it.
+ */
+function findInstalledPackageJson(
+  pkg: string,
+  startDirs: readonly string[],
+): string | undefined {
+  const segments = pkg.split("/");
+  const tried = new Set<string>();
+  for (const start of startDirs) {
+    let dir = start;
+    while (true) {
+      const pkgJson = join(dir, "node_modules", ...segments, "package.json");
+      if (!tried.has(pkgJson)) {
+        tried.add(pkgJson);
+        try {
+          if (Deno.statSync(pkgJson).isFile) return pkgJson;
+        } catch {
+          // not here — keep walking up
+        }
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return undefined;
+}
+
+function readPackageVersion(pkgJsonPath: string): string | undefined {
+  try {
+    const version = JSON.parse(Deno.readTextFileSync(pkgJsonPath))?.version;
+    if (typeof version === "string" && /^[0-9]/.test(version)) return version;
+  } catch {
+    // unreadable / non-standard version — leave unpinned
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Config reconciliation
+// ---------------------------------------------------------------------------
+
+function absolutizeTarget(value: string, baseFileUrl: URL): string {
+  if (value.startsWith("./") || value.startsWith("../")) {
+    return new URL(value, baseFileUrl).href;
+  }
+  return value;
+}
+
+interface ReconciledConfig {
+  /** Absolute path the inner runtime should load as `--config`. */
+  configPath: string;
+  /**
+   * The exact bytes the gateway will resolve against — the reload
+   * fingerprint. For the generated config this is its content; with no
+   * reconciliation needed it is the user config's own bytes.
+   */
+  fingerprint: string;
+  /** Packages pinned this pass (for logging). */
+  pins: AppliedPin[];
+  /** Files to watch for live dependency changes. */
+  watchPaths: string[];
+  /** Generated config bytes to persist, or null when using the user config. */
+  generated: string | null;
+  /** Where the generated config should be written. */
+  generatedPath: string;
+}
+
+/**
+ * Read the host deno config, pin unconstrained npm specifiers to the installed
+ * versions, and decide which config the gateway should load. Pure compute +
+ * reads; the caller persists the generated file.
+ */
+function reconcileConfig(
+  userConfigPath: string,
+  lockDir: string,
+  pin: boolean,
+): ReconciledConfig {
+  const userBytes = Deno.readTextFileSync(userConfigPath);
+  const parsed = JSON.parse(stripJsonc(userBytes)) as {
+    imports?: Record<string, string>;
+    scopes?: Record<string, Record<string, string>>;
+    [k: string]: unknown;
+  };
+
+  const baseFileUrl = pathToFileURL(userConfigPath);
+  const startDirs = [Deno.cwd(), dirname(fileURLToPath(import.meta.url))];
+  const watchPaths = new Set<string>([userConfigPath]);
+  const resolveVersion = (p: string): string | undefined => {
+    const pkgJson = findInstalledPackageJson(p, startDirs);
+    if (!pkgJson) return undefined;
+    const version = readPackageVersion(pkgJson);
+    if (version) watchPaths.add(pkgJson);
+    return version;
+  };
+
+  let changed = false;
+  const next: typeof parsed = { ...parsed };
+  const pins: AppliedPin[] = [];
+  const generatedPath = join(lockDir, "deno.gen.json");
+
+  if (pin && parsed.imports && typeof parsed.imports === "object") {
+    const reconciled = reconcileImports(parsed.imports, resolveVersion);
+    const withAbs: Record<string, string> = {};
+    for (const [k, v] of Object.entries(reconciled.imports)) {
+      const abs = absolutizeTarget(v, baseFileUrl);
+      if (abs !== v) changed = true;
+      withAbs[k] = abs;
+    }
+    if (reconciled.changed) changed = true;
+    pins.push(...reconciled.pins);
+    next.imports = withAbs;
+  }
+
+  if (pin && parsed.scopes && typeof parsed.scopes === "object") {
+    const outScopes: Record<string, Record<string, string>> = {};
+    for (const [scopeKey, map] of Object.entries(parsed.scopes)) {
+      const r = reconcileImports(map, resolveVersion);
+      if (r.changed) changed = true;
+      const withAbs: Record<string, string> = {};
+      for (const [k, v] of Object.entries(r.imports)) {
+        const abs = absolutizeTarget(v, baseFileUrl);
+        if (abs !== v) changed = true;
+        withAbs[k] = abs;
+      }
+      const newKey = absolutizeTarget(scopeKey, baseFileUrl);
+      if (newKey !== scopeKey) changed = true;
+      outScopes[newKey] = withAbs;
+    }
+    next.scopes = outScopes;
+  }
+
+  if (!changed) {
+    // The user's config is already correct — load it directly, watch it.
+    return {
+      configPath: userConfigPath,
+      fingerprint: userBytes,
+      pins: [],
+      watchPaths: [...watchPaths],
+      generated: null,
+      generatedPath,
+    };
+  }
+
+  const serialized = JSON.stringify(next, null, 2) + "\n";
+  return {
+    configPath: generatedPath,
+    fingerprint: serialized,
+    pins,
+    watchPaths: [...watchPaths],
+    generated: serialized,
+    generatedPath,
+  };
+}
+
+/** Persist the generated config when its content differs from disk. */
+function persistGenerated(rc: ReconciledConfig, lockDir: string): void {
+  if (rc.generated === null) return;
+  let previous: string | undefined;
+  try {
+    previous = Deno.readTextFileSync(rc.generatedPath);
+  } catch {
+    // first run
+  }
+  if (previous !== rc.generated) {
+    try {
+      Deno.mkdirSync(lockDir, { recursive: true });
+    } catch {
+      // dir already exists / not creatable — write will surface a real error
+    }
+    Deno.writeTextFileSync(rc.generatedPath, rc.generated);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Serve orchestrator
+// ---------------------------------------------------------------------------
+
+function resolveToAbs(p: string): string {
+  return isAbsolute(p) ? p : resolve(Deno.cwd(), p);
+}
+
+async function runServe(args: ServeArgs): Promise<never> {
+  const serverPath = args.serverOverride
+    ? resolveToAbs(args.serverOverride)
+    : fileURLToPath(new URL("./server.ts", import.meta.url));
+
+  // Managed lockfile: default to the gateway-owned scratch path unless the
+  // caller opted out. Never frozen, so dependency changes self-heal.
+  let lockAbs: string | undefined;
+  if (!args.noLock) {
+    lockAbs = resolveToAbs(args.lock ?? join(".1tube", "deno.lock"));
+    try {
+      Deno.mkdirSync(dirname(lockAbs), { recursive: true });
+    } catch {
+      // best-effort
+    }
+    if (args.refreshLock) {
+      try {
+        Deno.removeSync(lockAbs);
+      } catch {
+        // already absent
+      }
+    }
+  }
+  const lockDir = lockAbs ? dirname(lockAbs) : resolveToAbs(".1tube");
+
+  const userConfigAbs = args.config ? resolveToAbs(args.config) : undefined;
+
+  // When the host doesn't supply its own import map, fall back to 1tube's
+  // bundled deno.json (packageRoot/deno.json). The gateway's own sources use
+  // fully-qualified npm:/jsr: specifiers, so this only matters for hosts whose
+  // functions resolve bare aliases — and it never gets reconciled (its map is
+  // 1tube's own, fully constrained).
+  let bundledConfigAbs: string | undefined;
+  if (!userConfigAbs) {
+    const candidate = fileURLToPath(new URL("../deno.json", import.meta.url));
+    try {
+      if (Deno.statSync(candidate).isFile) bundledConfigAbs = candidate;
+    } catch {
+      // no bundled config (unbundled checkout) — run without one
+    }
+  }
+
+  // Child env additions (merged onto the inherited environment).
+  const childEnv: Record<string, string> = {};
+  if (lockAbs) childEnv.ONETUBE_LOCK = lockAbs;
+  // Deno 2.9's 24h minimum-dependency-age default makes freshly published
+  // pins fail to resolve; it must be set before the gateway's Deno starts.
+  if (
+    !Deno.env.get("NPM_CONFIG_MIN_RELEASE_AGE") &&
+    !Deno.env.get("npm_config_min_release_age")
+  ) {
+    childEnv.NPM_CONFIG_MIN_RELEASE_AGE = "0";
+  }
+
+  const buildAndPersist = (reason: "boot" | "reload"): ReconciledConfig | undefined => {
+    if (!userConfigAbs) return undefined;
+    let rc: ReconciledConfig;
+    try {
+      rc = reconcileConfig(userConfigAbs, lockDir, args.pin);
+    } catch (err) {
+      console.warn(
+        `[1tube] launch: could not reconcile ${userConfigAbs} (${
+          err instanceof Error ? err.message : String(err)
+        }) — using it as-is`,
+      );
+      return undefined;
+    }
+    persistGenerated(rc, lockDir);
+    if (rc.pins.length > 0) {
+      const summary = rc.pins.map((p) => `${p.name}@${p.version}`).join(", ");
+      const verb = reason === "boot" ? "pinned" : "re-pinned";
+      console.log(`[1tube] launch: ${verb} npm specifier(s) to installed: ${summary}`);
+    }
+    return rc;
+  };
+
+  const buildDenoArgs = (configPath: string | undefined): string[] => {
+    const denoArgs: string[] = ["run", "-q", "--allow-all"];
+    denoArgs.push(`--node-modules-dir=${args.nodeModulesDir}`);
+    if (lockAbs) denoArgs.push("--lock", lockAbs);
+    if (args.minimumDependencyAge !== undefined) {
+      denoArgs.push(`--minimum-dependency-age=${args.minimumDependencyAge}`);
+    }
+    for (const envFile of args.envFiles) {
+      denoArgs.push(`--env-file=${resolveToAbs(envFile)}`);
+    }
+    if (configPath) denoArgs.push("--config", configPath);
+    denoArgs.push(serverPath);
+    denoArgs.push(...args.forwarded);
+    return denoArgs;
+  };
+
+  // --- supervise loop: spawn the gateway, reload on dependency change ---
+
+  let stopping = false;
+  let currentChild: Deno.ChildProcess | undefined;
+
+  const stop = (sig: Deno.Signal) => {
+    stopping = true;
+    try {
+      currentChild?.kill(sig);
+    } catch {
+      // already gone
+    }
+  };
+  const onSigint = () => stop("SIGINT");
+  Deno.addSignalListener("SIGINT", onSigint);
+  let onSigterm: (() => void) | undefined;
+  if (Deno.build.os !== "windows") {
+    onSigterm = () => stop("SIGTERM");
+    Deno.addSignalListener("SIGTERM", onSigterm);
+  }
+
+  let lastFingerprint: string | undefined;
+
+  while (!stopping) {
+    const rc = buildAndPersist(lastFingerprint === undefined ? "boot" : "reload");
+    lastFingerprint = rc?.fingerprint ?? "";
+    const configPath = rc?.configPath ?? userConfigAbs ?? bundledConfigAbs;
+
+    const child = new Deno.Command(Deno.execPath(), {
+      args: buildDenoArgs(configPath),
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+      env: childEnv,
+    }).spawn();
+    currentChild = child;
+
+    let reloadRequested = false;
+    const watcher = args.depWatch && rc
+      ? startDepWatcher(rc.watchPaths, () => {
+        // Recompute the effective config; reload only on a real change.
+        let nextRc: ReconciledConfig;
+        try {
+          nextRc = reconcileConfig(userConfigAbs!, lockDir, args.pin);
+        } catch {
+          return;
+        }
+        if (nextRc.fingerprint === lastFingerprint) return;
+        console.log(
+          "[1tube] launch: dependency change detected — reloading gateway",
+        );
+        reloadRequested = true;
+        try {
+          child.kill(Deno.build.os === "windows" ? "SIGKILL" : "SIGTERM");
+        } catch {
+          // already exiting
+        }
+      })
+      : undefined;
+
+    const status = await child.status;
+    currentChild = undefined;
+    watcher?.close();
+
+    if (stopping) {
+      cleanupSignals(onSigint, onSigterm);
+      Deno.exit(status.code);
+    }
+    if (reloadRequested) {
+      continue; // respawn with the freshly reconciled config
+    }
+    // The gateway exited on its own — propagate its code.
+    cleanupSignals(onSigint, onSigterm);
+    Deno.exit(status.code);
+  }
+
+  cleanupSignals(onSigint, onSigterm);
+  Deno.exit(0);
+}
+
+function cleanupSignals(
+  onSigint: () => void,
+  onSigterm: (() => void) | undefined,
+): void {
+  try {
+    Deno.removeSignalListener("SIGINT", onSigint);
+  } catch {
+    // ignore
+  }
+  if (onSigterm) {
+    try {
+      Deno.removeSignalListener("SIGTERM", onSigterm);
+    } catch {
+      // ignore
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Dependency watcher
+// ---------------------------------------------------------------------------
+
+interface DepWatcher {
+  close(): void;
+}
+
+/**
+ * Watch the host config + each pinned dependency's package.json (its parent
+ * dir, so atomic-rename installs are still observed) and fire `onChange`
+ * (debounced) on any filesystem event.
+ */
+function startDepWatcher(paths: readonly string[], onChange: () => void): DepWatcher {
+  // Watch parent directories: editors and package managers frequently replace
+  // files via rename, which drops a file-level watch.
+  const dirs = [...new Set(paths.map((p) => dirname(p)))].filter((d) => {
+    try {
+      return Deno.statSync(d).isDirectory;
+    } catch {
+      return false;
+    }
+  });
+  if (dirs.length === 0) return { close() {} };
+
+  const targets = new Set(paths);
+  let watcher: Deno.FsWatcher;
+  try {
+    watcher = Deno.watchFs(dirs, { recursive: false });
+  } catch {
+    return { close() {} };
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let closed = false;
+  (async () => {
+    for await (const event of watcher) {
+      if (closed) break;
+      // Only react to the specific files we care about (the dirs may host
+      // many unrelated files, e.g. all of node_modules/<pkg>/).
+      if (!event.paths.some((p) => targets.has(p))) continue;
+      if (timer !== undefined) clearTimeout(timer);
+      timer = setTimeout(onChange, 250);
+    }
+  })();
+
+  return {
+    close() {
+      closed = true;
+      if (timer !== undefined) clearTimeout(timer);
+      try {
+        watcher.close();
+      } catch {
+        // already closed
+      }
+    },
+  };
+}
+
+if (import.meta.main) {
+  await run(Deno.args);
+}