@wtfalch/foundry 0.1.0

package/dist/runner/schema.d.ts

@@ -0,0 +1,163 @@
+import type { Checkpoint } from '../state.js';
+import type { RunFailure, RunStatus } from './types.js';
+/**
+ * Mirrors `migrations/0001_foundry_runs.sql`, which is the source of
+ * truth: the SQL carries the CHECKs and the partial unique index that is
+ * the run's lock, neither of which drizzle-kit would generate here (this
+ * repo hand-writes migrations, per app-template's convention). Internal to
+ * `./runner` -- a host reaches this table only through {@link createJobRunner},
+ * never by importing it directly (`@wtfalch/keys`' `./held` does the same
+ * with its own tables).
+ */
+export declare const foundryRuns: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "foundry_runs";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "foundry_runs";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        orgId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "org_id";
+            tableName: "foundry_runs";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: import("drizzle-orm/pg-core").PgColumn<{
+            name: "status";
+            tableName: "foundry_runs";
+            dataType: "string";
+            columnType: "PgText";
+            data: RunStatus;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: RunStatus;
+        }>;
+        stepIds: import("drizzle-orm/pg-core").PgColumn<{
+            name: "step_ids";
+            tableName: "foundry_runs";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: string[];
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: string[];
+        }>;
+        checkpoints: import("drizzle-orm/pg-core").PgColumn<{
+            name: "checkpoints";
+            tableName: "foundry_runs";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: Checkpoint[];
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Checkpoint[];
+        }>;
+        failure: import("drizzle-orm/pg-core").PgColumn<{
+            name: "failure";
+            tableName: "foundry_runs";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: RunFailure;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: RunFailure;
+        }>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "foundry_runs";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "updated_at";
+            tableName: "foundry_runs";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+export type FoundryRunRow = typeof foundryRuns.$inferSelect;

package/dist/runner/schema.js

@@ -0,0 +1,25 @@
+import { sql } from 'drizzle-orm';
+import { jsonb, pgTable, text, timestamp, uniqueIndex } from 'drizzle-orm/pg-core';
+/**
+ * Mirrors `migrations/0001_foundry_runs.sql`, which is the source of
+ * truth: the SQL carries the CHECKs and the partial unique index that is
+ * the run's lock, neither of which drizzle-kit would generate here (this
+ * repo hand-writes migrations, per app-template's convention). Internal to
+ * `./runner` -- a host reaches this table only through {@link createJobRunner},
+ * never by importing it directly (`@wtfalch/keys`' `./held` does the same
+ * with its own tables).
+ */
+export const foundryRuns = pgTable('foundry_runs', {
+    id: text('id').primaryKey(),
+    orgId: text('org_id').notNull(),
+    status: text('status').notNull().default('running').$type(),
+    stepIds: jsonb('step_ids').notNull().$type(),
+    checkpoints: jsonb('checkpoints').notNull().default([]).$type(),
+    failure: jsonb('failure').$type(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [
+    uniqueIndex('foundry_runs_org_lock_idx')
+        .on(table.orgId)
+        .where(sql `${table.status} <> 'succeeded'`),
+]);

package/dist/runner/types.d.ts

@@ -0,0 +1,97 @@
+import type { OrgId } from '../org.js';
+import type { Checkpoint } from '../state.js';
+import type { RunnerDb } from './db.js';
+/**
+ * One step a run executes. `id` is the checkpoint key (#17): stable across
+ * a kill and restart, since a run persists only `stepIds`, never a
+ * function -- the caller (the worker process) supplies the same
+ * `RunnerStep[]` again on every call to {@link JobRunner.runSteps}, and its
+ * ids must match the run's own `stepIds` exactly, in order.
+ *
+ * What `run()` actually does against Coolify, Cloudflare or Zitadel is
+ * someone else's ticket (#17's boundary drawn against #19/#20) -- this
+ * runner only sequences, checkpoints and locks.
+ */
+export interface RunnerStep {
+    id: string;
+    run(): Promise<void>;
+}
+export type RunStatus = 'running' | 'succeeded' | 'failed';
+/** Which step stopped the run, and why. Never cleared automatically -- #9: "no automatic retry". */
+export interface RunFailure {
+    step: string;
+    message: string;
+    at: string;
+}
+/** A run row, read back for polling (#17: "progress is readable by polling"). */
+export interface RunRecord {
+    id: string;
+    orgId: OrgId;
+    status: RunStatus;
+    /** The run's fixed plan, in order -- what {@link JobRunner.runSteps} checks a resume's steps against. */
+    stepIds: string[];
+    checkpoints: Checkpoint[];
+    failure: RunFailure | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface RunStepsOptions {
+    /**
+     * Checked before each step that has not already checkpointed; set, the
+     * run stops in place -- its row keeps whatever status and checkpoints it
+     * already had, neither 'succeeded' nor 'failed'. This is how a test
+     * lands #17's "killing the worker mid-run" at a deterministic point: in
+     * production nothing signals this, the process simply stops, and the
+     * row left behind is the same either way. The next call to `runSteps`
+     * with this `runId`, from the steps already done, is the resume -- there
+     * is no separate "resume" entry point because none is needed.
+     */
+    signal?: AbortSignal;
+}
+export interface CreateJobRunnerOptions {
+    db: RunnerDb;
+    /** Overridable clock, for deterministic tests (mirrors `@wtfalch/keys`' `held` module's own `now`). */
+    now?: () => Date;
+}
+/**
+ * The job runner (#17): enqueue an apply from a call without running it,
+ * run its steps from a worker process, read progress by polling. `db` is
+ * fixed at construction (mirrors `@wtfalch/keys`' `createHeldKeys`); every
+ * method after that takes only what varies per call.
+ */
+export interface JobRunner {
+    /**
+     * Writes the run's row and returns -- no step's `run()` is called here.
+     * That is the whole of "not in the request" (#17): the actual work
+     * happens only when a worker process later calls {@link runSteps} with
+     * this `runId`.
+     *
+     * Refused, per #9, when the org already has a run that has not
+     * succeeded: enforced by `foundry_runs_org_lock_idx`, a partial unique
+     * index, the lock as a database row rather than a lockfile, so the
+     * refusal holds across containers.
+     */
+    enqueueApply(orgId: OrgId, steps: RunnerStep[]): Promise<{
+        runId: string;
+    }>;
+    /**
+     * Runs a run's remaining steps in order, checkpointing each on success.
+     * Steps already checkpointed are skipped -- the resume behaviour #17
+     * requires, driven entirely by what `foundry_runs` already holds, never
+     * by anything this process remembers.
+     *
+     * On a step's `run()` throwing, the row is marked `failed` with which
+     * step and why, and the lock stays held: the row does not become
+     * 'succeeded', so `foundry_runs_org_lock_idx` still blocks a new apply
+     * for this org (#9: "no automatic retry", "keeps the lock"). This
+     * method never retries; a human decides when to call it again, and
+     * doing so is what resumes a failed run from its checkpoint (#9's
+     * decision comment: "a human fixes the cause and resumes from that
+     * checkpoint").
+     */
+    runSteps(runId: string, steps: RunnerStep[], options?: RunStepsOptions): Promise<RunRecord>;
+    /** A single read, for polling. Holds no connection open past the query. */
+    getRun(runId: string): Promise<RunRecord | null>;
+    /** The org's current lock-holding run, if it has one (status not yet 'succeeded'). */
+    currentRun(orgId: OrgId): Promise<RunRecord | null>;
+}

package/dist/runner/types.js

@@ -0,0 +1 @@
+export {};

package/dist/slug.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The declared org's slug: a pure validator, no I/O, no store access.
+ *
+ * Decided in https://github.com/wtfalch/foundry/issues/28, forced by the
+ * level-1 apex `oikos.host` being live: Cloudflare's free-tier Universal SSL
+ * covers a single wildcard level, so every level-1 org's hostnames are flat
+ * (`acme.oikos.host`, `acme-stage.oikos.host`, `acme-pr-12.oikos.host`).
+ * That makes the slug a live hostname from the moment the org exists — #7
+ * only froze it once the org had mail, which is too late: by then the
+ * hostname is already serving. This validator runs at creation, not at
+ * first use (#28 "Done when").
+ *
+ * Kept separate from `org.ts` and `store/postgres.ts` so it can be called
+ * from both without either depending on the other: `store/postgres.ts`
+ * calls it on `create` and `update` (#28), and anything that needs to
+ * pre-validate a slug before it ever reaches the store — the operator page,
+ * one day — can import it too.
+ */
+/** The flattened set {@link validateSlug} checks a candidate slug against. */
+export declare const RESERVED_SLUGS: ReadonlySet<string>;
+/**
+ * Why {@link validateSlug} refused a candidate slug, by name so a caller —
+ * `store/postgres.ts`'s `DeclaredOrgError`, eventually the operator page —
+ * can report it without parsing `message` text.
+ */
+export type SlugRejectionReason = 'invalid-label' | 'reserved' | 'environment-suffix';
+export interface SlugRejection {
+    reason: SlugRejectionReason;
+    message: string;
+}
+/**
+ * Validates a candidate org slug against every rule #28 decided. Returns
+ * `null` when the slug is acceptable, or a {@link SlugRejection} naming
+ * exactly one reason otherwise — the first rule the slug fails, checked in
+ * the order below, since a slug that fails more than one rule still only
+ * needs one reason reported.
+ */
+export declare function validateSlug(slug: string): SlugRejection | null;

package/dist/slug.js

@@ -0,0 +1,141 @@
+/**
+ * The declared org's slug: a pure validator, no I/O, no store access.
+ *
+ * Decided in https://github.com/wtfalch/foundry/issues/28, forced by the
+ * level-1 apex `oikos.host` being live: Cloudflare's free-tier Universal SSL
+ * covers a single wildcard level, so every level-1 org's hostnames are flat
+ * (`acme.oikos.host`, `acme-stage.oikos.host`, `acme-pr-12.oikos.host`).
+ * That makes the slug a live hostname from the moment the org exists — #7
+ * only froze it once the org had mail, which is too late: by then the
+ * hostname is already serving. This validator runs at creation, not at
+ * first use (#28 "Done when").
+ *
+ * Kept separate from `org.ts` and `store/postgres.ts` so it can be called
+ * from both without either depending on the other: `store/postgres.ts`
+ * calls it on `create` and `update` (#28), and anything that needs to
+ * pre-validate a slug before it ever reaches the store — the operator page,
+ * one day — can import it too.
+ */
+/**
+ * #28's reserved list, verbatim, in its three named groups. Kept as three
+ * separate arrays rather than flattened so each group's citation stays next
+ * to the names it covers; {@link RESERVED_SLUGS} is the flattened set
+ * `validateSlug` actually checks against.
+ */
+const RESERVED_ESTATE_SERVICES = [
+    'archon',
+    'foundry',
+    'agora',
+    'files',
+    'ai',
+    'keys',
+    'chat',
+    'calls',
+    'calendar',
+    'threads',
+    'audit',
+    'authz',
+    'manage',
+    'operator',
+    'mailbox',
+    'oikos',
+    'cms',
+];
+const RESERVED_INFRASTRUCTURE_AND_MAIL = [
+    'www',
+    'api',
+    'cdn',
+    'static',
+    'assets',
+    'ns',
+    'ns1',
+    'ns2',
+    'mx',
+    'mail',
+    'smtp',
+    'imap',
+    'pop',
+    'webmail',
+    'autodiscover',
+    'autoconfig',
+    'ftp',
+];
+/**
+ * Auth-sensitive names and environment words: reserved because a customer
+ * holding one could phish the rest (#28).
+ */
+const RESERVED_AUTH_AND_ENVIRONMENTS = [
+    'auth',
+    'login',
+    'signin',
+    'sso',
+    'id',
+    'account',
+    'admin',
+    'console',
+    'dashboard',
+    'billing',
+    'payments',
+    'secure',
+    'status',
+    'docs',
+    'help',
+    'support',
+    'stage',
+    'staging',
+    'preview',
+    'pr',
+    'test',
+    'dev',
+    'demo',
+    'internal',
+    'private',
+    'system',
+    'root',
+];
+/** The flattened set {@link validateSlug} checks a candidate slug against. */
+export const RESERVED_SLUGS = new Set([
+    ...RESERVED_ESTATE_SERVICES,
+    ...RESERVED_INFRASTRUCTURE_AND_MAIL,
+    ...RESERVED_AUTH_AND_ENVIRONMENTS,
+]);
+/**
+ * A DNS label: 1-63 characters, lowercase `a-z`, `0-9` and hyphen, no
+ * leading or trailing hyphen. Consecutive hyphens are legal DNS (RFC 1035
+ * doesn't forbid them; only positions 3-4 being `--` matters, and that's an
+ * IDNA/punycode rule this estate has no reason to import) so this pattern
+ * deliberately does not add a rule #28 never asked for.
+ */
+const DNS_LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+/** `<something>-pr-<digits>` — the preview-hostname shape (#28). */
+const PR_SUFFIX = /-pr-\d+$/;
+/** `<something>-stage` — the stage-hostname shape (#28). */
+const STAGE_SUFFIX = /-stage$/;
+/**
+ * Validates a candidate org slug against every rule #28 decided. Returns
+ * `null` when the slug is acceptable, or a {@link SlugRejection} naming
+ * exactly one reason otherwise — the first rule the slug fails, checked in
+ * the order below, since a slug that fails more than one rule still only
+ * needs one reason reported.
+ */
+export function validateSlug(slug) {
+    if (!DNS_LABEL.test(slug)) {
+        return {
+            reason: 'invalid-label',
+            message: `slug '${slug}' is not a valid DNS label: must be 1-63 characters, lowercase a-z, 0-9 and hyphen, and may not start or end with a hyphen`,
+        };
+    }
+    if (RESERVED_SLUGS.has(slug)) {
+        return {
+            reason: 'reserved',
+            message: `slug '${slug}' is reserved by the estate (#28) and cannot be taken by an org`,
+        };
+    }
+    if (STAGE_SUFFIX.test(slug) || PR_SUFFIX.test(slug)) {
+        return {
+            reason: 'environment-suffix',
+            message: `slug '${slug}' ends with an environment suffix ('-stage' or '-pr-<digits>') reserved for another org's own hostname (#28) — 'acme-stage' is only legal as acme's stage hostname, never as an org slug in its own right`,
+        };
+    }
+    return null;
+}

package/dist/state.d.ts

@@ -0,0 +1,63 @@
+import type { OrgId } from './org.js';
+/**
+ * One completed step of an in-progress or interrupted apply.
+ *
+ * Decided in #7 ("Shape") and https://github.com/wtfalch/foundry/issues/14's
+ * resolved research #5: a check/apply with lock and checkpoints, in the
+ * shape research #5 found already built in auth's namespace provisioner and
+ * reused rather than reinvented. A failed apply stops at its checkpoint and
+ * holds its lock as a database row, never a lockfile (#9, resolved).
+ */
+export interface Checkpoint {
+    step: string;
+    completedAt: string;
+}
+/**
+ * When an apply last completed, and against which declared org version.
+ *
+ * Decided in #9 (resolved): "an apply is refused when its plan no longer
+ * matches reality" — `declaredOrgVersion` is what a later plan compares
+ * against to detect that drift.
+ */
+export interface LastApplied {
+    at: string;
+    declaredOrgVersion: string;
+}
+/**
+ * Foundry's own record of what has actually been made true for an org,
+ * separate from the human-edited {@link DeclaredOrg} it is checked against.
+ *
+ * Decided in #7 ("Shape") and #10 (resolved): both files live in foundry's
+ * database, keyed by the same {@link OrgId}; the declared file is what a
+ * human wants, this one is what foundry has done about it.
+ */
+export interface AppliedState {
+    orgId: OrgId;
+    /**
+     * One id per service that takes jobs from many orgs (Files, AI,
+     * integrations — https://github.com/wtfalch/foundry/issues/14's resolved
+     * research #4) plus the per-org services (chat, mail), each keyed by that
+     * service's own name for the org.
+     */
+    serviceIds: Record<string, string>;
+    /** Checkpoints from the current or most recent apply. */
+    checkpoints: Checkpoint[];
+    /**
+     * The name of every {@link DeclaredOrg} field the most recent apply could
+     * not make true, because nothing implements it yet.
+     *
+     * Decision (#18): this field did not exist on the type this ticket found.
+     * #7 ("Shape") and #18's "Done when" both require `apply` to "fail loudly
+     * and by name on any field it cannot yet make true", but `Checkpoint` only
+     * records a *completed* step — recording an unimplemented field there
+     * would misuse its own documented meaning. #18's storage task ("`apply`
+     * must be able to fail by name on a field nothing implements yet, so the
+     * store records the field, not a rejection") needs somewhere to put that
+     * name, so this field carries it. Whether `apply` throws, partially
+     * applies, or does both is #19's decision, not this one; the store only
+     * has to persist whatever list it is given.
+     */
+    failedFields: string[];
+    /** `null` before this org has ever had a completed apply. */
+    lastApplied: LastApplied | null;
+}

package/dist/state.js

@@ -0,0 +1 @@
+export {};

package/dist/store/postgres.d.ts

@@ -0,0 +1,43 @@
+import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import type { DeclaredOrgStore } from '../store.js';
+/**
+ * The host's own drizzle handle or a transaction open on it, same shape
+ * `@wtfalch/keys`'s `HeldKeysDb` uses: postgres-js in a real host, PGlite in
+ * this package's own tests (`./test/db.ts`). This module never opens a
+ * connection itself.
+ */
+export type FoundryStoreDb = PgDatabase<PgQueryResultHKT, any, any>;
+/**
+ * Thrown by `create` and `update` when the store refuses a write: an id
+ * that already exists, an id that does not, a slug that fails
+ * `../slug.ts`'s `validateSlug` (#28: invalid DNS label, reserved, or an
+ * environment-suffix shape), a slug already taken by another org (#28:
+ * checked by the unique index `0004_slug_unique.sql` adds, whether caught
+ * ahead of time by a pre-check or by a race this store maps back to the
+ * same error) or — the one impossible combination #18 implements — a slug
+ * change once the org has mail. `store.ts`'s `update` doc requires a caller
+ * to be "ready for this to throw rather than silently drop a field"; this
+ * is that throw.
+ */
+export declare class DeclaredOrgError extends Error {
+    constructor(message: string);
+}
+/**
+ * `DeclaredOrgStore` (`../store.ts`) on Postgres, for #18: create, read and
+ * edit a {@link DeclaredOrg}, and read and write the {@link AppliedState}
+ * next to it, both in foundry's own database per #10 (resolved) — never git.
+ *
+ * Validation here is deliberately narrow. #18's "Done when" list names one
+ * impossible combination in full — the slug freezes once the org has mail
+ * (#7 corrections 3) — and #28 adds one more, in full: the slug is a
+ * validated (`../slug.ts`), globally unique, non-reserved DNS label, checked
+ * on both `create` and `update`. #27 adds a third, narrower rule: storage and
+ * AI spend limits are bigint-safe decimal strings of non-negative integers
+ * (or `null` for uncapped), checked the same way on both `create` and the
+ * merged result of `update`. The broader "combinations foundry knows are
+ * impossible are rejected with a reason" line needs a ruleset (domain
+ * requirements per service, `adoptedApp.form`, mail-level transitions…)
+ * that later tickets, not #18, #27 or #28, decide; `update` still merges and
+ * stores any other patch as given.
+ */
+export declare function createPostgresDeclaredOrgStore(db: FoundryStoreDb): DeclaredOrgStore;