1tube 0.1.46 → 0.1.48

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/deno.lock

@@ -15,13 +15,14 @@
     "npm:@ai-sdk/google@2": "2.0.74_zod@3.25.76",
     "npm:@ai-sdk/openai@2": "2.0.106_zod@3.25.76",
     "npm:ai@6": "6.0.193_zod@3.25.76",
-    "npm:drizzle-kit@1.0.0-rc.3": "1.0.0-rc.3",
+    "npm:drizzle-kit@1.0.0-rc.4": "1.0.0-rc.4",
     "npm:drizzle-orm@1.0.0-rc.3": "1.0.0-rc.3_zod@3.25.76",
+    "npm:drizzle-orm@1.0.0-rc.4": "1.0.0-rc.4_zod@3.25.76",
     "npm:es-module-lexer@2": "2.1.0",
     "npm:esbuild@~0.25.5": "0.25.12",
     "npm:esbuild@~0.28.1": "0.28.1",
-    "npm:hono@4": "4.12.27",
-    "npm:hono@^4.12.27": "4.12.27",
+    "npm:hono@4": "4.12.30",
+    "npm:hono@^4.12.30": "4.12.30",
     "npm:typescript@latest": "6.0.3",
     "npm:zod@^3.23.0": "3.25.76"
   },
@@ -129,8 +130,8 @@
         "json-schema"
       ]
     },
-    "@drizzle-team/brocli@0.11.0": {
-      "integrity": "sha512-hD3pekGiPg0WPCCGAZmusBBJsDqGUR66Y452YgQsZOnkdQ7ViEPKuyP4huUGEZQefp8g34RRodXYmJ2TbCH+tg=="
+    "@drizzle-team/brocli@0.12.0": {
+      "integrity": "sha512-mlUE+rZ8CatQekLhnaiN91Iemdd+e2gFKooGlnRB3oPTL3VghLfX24dx7HrzMNeC1JrIB/0kpsfyty3f5HNfxQ=="
     },
     "@esbuild/aix-ppc64@0.25.12": {
       "integrity": "sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==",
@@ -417,8 +418,8 @@
         "zod"
       ]
     },
-    "drizzle-kit@1.0.0-rc.3": {
-      "integrity": "sha512-lwGIi6GTlEYzrtac1Szecns+zrAxjaOoNysfBCKRQOXQE7nMJ8IU2I2S6ek3FHEm1N30dQb5YrTdqV7zNH6n7A==",
+    "drizzle-kit@1.0.0-rc.4": {
+      "integrity": "sha512-KZCpjRyu+oYHLj/UJogfFlOkWhHVkaEI2EOT1U3NDVXUzLoTyPjqwFxwOrlQxsY6jzRyxcz4EacqboGfhEeYrA==",
       "dependencies": [
         "@drizzle-team/brocli",
         "@js-temporal/polyfill",
@@ -437,6 +438,15 @@
         "zod"
       ]
     },
+    "drizzle-orm@1.0.0-rc.4_zod@3.25.76": {
+      "integrity": "sha512-BT+pf+qoiYHqltoA88Jmf6ilGMXPlpfE0hEJKc2adRtMCAl25Swk/t5gXcWxZNAwdtf3F5gCd2FpeOyP/pT0Hw==",
+      "dependencies": [
+        "zod"
+      ],
+      "optionalPeers": [
+        "zod"
+      ]
+    },
     "es-module-lexer@2.1.0": {
       "integrity": "sha512-n27zTYMjYu1aj4MjCWzSP7G9r75utsaoc8m61weK+W8JMBGGQybd43GstCXZ3WNmSFtGT9wi59qQTW6mhTR5LQ=="
     },
@@ -515,11 +525,11 @@
         "resolve-pkg-maps"
       ]
     },
-    "hono@4.12.27": {
-      "integrity": "sha512-1yrb/+w6HWQJrUCLkJ2IF5jNIPvvFkblV5RNOYl6bV+OA6p9GLcMpHFFGTosSvHvcAUibuUukRqhlYI4z32C7Q=="
+    "hono@4.12.30": {
+      "integrity": "sha512-emn+JoJjrN9YTpRDS5it/UI2SO9BAE37T6I3d963RxcZ81G9A4pr2SZTEiiaiKbzx+NKRg5BZ89fCL7gCJCUog=="
     },
-    "jiti@2.6.1": {
-      "integrity": "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==",
+    "jiti@2.7.0": {
+      "integrity": "sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==",
       "bin": true
     },
     "jsbi@4.3.2": {
@@ -553,9 +563,9 @@
     ],
     "packageJson": {
       "dependencies": [
-        "npm:drizzle-kit@1.0.0-rc.3",
-        "npm:drizzle-orm@1.0.0-rc.3",
-        "npm:hono@^4.12.27"
+        "npm:drizzle-kit@1.0.0-rc.4",
+        "npm:drizzle-orm@1.0.0-rc.4",
+        "npm:hono@^4.12.30"
       ]
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "1tube",
-  "version": "0.1.46",
+  "version": "0.1.48",
   "private": false,
   "description": "Self-hosted Supabase Edge Functions gateway for Deno, plus an ESLint plugin for consumers",
   "license": "MIT",
@@ -55,16 +55,16 @@
     "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"
   },
   "dependencies": {
-    "drizzle-orm": "1.0.0-rc.3",
-    "hono": "^4.12.27"
+    "drizzle-orm": "1.0.0-rc.4",
+    "hono": "^4.12.30"
   },
   "devDependencies": {
-    "drizzle-kit": "1.0.0-rc.3"
+    "drizzle-kit": "1.0.0-rc.4"
   }
 }

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);