@hyperfixation/cli 0.1.0 → 0.1.1

package/dist/state.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The ten steps of a cloud `hf new`, in the order it runs them. A step is recorded only once
+ * everything it created is in the state file, so a rerun resumes at the first unrecorded step
+ * rather than re-creating what the previous run already paid for.
+ *
+ * `database` sits immediately before `coolify` because it is the one step that *rotates*: a cold
+ * run gives the roles new passwords, and a deployed app keeps the old ones until the envs are
+ * PATCHed and the app redeployed. Every fallible external create — the repo, the backup, Sentry,
+ * Langfuse, the DNS record — therefore happens first, so a failure in one of them cannot leave a
+ * live app holding credentials nothing will replace.
+ */
+export declare const STEPS: readonly ["template", "install", "repo", "backup", "sentry", "langfuse", "dns", "database", "coolify", "deploy"];
+export type StepName = (typeof STEPS)[number];
+export interface StepRecord {
+    /** ISO 8601, when the step finished. */
+    doneAt: string;
+}
+export interface CoolifyState {
+    projectUuid?: string;
+    appUuid?: string;
+    /**
+     * `secretsHash` of the secrets the last bulk env PATCH carried.
+     *
+     * The `coolify` step is "done" only while this matches what the state holds now: a cold run
+     * that rotated the role passwords leaves the deployed app authenticating with the old ones, and
+     * a recorded `steps.coolify` would otherwise make a rerun skip the one PATCH that fixes it.
+     */
+    envsSecretsHash?: string;
+}
+/** The three role passwords a cold run generates. Nothing else on the laptop has a copy. */
+export interface DatabaseState {
+    migratorPassword?: string;
+    applicationPassword?: string;
+    readonlyPassword?: string;
+}
+export interface LangfuseState {
+    publicKey?: string;
+    secretKey?: string;
+}
+export interface StatusTokenState {
+    read?: string;
+    write?: string;
+}
+/**
+ * Everything one cloud app's provisioning produced, so that a rerun, `hf doctor` and
+ * `hf restore-check` do not have to ask five APIs what already exists.
+ *
+ * Every field is optional but `steps`: the file is written between steps, and each step fills
+ * in its own part.
+ */
+export interface AppState {
+    steps: Partial<Record<StepName, StepRecord>>;
+    /** `owner/name` of the app's GitHub repository. */
+    repo?: string;
+    coolify?: CoolifyState;
+    database?: DatabaseState;
+    sentryDsn?: string;
+    langfuse?: LangfuseState;
+    statusTokens?: StatusTokenState;
+    /**
+     * `BETTER_AUTH_SECRET` — generated once, for this app, and kept only here: it is the one
+     * `REQUIRED_ENV` secret no provider hands back, so nothing else can be asked for it again.
+     * Never printed; it reaches the app through the Coolify env PATCH alone.
+     */
+    betterAuthSecret?: string;
+    lastRestoreCheckAt?: string;
+    lastDeployedSha?: string;
+}
+/** 32 random bytes, the length `better-auth` documents, in the form an env var can carry. */
+export declare function generateBetterAuthSecret(): string;
+/**
+ * A fingerprint of every secret the Coolify envs carry, so a rotation is detectable without
+ * keeping a second copy of the secrets themselves.
+ *
+ * Only the values matter, not the state around them: `coolify.envsSecretsHash` is compared
+ * against this, and a step that rotated a password must come out different.
+ */
+export declare function secretsHash(state: AppState): string;
+/**
+ * The state file exists but does not parse, or does not have the shape above.
+ *
+ * Never repaired and never overwritten: the file is the only copy of three database passwords,
+ * two status tokens and a Langfuse secret key, so silently starting a fresh one would strand a
+ * deployed app whose roles nothing can log in as any more. The operator is told where the file
+ * is and decides.
+ */
+export declare class AppStateInvalid extends Error {
+    readonly file: string;
+    constructor(file: string, problem: string);
+}
+export interface AppStateStore {
+    readonly file: string;
+    /** The state as last written. Replaced, never mutated in place, by `patch` and `markDone`. */
+    readonly state: AppState;
+    isDone(step: StepName): boolean;
+    markDone(step: StepName): Promise<void>;
+    /**
+     * Forgets a step, so the next run repeats it.
+     *
+     * What a rotation needs: the secrets the `coolify` step PATCHed and the `deploy` that published
+     * them are no longer true of the app, and `patch` merges rather than removes.
+     */
+    clearDone(step: StepName): Promise<void>;
+    /**
+     * Merges `changes` in and writes the file. Object-valued keys (`coolify`, `database`,
+     * `langfuse`, `statusTokens`) merge field by field, so a step can record the one uuid it
+     * learned without carrying the rest.
+     */
+    patch(changes: Partial<AppState>): Promise<void>;
+}
+/** `~/.config/hf/state`, one `<name>.json` per app. */
+export declare function stateDir(env?: NodeJS.ProcessEnv): string;
+export declare function stateFile(name: string, env?: NodeJS.ProcessEnv): string;
+export interface OpenAppStateOptions {
+    /** The directory holding `<name>.json`. Defaults to `stateDir()`. */
+    dir?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Opens one app's state cache, or starts an empty one when the file does not exist yet.
+ *
+ * The file must be mode 0600; a looser one is tightened and then refused (`InsecureFileMode`).
+ */
+export declare function openAppState(name: string, options?: OpenAppStateOptions): Promise<AppStateStore>;

package/dist/state.js

@@ -0,0 +1,217 @@
+import { createHash, randomBytes } from "node:crypto";
+import path from "node:path";
+import { configHome } from "./config.js";
+import { readSecretFile, writeSecretFile } from "./secret-file.js";
+/**
+ * The ten steps of a cloud `hf new`, in the order it runs them. A step is recorded only once
+ * everything it created is in the state file, so a rerun resumes at the first unrecorded step
+ * rather than re-creating what the previous run already paid for.
+ *
+ * `database` sits immediately before `coolify` because it is the one step that *rotates*: a cold
+ * run gives the roles new passwords, and a deployed app keeps the old ones until the envs are
+ * PATCHed and the app redeployed. Every fallible external create — the repo, the backup, Sentry,
+ * Langfuse, the DNS record — therefore happens first, so a failure in one of them cannot leave a
+ * live app holding credentials nothing will replace.
+ */
+export const STEPS = [
+    "template",
+    "install",
+    "repo",
+    "backup",
+    "sentry",
+    "langfuse",
+    "dns",
+    "database",
+    "coolify",
+    "deploy",
+];
+/** 32 random bytes, the length `better-auth` documents, in the form an env var can carry. */
+export function generateBetterAuthSecret() {
+    return randomBytes(32).toString("base64url");
+}
+/**
+ * A fingerprint of every secret the Coolify envs carry, so a rotation is detectable without
+ * keeping a second copy of the secrets themselves.
+ *
+ * Only the values matter, not the state around them: `coolify.envsSecretsHash` is compared
+ * against this, and a step that rotated a password must come out different.
+ */
+export function secretsHash(state) {
+    const database = state.database ?? {};
+    const material = [
+        database.migratorPassword,
+        database.applicationPassword,
+        database.readonlyPassword,
+        state.betterAuthSecret,
+        state.statusTokens?.read,
+        state.statusTokens?.write,
+    ];
+    return createHash("sha256").update(JSON.stringify(material)).digest("hex");
+}
+/**
+ * The state file exists but does not parse, or does not have the shape above.
+ *
+ * Never repaired and never overwritten: the file is the only copy of three database passwords,
+ * two status tokens and a Langfuse secret key, so silently starting a fresh one would strand a
+ * deployed app whose roles nothing can log in as any more. The operator is told where the file
+ * is and decides.
+ */
+export class AppStateInvalid extends Error {
+    file;
+    constructor(file, problem) {
+        super(`${file} is not a usable hf state file: ${problem}. It is the only copy of this app's ` +
+            `passwords and tokens, so nothing was overwritten — inspect it, or move it aside to ` +
+            `start over.`);
+        this.name = "AppStateInvalid";
+        this.file = file;
+    }
+}
+/** `~/.config/hf/state`, one `<name>.json` per app. */
+export function stateDir(env = process.env) {
+    return path.join(configHome(env), "state");
+}
+export function stateFile(name, env = process.env) {
+    return path.join(stateDir(env), `${name}.json`);
+}
+/**
+ * Opens one app's state cache, or starts an empty one when the file does not exist yet.
+ *
+ * The file must be mode 0600; a looser one is tightened and then refused (`InsecureFileMode`).
+ */
+export async function openAppState(name, options = {}) {
+    const env = options.env ?? process.env;
+    const file = options.dir === undefined ? stateFile(name, env) : path.join(options.dir, `${name}.json`);
+    const contents = await readSecretFile(file);
+    let state = contents === undefined ? { steps: {} } : parseAppState(contents, file);
+    const write = async (next) => {
+        await writeSecretFile(file, `${JSON.stringify(next, null, 2)}\n`);
+        state = next;
+    };
+    return {
+        file,
+        get state() {
+            return state;
+        },
+        isDone: (step) => state.steps[step] !== undefined,
+        markDone: async (step) => {
+            await write({
+                ...state,
+                steps: { ...state.steps, [step]: { doneAt: new Date().toISOString() } },
+            });
+        },
+        clearDone: async (step) => {
+            if (state.steps[step] === undefined)
+                return;
+            const steps = { ...state.steps };
+            delete steps[step];
+            await write({ ...state, steps });
+        },
+        patch: async (changes) => {
+            await write(merge(state, changes));
+        },
+    };
+}
+function merge(state, changes) {
+    return {
+        ...state,
+        ...changes,
+        steps: { ...state.steps, ...changes.steps },
+        ...mergeObject(state, changes, "coolify"),
+        ...mergeObject(state, changes, "database"),
+        ...mergeObject(state, changes, "langfuse"),
+        ...mergeObject(state, changes, "statusTokens"),
+    };
+}
+function mergeObject(state, changes, key) {
+    const change = changes[key];
+    if (change === undefined)
+        return {};
+    return { [key]: { ...state[key], ...change } };
+}
+/**
+ * The schema, hand-written because the whole contract is nine keys and a step map, and because
+ * an unknown key has to be an error rather than something a permissive parser drops on the next
+ * write.
+ */
+function parseAppState(contents, file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        throw new AppStateInvalid(file, "it is not valid JSON");
+    }
+    const root = asObject(parsed, file, "the top level");
+    const state = { steps: {} };
+    for (const [key, value] of Object.entries(root)) {
+        switch (key) {
+            case "steps":
+                state.steps = parseSteps(value, file);
+                break;
+            case "repo":
+            case "sentryDsn":
+            case "betterAuthSecret":
+            case "lastRestoreCheckAt":
+            case "lastDeployedSha":
+                state[key] = asString(value, file, key);
+                break;
+            case "coolify":
+                state.coolify = parseFields(value, file, key, [
+                    "projectUuid",
+                    "appUuid",
+                    "envsSecretsHash",
+                ]);
+                break;
+            case "database":
+                state.database = parseFields(value, file, key, [
+                    "migratorPassword",
+                    "applicationPassword",
+                    "readonlyPassword",
+                ]);
+                break;
+            case "langfuse":
+                state.langfuse = parseFields(value, file, key, ["publicKey", "secretKey"]);
+                break;
+            case "statusTokens":
+                state.statusTokens = parseFields(value, file, key, ["read", "write"]);
+                break;
+            default:
+                throw new AppStateInvalid(file, `${JSON.stringify(key)} is not an hf state key`);
+        }
+    }
+    if (root.steps === undefined)
+        throw new AppStateInvalid(file, "it has no steps");
+    return state;
+}
+function parseSteps(value, file) {
+    const steps = {};
+    for (const [name, record] of Object.entries(asObject(value, file, "steps"))) {
+        if (!STEPS.includes(name)) {
+            throw new AppStateInvalid(file, `steps.${name} is not a step of hf new`);
+        }
+        const fields = asObject(record, file, `steps.${name}`);
+        steps[name] = { doneAt: asString(fields.doneAt, file, `steps.${name}.doneAt`) };
+    }
+    return steps;
+}
+function parseFields(value, file, key, fields) {
+    const out = {};
+    for (const [field, entry] of Object.entries(asObject(value, file, key))) {
+        if (!fields.includes(field)) {
+            throw new AppStateInvalid(file, `${key}.${field} is not an hf state key`);
+        }
+        out[field] = asString(entry, file, `${key}.${field}`);
+    }
+    return out;
+}
+function asObject(value, file, what) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new AppStateInvalid(file, `${what} is not an object`);
+    }
+    return value;
+}
+function asString(value, file, what) {
+    if (typeof value !== "string")
+        throw new AppStateInvalid(file, `${what} is not a string`);
+    return value;
+}

package/dist/status-token.d.ts

@@ -19,6 +19,8 @@ export interface StatusTokenAppOptions {
      * up yet" would also require `--rotate`, and `--rotate` would take out the other, live token.
      */
     explicit?: boolean;
+    /** Connection URLs in place of a `.env`; see `ResolveAppOptions`. */
+    env?: Record<string, string>;
 }
 export interface StatusTokenAppResult {
     app: ResolvedApp;

package/dist/status-token.js

@@ -35,7 +35,7 @@ export class StatusTokenAlreadySet extends Error {
  * caller; nothing here ever stores or logs it.
  */
 export async function statusTokenApp(options = {}) {
-    const app = await resolveApp(options.dir);
+    const app = await resolveApp(options.dir, { env: options.env });
     const databaseUrl = requireEnv(app, "DATABASE_URL");
     const kinds = options.kinds ?? ["read", "write"];
     const pool = new Pool({ connectionString: databaseUrl, max: 1 });

package/dist/template-source.d.ts

@@ -1,5 +1,7 @@
 /** 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";
+/** What a cloud `hf new` fetches when `--from` is absent; giget's `gh:` provider resolves it. */
+export declare const TEMPLATE_REPOSITORY = "gh:grahamlutz/hyperfixation-template";
 /**
  * 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.
@@ -14,3 +16,24 @@ export declare const TEMPLATE_DIR_ENV = "HF_TEMPLATE_DIR";
 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>;
+/** giget's `downloadTemplate`, narrowed to what `fetchTemplate` asks of it so a test can be one. */
+export type TemplateDownload = (source: string, options: {
+    dir: string;
+    force: boolean;
+}) => Promise<{
+    dir: string;
+}>;
+export interface FetchTemplateOptions {
+    /** Replaces the real download; the tests never reach the network. */
+    download?: TemplateDownload;
+}
+/**
+ * Fetches the template into `dir` — the cloud path's counterpart to `requireTemplateSource`.
+ *
+ * `source` is a giget specifier (`gh:owner/repo`, optionally `#ref`), defaulting to
+ * `TEMPLATE_REPOSITORY`; `--from` passes whatever the operator typed straight through, so a
+ * branch or a fork needs no flag of its own. What arrives is checked for `TEMPLATE_MARKER`
+ * before `newApp` is let near it: a specifier that resolves to some other repository would
+ * otherwise be copied, substituted and committed as an app.
+ */
+export declare function fetchTemplate(source: string | undefined, dir: string, options?: FetchTemplateOptions): Promise<string>;

package/dist/template-source.js

@@ -1,9 +1,12 @@
 import { stat } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { downloadTemplate } from "giget";
 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";
+/** What a cloud `hf new` fetches when `--from` is absent; giget's `gh:` provider resolves it. */
+export const TEMPLATE_REPOSITORY = "gh:grahamlutz/hyperfixation-template";
 /**
  * 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.
@@ -36,6 +39,26 @@ export async function requireTemplateSource(cwd) {
     }
     return found;
 }
+/**
+ * Fetches the template into `dir` — the cloud path's counterpart to `requireTemplateSource`.
+ *
+ * `source` is a giget specifier (`gh:owner/repo`, optionally `#ref`), defaulting to
+ * `TEMPLATE_REPOSITORY`; `--from` passes whatever the operator typed straight through, so a
+ * branch or a fork needs no flag of its own. What arrives is checked for `TEMPLATE_MARKER`
+ * before `newApp` is let near it: a specifier that resolves to some other repository would
+ * otherwise be copied, substituted and committed as an app.
+ */
+export async function fetchTemplate(source, dir, options = {}) {
+    const specifier = source ?? TEMPLATE_REPOSITORY;
+    const download = options.download ?? defaultDownload;
+    const target = path.resolve(dir);
+    const { dir: fetched } = await download(specifier, { dir: target, force: true });
+    if (!(await isTemplate(fetched))) {
+        throw new TemplateError(`${specifier} has no ${TEMPLATE_MARKER}: it is not the hyperfixation template`);
+    }
+    return fetched;
+}
+const defaultDownload = async (source, options) => await downloadTemplate(source, { ...options, silent: true });
 async function isTemplate(dir) {
     try {
         return (await stat(path.join(dir, TEMPLATE_MARKER))).isFile();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperfixation/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "description": "The hf binary and its Turborepo generator templates",
   "repository": {
@@ -29,17 +29,20 @@
     "!dist/test-support/**"
   ],
   "dependencies": {
-    "@hyperfixation/auth": "0.1.0",
-    "@hyperfixation/core": "0.1.0",
-    "@hyperfixation/db": "0.1.0",
+    "@hyperfixation/auth": "0.1.1",
+    "@hyperfixation/core": "0.1.1",
+    "@hyperfixation/db": "0.1.1",
+    "giget": "3.3.1",
     "pg": "^8.23.0"
   },
   "devDependencies": {
-    "@hyperfixation/eslint-config": "0.1.0",
-    "@hyperfixation/testing": "0.1.0",
+    "@hyperfixation/eslint-config": "0.1.1",
+    "@hyperfixation/testing": "0.1.1",
     "@microsoft/api-extractor": "^7.59.1",
     "@types/pg": "^8.23.1",
-    "eslint": "^10.10.0"
+    "eslint": "^10.10.0",
+    "msw": "2.15.0",
+    "openapi-request-validator": "12.1.3"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",