@hyperfixation/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Graham Lutz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/app.d.ts

@@ -0,0 +1,26 @@
+import { type AppNames } from "./names.js";
+export declare class NotAnApp extends Error {
+    constructor(message: string);
+}
+export interface ResolvedApp {
+    dir: string;
+    /** `package.json`'s `name`, which is what `hf new` substituted for `__APP_NAME__`. */
+    appName: string;
+    names: AppNames;
+    /** The app's own migrations, which `hf migrate` and E005 both read. */
+    migrationsDir: string;
+    /** `.env` under `process.env`, the precedence every dotenv loader uses. */
+    env: Record<string, string | undefined>;
+    /** `.env` alone, so `hf check` can say a name is missing from the file and not from a shell. */
+    envFile: Record<string, string>;
+    /** The names `.env.example` declares; the app's env contract, kept equal to `REQUIRED_ENV`. */
+    declared: readonly string[];
+}
+/**
+ * Finds the app around `dir` and reads everything the other commands need from it.
+ *
+ * The app name comes from `package.json` rather than from a file `hf new` leaves behind: the
+ * template's `package.json` carries `__APP_NAME__`, so after substitution it already *is* the
+ * record, and a second copy of the name is a second thing that can disagree.
+ */
+export declare function resolveApp(dir?: string): Promise<ResolvedApp>;

package/dist/app.js

@@ -0,0 +1,57 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { deriveNames } from "./names.js";
+import { readEnvFile } from "./env-file.js";
+/** What makes a directory an app rather than any package: the registry `defineApp` lives in. */
+const APP_ENTRY = path.join("src", "hyperfixation.ts");
+export class NotAnApp extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NotAnApp";
+    }
+}
+/**
+ * Finds the app around `dir` and reads everything the other commands need from it.
+ *
+ * The app name comes from `package.json` rather than from a file `hf new` leaves behind: the
+ * template's `package.json` carries `__APP_NAME__`, so after substitution it already *is* the
+ * record, and a second copy of the name is a second thing that can disagree.
+ */
+export async function resolveApp(dir = process.cwd()) {
+    const root = await findAppRoot(path.resolve(dir));
+    const manifest = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+    if (typeof manifest.name !== "string") {
+        throw new NotAnApp(`${root}/package.json has no name`);
+    }
+    const envFile = await readEnvFile(path.join(root, ".env"));
+    const example = await readEnvFile(path.join(root, ".env.example"));
+    return {
+        dir: root,
+        appName: manifest.name,
+        names: deriveNames(manifest.name),
+        migrationsDir: path.join(root, "drizzle"),
+        env: { ...envFile, ...process.env },
+        envFile,
+        declared: Object.keys(example),
+    };
+}
+async function findAppRoot(from) {
+    let dir = from;
+    for (;;) {
+        if (await isFile(path.join(dir, APP_ENTRY)))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            throw new NotAnApp(`no hyperfixation app at or above ${from}: ${APP_ENTRY} is what marks one`);
+        }
+        dir = parent;
+    }
+}
+async function isFile(target) {
+    try {
+        return (await stat(target)).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "./cli.js";
+process.exitCode = await main(process.argv.slice(2));

package/dist/bootstrap.d.ts

@@ -0,0 +1,32 @@
+import { type BootstrapResult } from "@hyperfixation/auth";
+import { type ResolvedApp } from "./app.js";
+export interface BootstrapAppOptions {
+    dir?: string;
+    /** Overrides `HF_BOOTSTRAP_EMAIL`; one of the two has to be set. */
+    email?: string;
+    name?: string;
+    /**
+     * Overrides `HF_BOOTSTRAP_BUDGET_USD`; one of the two has to be set. Not part of
+     * `REQUIRED_ENV` — like `HF_BOOTSTRAP_EMAIL`, it is a one-shot bootstrap input, not something
+     * the deployed `web`/`worker`/`migrate` containers carry, so a flag is `.env.example`'s only
+     * alternative for a local run.
+     */
+    budgetUsd?: string;
+}
+export interface BootstrapAppResult extends BootstrapResult {
+    app: ResolvedApp;
+}
+/**
+ * `hf bootstrap` — the app's first admin, granted from the box and never from a request.
+ *
+ * It connects as the **application** role, not the migrator: the row it writes is an ordinary
+ * `hf_user` row and the audit line an ordinary `hf_audit` row, and running the one grant that
+ * has no admin behind it with owner privileges would be the only reason this command ever
+ * needed them. `bootstrapAdmin` does the refusing; this only decides which address to offer it.
+ *
+ * It also seeds the `hf_app_state` singleton (`ON CONFLICT (id) DO NOTHING`), independently of
+ * the admin grant: `AppStateMissing` documents this command as the only thing that seeds it, and
+ * a redeploy that reruns `hf bootstrap` against an already-admin'd app must still be able to
+ * seed it if it hasn't been yet — `budget_usd` has no default, so nothing else ever will.
+ */
+export declare function bootstrapApp(options?: BootstrapAppOptions): Promise<BootstrapAppResult>;

package/dist/bootstrap.js

@@ -0,0 +1,47 @@
+import { bootstrapAdmin, BOOTSTRAP_EMAIL_ENV } from "@hyperfixation/auth";
+import { Pool } from "pg";
+import { resolveApp } from "./app.js";
+import { MissingEnv, requireEnv } from "./require-env.js";
+const BOOTSTRAP_BUDGET_ENV = "HF_BOOTSTRAP_BUDGET_USD";
+/**
+ * `hf bootstrap` — the app's first admin, granted from the box and never from a request.
+ *
+ * It connects as the **application** role, not the migrator: the row it writes is an ordinary
+ * `hf_user` row and the audit line an ordinary `hf_audit` row, and running the one grant that
+ * has no admin behind it with owner privileges would be the only reason this command ever
+ * needed them. `bootstrapAdmin` does the refusing; this only decides which address to offer it.
+ *
+ * It also seeds the `hf_app_state` singleton (`ON CONFLICT (id) DO NOTHING`), independently of
+ * the admin grant: `AppStateMissing` documents this command as the only thing that seeds it, and
+ * a redeploy that reruns `hf bootstrap` against an already-admin'd app must still be able to
+ * seed it if it hasn't been yet — `budget_usd` has no default, so nothing else ever will.
+ */
+export async function bootstrapApp(options = {}) {
+    const app = await resolveApp(options.dir);
+    const databaseUrl = requireEnv(app, "DATABASE_URL");
+    const budgetUsd = options.budgetUsd ?? requireEnv(app, BOOTSTRAP_BUDGET_ENV);
+    if (!Number.isFinite(Number(budgetUsd)) || Number(budgetUsd) <= 0) {
+        throw new Error(`${BOOTSTRAP_BUDGET_ENV} must be a positive number, got ${budgetUsd}`);
+    }
+    const designated = app.env[BOOTSTRAP_EMAIL_ENV];
+    const email = options.email ?? designated;
+    if (email === undefined || email === "") {
+        throw new MissingEnv([BOOTSTRAP_EMAIL_ENV], app.dir);
+    }
+    const pool = new Pool({ connectionString: databaseUrl, max: 1 });
+    try {
+        await pool.query("INSERT INTO hf_app_state (id, budget_usd) VALUES (1, $1) ON CONFLICT (id) DO NOTHING", [budgetUsd]);
+        const result = await bootstrapAdmin(pool, {
+            email,
+            name: options.name,
+            // Explicitly, and from the app's `.env` rather than this process's environment: a
+            // designation the deploy made is the app's, and `--email` on its own must not become one
+            // — that would turn the first-user branch's refusal into a promotion of whoever was typed.
+            designatedEmail: designated === undefined || designated === "" ? null : designated,
+        });
+        return { ...result, app };
+    }
+    finally {
+        await pool.end();
+    }
+}

package/dist/check.d.ts

@@ -0,0 +1,26 @@
+import { type RecordTable } from "@hyperfixation/db";
+import { type ResolvedApp } from "./app.js";
+export interface CheckFinding {
+    /** `env`, `migrations`, `registry`, or a boot-check code. */
+    code: string;
+    message: string;
+}
+export interface CheckAppResult {
+    app: ResolvedApp;
+    findings: readonly CheckFinding[];
+    /** Undefined when the registry could not be read; E001–E003 then checked nothing. */
+    recordTables: readonly RecordTable[] | undefined;
+    ok: boolean;
+}
+/**
+ * `hf check` — the three things that are wrong about a deploy before any request reaches it:
+ * an env var the app declares and the environment does not carry, a migration in the tree that
+ * is not in the database, and E001–E006 against the role the app actually connects as.
+ *
+ * It reports every finding rather than throwing on the first. A missing var and a pending
+ * migration are usually the same mistake — an incomplete deploy — and fixing them one error
+ * message at a time is three round trips through a build.
+ */
+export declare function checkApp(options?: {
+    dir?: string;
+}): Promise<CheckAppResult>;

package/dist/check.js

@@ -0,0 +1,113 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { BootCheckFailure, runBootChecks, } from "@hyperfixation/db";
+import { CORE_MIGRATIONS_DIR, CORE_MIGRATIONS_TABLE } from "@hyperfixation/db/migrator";
+import { Client } from "pg";
+import { resolveApp } from "./app.js";
+import { probeApp } from "./probe.js";
+/** Where drizzle records the app's own migrations; core's are in `CORE_MIGRATIONS_TABLE`. */
+const APP_MIGRATIONS_TABLE = "__drizzle_migrations";
+/**
+ * `hf check` — the three things that are wrong about a deploy before any request reaches it:
+ * an env var the app declares and the environment does not carry, a migration in the tree that
+ * is not in the database, and E001–E006 against the role the app actually connects as.
+ *
+ * It reports every finding rather than throwing on the first. A missing var and a pending
+ * migration are usually the same mistake — an incomplete deploy — and fixing them one error
+ * message at a time is three round trips through a build.
+ */
+export async function checkApp(options = {}) {
+    const app = await resolveApp(options.dir);
+    const findings = [];
+    findings.push(...missingEnv(app));
+    const databaseUrl = app.env.DATABASE_URL;
+    const migratorUrl = app.env.MIGRATOR_DATABASE_URL;
+    const registry = await probeApp(app);
+    if (registry === undefined) {
+        findings.push({
+            code: "registry",
+            message: `could not read ${app.appName}'s registry from src/hyperfixation.ts; ` +
+                "E001-E003 checked no record tables",
+        });
+    }
+    if (migratorUrl !== undefined && migratorUrl !== "") {
+        findings.push(...(await pendingMigrations(app, migratorUrl)));
+    }
+    if (databaseUrl !== undefined && databaseUrl !== "") {
+        try {
+            await runBootChecks({
+                databaseUrl,
+                recordTables: registry?.recordTables ?? [],
+                appMigrationsDir: app.migrationsDir,
+            });
+        }
+        catch (error) {
+            findings.push(error instanceof BootCheckFailure
+                ? { code: error.code, message: error.message }
+                : { code: "boot", message: error.message });
+        }
+    }
+    return { app, findings, recordTables: registry?.recordTables, ok: findings.length === 0 };
+}
+/**
+ * The app's env contract is `.env.example`, not a list this package keeps: track B's
+ * `compose-envs.test.ts` already pins that file, both compose blocks and `REQUIRED_ENV` to each
+ * other, so reading it here means an app that adds a var of its own is checked for it too.
+ *
+ * Absent, not empty. `.env.example` ships `SENTRY_DSN`, the three Langfuse vars and both
+ * provider keys empty on purpose — `instrumentation.ts` and `startWorker()` register neither
+ * when unset — so an empty value is a declared local state and only a name that is not there
+ * at all is a gap.
+ */
+function missingEnv(app) {
+    const missing = app.declared.filter((name) => !(name in app.env));
+    return missing.length === 0
+        ? []
+        : [{ code: "env", message: `unset: ${missing.join(", ")}` }];
+}
+async function pendingMigrations(app, migratorUrl) {
+    const client = new Client({ connectionString: migratorUrl });
+    await client.connect();
+    try {
+        const findings = [];
+        const sets = [
+            { what: "core", dir: CORE_MIGRATIONS_DIR, table: CORE_MIGRATIONS_TABLE },
+            { what: "app", dir: app.migrationsDir, table: APP_MIGRATIONS_TABLE },
+        ];
+        for (const set of sets) {
+            const inTree = await journalLength(set.dir);
+            const applied = await appliedCount(client, set.table);
+            if (inTree > applied) {
+                findings.push({
+                    code: "migrations",
+                    message: `${inTree - applied} ${set.what} migration(s) pending; run hf migrate`,
+                });
+            }
+        }
+        return findings;
+    }
+    finally {
+        await client.end();
+    }
+}
+async function journalLength(dir) {
+    try {
+        const journal = JSON.parse(await readFile(path.join(dir, "meta", "_journal.json"), "utf8"));
+        return journal.entries?.length ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * A missing table is "none applied", which is the state of a database nobody has migrated.
+ * Two round trips rather than one `CASE`: Postgres parses the whole statement before it
+ * evaluates any of it, so a branch naming a relation that does not exist still fails.
+ */
+async function appliedCount(client, table) {
+    const { rows: present } = await client.query("SELECT to_regclass($1)::text AS oid", [`drizzle.${table}`]);
+    if (present[0]?.oid === null)
+        return 0;
+    const { rows } = await client.query(`SELECT count(*)::int AS count FROM drizzle.${table}`);
+    return rows[0]?.count ?? 0;
+}

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+export declare const COMMANDS: readonly ["new", "migrate", "bootstrap", "status-token", "check", "gen", "dev", "up"];
+export type Command = (typeof COMMANDS)[number];
+export declare const USAGE = "hf \u2014 the hyperfixation CLI\n\n  hf new <name> --local     copy the template into ./<name>, substitute its placeholders, and\n                            prompt for the bootstrap admin's email\n      --from <dir>            template checkout (default: the sibling hyperfixation-template)\n      --into <dir>            where to create <name> (default: the working directory)\n      --email <address>       the bootstrap admin's address; skips the prompt\n\n  hf up                     install, infra, migrate, bootstrap, status tokens, then hf dev \u2014\n                            the whole local loop after hf new, safe to rerun; seeds a $10\n                            budget unless HF_BOOTSTRAP_BUDGET_USD is set in .env\n\n  hf migrate                create the application role, then run the app's migrate.ts\n      --skip-roles            the cloud path, where the roles already exist\n\n  hf bootstrap              grant the app its one bootstrap admin, and seed hf_app_state\n      --email <address>       the address to promote; otherwise HF_BOOTSTRAP_EMAIL\n      --budget-usd <amount>    the app's starting budget; otherwise HF_BOOTSTRAP_BUDGET_USD\n\n  hf status-token           provision /api/status's read and write tokens\n      --read                   only the read token; refuses if it is already set\n      --write                  only the write token; refuses if it is already set\n      --rotate                 replace a token that is already set\n                               (no flags: fills in whichever of the two is unset)\n\n  hf check                  declared env, pending migrations, and E001-E006\n\n  hf gen [generator]        the app's turbo generators\n\n  hf dev                    docker compose up, then pnpm dev under HF_BUILD_SHA=dev-<timestamp>\n      --no-compose            leave the dev infrastructure alone\n      --compose-only          bring the infrastructure up and stop\n\nEvery command but `new` runs against the app at or above the working directory, or --dir.\n";
+export interface Io {
+    out(line: string): void;
+    err(line: string): void;
+}
+/**
+ * Parses argv and runs one command, returning the process's exit code.
+ *
+ * Every failure is caught here and printed as one line: these commands fail for reasons the
+ * user can act on — a name that is not an identifier, an unset var, a template checkout that is
+ * not there — and a stack trace in front of that sentence buries it.
+ */
+export declare function main(argv: readonly string[], io?: Io): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,264 @@
+import { parseArgs } from "node:util";
+import { bootstrapApp } from "./bootstrap.js";
+import { checkApp } from "./check.js";
+import { dev, devBuildSha } from "./dev.js";
+import { generate } from "./gen.js";
+import { migrateApp } from "./migrate.js";
+import { newApp } from "./new.js";
+import { statusTokenApp } from "./status-token.js";
+import { requireTemplateSource } from "./template-source.js";
+import { DEV_BUDGET_USD, upApp } from "./up.js";
+export const COMMANDS = [
+    "new",
+    "migrate",
+    "bootstrap",
+    "status-token",
+    "check",
+    "gen",
+    "dev",
+    "up",
+];
+export const USAGE = `hf — the hyperfixation CLI
+
+  hf new <name> --local     copy the template into ./<name>, substitute its placeholders, and
+                            prompt for the bootstrap admin's email
+      --from <dir>            template checkout (default: the sibling hyperfixation-template)
+      --into <dir>            where to create <name> (default: the working directory)
+      --email <address>       the bootstrap admin's address; skips the prompt
+
+  hf up                     install, infra, migrate, bootstrap, status tokens, then hf dev —
+                            the whole local loop after hf new, safe to rerun; seeds a $10
+                            budget unless HF_BOOTSTRAP_BUDGET_USD is set in .env
+
+  hf migrate                create the application role, then run the app's migrate.ts
+      --skip-roles            the cloud path, where the roles already exist
+
+  hf bootstrap              grant the app its one bootstrap admin, and seed hf_app_state
+      --email <address>       the address to promote; otherwise HF_BOOTSTRAP_EMAIL
+      --budget-usd <amount>    the app's starting budget; otherwise HF_BOOTSTRAP_BUDGET_USD
+
+  hf status-token           provision /api/status's read and write tokens
+      --read                   only the read token; refuses if it is already set
+      --write                  only the write token; refuses if it is already set
+      --rotate                 replace a token that is already set
+                               (no flags: fills in whichever of the two is unset)
+
+  hf check                  declared env, pending migrations, and E001-E006
+
+  hf gen [generator]        the app's turbo generators
+
+  hf dev                    docker compose up, then pnpm dev under HF_BUILD_SHA=dev-<timestamp>
+      --no-compose            leave the dev infrastructure alone
+      --compose-only          bring the infrastructure up and stop
+
+Every command but \`new\` runs against the app at or above the working directory, or --dir.
+`;
+const consoleIo = {
+    out: (line) => console.log(line),
+    err: (line) => console.error(line),
+};
+/**
+ * Parses argv and runs one command, returning the process's exit code.
+ *
+ * Every failure is caught here and printed as one line: these commands fail for reasons the
+ * user can act on — a name that is not an identifier, an unset var, a template checkout that is
+ * not there — and a stack trace in front of that sentence buries it.
+ */
+export async function main(argv, io = consoleIo) {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === "--help" || command === "-h") {
+        io.out(USAGE);
+        return command === undefined ? 1 : 0;
+    }
+    if (!COMMANDS.includes(command)) {
+        io.err(`unknown command ${JSON.stringify(command)}`);
+        io.err(USAGE);
+        return 1;
+    }
+    try {
+        return await dispatch(command, rest, io);
+    }
+    catch (error) {
+        io.err(`hf ${command}: ${error.message}`);
+        return 1;
+    }
+}
+async function dispatch(command, argv, io) {
+    switch (command) {
+        case "new":
+            return await commandNew(argv, io);
+        case "migrate":
+            return await commandMigrate(argv, io);
+        case "bootstrap":
+            return await commandBootstrap(argv, io);
+        case "status-token":
+            return await commandStatusToken(argv, io);
+        case "check":
+            return await commandCheck(argv, io);
+        case "gen":
+            return await commandGen(argv);
+        case "dev":
+            return await commandDev(argv, io);
+        case "up":
+            return await commandUp(argv, io);
+    }
+}
+async function commandNew(argv, io) {
+    const { values, positionals } = parseArgs({
+        args: [...argv],
+        options: {
+            local: { type: "boolean", default: false },
+            from: { type: "string" },
+            into: { type: "string" },
+            email: { type: "string" },
+        },
+        allowPositionals: true,
+    });
+    const name = positionals[0];
+    if (name === undefined) {
+        io.err("hf new needs a name: hf new <name> --local");
+        return 1;
+    }
+    const from = values.from ?? (await requireTemplateSource());
+    const result = await newApp({
+        name,
+        from,
+        into: values.into,
+        local: values.local,
+        email: values.email,
+    });
+    io.out(`created ${result.dir} from ${from}`);
+    io.out(`  app ${result.appName}, database ${result.databaseName}`);
+    io.out(`  ${result.substituted.length} file(s) substituted` +
+        (result.wroteEnv ? ", .env written from .env.example" : "") +
+        (result.wroteBootstrapEmail ? ", HF_BOOTSTRAP_EMAIL set" : ""));
+    io.out("");
+    io.out(`next: cd ${result.given} && hf up`);
+    return 0;
+}
+async function commandMigrate(argv, io) {
+    const { values } = parseArgs({
+        args: [...argv],
+        options: { dir: { type: "string" }, "skip-roles": { type: "boolean", default: false } },
+    });
+    const result = await migrateApp({ dir: values.dir, skipRoles: values["skip-roles"] });
+    if (result.roles !== undefined) {
+        io.out(`${result.roles.created ? "created" : "updated"} application role ${result.roles.applicationRole}`);
+    }
+    io.out(`migrated ${result.app.appName}`);
+    return 0;
+}
+async function commandBootstrap(argv, io) {
+    const { values } = parseArgs({
+        args: [...argv],
+        options: {
+            dir: { type: "string" },
+            email: { type: "string" },
+            name: { type: "string" },
+            "budget-usd": { type: "string" },
+        },
+    });
+    const result = await bootstrapApp({
+        dir: values.dir,
+        email: values.email,
+        name: values.name,
+        budgetUsd: values["budget-usd"],
+    });
+    io.out(`${result.created ? "created" : "promoted"} ${result.email} as ${result.app.appName}'s admin`);
+    return 0;
+}
+async function commandStatusToken(argv, io) {
+    const { values } = parseArgs({
+        args: [...argv],
+        options: {
+            dir: { type: "string" },
+            read: { type: "boolean", default: false },
+            write: { type: "boolean", default: false },
+            rotate: { type: "boolean", default: false },
+        },
+    });
+    const explicit = values.read || values.write;
+    const kinds = explicit
+        ? [...(values.read ? ["read"] : []), ...(values.write ? ["write"] : [])]
+        : ["read", "write"];
+    const result = await statusTokenApp({
+        dir: values.dir,
+        kinds,
+        rotate: values.rotate,
+        explicit,
+    });
+    const generated = kinds.filter((kind) => result.tokens[kind] !== undefined);
+    if (generated.length === 0) {
+        io.out(`${result.app.appName}: every requested token is already set; nothing to do`);
+        return 0;
+    }
+    io.out(`${result.app.appName}: status token(s) provisioned — shown once, not stored:`);
+    for (const kind of generated)
+        io.out(`  ${kind}: ${result.tokens[kind]}`);
+    for (const kind of kinds) {
+        if (!generated.includes(kind))
+            io.out(`  ${kind}: already set, left alone`);
+    }
+    return 0;
+}
+async function commandCheck(argv, io) {
+    const { values } = parseArgs({ args: [...argv], options: { dir: { type: "string" } } });
+    const result = await checkApp({ dir: values.dir });
+    if (result.ok) {
+        io.out(`${result.app.appName}: env, migrations and E001-E006 all clear`);
+        return 0;
+    }
+    for (const finding of result.findings)
+        io.err(`${finding.code}: ${finding.message}`);
+    return 1;
+}
+async function commandGen(argv) {
+    // No `parseArgs`: everything after `hf gen` is the generator's, including flags this CLI
+    // happens to share a name with.
+    const dirFlag = argv.indexOf("--dir");
+    const dir = dirFlag === -1 ? undefined : argv[dirFlag + 1];
+    const rest = dirFlag === -1 ? argv : [...argv.slice(0, dirFlag), ...argv.slice(dirFlag + 2)];
+    await generate({ dir, args: rest });
+    return 0;
+}
+async function commandDev(argv, io) {
+    const { values } = parseArgs({
+        args: [...argv],
+        options: {
+            dir: { type: "string" },
+            "no-compose": { type: "boolean", default: false },
+            "compose-only": { type: "boolean", default: false },
+        },
+    });
+    // Printed before the child starts, not after it exits: `pnpm dev` runs until interrupted,
+    // and the version is what the user needs in front of them while it does.
+    const buildSha = devBuildSha();
+    io.out(`HF_BUILD_SHA=${buildSha}`);
+    await dev({
+        dir: values.dir,
+        skipCompose: values["no-compose"],
+        composeOnly: values["compose-only"],
+        buildSha,
+    });
+    return 0;
+}
+async function commandUp(argv, io) {
+    const { values } = parseArgs({ args: [...argv], options: { dir: { type: "string" } } });
+    const result = await upApp({ dir: values.dir });
+    io.out(result.installedDependencies ? "installed dependencies" : "dependencies already installed");
+    io.out(result.composeStarted ? "brought up the dev infrastructure" : "no docker-compose.yml to bring up");
+    io.out(`migrated ${result.app.appName}`);
+    io.out(result.bootstrapped ? "bootstrapped the admin" : "admin already bootstrapped; left alone");
+    if (result.budgetDefaulted) {
+        io.out(`HF_BOOTSTRAP_BUDGET_USD unset: seeded the monthly LLM budget at $${DEV_BUDGET_USD} (dev default)`);
+    }
+    io.out(result.tokensProvisioned.length > 0
+        ? `provisioned status token(s): ${result.tokensProvisioned.join(", ")}`
+        : "status tokens already provisioned");
+    // Printed before the child starts, not after it exits: `pnpm dev` runs until interrupted,
+    // and the version is what the user needs in front of them while it does.
+    const buildSha = devBuildSha();
+    io.out(`HF_BUILD_SHA=${buildSha}`);
+    await dev({ dir: result.app.dir, skipCompose: true, buildSha });
+    return 0;
+}

package/dist/dev.d.ts

@@ -0,0 +1,43 @@
+import { type ResolvedApp } from "./app.js";
+/** Postgres and mailpit, and nothing else; the app itself runs on the host under `hf dev`. */
+export declare const DEV_COMPOSE_FILE = "docker-compose.yml";
+/**
+ * The version a local process runs under.
+ *
+ * `startWorker()` refuses an `HF_BUILD_SHA` shorter than seven characters and DBOS treats it as
+ * the `applicationVersion`, which is the thing a redeploy changes. A timestamp is what makes a
+ * restart of `hf dev` look like a redeploy — the run model's bump path is then exercised by an
+ * ordinary edit-and-restart loop rather than only by the redeploy suite — and the `dev-` prefix
+ * is what guarantees it can never collide with a deployed commit sha.
+ */
+export declare function devBuildSha(now?: number): string;
+export interface DevOptions {
+    dir?: string;
+    /** Skips `docker compose up`; for a database that is already running elsewhere. */
+    skipCompose?: boolean;
+    /** Runs `docker compose up` and `hf migrate`'s prerequisites, then stops. */
+    composeOnly?: boolean;
+    buildSha?: string;
+}
+export interface DevResult {
+    app: ResolvedApp;
+    buildSha: string;
+}
+/**
+ * `hf dev` — the dev infrastructure, then the app's own `dev` script under a version the worker
+ * will accept.
+ *
+ * It runs `pnpm dev` rather than reimplementing it: `next dev` is the app's to configure, and
+ * the one thing the app's script cannot do for itself is invent a build sha, because a value
+ * committed to `.env` would be the same "version" across every restart and a redeploy that
+ * changed nothing is not a redeploy.
+ */
+export declare function dev(options?: DevOptions): Promise<DevResult>;
+/**
+ * `docker compose up`, if the app has a compose file — shared with `hf up`, which brings the
+ * same infrastructure up ahead of `hf migrate` rather than duplicating this check.
+ *
+ * Returns whether compose was actually started, so a caller can report it distinctly from "there
+ * was nothing to bring up."
+ */
+export declare function ensureCompose(app: ResolvedApp): Promise<boolean>;