@helipod/cli 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,366 @@
+import { ProjectArtifacts, LoadedProject, ResolvedRoute } from './project.js';
+export { DEFAULT_INDEX, loadProject } from './project.js';
+import { GeneratedBundle } from '@helipod/codegen';
+export { writeGenerated } from '@helipod/codegen';
+import { ComponentDefinition, HelipodConfig, WakeHost } from '@helipod/component';
+export { HelipodConfig } from '@helipod/component';
+import { D as DeployWireResult, F as FleetHandles } from './http-handler-BFprdo3f.js';
+export { H as HttpRequest, a as HttpResponse, S as ServerInfo, h as handleHttpRequest } from './http-handler-BFprdo3f.js';
+import { ServerHandle, ServeOptions, RuntimeHost, EmbeddedRuntime, WriteRouter, EmbeddedWriteFanoutAdapter } from '@helipod/runtime-embedded';
+import { AdminApi } from '@helipod/admin';
+import { StorageRoute } from '@helipod/storage';
+import { DocStore } from '@helipod/docstore';
+import { InMemoryLogSink, RegisteredFunction } from '@helipod/executor';
+import { BlobStore } from '@helipod/blobstore';
+import { S3Config } from '@helipod/blobstore-s3';
+import '@helipod/values';
+
+/**
+ * The push pipeline: load the project → run codegen → return artifacts. `helipod dev` runs
+ * this on startup and on every file change (hot reload re-runs `push` and re-registers the
+ * module map with the running engine — no restart).
+ */
+
+interface PushResult {
+    project: ProjectArtifacts;
+    generated: GeneratedBundle;
+}
+declare function push(loaded: LoadedProject, components?: ComponentDefinition[], existingTableNumbers?: Record<string, number>): PushResult;
+
+type RuntimeKind = "bun" | "node" | "auto";
+interface DevOptions {
+    port?: number;
+    ip?: string;
+    functionsDir?: string;
+    dataPath?: string;
+    runtime?: RuntimeKind;
+    /** Optional static web UI directory to serve alongside the API/WebSocket. */
+    webDir?: string;
+    /** Postgres connection string (flag wins over `HELIPOD_DATABASE_URL`); unset → SQLite. */
+    databaseUrl?: string;
+    /** File-storage backend flag overrides (`--storage-bucket`/`--storage-endpoint`; win over env). */
+    storageBucket?: string;
+    storageEndpoint?: string;
+}
+interface ResolvedDevOptions {
+    port: number;
+    ip: string;
+    functionsDir: string;
+    dataPath: string;
+    runtime: RuntimeKind;
+    webDir: string | undefined;
+    databaseUrl: string | undefined;
+    storageBucket: string | undefined;
+    storageEndpoint: string | undefined;
+}
+declare function resolveDevOptions(options?: DevOptions): ResolvedDevOptions;
+/** Detect the active JS runtime (Bun is primary; Node is supported). */
+declare function detectRuntime(): "bun" | "node";
+
+type DevServer = ServerHandle<ResolvedRoute>;
+type DevServerOptions = ServeOptions<ResolvedRoute, AdminApi, StorageRoute, DeployWireResult, FleetHandles>;
+/** Start the dev server using the best backend for the current runtime. */
+declare function startDevServer(runtime: EmbeddedRuntime, options: DevServerOptions): Promise<DevServer>;
+/**
+ * The process {@link RuntimeHost}: binds a runtime to a real TCP port via `Bun.serve` (primary) or
+ * `node:http` + `ws`. This class is the ONLY place in the CLI that owns those host primitives — the
+ * `detectRuntime()` bun/node split is its private internal (in {@link startDevServer}). Production
+ * entrypoints (`dev`/`serve`/`binary`) reach serving exclusively through `host.serve(...)`; a
+ * Durable Object host (Slice 3) will implement the same seam without touching any of the above.
+ * `serve` is a thin delegation to {@link startDevServer}, which stays exported for tests/benches.
+ */
+declare class ProcessRuntimeHost implements RuntimeHost<ResolvedRoute, AdminApi, StorageRoute, DeployWireResult, FleetHandles> {
+    serve(runtime: EmbeddedRuntime, options: DevServerOptions): Promise<DevServer>;
+}
+
+/**
+ * A small debounced watch loop. The fs-watch wiring is injected so the debounce/dispatch
+ * logic is testable without touching the filesystem.
+ */
+type WatchTriggerReason = "initial" | "change";
+interface WatchLoopOptions {
+    /** Subscribe to raw change events; return an unsubscribe. */
+    subscribe: (onChange: () => void) => () => void;
+    /** Called (debounced) to rebuild; reason "initial" fires once up front. */
+    onTrigger: (reason: WatchTriggerReason) => void | Promise<void>;
+    debounceMs?: number;
+    /** Injectable timer for tests. */
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+interface WatchLoop {
+    start(): void;
+    stop(): void;
+}
+declare function createWatchLoop(options: WatchLoopOptions): WatchLoop;
+
+declare function loadFunctionsDir(dir: string): Promise<LoadedProject>;
+
+declare function loadConfig(projectDir: string): Promise<HelipodConfig>;
+
+/** The default backend functions directory name. */
+declare const DEFAULT_FUNCTIONS_DIR = "helipod";
+interface ResolvedFunctionsDir {
+    /** Absolute path to the functions directory. */
+    functionsDir: string;
+    /** Absolute path to the project root (where helipod.config.ts lives). */
+    projectRoot: string;
+}
+/**
+ * Resolve the functions directory. Precedence, highest first:
+ *   1. an explicit `--dir` value
+ *   2. `functionsDir` in helipod.config.ts
+ *   3. DEFAULT_FUNCTIONS_DIR
+ *
+ * There is deliberately NO implicit fallback to `convex/`: a Convex layout is
+ * converted by `helipod migrate`, never adopted silently. See
+ * docs_old/superpowers/specs/2026-06-06-functions-dir-rename-design.md.
+ *
+ * With an explicit flag the project root is that path's parent, so a caller can point at a
+ * functions directory anywhere. Without one the root is the cwd, which is what makes it safe
+ * to read the config before the directory name is known: helipod.config.ts always sits at
+ * the root and never inside the functions directory.
+ */
+declare function resolveFunctionsDir(flagValue: string | undefined, cwd: string): Promise<ResolvedFunctionsDir>;
+/** The failure message when the resolved directory does not exist. The one Convex-aware string in the CLI. */
+declare function functionsDirNotFoundMessage(functionsDir: string): string;
+
+declare function devCommand(args: string[]): Promise<number>;
+declare function codegenCommand(args: string[]): Promise<number>;
+declare function runCli(argv: string[]): Promise<number>;
+
+/** Resolved storage config. A `bucket` selects the S3 backend; everything else is FS. */
+type StorageConfig = Partial<S3Config> & {
+    bucket?: string;
+};
+
+interface BootResult {
+    runtime: EmbeddedRuntime;
+    adminApi: AdminApi;
+    project: ProjectArtifacts;
+    generated: GeneratedBundle;
+    store: DocStore;
+    logSink: InMemoryLogSink;
+    /** The boot-time component set (from helipod.config.ts) — `applyDeploy` re-composes against it. */
+    components: ComponentDefinition[];
+    /** The always-on file-storage byte backend (FS or S3), shared by the provider/reaper/routes. */
+    blobStore: BlobStore;
+    /**
+     * The engine-owned `/api/storage/*` handlers (upload/confirm/serve). Reserved-path routes the
+     * server splices into its dispatch (NOT user `http.ts` routes) — see `server.ts`.
+     */
+    storageRoutes: StorageRoute[];
+    /**
+     * Reserved engine routes contributed by composed components (e.g. `@helipod/auth`'s
+     * `/api/auth/oauth/*`), each bound to `runtime.runHttpAction` and shaped as an engine-owned
+     * `StorageRoute` `{method,pathPrefix,handler}` so `server.ts` dispatches them exactly like the
+     * always-on storage routes. Fixed at boot (the component set is fixed at boot — only functions/
+     * schema hot-swap), so no `setRoutes` live-swap is needed. Empty when no component declares routes.
+     */
+    componentRoutes: StorageRoute[];
+    /**
+     * Set only when `objectStoreUrl` was given — the object-store node's graceful-shutdown handle.
+     * `serve.ts`'s shutdown calls this AFTER `server.close()` and BEFORE `store.close()`. Two shapes,
+     * mutually exclusive by construction (at most one of `replica`/writer ever built this boot):
+     *   - Writer (Tier 3 Slice 6, Task 6.5): `store.relinquish()`, which best-effort CAS-clears the
+     *     lease IN THE BUCKET, not just in-process — see `ObjectStoreDocStore.relinquish()`'s doc —
+     *     so a challenger takes over immediately instead of waiting out the full TTL.
+     *   - Replica (Tier 3 Slice 8, Task 8.2): stops the reactive-tailer wiring helper (Task 8.1) and
+     *     `removeConsumer`s this replica's watermark, so a departed replica stops pinning the
+     *     writer's gc — see `buildObjectStoreReplicaNode`'s doc.
+     */
+    objectStoreRelease?: () => Promise<void>;
+    /**
+     * Tier 3 Slice 8 follow-on (replica write-forwarding): set only when this boot is a
+     * `--replica` configured with `--writer-url` (i.e. a `ReplicaWriteForwarder` was wired in as
+     * the runtime's `writeRouter`). `serve.ts` threads this straight through to
+     * `startDevServer`'s `replicaWriterUrl` option, which arms `/api/run`'s single-hop defensive
+     * guard (`http-handler.ts`). Absent whenever `--writer-url` is unset (the pre-existing
+     * reject-with-message replica behavior, unchanged) or this isn't a replica boot at all.
+     */
+    replicaWriterUrl?: string;
+}
+/**
+ * Merge the always-on `_storage:*` privileged built-ins into a function map. The `_storage` modules
+ * must live in the runtime's `modules` map (not just `systemModules`) because the action-mode
+ * `ctx.storage.store` reaches them through the trusted `invoke`, and the reaper driver through
+ * `runFunction` — both resolve `modules`. Since `setModules` (dev reload / `helipod deploy`)
+ * REPLACES `modules` wholesale, every such swap must re-apply this so storage survives a hot-swap.
+ */
+declare function withStorageModules(map: Record<string, RegisteredFunction>): Record<string, RegisteredFunction>;
+/**
+ * Every input the boot core takes. `bootProject` DERIVES its own options from this type (rather than
+ * re-declaring them) and forwards them with a spread — see `BootProjectOptions`'s doc for why that
+ * matters. Adding an option here therefore reaches `bootProject`'s public surface automatically; the
+ * only keys that don't are the two `bootProject` produces itself (`loaded`/`components`).
+ */
+interface BootLoadedOptions {
+    loaded: LoadedProject;
+    components: ComponentDefinition[];
+    dataPath: string;
+    adminKey: string;
+    /** Postgres connection string; when unset, falls back to the zero-config SQLite file store. */
+    databaseUrl?: string;
+    /** File-storage backend overrides (CLI flags win over env, resolved via `resolveStorageConfig`). */
+    storage?: StorageConfig;
+    /**
+     * Override the pending-upload TTL (ms) the `ctx.storage` provider stamps on `expiresAt`. Unset →
+     * the provider default (1h). Exists so tests can force a short reap deadline; production leaves
+     * it at the default.
+     */
+    storageUploadTtlMs?: number;
+    /**
+     * Override the orphan-reaper's sweep interval (ms). Unset → the reaper default (60s). Same
+     * test-only motivation as `storageUploadTtlMs`.
+     */
+    storageReaperSweepMs?: number;
+    /**
+     * Tier 2 fleet wiring (from `@helipod/fleet`'s `prepareFleetNode`). When set, `store` is the
+     * pre-constructed (read-only-until-promoted) Postgres store — used INSTEAD of `makeStore` — and
+     * the runtime is built as a fleet node: writes route through `writeRouter` when this node isn't
+     * the writer, drivers are deferred until promotion (`deferDrivers`), and a promoted writer's
+     * commits fan out via `fanoutAdapter` (pg_notify). Absent for dev / non-fleet serve.
+     */
+    fleet?: {
+        store: DocStore;
+        writeRouter?: WriteRouter;
+        deferDrivers?: boolean;
+        fanoutAdapter?: EmbeddedWriteFanoutAdapter;
+        /** Shards B2a: shard count — >1 builds a ShardedTransactor (per-shard parallel commits). */
+        numShards?: number;
+        /** Fleet B3 hybrid (multi-writer): the replica-backed query store (queries route here; mutations
+         *  commit to `store`). Threaded straight into `createEmbeddedRuntime`. */
+        queryStore?: DocStore;
+        /** Receipted Outbox (verdict §(c) placement): the authoritative receipts store the Connect handshake
+         *  classifies/prunes against — the PRIMARY on a sync node (whose `store` is the receipt-less replica),
+         *  so the handshake never spuriously resets. Threaded straight into `createEmbeddedRuntime`. */
+        receiptsStore?: DocStore;
+        /** Fleet B3 hybrid RYOW: awaited in the runtime fan-out drain before a local commit's re-runs. */
+        beforeNotify?: (commitTs: bigint) => Promise<void>;
+        /** Fleet B4: group commit — resolved by `@helipod/fleet`'s `node.ts` from its OWN
+         *  `HELIPOD_GROUP_COMMIT` read (mirrors how `numShards` is resolved fleet-side, before
+         *  `bootLoaded` runs) and threaded straight into `createEmbeddedRuntime`. Unset → `false`. */
+        groupCommit?: boolean;
+        /** Triggers D1: the stable-prefix accessor for `DriverContext.readLog` (`min(shard_leases.frontier_ts)`
+         *  in a fleet). Threaded straight into `createEmbeddedRuntime`; absent outside a fleet. */
+        stablePrefix?: () => Promise<bigint | null>;
+        /** Receipted Outbox: fleet owns the `clientReceiptsGuard()` registration on the concrete Postgres
+         *  store (in `armWriter`, before the fence) — so `createEmbeddedRuntime` must SKIP its own, which
+         *  would land on a sync node's `SwitchableDocStore` and vanish on the promotion swapTo. Threaded
+         *  straight into `createEmbeddedRuntime`; absent outside a fleet (the runtime owns it there). */
+        externalReceiptsGuard?: boolean;
+    };
+    /**
+     * Tier 3 Slice 6: object-storage substrate writer node. When set, `store` (at the `opts.fleet?.
+     * store ?? … ?? makeStore(...)` seam below) becomes an `ObjectStoreDocStore` over this URL's
+     * bucket (shard "0") instead of the usual SQLite/Postgres store — see `buildObjectStoreWriterNode`'s
+     * doc comment. Mutually exclusive with `fleet` (Tier 2 and Tier 3 are alternative write-scaling
+     * stories); combining both throws.
+     */
+    objectStoreUrl?: string;
+    /** Called once, synchronously, the moment the lease-heartbeat driver detects this node has been
+     *  fenced (lost the shard-0 lease to a challenger). `serve.ts` wires this to trigger graceful
+     *  shutdown. Ignored when `objectStoreUrl` is unset. */
+    objectStoreOnFenced?: (e: Error) => void;
+    /** Test-only overrides (mirrors `storageUploadTtlMs`'s pattern) — unset → the production defaults
+     *  (`DEFAULT_OBJECTSTORE_LEASE_TTL_MS`/`DEFAULT_OBJECTSTORE_HEARTBEAT_MS`/`leaseTtlMs + 5000`). */
+    objectStoreLeaseTtlMs?: number;
+    objectStoreHeartbeatMs?: number;
+    objectStoreAcquireTimeoutMs?: number;
+    objectStoreAcquirePollIntervalMs?: number;
+    /** Test-only: force a deterministic writer id instead of a fresh `randomUUID()` per boot. */
+    objectStoreWriterId?: string;
+    /** Tier 3 Slice 7, Task 7.3: the gc-driver's sweep cadence (ms). Unset → `DEFAULT_OBJECTSTORE_GC_MS`
+     *  (~60s). `serve.ts` threads `HELIPOD_OBJECTSTORE_GC_MS` in here; tests can also set it directly
+     *  to force an observable reclamation on a short timescale. Ignored when `objectStoreUrl` is unset. */
+    objectStoreGcMs?: number;
+    /** Tier 3 multi-shard single-node serve: the number of object-storage lanes a `--object-store`
+     *  WRITER node owns (`serve.ts` threads `--shards`/`HELIPOD_FLEET_SHARDS` in here). Unset / `1`
+     *  → the shipped single-shard path (shard "0"), byte-identical. `> 1` → this node opens+acquires
+     *  all `shardIdList(N)` lanes and composes a `ShardedObjectStoreDocStore`; the runtime's
+     *  `numShards` is sized to N so the `ShardedTransactor` routes writes to the owning lane. Ignored
+     *  for a `--replica` boot (a replica reads its lane count from the bucket's `globals.numShards`, not
+     *  this flag — it has no `--shards` of its own) and when `objectStoreUrl` is unset. */
+    objectStoreShards?: number;
+    /** Tier 3 Slice 8, Task 8.2: boot this node as a READ-ONLY REPLICA of `objectStoreUrl`'s shard
+     *  instead of a writer — materializes + tails, NEVER acquires the write lease (every mutation is
+     *  rejected with `REPLICA_WRITE_REJECTED_MESSAGE`), and runs no heartbeat/gc drivers. Requires
+     *  `objectStoreUrl` (throws if set without it — `serve.ts` also validates this at the CLI-flag
+     *  level, before ever reaching here). Ignored (no-op) when `objectStoreUrl` is unset. */
+    replica?: boolean;
+    /** Test-only: force a deterministic consumer-watermark id for the replica's tailer. Ignored
+     *  unless `replica` is set. See `buildObjectStoreReplicaNode`'s `consumerId`. */
+    objectStoreReplicaConsumerId?: string;
+    /** Test-only: shorten the replica's reactive-tailer poll cadence so a materialize-and-fan-out
+     *  round is observable within a test's timescale. Unset → `DEFAULT_OBJECTSTORE_REPLICA_POLL_MS`
+     *  (1000ms). Ignored unless `replica` is set. */
+    objectStoreReplicaPollMs?: number;
+    /**
+     * Tier 3 Slice 8 follow-on: the writer node's URL, from `--writer-url`/`HELIPOD_WRITER_URL`.
+     * When set on a `replica` boot, every mutation/action is FORWARDED here (`ReplicaWriteForwarder`,
+     * wired in as `createEmbeddedRuntime`'s `writeRouter`) instead of being rejected locally.
+     * Ignored unless `replica` is also set. Unset (the default) → today's unchanged reject-with-
+     * `REPLICA_WRITE_REJECTED_MESSAGE` behavior.
+     */
+    writerUrl?: string;
+    /**
+     * The wake seam: the host's single alarm, for a host that STOPS THE PROCESS between requests (so
+     * `setTimeout` never fires and every driver silently goes dead). `serve.ts` builds this from
+     * `--wake-url`/`HELIPOD_WAKE_URL` (`httpWakeHost`); the runtime then multiplexes every driver
+     * timer down to one arm. Threaded straight into `createEmbeddedRuntime`. Unset (every existing
+     * deployment) → plain `setTimeout`, byte-for-byte unchanged.
+     */
+    wakeHost?: WakeHost;
+    /**
+     * The wake seam's other half: answers `DriverContext.backstopMs`, the floor/stretch applied to a
+     * driver's BACKSTOP poll cadence only (never a next-work wake). `serve.ts` builds this from
+     * `--backstop-min-ms`/`HELIPOD_BACKSTOP_MIN_MS`. Threaded straight into `createEmbeddedRuntime`.
+     * Unset → identity (the drivers' own 30s/60s), byte-for-byte unchanged.
+     */
+    backstopMs?: (defaultMs: number) => number;
+}
+/**
+ * `bootProject`'s options: everything `bootLoaded` takes, MINUS the two things `bootProject` exists
+ * to produce itself, PLUS the `functionsDir` it produces them from. Derived deliberately — never
+ * re-declared.
+ *
+ * WHY (a trap this has already cost a full debug cycle — do not re-introduce it): `bootProject` used to
+ * re-declare its own option type and forward every key BY HAND into a fresh object literal. That
+ * shape drops options SILENTLY. TypeScript's excess-property check does not apply through a spread,
+ * and every caller passes optional options via conditional spread
+ * (`...(x !== undefined ? { k: v } : {})`, see `serve.ts`) — so a caller could hand `bootProject` a
+ * key its type never declared, get ZERO diagnostics, and have the value vanish before it ever
+ * reached `createEmbeddedRuntime`. That is exactly how the wake seam shipped dead: `serve.ts` built
+ * a valid `httpWakeHost(--wake-url)`, `bootProject` dropped it, the runtime silently took the
+ * `setTimeout` branch, and scheduled work never fired on a host that stops the process between
+ * requests — with the whole suite green, because nothing type-checked or tested the seam BETWEEN
+ * the two functions.
+ *
+ * Deriving from `BootLoadedOptions` + forwarding with a spread makes the drop structurally
+ * impossible rather than merely caught: a new `bootLoaded` option is part of this type, and is
+ * forwarded, the moment it is declared. The `Omit` is the ONLY exclusion list, and it is deliberate:
+ * `loaded`/`components` are `bootProject`'s own outputs (`loadFunctionsDir`/`loadConfig`), so
+ * accepting them from a caller would be meaningless. Anything else belongs here automatically.
+ */
+type BootProjectOptions = Omit<BootLoadedOptions, "loaded" | "components"> & {
+    functionsDir: string;
+};
+declare function bootProject(opts: BootProjectOptions): Promise<BootResult>;
+
+interface BinaryOptions {
+    port: number;
+    ip: string;
+    dataDir: string;
+    adminKey: string;
+    /** Postgres connection string (flag wins over `HELIPOD_DATABASE_URL`); unset → SQLite. */
+    databaseUrl?: string;
+}
+declare function resolveBinaryOptions(argv: string[], env: Record<string, string | undefined>): BinaryOptions;
+declare function startBinaryServer(loaded: LoadedProject, components: ComponentDefinition[], opts: BinaryOptions, dashboard?: Record<string, string>): Promise<{
+    server: DevServer;
+    store: DocStore;
+    runtime: EmbeddedRuntime;
+}>;
+declare function runBinaryServer(loaded: LoadedProject, components: ComponentDefinition[], dashboard?: Record<string, string>): Promise<void>;
+
+export { type BootLoadedOptions, type BootProjectOptions, type BootResult, DEFAULT_FUNCTIONS_DIR, type DevOptions, type DevServer, type DevServerOptions, LoadedProject, ProcessRuntimeHost, ProjectArtifacts, type PushResult, type ResolvedDevOptions, type ResolvedFunctionsDir, type RuntimeKind, type WatchLoop, type WatchLoopOptions, type WatchTriggerReason, bootProject, codegenCommand, createWatchLoop, detectRuntime, devCommand, functionsDirNotFoundMessage, loadConfig, loadFunctionsDir, push, resolveBinaryOptions, resolveDevOptions, resolveFunctionsDir, runBinaryServer, runCli, startBinaryServer, startDevServer, withStorageModules };

package/dist/index.js

@@ -0,0 +1,120 @@
+import {
+  DEFAULT_FUNCTIONS_DIR,
+  ProcessRuntimeHost,
+  bootLoaded,
+  bootProject,
+  codegenCommand,
+  createWatchLoop,
+  detectRuntime,
+  devCommand,
+  functionsDirNotFoundMessage,
+  loadConfig,
+  loadFunctionsDir,
+  push,
+  resolveDevOptions,
+  resolveFunctionsDir,
+  runCli,
+  startDevServer,
+  withStorageModules
+} from "./chunk-IBFZ2HUR.js";
+import {
+  handleHttpRequest
+} from "./chunk-N5J276OX.js";
+import {
+  DEFAULT_INDEX,
+  loadProject
+} from "./chunk-EPHSHGFU.js";
+
+// src/index.ts
+import { writeGenerated } from "@helipod/codegen";
+
+// src/binary-main.ts
+import { join } from "path";
+function resolveBinaryOptions(argv, env) {
+  let port = env.PORT ? Number(env.PORT) : 3e3;
+  let ip = "0.0.0.0";
+  let dataDir = "./data";
+  let databaseUrl = env.HELIPOD_DATABASE_URL;
+  const adminKey = (env.HELIPOD_ADMIN_KEY ?? "").trim();
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--port" && argv[i + 1] !== void 0) port = Number(argv[++i]);
+    else if (a === "--hostname" && argv[i + 1] !== void 0) ip = argv[++i];
+    else if (a === "--data-dir" && argv[i + 1] !== void 0) dataDir = argv[++i];
+    else if (a === "--database-url" && argv[i + 1] !== void 0) databaseUrl = argv[++i];
+  }
+  return { port, ip, dataDir, adminKey, databaseUrl };
+}
+async function startBinaryServer(loaded, components, opts, dashboard) {
+  const boot = await bootLoaded({
+    loaded,
+    components,
+    dataPath: join(opts.dataDir, "db.sqlite"),
+    adminKey: opts.adminKey,
+    databaseUrl: opts.databaseUrl
+  });
+  let dash;
+  if (dashboard) {
+    const bun = globalThis.Bun;
+    if (!bun) throw new Error("Bun runtime not available to read the embedded dashboard");
+    const indexPath = dashboard["/"];
+    if (!indexPath) throw new Error('embedded dashboard map is missing its "/" (index.html) entry');
+    const html = await bun.file(indexPath).text();
+    dash = { html, assets: dashboard };
+  }
+  const server = await new ProcessRuntimeHost().serve(boot.runtime, {
+    port: opts.port,
+    ip: opts.ip,
+    admin: { api: boot.adminApi, key: opts.adminKey },
+    routes: boot.project.routes,
+    storageRoutes: boot.storageRoutes,
+    componentRoutes: boot.componentRoutes,
+    dashboard: dash
+  });
+  return { server, store: boot.store, runtime: boot.runtime };
+}
+async function runBinaryServer(loaded, components, dashboard) {
+  const opts = resolveBinaryOptions(process.argv.slice(2), process.env);
+  if (!opts.adminKey) {
+    process.stderr.write("\u2717 HELIPOD_ADMIN_KEY is required \u2014 set it to a strong secret.\n");
+    process.exit(1);
+  }
+  const { server, store } = await startBinaryServer(loaded, components, opts, dashboard);
+  process.stdout.write(JSON.stringify({ ready: true, port: opts.port, url: `http://${opts.ip}:${opts.port}` }) + "\n");
+  let closing = false;
+  const shutdown = async () => {
+    if (closing) return;
+    closing = true;
+    await server.close();
+    await store.close();
+    process.exit(0);
+  };
+  process.on("SIGTERM", () => void shutdown());
+  process.on("SIGINT", () => void shutdown());
+}
+export {
+  DEFAULT_FUNCTIONS_DIR,
+  DEFAULT_INDEX,
+  ProcessRuntimeHost,
+  bootProject,
+  codegenCommand,
+  createWatchLoop,
+  detectRuntime,
+  devCommand,
+  functionsDirNotFoundMessage,
+  handleHttpRequest,
+  loadConfig,
+  loadFunctionsDir,
+  loadProject,
+  push,
+  resolveBinaryOptions,
+  resolveDevOptions,
+  resolveFunctionsDir,
+  runBinaryServer,
+  runCli,
+  startBinaryServer,
+  startDevServer,
+  withStorageModules,
+  writeGenerated
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/binary-main.ts"],"sourcesContent":["/**\n * `@helipod/cli` — the `helipod` dev tooling: project loading, the push pipeline (load →\n * codegen → register), the HTTP dev server, hot-reload watch loop, and the command dispatch.\n */\nexport type { LoadedProject, ProjectArtifacts } from \"./project\";\nexport { loadProject, DEFAULT_INDEX } from \"./project\";\n\nexport type { PushResult } from \"./push-pipeline\";\nexport { push } from \"./push-pipeline\";\n\nexport type { DevOptions, ResolvedDevOptions, RuntimeKind } from \"./dev-options\";\nexport { resolveDevOptions, detectRuntime } from \"./dev-options\";\n\nexport type { HttpRequest, HttpResponse, ServerInfo } from \"./http-handler\";\nexport { handleHttpRequest } from \"./http-handler\";\n\nexport type { DevServer, DevServerOptions } from \"./server\";\nexport { startDevServer, ProcessRuntimeHost } from \"./server\";\n\nexport type { WatchLoop, WatchLoopOptions, WatchTriggerReason } from \"./watch\";\nexport { createWatchLoop } from \"./watch\";\n\nexport { loadFunctionsDir } from \"./load-modules\";\nexport type { HelipodConfig } from \"@helipod/component\";\nexport { loadConfig } from \"./load-config\";\nexport type { ResolvedFunctionsDir } from \"./functions-dir\";\nexport { resolveFunctionsDir, functionsDirNotFoundMessage, DEFAULT_FUNCTIONS_DIR } from \"./functions-dir\";\nexport { runCli, devCommand, codegenCommand } from \"./cli\";\n\n// The shared boot core + codegen writer, re-exported so an out-of-CLI host (e.g. `@helipod/vite`'s\n// in-process embed mode) can boot the engine and write `_generated` through the package boundary\n// rather than reaching into deep source paths. All already-existing internals — purely additive.\nexport { bootProject, withStorageModules } from \"./boot\";\nexport type { BootResult, BootProjectOptions, BootLoadedOptions } from \"./boot\";\nexport { writeGenerated } from \"@helipod/codegen\";\n\nexport { runBinaryServer, startBinaryServer, resolveBinaryOptions } from \"./binary-main\";\n","/**\n * The runtime entry a `helipod build` binary calls. It is compiled `serve`: boot an already-loaded\n * project (static imports, not a dir scan), start the shared server, print a machine-readable ready\n * line, and shut down gracefully. `startBinaryServer` is the testable core (no signals/exit).\n */\nimport { join } from \"node:path\";\nimport type { ComponentDefinition } from \"@helipod/component\";\nimport type { EmbeddedRuntime } from \"@helipod/runtime-embedded\";\nimport type { DocStore } from \"@helipod/docstore\";\nimport type { LoadedProject } from \"./project\";\nimport { bootLoaded } from \"./boot\";\nimport { ProcessRuntimeHost, type DevServer } from \"./server\";\n\nexport interface BinaryOptions {\n  port: number;\n  ip: string;\n  dataDir: string;\n  adminKey: string;\n  /** Postgres connection string (flag wins over `HELIPOD_DATABASE_URL`); unset → SQLite. */\n  databaseUrl?: string;\n}\n\n/** The materialized embedded dashboard: key-injected HTML plus the urlPath→embedded-path asset map. */\nexport interface EmbeddedDashboard { html: string; assets: Record<string, string> }\n\n/** Minimal structural surface of `Bun.file(path)`, reached only inside a compiled binary. */\ninterface BunFileLike {\n  text(): Promise<string>;\n}\ninterface BunFileRuntime {\n  file(path: string): BunFileLike;\n}\n\nexport function resolveBinaryOptions(argv: string[], env: Record<string, string | undefined>): BinaryOptions {\n  let port = env.PORT ? Number(env.PORT) : 3000;\n  let ip = \"0.0.0.0\";\n  let dataDir = \"./data\";\n  let databaseUrl = env.HELIPOD_DATABASE_URL;\n  const adminKey = (env.HELIPOD_ADMIN_KEY ?? \"\").trim();\n  for (let i = 0; i < argv.length; i++) {\n    const a = argv[i];\n    if (a === \"--port\" && argv[i + 1] !== undefined) port = Number(argv[++i]);\n    else if (a === \"--hostname\" && argv[i + 1] !== undefined) ip = argv[++i] as string;\n    else if (a === \"--data-dir\" && argv[i + 1] !== undefined) dataDir = argv[++i] as string;\n    else if (a === \"--database-url\" && argv[i + 1] !== undefined) databaseUrl = argv[++i] as string;\n  }\n  return { port, ip, dataDir, adminKey, databaseUrl };\n}\n\nexport async function startBinaryServer(\n  loaded: LoadedProject,\n  components: ComponentDefinition[],\n  opts: BinaryOptions,\n  dashboard?: Record<string, string>,\n): Promise<{ server: DevServer; store: DocStore; runtime: EmbeddedRuntime }> {\n  const boot = await bootLoaded({\n    loaded,\n    components,\n    dataPath: join(opts.dataDir, \"db.sqlite\"),\n    adminKey: opts.adminKey,\n    databaseUrl: opts.databaseUrl,\n  });\n  let dash: EmbeddedDashboard | undefined;\n  if (dashboard) {\n    const bun = (globalThis as { Bun?: BunFileRuntime }).Bun;\n    if (!bun) throw new Error(\"Bun runtime not available to read the embedded dashboard\");\n    const indexPath = dashboard[\"/\"];\n    if (!indexPath) throw new Error(\"embedded dashboard map is missing its \\\"/\\\" (index.html) entry\");\n    const html = await bun.file(indexPath).text();\n    dash = { html, assets: dashboard };\n  }\n  const server = await new ProcessRuntimeHost().serve(boot.runtime, {\n    port: opts.port,\n    ip: opts.ip,\n    admin: { api: boot.adminApi, key: opts.adminKey },\n    routes: boot.project.routes,\n    storageRoutes: boot.storageRoutes,\n    componentRoutes: boot.componentRoutes,\n    dashboard: dash,\n  });\n  return { server, store: boot.store, runtime: boot.runtime };\n}\n\nexport async function runBinaryServer(\n  loaded: LoadedProject,\n  components: ComponentDefinition[],\n  dashboard?: Record<string, string>,\n): Promise<void> {\n  const opts = resolveBinaryOptions(process.argv.slice(2), process.env);\n  if (!opts.adminKey) {\n    process.stderr.write(\"✗ HELIPOD_ADMIN_KEY is required — set it to a strong secret.\\n\");\n    process.exit(1);\n  }\n  const { server, store } = await startBinaryServer(loaded, components, opts, dashboard);\n  process.stdout.write(JSON.stringify({ ready: true, port: opts.port, url: `http://${opts.ip}:${opts.port}` }) + \"\\n\");\n  let closing = false;\n  const shutdown = async (): Promise<void> => {\n    if (closing) return;\n    closing = true;\n    await server.close();\n    await store.close();\n    process.exit(0);\n  };\n  process.on(\"SIGTERM\", () => void shutdown());\n  process.on(\"SIGINT\", () => void shutdown());\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,SAAS,sBAAsB;;;AC7B/B,SAAS,YAAY;AA4Bd,SAAS,qBAAqB,MAAgB,KAAwD;AAC3G,MAAI,OAAO,IAAI,OAAO,OAAO,IAAI,IAAI,IAAI;AACzC,MAAI,KAAK;AACT,MAAI,UAAU;AACd,MAAI,cAAc,IAAI;AACtB,QAAM,YAAY,IAAI,qBAAqB,IAAI,KAAK;AACpD,WAAS,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;AACpC,UAAM,IAAI,KAAK,CAAC;AAChB,QAAI,MAAM,YAAY,KAAK,IAAI,CAAC,MAAM,OAAW,QAAO,OAAO,KAAK,EAAE,CAAC,CAAC;AAAA,aAC/D,MAAM,gBAAgB,KAAK,IAAI,CAAC,MAAM,OAAW,MAAK,KAAK,EAAE,CAAC;AAAA,aAC9D,MAAM,gBAAgB,KAAK,IAAI,CAAC,MAAM,OAAW,WAAU,KAAK,EAAE,CAAC;AAAA,aACnE,MAAM,oBAAoB,KAAK,IAAI,CAAC,MAAM,OAAW,eAAc,KAAK,EAAE,CAAC;AAAA,EACtF;AACA,SAAO,EAAE,MAAM,IAAI,SAAS,UAAU,YAAY;AACpD;AAEA,eAAsB,kBACpB,QACA,YACA,MACA,WAC2E;AAC3E,QAAM,OAAO,MAAM,WAAW;AAAA,IAC5B;AAAA,IACA;AAAA,IACA,UAAU,KAAK,KAAK,SAAS,WAAW;AAAA,IACxC,UAAU,KAAK;AAAA,IACf,aAAa,KAAK;AAAA,EACpB,CAAC;AACD,MAAI;AACJ,MAAI,WAAW;AACb,UAAM,MAAO,WAAwC;AACrD,QAAI,CAAC,IAAK,OAAM,IAAI,MAAM,0DAA0D;AACpF,UAAM,YAAY,UAAU,GAAG;AAC/B,QAAI,CAAC,UAAW,OAAM,IAAI,MAAM,8DAAgE;AAChG,UAAM,OAAO,MAAM,IAAI,KAAK,SAAS,EAAE,KAAK;AAC5C,WAAO,EAAE,MAAM,QAAQ,UAAU;AAAA,EACnC;AACA,QAAM,SAAS,MAAM,IAAI,mBAAmB,EAAE,MAAM,KAAK,SAAS;AAAA,IAChE,MAAM,KAAK;AAAA,IACX,IAAI,KAAK;AAAA,IACT,OAAO,EAAE,KAAK,KAAK,UAAU,KAAK,KAAK,SAAS;AAAA,IAChD,QAAQ,KAAK,QAAQ;AAAA,IACrB,eAAe,KAAK;AAAA,IACpB,iBAAiB,KAAK;AAAA,IACtB,WAAW;AAAA,EACb,CAAC;AACD,SAAO,EAAE,QAAQ,OAAO,KAAK,OAAO,SAAS,KAAK,QAAQ;AAC5D;AAEA,eAAsB,gBACpB,QACA,YACA,WACe;AACf,QAAM,OAAO,qBAAqB,QAAQ,KAAK,MAAM,CAAC,GAAG,QAAQ,GAAG;AACpE,MAAI,CAAC,KAAK,UAAU;AAClB,YAAQ,OAAO,MAAM,0EAAgE;AACrF,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,QAAM,EAAE,QAAQ,MAAM,IAAI,MAAM,kBAAkB,QAAQ,YAAY,MAAM,SAAS;AACrF,UAAQ,OAAO,MAAM,KAAK,UAAU,EAAE,OAAO,MAAM,MAAM,KAAK,MAAM,KAAK,UAAU,KAAK,EAAE,IAAI,KAAK,IAAI,GAAG,CAAC,IAAI,IAAI;AACnH,MAAI,UAAU;AACd,QAAM,WAAW,YAA2B;AAC1C,QAAI,QAAS;AACb,cAAU;AACV,UAAM,OAAO,MAAM;AACnB,UAAM,MAAM,MAAM;AAClB,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,UAAQ,GAAG,WAAW,MAAM,KAAK,SAAS,CAAC;AAC3C,UAAQ,GAAG,UAAU,MAAM,KAAK,SAAS,CAAC;AAC5C;","names":[]}

package/dist/project.d.ts

@@ -0,0 +1,53 @@
+import { SimpleIndexCatalog, RegisteredFunction, ContextProvider } from '@helipod/executor';
+import { SchemaDefinition, SchemaDefinitionJSON } from '@helipod/values';
+import { AnalyzedFunctionManifest } from '@helipod/codegen';
+import { BootContext, Driver, ResolvedComponentRoute, ComponentDefinition } from '@helipod/component';
+
+/**
+ * Turn a loaded project (a live schema + function modules) into the artifacts the engine and
+ * codegen need: the schema JSON, an index catalog (with table numbers assigned + an implicit
+ * `by_creation` index per table), the `path:name → function` map, and the analyzed manifest.
+ */
+
+declare const DEFAULT_INDEX = "by_creation";
+interface LoadedProject {
+    schema: SchemaDefinition;
+    /** module path (without extension) → its exports (name → value). */
+    modules: Record<string, Record<string, unknown>>;
+}
+interface ProjectArtifacts {
+    schemaJson: SchemaDefinitionJSON;
+    catalog: SimpleIndexCatalog;
+    moduleMap: Record<string, RegisteredFunction>;
+    manifest: AnalyzedFunctionManifest;
+    tableNumbers: Record<string, number>;
+    componentNames: ReadonlySet<string>;
+    contextProviders: ContextProvider[];
+    /** Component boot steps (e.g. the scheduler's cron reconciler) — must run once at engine create. */
+    bootSteps: {
+        name: string;
+        run: (ctx: BootContext) => Promise<void>;
+    }[];
+    /**
+     * Component drivers (e.g. the scheduler's event loop) — must be started at engine create for a
+     * composed component's background work to actually run. Omitting this from
+     * `createEmbeddedRuntime(...)` silently leaves drivers never started (jobs enqueue but never
+     * dispatch) — see `../test/scheduler-e2e.test.ts` for the proof this wiring matters.
+     */
+    drivers: Driver[];
+    /** The app's `http.ts` router, resolved to `path:name` function paths for dispatch. */
+    routes: ResolvedRoute[];
+    /** Reserved engine routes contributed by composed components (e.g. auth's `/api/auth/oauth/*`). */
+    componentRoutes: ResolvedComponentRoute[];
+}
+/** A single `http.ts` route, with its handler resolved from a `RegisteredFunction` value to the
+ * `path:name` string that `runtime.runHttpAction` looks up in `composed.moduleMap`. */
+interface ResolvedRoute {
+    method: string;
+    path?: string;
+    pathPrefix?: string;
+    handlerPath: string;
+}
+declare function loadProject(loaded: LoadedProject, components?: ComponentDefinition[], existingTableNumbers?: Record<string, number>): ProjectArtifacts;
+
+export { DEFAULT_INDEX, type LoadedProject, type ProjectArtifacts, type ResolvedRoute, loadProject };

package/dist/project.js

@@ -0,0 +1,9 @@
+import {
+  DEFAULT_INDEX,
+  loadProject
+} from "./chunk-EPHSHGFU.js";
+export {
+  DEFAULT_INDEX,
+  loadProject
+};
+//# sourceMappingURL=project.js.map

package/dist/project.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@helipod/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "FSL-1.1-Apache-2.0",
+  "bin": {
+    "helipod": "./dist/bin.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./http-handler": {
+      "types": "./dist/http-handler.d.ts",
+      "default": "./dist/http-handler.js"
+    },
+    "./project": {
+      "types": "./dist/project.d.ts",
+      "default": "./dist/project.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --exclude 'test/*-e2e.test.ts'",
+    "test:e2e": "vitest run test/*-e2e.test.ts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  },
+  "dependencies": {
+    "@helipod/admin": "0.1.0",
+    "@helipod/blobstore": "0.1.0",
+    "@helipod/blobstore-fs": "0.1.0",
+    "@helipod/blobstore-s3": "0.1.0",
+    "@helipod/codegen": "0.1.0",
+    "@helipod/component": "0.1.0",
+    "@helipod/deploy": "0.1.0",
+    "@helipod/docstore": "0.1.0",
+    "@helipod/docstore-postgres": "0.1.0",
+    "@helipod/docstore-sqlite": "0.1.0",
+    "@helipod/errors": "0.1.0",
+    "@helipod/executor": "0.1.0",
+    "@helipod/id-codec": "0.1.0",
+    "@helipod/objectstore": "0.1.0",
+    "@helipod/objectstore-fs": "0.1.0",
+    "@helipod/objectstore-s3": "0.1.0",
+    "@helipod/query-engine": "0.1.0",
+    "@helipod/receipts": "0.1.0",
+    "@helipod/runtime-embedded": "0.1.0",
+    "@helipod/storage": "0.1.0",
+    "@helipod/sync": "0.1.0",
+    "@helipod/values": "0.1.0",
+    "esbuild": "^0.27.0",
+    "ws": "^8.18.0",
+    "@helipod/dashboard": "0.1.0"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.2.17",
+    "@levischuck/tiny-cbor": "0.2.11",
+    "@simplewebauthn/server": "13.3.2",
+    "@helipod/auth": "0.1.0",
+    "@helipod/client": "0.1.0",
+    "@helipod/fleet": "0.0.0",
+    "@helipod/notifications": "0.1.0",
+    "@helipod/objectstore-substrate": "0.0.0",
+    "@helipod/scheduler": "0.1.0",
+    "@helipod/triggers": "0.1.0",
+    "@helipod/workflow": "0.1.0",
+    "@types/node": "^22.10.5",
+    "@types/ws": "^8.5.13",
+    "fake-indexeddb": "^6.0.0",
+    "jose": "6.2.3",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/helipod-sh/helipod.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/helipod-sh/helipod"
+}