@hyperfixation/cli 0.1.0

package/dist/require-env.js

@@ -0,0 +1,15 @@
+export class MissingEnv extends Error {
+    names;
+    constructor(names, dir) {
+        super(`${names.join(", ")} unset: set ${names.length === 1 ? "it" : "them"} in ${dir}/.env`);
+        this.name = "MissingEnv";
+        this.names = names;
+    }
+}
+/** Reads one var out of `.env`-under-`process.env`, or names the file the user has to edit. */
+export function requireEnv(app, name) {
+    const value = app.env[name];
+    if (value === undefined || value === "")
+        throw new MissingEnv([name], app.dir);
+    return value;
+}

package/dist/roles.d.ts

@@ -0,0 +1,34 @@
+export interface LocalRoleOptions {
+    databaseName: string;
+    applicationRole: string;
+    applicationPassword: string;
+}
+export interface LocalRoleResult {
+    applicationRole: string;
+    created: boolean;
+}
+/**
+ * Creates the application role for a **local** app, on the migrator's own connection.
+ *
+ * `@hyperfixation/db`'s `provisionRoles` is the cloud path and is not usable here: it derives
+ * both role names from the app name and records the application role's default privileges
+ * `FOR ROLE hf_<app>_migrator`. Locally the migrator is the compose superuser `postgres` — that
+ * is what track B's `.env.example` puts in `MIGRATOR_DATABASE_URL` — so privileges recorded for
+ * a role that creates nothing would leave the application role unable to read the tables the
+ * migrator just made. The grant here is recorded for whoever is connected, which is the role
+ * that will own every `hf_*` object on this machine.
+ *
+ * The connection therefore has to be able to create a role, which the compose superuser can and
+ * a deployed migrator role cannot — `hf migrate --skip-roles` is the cloud path, where `hf new`
+ * created both roles before the first deploy.
+ *
+ * Idempotent: an existing role is re-`ALTER`ed to the password `.env` declares, and the grants
+ * on already-existing objects are re-issued, so running it after the first `hf migrate` is a
+ * no-op rather than a permissions gap.
+ */
+export declare function provisionLocalRoles(migratorConnectionString: string, options: LocalRoleOptions): Promise<LocalRoleResult>;
+/** The role and password a `DATABASE_URL` carries — what the application role has to become. */
+export declare function credentialsOf(connectionString: string): {
+    user: string;
+    password: string;
+};

package/dist/roles.js

@@ -0,0 +1,51 @@
+import { quoteIdent } from "@hyperfixation/db";
+import { Client } from "pg";
+/**
+ * Creates the application role for a **local** app, on the migrator's own connection.
+ *
+ * `@hyperfixation/db`'s `provisionRoles` is the cloud path and is not usable here: it derives
+ * both role names from the app name and records the application role's default privileges
+ * `FOR ROLE hf_<app>_migrator`. Locally the migrator is the compose superuser `postgres` — that
+ * is what track B's `.env.example` puts in `MIGRATOR_DATABASE_URL` — so privileges recorded for
+ * a role that creates nothing would leave the application role unable to read the tables the
+ * migrator just made. The grant here is recorded for whoever is connected, which is the role
+ * that will own every `hf_*` object on this machine.
+ *
+ * The connection therefore has to be able to create a role, which the compose superuser can and
+ * a deployed migrator role cannot — `hf migrate --skip-roles` is the cloud path, where `hf new`
+ * created both roles before the first deploy.
+ *
+ * Idempotent: an existing role is re-`ALTER`ed to the password `.env` declares, and the grants
+ * on already-existing objects are re-issued, so running it after the first `hf migrate` is a
+ * no-op rather than a permissions gap.
+ */
+export async function provisionLocalRoles(migratorConnectionString, options) {
+    const role = quoteIdent(options.applicationRole);
+    const client = new Client({ connectionString: migratorConnectionString });
+    await client.connect();
+    try {
+        const { rows } = await client.query("SELECT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = $1) AS exists", [options.applicationRole]);
+        const created = rows[0]?.exists !== true;
+        await client.query(`${created ? "CREATE" : "ALTER"} ROLE ${role} LOGIN PASSWORD ` +
+            `${quoteLiteral(options.applicationPassword)} CONNECTION LIMIT 25`);
+        await client.query(`GRANT CONNECT ON DATABASE ${quoteIdent(options.databaseName)} TO ${role}`);
+        await client.query(`GRANT USAGE ON SCHEMA public TO ${role}`);
+        await client.query(`ALTER DEFAULT PRIVILEGES IN SCHEMA public ` +
+            `GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ${role}`);
+        await client.query(`ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO ${role}`);
+        await client.query(`GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO ${role}`);
+        await client.query(`GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO ${role}`);
+        return { applicationRole: options.applicationRole, created };
+    }
+    finally {
+        await client.end();
+    }
+}
+/** The role and password a `DATABASE_URL` carries — what the application role has to become. */
+export function credentialsOf(connectionString) {
+    const url = new URL(connectionString);
+    return { user: decodeURIComponent(url.username), password: decodeURIComponent(url.password) };
+}
+function quoteLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}

package/dist/spawn.d.ts

@@ -0,0 +1,20 @@
+import { type StdioOptions } from "node:child_process";
+export declare class CommandFailed extends Error {
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    constructor(command: string, exitCode: number | null, signal: NodeJS.Signals | null);
+}
+export interface RunOptions {
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    stdio?: StdioOptions;
+}
+/**
+ * Runs a child to completion and throws on a non-zero exit.
+ *
+ * `stdio: "inherit"` by default: every command this spawns — the migrator, `turbo gen`, `next
+ * dev` — is one whose output the user is meant to read, and buffering it would turn a prompt
+ * into a hang. `SIGINT` is deliberately not forwarded; the child shares the terminal's process
+ * group and gets it from the terminal at the same moment the CLI does.
+ */
+export declare function run(command: string, args: readonly string[], options: RunOptions): Promise<void>;

package/dist/spawn.js

@@ -0,0 +1,34 @@
+import { spawn } from "node:child_process";
+export class CommandFailed extends Error {
+    exitCode;
+    signal;
+    constructor(command, exitCode, signal) {
+        super(`${command} exited ${signal === null ? `with code ${String(exitCode)}` : `on ${signal}`}`);
+        this.name = "CommandFailed";
+        this.exitCode = exitCode;
+        this.signal = signal;
+    }
+}
+/**
+ * Runs a child to completion and throws on a non-zero exit.
+ *
+ * `stdio: "inherit"` by default: every command this spawns — the migrator, `turbo gen`, `next
+ * dev` — is one whose output the user is meant to read, and buffering it would turn a prompt
+ * into a hang. `SIGINT` is deliberately not forwarded; the child shares the terminal's process
+ * group and gets it from the terminal at the same moment the CLI does.
+ */
+export async function run(command, args, options) {
+    const child = spawn(command, [...args], {
+        cwd: options.cwd,
+        env: options.env ?? process.env,
+        stdio: options.stdio ?? "inherit",
+    });
+    const [code, signal] = await new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("exit", (exitCode, exitSignal) => resolve([exitCode, exitSignal]));
+    });
+    // A child killed by the terminal's own SIGINT is the user stopping `hf dev`, not a failure.
+    if (code === 0 || signal === "SIGINT" || signal === "SIGTERM")
+        return;
+    throw new CommandFailed([command, ...args].join(" "), code, signal);
+}

package/dist/status-token.d.ts

@@ -0,0 +1,42 @@
+import { type ResolvedApp } from "./app.js";
+export type StatusTokenKind = "read" | "write";
+/** One column already carries a hash and `--rotate` was not passed to authorize replacing it. */
+export declare class StatusTokenAlreadySet extends Error {
+    readonly kind: StatusTokenKind;
+    constructor(kind: StatusTokenKind);
+}
+export interface StatusTokenAppOptions {
+    dir?: string;
+    /** Which token(s) to (re)generate. Both when omitted. */
+    kinds?: readonly StatusTokenKind[];
+    /** Overwrites a hash that is already set; otherwise a set column is refused. */
+    rotate?: boolean;
+    /**
+     * True when `kinds` was narrowed by an explicit `--read`/`--write`, rather than defaulted to
+     * both. An explicit ask for a kind that is already set is refused the same as before, since
+     * the operator named it on purpose; the *default* two-kind run instead skips whichever kind
+     * is already set and only fills the gap — otherwise "run it to provision the token nobody set
+     * up yet" would also require `--rotate`, and `--rotate` would take out the other, live token.
+     */
+    explicit?: boolean;
+}
+export interface StatusTokenAppResult {
+    app: ResolvedApp;
+    /** The plaintext of each token generated this run — the only time it is ever available. */
+    tokens: Partial<Record<StatusTokenKind, string>>;
+}
+/**
+ * `hf status-token` — provisions `hf_app_state.read_token_hash`/`write_token_hash`, the two
+ * secrets `/api/status` is authorized against (`statusTokenMatches` in `@hyperfixation/core`
+ * refuses every request when a hash is unset, so an app cannot serve status until this has run
+ * at least once).
+ *
+ * Connects as the **application** role, like `hf bootstrap`: this only ever updates the
+ * singleton row an app already owns, never anything a migrator-level grant is needed for.
+ *
+ * Read and write tokens are independent secrets — the write token is strictly the more
+ * privileged of the two (`createStatusHandler` accepts it on `GET` as well), so rotating one
+ * does not have to rotate the other. Each plaintext token is printed exactly once, by the
+ * caller; nothing here ever stores or logs it.
+ */
+export declare function statusTokenApp(options?: StatusTokenAppOptions): Promise<StatusTokenAppResult>;

package/dist/status-token.js

@@ -0,0 +1,90 @@
+import { randomBytes } from "node:crypto";
+import { hashStatusToken } from "@hyperfixation/core";
+import { AppStateMissing } from "@hyperfixation/db";
+import { Pool } from "pg";
+import { resolveApp } from "./app.js";
+import { requireEnv } from "./require-env.js";
+const COLUMN = {
+    read: "read_token_hash",
+    write: "write_token_hash",
+};
+const SELECT_HASHES_STATEMENT = "SELECT read_token_hash, write_token_hash FROM hf_app_state WHERE id = 1 FOR UPDATE";
+const AUDIT_STATEMENT = "INSERT INTO hf_audit (actor_id, action, target_type, target_id, meta) " +
+    "VALUES (NULL, 'app.status_token_provisioned', 'hf_app_state', '1', $1::jsonb)";
+/** One column already carries a hash and `--rotate` was not passed to authorize replacing it. */
+export class StatusTokenAlreadySet extends Error {
+    kind;
+    constructor(kind) {
+        super(`the ${kind} token is already set; pass --rotate to replace it`);
+        this.name = "StatusTokenAlreadySet";
+        this.kind = kind;
+    }
+}
+/**
+ * `hf status-token` — provisions `hf_app_state.read_token_hash`/`write_token_hash`, the two
+ * secrets `/api/status` is authorized against (`statusTokenMatches` in `@hyperfixation/core`
+ * refuses every request when a hash is unset, so an app cannot serve status until this has run
+ * at least once).
+ *
+ * Connects as the **application** role, like `hf bootstrap`: this only ever updates the
+ * singleton row an app already owns, never anything a migrator-level grant is needed for.
+ *
+ * Read and write tokens are independent secrets — the write token is strictly the more
+ * privileged of the two (`createStatusHandler` accepts it on `GET` as well), so rotating one
+ * does not have to rotate the other. Each plaintext token is printed exactly once, by the
+ * caller; nothing here ever stores or logs it.
+ */
+export async function statusTokenApp(options = {}) {
+    const app = await resolveApp(options.dir);
+    const databaseUrl = requireEnv(app, "DATABASE_URL");
+    const kinds = options.kinds ?? ["read", "write"];
+    const pool = new Pool({ connectionString: databaseUrl, max: 1 });
+    try {
+        const client = await pool.connect();
+        try {
+            await client.query("BEGIN");
+            const tokens = await rotateTokens(client, kinds, options.rotate ?? false, options.explicit ?? false);
+            await client.query("COMMIT");
+            return { app, tokens };
+        }
+        catch (error) {
+            await client.query("ROLLBACK");
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+    }
+    finally {
+        await pool.end();
+    }
+}
+async function rotateTokens(client, kinds, allowRotate, explicit) {
+    const { rows } = await client.query(SELECT_HASHES_STATEMENT);
+    const existing = rows[0];
+    if (existing === undefined)
+        throw new AppStateMissing("hf status-token");
+    const toGenerate = [];
+    for (const kind of kinds) {
+        const alreadySet = existing[COLUMN[kind]] !== null;
+        if (!alreadySet || allowRotate) {
+            toGenerate.push(kind);
+        }
+        else if (explicit) {
+            throw new StatusTokenAlreadySet(kind);
+        }
+        // Default two-kind run, already set, no --rotate: silently left alone.
+    }
+    const tokens = {};
+    for (const kind of toGenerate) {
+        const token = randomBytes(32).toString("base64url");
+        tokens[kind] = token;
+        await client.query(`UPDATE hf_app_state SET ${COLUMN[kind]} = $1 WHERE id = 1`, [
+            hashStatusToken(token),
+        ]);
+    }
+    if (toGenerate.length > 0) {
+        await client.query(AUDIT_STATEMENT, [JSON.stringify({ kinds: toGenerate })]);
+    }
+    return tokens;
+}

package/dist/template-source.d.ts

@@ -0,0 +1,16 @@
+/** Points `hf new` at a template checkout; what a CI job or a second checkout sets. */
+export declare const TEMPLATE_DIR_ENV = "HF_TEMPLATE_DIR";
+/**
+ * Where `hf new --local` looks when `--from` is not given: the environment, then the sibling
+ * checkout beside the working directory, then the sibling beside this package's own repo.
+ *
+ * The last one is what makes `hf new demo-app --local` work when `hf` is run from inside
+ * hyperfixation-core, which is the Phase 1 development layout the plan describes:
+ *
+ *   Code/
+ *     hyperfixation/            (this repo)
+ *     hyperfixation-template/
+ */
+export declare function findTemplateSource(cwd?: string): Promise<string | undefined>;
+/** The same search, but a miss is the error the user has to act on rather than `undefined`. */
+export declare function requireTemplateSource(cwd?: string): Promise<string>;

package/dist/template-source.js

@@ -0,0 +1,46 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { TEMPLATE_MARKER, TemplateError } from "./new.js";
+/** Points `hf new` at a template checkout; what a CI job or a second checkout sets. */
+export const TEMPLATE_DIR_ENV = "HF_TEMPLATE_DIR";
+/**
+ * Where `hf new --local` looks when `--from` is not given: the environment, then the sibling
+ * checkout beside the working directory, then the sibling beside this package's own repo.
+ *
+ * The last one is what makes `hf new demo-app --local` work when `hf` is run from inside
+ * hyperfixation-core, which is the Phase 1 development layout the plan describes:
+ *
+ *   Code/
+ *     hyperfixation/            (this repo)
+ *     hyperfixation-template/
+ */
+export async function findTemplateSource(cwd = process.cwd()) {
+    const fromEnv = process.env[TEMPLATE_DIR_ENV];
+    const candidates = [
+        ...(fromEnv === undefined || fromEnv === "" ? [] : [path.resolve(fromEnv)]),
+        path.resolve(cwd, "..", "hyperfixation-template"),
+        path.resolve(fileURLToPath(new URL("../../..", import.meta.url)), "..", "hyperfixation-template"),
+    ];
+    for (const candidate of candidates) {
+        if (await isTemplate(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** The same search, but a miss is the error the user has to act on rather than `undefined`. */
+export async function requireTemplateSource(cwd) {
+    const found = await findTemplateSource(cwd);
+    if (found === undefined) {
+        throw new TemplateError(`no hyperfixation-template checkout found: pass --from <dir> or set ${TEMPLATE_DIR_ENV}`);
+    }
+    return found;
+}
+async function isTemplate(dir) {
+    try {
+        return (await stat(path.join(dir, TEMPLATE_MARKER))).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/up.d.ts

@@ -0,0 +1,40 @@
+import { type ResolvedApp } from "./app.js";
+import { type StatusTokenKind } from "./status-token.js";
+/**
+ * What `hf up` seeds `hf_app_state.budget_usd` with when `HF_BOOTSTRAP_BUDGET_USD` isn't set.
+ * Local only: `hf bootstrap` itself still refuses to run without an explicit budget, so a
+ * deployed app never starts under a cap nobody chose.
+ */
+export declare const DEV_BUDGET_USD = "10";
+export interface UpOptions {
+    dir?: string;
+}
+export interface UpResult {
+    app: ResolvedApp;
+    installedDependencies: boolean;
+    composeStarted: boolean;
+    /** False when an admin already existed and `hf bootstrap` was skipped rather than rerun. */
+    bootstrapped: boolean;
+    /** True when this run seeded `DEV_BUDGET_USD` because the app's `.env` sets no budget. */
+    budgetDefaulted: boolean;
+    /** Which token kind(s) were generated this run; empty when both were already set. */
+    tokensProvisioned: readonly StatusTokenKind[];
+}
+/**
+ * `hf up` — the whole local QA loop in one idempotent command: install, infra, migrate,
+ * bootstrap, status tokens, then `hf dev` in the foreground.
+ *
+ * Every step but the last is safe to rerun. `hf bootstrap` is the one step whose own contract is
+ * "exactly once" (`BootstrapRefused` — an app gets one bootstrap admin, on purpose), so this
+ * catches that specific refusal rather than asking `bootstrapApp` to change what it means; every
+ * other step already no-ops on its own (`ensureCompose`'s `--wait`, `statusTokenApp`'s default
+ * two-kind run leaving a set column alone). `hf dev` itself is the caller's to run afterward,
+ * since it blocks in the foreground and this function is meant to return a result.
+ */
+export declare function upApp(options?: UpOptions): Promise<UpResult>;
+/** True when `node_modules` isn't there yet — `pnpm install` has never run for this app. */
+export declare function needsInstall(dir: string): Promise<boolean>;
+/** True when the app's `.env` names no budget, so `hf up` will supply `DEV_BUDGET_USD`. */
+export declare function usesDefaultBudget(app: ResolvedApp): boolean;
+/** Runs `hf bootstrap`; swallows `BootstrapRefused` since the app already has its one admin. */
+export declare function bootstrapIfNeeded(app: ResolvedApp): Promise<boolean>;

package/dist/up.js

@@ -0,0 +1,76 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { BootstrapRefused } from "@hyperfixation/auth";
+import { resolveApp } from "./app.js";
+import { bootstrapApp } from "./bootstrap.js";
+import { ensureCompose } from "./dev.js";
+import { migrateApp } from "./migrate.js";
+import { run } from "./spawn.js";
+import { statusTokenApp } from "./status-token.js";
+/**
+ * What `hf up` seeds `hf_app_state.budget_usd` with when `HF_BOOTSTRAP_BUDGET_USD` isn't set.
+ * Local only: `hf bootstrap` itself still refuses to run without an explicit budget, so a
+ * deployed app never starts under a cap nobody chose.
+ */
+export const DEV_BUDGET_USD = "10";
+const BUDGET_ENV = "HF_BOOTSTRAP_BUDGET_USD";
+/**
+ * `hf up` — the whole local QA loop in one idempotent command: install, infra, migrate,
+ * bootstrap, status tokens, then `hf dev` in the foreground.
+ *
+ * Every step but the last is safe to rerun. `hf bootstrap` is the one step whose own contract is
+ * "exactly once" (`BootstrapRefused` — an app gets one bootstrap admin, on purpose), so this
+ * catches that specific refusal rather than asking `bootstrapApp` to change what it means; every
+ * other step already no-ops on its own (`ensureCompose`'s `--wait`, `statusTokenApp`'s default
+ * two-kind run leaving a set column alone). `hf dev` itself is the caller's to run afterward,
+ * since it blocks in the foreground and this function is meant to return a result.
+ */
+export async function upApp(options = {}) {
+    const app = await resolveApp(options.dir);
+    const installedDependencies = await needsInstall(app.dir);
+    if (installedDependencies)
+        await run("pnpm", ["install"], { cwd: app.dir });
+    const composeStarted = await ensureCompose(app);
+    await migrateApp({ dir: app.dir });
+    const defaultsBudget = usesDefaultBudget(app);
+    const bootstrapped = await bootstrapIfNeeded(app);
+    const { tokens } = await statusTokenApp({ dir: app.dir });
+    const tokensProvisioned = Object.keys(tokens);
+    return {
+        app,
+        installedDependencies,
+        composeStarted,
+        bootstrapped,
+        budgetDefaulted: bootstrapped && defaultsBudget,
+        tokensProvisioned,
+    };
+}
+/** True when `node_modules` isn't there yet — `pnpm install` has never run for this app. */
+export async function needsInstall(dir) {
+    try {
+        return !(await stat(path.join(dir, "node_modules"))).isDirectory();
+    }
+    catch {
+        return true;
+    }
+}
+/** True when the app's `.env` names no budget, so `hf up` will supply `DEV_BUDGET_USD`. */
+export function usesDefaultBudget(app) {
+    const value = app.env[BUDGET_ENV];
+    return value === undefined || value === "";
+}
+/** Runs `hf bootstrap`; swallows `BootstrapRefused` since the app already has its one admin. */
+export async function bootstrapIfNeeded(app) {
+    try {
+        await bootstrapApp({
+            dir: app.dir,
+            budgetUsd: usesDefaultBudget(app) ? DEV_BUDGET_USD : undefined,
+        });
+        return true;
+    }
+    catch (error) {
+        if (error instanceof BootstrapRefused)
+            return false;
+        throw error;
+    }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@hyperfixation/cli",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "The hf binary and its Turborepo generator templates",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/grahamlutz/hyperfixation-core.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "hf": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/test-support/**"
+  ],
+  "dependencies": {
+    "@hyperfixation/auth": "0.1.0",
+    "@hyperfixation/core": "0.1.0",
+    "@hyperfixation/db": "0.1.0",
+    "pg": "^8.23.0"
+  },
+  "devDependencies": {
+    "@hyperfixation/eslint-config": "0.1.0",
+    "@hyperfixation/testing": "0.1.0",
+    "@microsoft/api-extractor": "^7.59.1",
+    "@types/pg": "^8.23.1",
+    "eslint": "^10.10.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint src",
+    "api-extractor": "api-extractor run",
+    "api-extractor:update": "api-extractor run --local",
+    "test": "vitest run --passWithNoTests"
+  }
+}