@hyperfixation/cli 0.1.0

package/dist/dev.js

@@ -0,0 +1,63 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { resolveApp } from "./app.js";
+import { run } from "./spawn.js";
+/** Postgres and mailpit, and nothing else; the app itself runs on the host under `hf dev`. */
+export 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 function devBuildSha(now = Date.now()) {
+    return `dev-${String(now)}`;
+}
+/**
+ * `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 async function dev(options = {}) {
+    const app = await resolveApp(options.dir);
+    const buildSha = options.buildSha ?? devBuildSha();
+    if (options.skipCompose !== true)
+        await ensureCompose(app);
+    if (options.composeOnly === true)
+        return { app, buildSha };
+    await run("pnpm", ["dev"], {
+        cwd: app.dir,
+        env: { ...app.env, HF_PROCESS: "web", HF_BUILD_SHA: buildSha },
+    });
+    return { app, buildSha };
+}
+/**
+ * `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 async function ensureCompose(app) {
+    if (!(await isFile(path.join(app.dir, DEV_COMPOSE_FILE))))
+        return false;
+    await run("docker", ["compose", "-f", DEV_COMPOSE_FILE, "up", "-d", "--wait"], {
+        cwd: app.dir,
+    });
+    return true;
+}
+async function isFile(target) {
+    try {
+        return (await stat(target)).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/env-file.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Just enough dotenv for the template's own `.env`: `NAME=value`, `#` comments, and optional
+ * surrounding quotes. No interpolation and no `export` — the template writes neither, and a
+ * parser that guesses at shell semantics would disagree with compose, which reads the same file
+ * with rules of its own.
+ */
+export declare function parseEnvFile(contents: string): Record<string, string>;
+export declare function readEnvFile(file: string): Promise<Record<string, string>>;
+/** The names `.env.example` declares, in file order — the app's own env contract. */
+export declare function declaredNames(contents: string): string[];

package/dist/env-file.js

@@ -0,0 +1,44 @@
+import { readFile } from "node:fs/promises";
+/**
+ * Just enough dotenv for the template's own `.env`: `NAME=value`, `#` comments, and optional
+ * surrounding quotes. No interpolation and no `export` — the template writes neither, and a
+ * parser that guesses at shell semantics would disagree with compose, which reads the same file
+ * with rules of its own.
+ */
+export function parseEnvFile(contents) {
+    const env = {};
+    for (const line of contents.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const name = trimmed.slice(0, eq).trim();
+        const raw = trimmed.slice(eq + 1).trim();
+        env[name] = unquote(raw);
+    }
+    return env;
+}
+export async function readEnvFile(file) {
+    try {
+        return parseEnvFile(await readFile(file, "utf8"));
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return {};
+        throw cause;
+    }
+}
+/** The names `.env.example` declares, in file order — the app's own env contract. */
+export function declaredNames(contents) {
+    return Object.keys(parseEnvFile(contents));
+}
+function unquote(value) {
+    if (value.length >= 2 && (value.startsWith('"') || value.startsWith("'"))) {
+        const quote = value[0];
+        if (value.endsWith(quote))
+            return value.slice(1, -1);
+    }
+    return value;
+}

package/dist/gen.d.ts

@@ -0,0 +1,29 @@
+import { type ResolvedApp } from "./app.js";
+/** Track B's generators: `flow` and `record`, each of which also writes the registration. */
+export declare const GENERATOR_CONFIG: string;
+/** `@turbo/gen` declares its bin as `gen`; that is the name pnpm links into the app. */
+export declare const GENERATOR_BIN = "gen";
+export declare class NoGenerators extends Error {
+    constructor(dir: string);
+}
+export interface GenerateOptions {
+    dir?: string;
+    /** Generator name and any `--flag value` pairs, passed through to `turbo gen`. */
+    args?: readonly string[];
+}
+/**
+ * `hf gen` — the app's own Turborepo generators, run through the app's `turbo`.
+ *
+ * It adds nothing to the generators but the ability to run them from anywhere inside the app,
+ * and deliberately holds no templates of its own: a generator's whole value is that it writes
+ * the *registration* as well as the file, and only the app's `src/hyperfixation.ts` can be
+ * appended to. A copy of the templates in this package would be a second one to keep in step
+ * with the registry shape.
+ *
+ * `@turbo/gen`'s own bin, not `turbo gen`. `turbo gen` re-fetches `@turbo/gen` through
+ * `pnpm dlx` even when the app already depends on it, and that second copy is installed outside
+ * the app's `pnpm-workspace.yaml` — so it is refused by pnpm 12 for `esbuild`'s build script,
+ * which the app's own `allowBuilds` had already permitted. The installed bin is the same
+ * generator with none of that.
+ */
+export declare function generate(options?: GenerateOptions): Promise<ResolvedApp>;

package/dist/gen.js

@@ -0,0 +1,44 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { resolveApp } from "./app.js";
+import { run } from "./spawn.js";
+/** Track B's generators: `flow` and `record`, each of which also writes the registration. */
+export const GENERATOR_CONFIG = path.join("turbo", "generators", "config.ts");
+/** `@turbo/gen` declares its bin as `gen`; that is the name pnpm links into the app. */
+export const GENERATOR_BIN = "gen";
+export class NoGenerators extends Error {
+    constructor(dir) {
+        super(`${dir} has no ${GENERATOR_CONFIG}; hf gen has nothing to run`);
+        this.name = "NoGenerators";
+    }
+}
+/**
+ * `hf gen` — the app's own Turborepo generators, run through the app's `turbo`.
+ *
+ * It adds nothing to the generators but the ability to run them from anywhere inside the app,
+ * and deliberately holds no templates of its own: a generator's whole value is that it writes
+ * the *registration* as well as the file, and only the app's `src/hyperfixation.ts` can be
+ * appended to. A copy of the templates in this package would be a second one to keep in step
+ * with the registry shape.
+ *
+ * `@turbo/gen`'s own bin, not `turbo gen`. `turbo gen` re-fetches `@turbo/gen` through
+ * `pnpm dlx` even when the app already depends on it, and that second copy is installed outside
+ * the app's `pnpm-workspace.yaml` — so it is refused by pnpm 12 for `esbuild`'s build script,
+ * which the app's own `allowBuilds` had already permitted. The installed bin is the same
+ * generator with none of that.
+ */
+export async function generate(options = {}) {
+    const app = await resolveApp(options.dir);
+    if (!(await isFile(path.join(app.dir, GENERATOR_CONFIG))))
+        throw new NoGenerators(app.dir);
+    await run("pnpm", ["exec", GENERATOR_BIN, "run", ...(options.args ?? [])], { cwd: app.dir });
+    return app;
+}
+async function isFile(target) {
+    try {
+        return (await stat(target)).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { main, COMMANDS, USAGE, type Command, type Io } from "./cli.js";
+export { newApp, placeholders, substitute, TemplateError, TEMPLATE_MARKER, EXCLUDED_ENTRIES, type NewAppOptions, type NewAppResult, } from "./new.js";
+export { findTemplateSource, requireTemplateSource, TEMPLATE_DIR_ENV, } from "./template-source.js";
+export { deriveNames, APP_ID, GIVEN_NAME, InvalidAppName, type AppNames } from "./names.js";
+export { resolveApp, NotAnApp, type ResolvedApp } from "./app.js";
+export { declaredNames, parseEnvFile, readEnvFile } from "./env-file.js";
+export { MissingEnv, requireEnv } from "./require-env.js";
+export { credentialsOf, provisionLocalRoles, type LocalRoleOptions, type LocalRoleResult, } from "./roles.js";
+export { migrateApp, MIGRATE_ENTRY, type MigrateAppOptions, type MigrateAppResult, } from "./migrate.js";
+export { bootstrapApp, type BootstrapAppOptions, type BootstrapAppResult } from "./bootstrap.js";
+export { statusTokenApp, StatusTokenAlreadySet, type StatusTokenAppOptions, type StatusTokenAppResult, type StatusTokenKind, } from "./status-token.js";
+export { checkApp, type CheckAppResult, type CheckFinding } from "./check.js";
+export { probeApp, type AppRegistry } from "./probe.js";
+export { generate, GENERATOR_BIN, GENERATOR_CONFIG, NoGenerators, type GenerateOptions, } from "./gen.js";
+export { dev, devBuildSha, DEV_COMPOSE_FILE, type DevOptions, type DevResult } from "./dev.js";
+export { run, CommandFailed, type RunOptions } from "./spawn.js";

package/dist/index.js

@@ -0,0 +1,16 @@
+export { main, COMMANDS, USAGE } from "./cli.js";
+export { newApp, placeholders, substitute, TemplateError, TEMPLATE_MARKER, EXCLUDED_ENTRIES, } from "./new.js";
+export { findTemplateSource, requireTemplateSource, TEMPLATE_DIR_ENV, } from "./template-source.js";
+export { deriveNames, APP_ID, GIVEN_NAME, InvalidAppName } from "./names.js";
+export { resolveApp, NotAnApp } from "./app.js";
+export { declaredNames, parseEnvFile, readEnvFile } from "./env-file.js";
+export { MissingEnv, requireEnv } from "./require-env.js";
+export { credentialsOf, provisionLocalRoles, } from "./roles.js";
+export { migrateApp, MIGRATE_ENTRY, } from "./migrate.js";
+export { bootstrapApp } from "./bootstrap.js";
+export { statusTokenApp, StatusTokenAlreadySet, } from "./status-token.js";
+export { checkApp } from "./check.js";
+export { probeApp } from "./probe.js";
+export { generate, GENERATOR_BIN, GENERATOR_CONFIG, NoGenerators, } from "./gen.js";
+export { dev, devBuildSha, DEV_COMPOSE_FILE } from "./dev.js";
+export { run, CommandFailed } from "./spawn.js";

package/dist/migrate.d.ts

@@ -0,0 +1,25 @@
+import { type ResolvedApp } from "./app.js";
+import { type LocalRoleResult } from "./roles.js";
+/** The entrypoint track B's template ships; the same file the deployed `migrate` service runs. */
+export declare const MIGRATE_ENTRY = "migrate.ts";
+export interface MigrateAppOptions {
+    dir?: string;
+    /** Skips role provisioning — the cloud path, where `hf new` created the roles. */
+    skipRoles?: boolean;
+}
+export interface MigrateAppResult {
+    app: ResolvedApp;
+    roles: LocalRoleResult | undefined;
+}
+/**
+ * `hf migrate` — the application role, then the app's own migrator entrypoint.
+ *
+ * The second half is a child process running `migrate.ts` rather than a direct call to
+ * `migrate()` from `@hyperfixation/db/migrator`, for one reason: the record tables and the app
+ * migrations directory come from the app's registry, and `migrate.ts` is what reads them. It is
+ * also the file the deployed one-shot `migrate` service runs, so `hf migrate` on a laptop and a
+ * deploy cannot drift apart — which they would the moment the CLI grew its own argument list.
+ *
+ * The first half is the CLI's own, and only local: a container never creates a role.
+ */
+export declare function migrateApp(options?: MigrateAppOptions): Promise<MigrateAppResult>;

package/dist/migrate.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { resolveApp } from "./app.js";
+import { requireEnv } from "./require-env.js";
+import { credentialsOf, provisionLocalRoles } from "./roles.js";
+import { run } from "./spawn.js";
+/** The entrypoint track B's template ships; the same file the deployed `migrate` service runs. */
+export const MIGRATE_ENTRY = "migrate.ts";
+/**
+ * `hf migrate` — the application role, then the app's own migrator entrypoint.
+ *
+ * The second half is a child process running `migrate.ts` rather than a direct call to
+ * `migrate()` from `@hyperfixation/db/migrator`, for one reason: the record tables and the app
+ * migrations directory come from the app's registry, and `migrate.ts` is what reads them. It is
+ * also the file the deployed one-shot `migrate` service runs, so `hf migrate` on a laptop and a
+ * deploy cannot drift apart — which they would the moment the CLI grew its own argument list.
+ *
+ * The first half is the CLI's own, and only local: a container never creates a role.
+ */
+export async function migrateApp(options = {}) {
+    const app = await resolveApp(options.dir);
+    const databaseUrl = requireEnv(app, "DATABASE_URL");
+    const migratorUrl = requireEnv(app, "MIGRATOR_DATABASE_URL");
+    let roles;
+    if (options.skipRoles !== true) {
+        const credentials = credentialsOf(databaseUrl);
+        roles = await provisionLocalRoles(migratorUrl, {
+            databaseName: app.names.databaseName,
+            applicationRole: credentials.user,
+            applicationPassword: credentials.password,
+        });
+    }
+    await run(process.execPath, ["--import", "tsx", path.join(app.dir, MIGRATE_ENTRY)], {
+        cwd: app.dir,
+        env: { ...app.env, HF_PROCESS: "migrate" },
+    });
+    return { app, roles };
+}

package/dist/names.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What a user may type. Hyphens are allowed here and nowhere downstream: `demo-app` is a
+ * directory and an npm package name, and the plan's own exit bar spells the example with one.
+ */
+export declare const GIVEN_NAME: RegExp;
+/**
+ * The plan's rule, applied to every derived identifier — the database, both roles, and the
+ * name `defineApp` carries into the advisory lock and DBOS. `@hyperfixation/db`'s own
+ * `assertAppName` is this same pattern, so an app name that fails here fails `migrate()` later
+ * anyway; refusing at `hf new` is the only point at which the directory does not yet exist.
+ */
+export declare const APP_ID: RegExp;
+export declare class InvalidAppName extends Error {
+    constructor(message: string);
+}
+export interface AppNames {
+    /** Exactly what was typed; the directory `hf new` creates. */
+    given: string;
+    /** `__APP_NAME__`: the given name with `-` replaced by `_`. */
+    appName: string;
+    /** `__DB_NAME__`. */
+    databaseName: string;
+    /** `hf_<appName>` — the same string as the database name, as `roleNames()` derives it. */
+    applicationRole: string;
+    migratorRole: string;
+}
+/**
+ * The substitution `hf new` performs, and the only place the two placeholders are defined.
+ *
+ * `__APP_NAME__` is the *underscored* form rather than what was typed, because it is what
+ * `src/hyperfixation.ts` hands `defineApp` and what the template's `.env.example` builds the
+ * application role out of — both of which reach `roleNames()`, which refuses a hyphen. The
+ * directory keeps the typed name; nothing inside the app does.
+ */
+export declare function deriveNames(given: string): AppNames;

package/dist/names.js

@@ -0,0 +1,44 @@
+/**
+ * What a user may type. Hyphens are allowed here and nowhere downstream: `demo-app` is a
+ * directory and an npm package name, and the plan's own exit bar spells the example with one.
+ */
+export const GIVEN_NAME = /^[a-z][a-z0-9_-]{0,62}$/;
+/**
+ * The plan's rule, applied to every derived identifier — the database, both roles, and the
+ * name `defineApp` carries into the advisory lock and DBOS. `@hyperfixation/db`'s own
+ * `assertAppName` is this same pattern, so an app name that fails here fails `migrate()` later
+ * anyway; refusing at `hf new` is the only point at which the directory does not yet exist.
+ */
+export const APP_ID = /^[a-z][a-z0-9_]{0,62}$/;
+export class InvalidAppName extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidAppName";
+    }
+}
+/**
+ * The substitution `hf new` performs, and the only place the two placeholders are defined.
+ *
+ * `__APP_NAME__` is the *underscored* form rather than what was typed, because it is what
+ * `src/hyperfixation.ts` hands `defineApp` and what the template's `.env.example` builds the
+ * application role out of — both of which reach `roleNames()`, which refuses a hyphen. The
+ * directory keeps the typed name; nothing inside the app does.
+ */
+export function deriveNames(given) {
+    if (!GIVEN_NAME.test(given)) {
+        throw new InvalidAppName(`app name must match ${GIVEN_NAME.source}, got ${JSON.stringify(given)}`);
+    }
+    const appName = given.replaceAll("-", "_");
+    const databaseName = `hf_${appName}`;
+    if (!APP_ID.test(databaseName)) {
+        throw new InvalidAppName(`database name must match ${APP_ID.source}, but ${JSON.stringify(given)} derives ` +
+            `${JSON.stringify(databaseName)} — an app name may be at most 60 characters`);
+    }
+    return {
+        given,
+        appName,
+        databaseName,
+        applicationRole: databaseName,
+        migratorRole: `${databaseName}_migrator`,
+    };
+}

package/dist/new.d.ts

@@ -0,0 +1,57 @@
+import { type AppNames } from "./names.js";
+/**
+ * The file that marks a directory as a copy source. `hf new`'s first act on the source is to
+ * assert it exists; its last act on the copy is to delete it, so an app is never a template
+ * twice.
+ */
+export declare const TEMPLATE_MARKER = ".hyperfixation-template";
+/**
+ * Not copied. Build output and `node_modules` belong to the source checkout, `.git` would make
+ * the new app a clone of the template's history rather than a repository of its own, and `.env`
+ * is the one file in the tree that may hold a secret.
+ */
+export declare const EXCLUDED_ENTRIES: readonly string[];
+export declare class TemplateError extends Error {
+    constructor(message: string);
+}
+export interface NewAppOptions {
+    /** The name as typed; becomes the directory and, underscored, both placeholders. */
+    name: string;
+    /** The template checkout to copy. */
+    from: string;
+    /** Where the app directory is created. Defaults to the current working directory. */
+    into?: string;
+    /**
+     * Phase 1 is local only. Passing `false` is refused rather than ignored, because the cloud
+     * `hf new` provisions GitHub, Postgres, Coolify and Cloudflare and a half-provisioned app is
+     * worse than none.
+     */
+    local: boolean;
+    /** The bootstrap admin's address, written to `.env` as `HF_BOOTSTRAP_EMAIL`. Skips the prompt. */
+    email?: string;
+    /** Overrides the real interactive prompt; for tests and other callers with their own stdin. */
+    promptEmail?: () => Promise<string>;
+}
+export interface NewAppResult extends AppNames {
+    /** Absolute path of the created app. */
+    dir: string;
+    /** Files whose contents a placeholder substitution changed. */
+    substituted: readonly string[];
+    /** True when `.env` was written from `.env.example`. */
+    wroteEnv: boolean;
+    /** True when `HF_BOOTSTRAP_EMAIL` was written to `.env`, from `--email` or the prompt. */
+    wroteBootstrapEmail: boolean;
+}
+/**
+ * Copies the template checkout and substitutes the two placeholders across it.
+ *
+ * This is giget's semantics against a local directory rather than giget itself: Phase 1's
+ * source is the sibling `hyperfixation-template` checkout, which giget's providers do not
+ * address at all (it resolves `gh:`/`gitlab:`/tarball URLs), and `--local` is the only mode
+ * that exists until Phase 3. The remote fetch is that phase's to add, beside the provisioning
+ * steps that are the rest of a cloud `hf new`.
+ */
+export declare function newApp(options: NewAppOptions): Promise<NewAppResult>;
+/** The placeholder map. Exported because `hf check` reports a leftover placeholder by name. */
+export declare function placeholders(names: AppNames): Record<string, string>;
+export declare function substitute(contents: string, names: AppNames): string;

package/dist/new.js

@@ -0,0 +1,151 @@
+import { readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { cp } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { deriveNames } from "./names.js";
+/**
+ * The file that marks a directory as a copy source. `hf new`'s first act on the source is to
+ * assert it exists; its last act on the copy is to delete it, so an app is never a template
+ * twice.
+ */
+export const TEMPLATE_MARKER = ".hyperfixation-template";
+/**
+ * Not copied. Build output and `node_modules` belong to the source checkout, `.git` would make
+ * the new app a clone of the template's history rather than a repository of its own, and `.env`
+ * is the one file in the tree that may hold a secret.
+ */
+export const EXCLUDED_ENTRIES = [
+    ".git",
+    "node_modules",
+    ".next",
+    ".turbo",
+    "dist",
+    "out",
+    ".env",
+    "tsconfig.tsbuildinfo",
+    "next-env.d.ts",
+];
+/** Extensions copied byte for byte; everything else is read as UTF-8 and substituted. */
+const BINARY_EXTENSIONS = new Set([
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".ico",
+    ".webp",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".otf",
+    ".pdf",
+    ".zip",
+]);
+export class TemplateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TemplateError";
+    }
+}
+/**
+ * Copies the template checkout and substitutes the two placeholders across it.
+ *
+ * This is giget's semantics against a local directory rather than giget itself: Phase 1's
+ * source is the sibling `hyperfixation-template` checkout, which giget's providers do not
+ * address at all (it resolves `gh:`/`gitlab:`/tarball URLs), and `--local` is the only mode
+ * that exists until Phase 3. The remote fetch is that phase's to add, beside the provisioning
+ * steps that are the rest of a cloud `hf new`.
+ */
+export async function newApp(options) {
+    if (!options.local) {
+        throw new TemplateError("hf new needs --local: provisioning GitHub, Postgres, Coolify and Cloudflare is Phase 3");
+    }
+    const names = deriveNames(options.name);
+    const source = path.resolve(options.from);
+    await assertTemplateSource(source);
+    const dir = path.resolve(options.into ?? process.cwd(), names.given);
+    if (await exists(dir)) {
+        throw new TemplateError(`${dir} already exists; hf new will not write into it`);
+    }
+    await cp(source, dir, {
+        recursive: true,
+        filter: (src) => !EXCLUDED_ENTRIES.includes(path.basename(src)),
+    });
+    const substituted = await substituteTree(dir, names);
+    await rm(path.join(dir, TEMPLATE_MARKER));
+    const example = path.join(dir, ".env.example");
+    const wroteEnv = await exists(example);
+    let wroteBootstrapEmail = false;
+    if (wroteEnv) {
+        let contents = await readFile(example, "utf8");
+        const email = options.email ?? (await (options.promptEmail ?? promptForBootstrapEmail)());
+        if (email !== "") {
+            contents = `${contents.trimEnd()}\nHF_BOOTSTRAP_EMAIL=${email}\n`;
+            wroteBootstrapEmail = true;
+        }
+        await writeFile(path.join(dir, ".env"), contents);
+    }
+    return { ...names, dir, substituted, wroteEnv, wroteBootstrapEmail };
+}
+/** The one-time prompt: the address `hf up` later hands `hf bootstrap` via `.env`. */
+async function promptForBootstrapEmail() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question("bootstrap admin email (blank to skip): ")).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+/** The placeholder map. Exported because `hf check` reports a leftover placeholder by name. */
+export function placeholders(names) {
+    return { __APP_NAME__: names.appName, __DB_NAME__: names.databaseName };
+}
+export function substitute(contents, names) {
+    let out = contents;
+    for (const [token, value] of Object.entries(placeholders(names))) {
+        out = out.replaceAll(token, value);
+    }
+    return out;
+}
+async function assertTemplateSource(source) {
+    if (!(await exists(source))) {
+        throw new TemplateError(`template source ${source} does not exist`);
+    }
+    if (!(await exists(path.join(source, TEMPLATE_MARKER)))) {
+        throw new TemplateError(`${source} has no ${TEMPLATE_MARKER}: it is not a hyperfixation template checkout`);
+    }
+}
+async function substituteTree(dir, names) {
+    const changed = [];
+    for (const file of await walk(dir)) {
+        if (BINARY_EXTENSIONS.has(path.extname(file)))
+            continue;
+        const before = await readFile(file, "utf8");
+        const after = substitute(before, names);
+        if (after === before)
+            continue;
+        await writeFile(file, after);
+        changed.push(path.relative(dir, file));
+    }
+    return changed.sort();
+}
+async function walk(dir) {
+    const out = [];
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...(await walk(full)));
+        else if (entry.isFile())
+            out.push(full);
+    }
+    return out;
+}
+async function exists(target) {
+    try {
+        await stat(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/probe.d.ts

@@ -0,0 +1,19 @@
+import type { RecordTable } from "@hyperfixation/db";
+import type { ResolvedApp } from "./app.js";
+export interface AppRegistry {
+    appName: string;
+    recordTables: readonly RecordTable[];
+}
+/**
+ * Reads the app's registry by importing it in the app's own process.
+ *
+ * E001–E003 are checks *about the registered record tables*, so without this `hf check` would
+ * run them over an empty list and report green on an app whose tables are wrong. There is no
+ * way to learn the list statically: `src/hyperfixation.ts` is TypeScript that resolves
+ * `@hyperfixation/*` through the app's own `node_modules`, which is why the probe is a child
+ * under the app's `tsx` and not an import here.
+ *
+ * A failure is `undefined`, not a throw — an app whose dependencies are not installed yet is a
+ * finding `hf check` reports, not a reason for it to stop.
+ */
+export declare function probeApp(app: ResolvedApp): Promise<AppRegistry | undefined>;

package/dist/probe.js

@@ -0,0 +1,41 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/** Prefixes the one line of the probe's stdout that is ours; the app may log at import. */
+const PROBE_MARKER = "hf-probe:";
+const PROBE_SOURCE = `const m = await import("./src/hyperfixation.ts");\n` +
+    `console.log(${JSON.stringify(PROBE_MARKER)} + JSON.stringify(` +
+    `{ appName: m.app.name, recordTables: m.recordTables ?? [] }));\n`;
+/**
+ * Reads the app's registry by importing it in the app's own process.
+ *
+ * E001–E003 are checks *about the registered record tables*, so without this `hf check` would
+ * run them over an empty list and report green on an app whose tables are wrong. There is no
+ * way to learn the list statically: `src/hyperfixation.ts` is TypeScript that resolves
+ * `@hyperfixation/*` through the app's own `node_modules`, which is why the probe is a child
+ * under the app's `tsx` and not an import here.
+ *
+ * A failure is `undefined`, not a throw — an app whose dependencies are not installed yet is a
+ * finding `hf check` reports, not a reason for it to stop.
+ */
+export async function probeApp(app) {
+    try {
+        const { stdout } = await execFileAsync(process.execPath, ["--import", "tsx", "--input-type=module", "--eval", PROBE_SOURCE], {
+            cwd: app.dir,
+            encoding: "utf8",
+            env: {
+                ...app.env,
+                HF_PROCESS: "migrate",
+                // `defineApp()` reads it; the probe never launches DBOS, so any accepted value does.
+                HF_BUILD_SHA: app.env.HF_BUILD_SHA ?? "dev-probe",
+            },
+        });
+        const line = stdout.split("\n").find((it) => it.startsWith(PROBE_MARKER));
+        if (line === undefined)
+            return undefined;
+        return JSON.parse(line.slice(PROBE_MARKER.length));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/require-env.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedApp } from "./app.js";
+export declare class MissingEnv extends Error {
+    readonly names: readonly string[];
+    constructor(names: readonly string[], dir: string);
+}
+/** Reads one var out of `.env`-under-`process.env`, or names the file the user has to edit. */
+export declare function requireEnv(app: ResolvedApp, name: string): string;