@wtfalch/foundry 0.11.0 → 0.13.0

package/dist/store/schema.d.ts

@@ -79,6 +79,23 @@ export declare const declaredOrgs: import("drizzle-orm/pg-core").PgTableWithColu
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        version: import("drizzle-orm/pg-core").PgColumn<{
+            name: "version";
+            tableName: "foundry_declared_orgs";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         mailMode: import("drizzle-orm/pg-core").PgColumn<{
             name: "mail_mode";
             tableName: "foundry_declared_orgs";
@@ -482,33 +499,6 @@ export declare const declaredOrgs: import("drizzle-orm/pg-core").PgTableWithColu
         }, {}, {
             $type: HostingEntry[];
         }>;
-        hostingAdopt: import("drizzle-orm/pg-core").PgColumn<{
-            name: "hosting_adopt";
-            tableName: "foundry_declared_orgs";
-            dataType: "json";
-            columnType: "PgJsonb";
-            data: {
-                database?: string;
-                tunnel?: string;
-                connectorApp?: string;
-            };
-            driverParam: unknown;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {
-            $type: {
-                database?: string;
-                tunnel?: string;
-                connectorApp?: string;
-            };
-        }>;
         ssoEnabled: import("drizzle-orm/pg-core").PgColumn<{
             name: "sso_enabled";
             tableName: "foundry_declared_orgs";
@@ -1836,140 +1826,6 @@ export declare const foundryRequestedChanges: import("drizzle-orm/pg-core").PgTa
     };
     dialect: "pg";
 }>;
-/**
- * Mirrors `migrations/0031_adoptions.sql`, which is the source of truth (the
- * CHECKs live there). One row per live resource foundry took over (#311).
- * `settings` holds non-secret settings only; secrets go to the vault under
- * `vaultRef`.
- */
-export declare const foundryAdoptions: import("drizzle-orm/pg-core").PgTableWithColumns<{
-    name: "foundry_adoptions";
-    schema: undefined;
-    columns: {
-        orgId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "org_id";
-            tableName: "foundry_adoptions";
-            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;
-        }, {}, {}>;
-        resourceKey: import("drizzle-orm/pg-core").PgColumn<{
-            name: "resource_key";
-            tableName: "foundry_adoptions";
-            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;
-        }, {}, {}>;
-        kind: import("drizzle-orm/pg-core").PgColumn<{
-            name: "kind";
-            tableName: "foundry_adoptions";
-            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;
-        }, {}, {}>;
-        takenAt: import("drizzle-orm/pg-core").PgColumn<{
-            name: "taken_at";
-            tableName: "foundry_adoptions";
-            dataType: "date";
-            columnType: "PgTimestamp";
-            data: Date;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        settings: import("drizzle-orm/pg-core").PgColumn<{
-            name: "settings";
-            tableName: "foundry_adoptions";
-            dataType: "json";
-            columnType: "PgJsonb";
-            data: Record<string, unknown>;
-            driverParam: unknown;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {
-            $type: Record<string, unknown>;
-        }>;
-        vaultRef: import("drizzle-orm/pg-core").PgColumn<{
-            name: "vault_ref";
-            tableName: "foundry_adoptions";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        state: import("drizzle-orm/pg-core").PgColumn<{
-            name: "state";
-            tableName: "foundry_adoptions";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-    };
-    dialect: "pg";
-}>;
 export type DeclaredOrgRow = typeof declaredOrgs.$inferSelect;
 export type NewDeclaredOrgRow = typeof declaredOrgs.$inferInsert;
 export type AppliedStateRow = typeof foundryAppliedState.$inferSelect;
@@ -1979,4 +1835,3 @@ export type DeclaredPlatformRow = typeof foundryDeclaredPlatform.$inferSelect;
 export type NewDeclaredPlatformRow = typeof foundryDeclaredPlatform.$inferInsert;
 export type RequestedChangeRow = typeof foundryRequestedChanges.$inferSelect;
 export type NewRequestedChangeRow = typeof foundryRequestedChanges.$inferInsert;
-export type AdoptionRow = typeof foundryAdoptions.$inferSelect;

package/dist/store/schema.js

@@ -1,4 +1,4 @@
-import { bigserial, boolean, jsonb, pgTable, primaryKey, text, timestamp, } from 'drizzle-orm/pg-core';
+import { bigserial, boolean, integer, jsonb, pgTable, text, timestamp } from 'drizzle-orm/pg-core';
 /**
  * Mirrors `migrations/0001_declared_org.sql`, which is the source of truth:
  * the SQL carries the CHECKs drizzle-kit does not generate here (this
@@ -10,6 +10,8 @@ export const declaredOrgs = pgTable('foundry_declared_orgs', {
     slug: text('slug').notNull(),
     displayName: text('display_name').notNull(),
     domain: text('domain'),
+    // Bumped by 1 on every write (migrations/0033, #351): the compare-and-set token for `update`'s `expectedVersion`.
+    version: integer('version').notNull().default(1),
     mailMode: text('mail_mode').notNull().default('off'),
     mailUsesDomain: boolean('mail_uses_domain').notNull().default(false),
     // MailConfig (org.ts, #162). null until an operator declares one -- the
@@ -54,9 +56,6 @@ export const declaredOrgs = pgTable('foundry_declared_orgs', {
     // hosting_access_emails and hosting_app_env columns, which stay for an older
     // reader and are no longer written.
     hostingEntries: jsonb('hosting_entries').notNull().default([]).$type(),
-    // HostingConfig.adopt (org.ts): the live resources the org takes over by
-    // uuid. null when it adopts none. An entry's own `adopt` lives in `hostingEntries`.
-    hostingAdopt: jsonb('hosting_adopt').$type(),
     ssoEnabled: boolean('sso_enabled').notNull().default(false),
     guestsEnabled: boolean('guests_enabled').notNull().default(false),
     soloEnabled: boolean('solo_enabled').notNull().default(false),
@@ -175,18 +174,3 @@ export const foundryRequestedChanges = pgTable('foundry_requested_changes', {
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
     state: text('state').notNull().default('needs_approval'),
 });
-/**
- * Mirrors `migrations/0031_adoptions.sql`, which is the source of truth (the
- * CHECKs live there). One row per live resource foundry took over (#311).
- * `settings` holds non-secret settings only; secrets go to the vault under
- * `vaultRef`.
- */
-export const foundryAdoptions = pgTable('foundry_adoptions', {
-    orgId: text('org_id').notNull(),
-    resourceKey: text('resource_key').notNull(),
-    kind: text('kind').notNull(),
-    takenAt: timestamp('taken_at', { withTimezone: true }).notNull(),
-    settings: jsonb('settings').notNull().$type(),
-    vaultRef: text('vault_ref'),
-    state: text('state').notNull().default('adopted'),
-}, (table) => [primaryKey({ columns: [table.orgId, table.resourceKey] })]);

package/dist/store.d.ts

@@ -2,6 +2,17 @@ import type { DeclaredOrg, OrgId } from './org.js';
 import type { DeclaredPlatform } from './platform.js';
 import type { RequestedChange, RequestedChangeValue } from './requested-changes.js';
 import type { AppliedState } from './state.js';
+/** `DeclaredOrgStore.update`'s options (#351). */
+export interface UpdateOptions {
+    /** The {@link DeclaredOrg.version} the caller's patch was computed from. */
+    expectedVersion: number;
+}
+/** `update` refused a write because the org's version no longer matches `expectedVersion` (#351). */
+export interface StaleUpdate {
+    stale: true;
+    /** The org as it stands now. */
+    current: DeclaredOrg;
+}
 /**
  * The persistence seam https://github.com/wtfalch/foundry/issues/18
  * implements: create, read and edit a {@link DeclaredOrg}, and read and
@@ -39,6 +50,13 @@ export interface DeclaredOrgStore {
      * than silently drop a field.
      */
     update(id: OrgId, patch: Partial<DeclaredOrg>): Promise<DeclaredOrg>;
+    /**
+     * With `expectedVersion` (#351), the write happens only if the org is still
+     * at that {@link DeclaredOrg.version}. Otherwise nothing is written and the
+     * result is `{ stale: true, current }`, the org as it now stands. Never
+     * throws for a version mismatch.
+     */
+    update(id: OrgId, patch: Partial<DeclaredOrg>, opts: UpdateOptions): Promise<DeclaredOrg | StaleUpdate>;
     getAppliedState(id: OrgId): Promise<AppliedState | null>;
     putAppliedState(state: AppliedState): Promise<void>;
     /**
@@ -96,40 +114,3 @@ export interface RequestedChangeStore {
     /** Every request an org has made, oldest first. */
     listForOrg(orgId: OrgId): Promise<RequestedChange[]>;
 }
-export type AdoptionKind = 'app' | 'database' | 'tunnel' | 'connector' | 'access';
-export type AdoptionState = 'adopted' | 'confirmed' | 'restored' | 'released';
-/**
- * What foundry recorded before it first changed a live resource it took over
- * (#311). `settings` holds non-secret settings only; secrets live in the
- * `AdoptionVault` (`plan/adoption-vault.ts`) under `vaultRef`.
- */
-export interface Adoption {
-    orgId: OrgId;
-    /** The scope key of the resource, for example `coolify:app:<orgId>:<entryKey>`. */
-    resourceKey: string;
-    kind: AdoptionKind;
-    /** ISO time the snapshot was taken. */
-    takenAt: string;
-    settings: Record<string, unknown>;
-    /** The vault ref of the secret part of the snapshot, or `null` when it has none. */
-    vaultRef: string | null;
-    state: AdoptionState;
-}
-/** The persistence seam for #311's {@link Adoption} rows, beside {@link DeclaredOrgStore}. */
-export interface AdoptionStore {
-    /**
-     * Inserts the row, or replaces it in any state; the row is stored as
-     * `adopted`. A new snapshot after a restore or a release replaces the old one.
-     */
-    put(adoption: Omit<Adoption, 'state'>): Promise<void>;
-    get(orgId: OrgId, resourceKey: string): Promise<Adoption | null>;
-    /** Every row of an org, ordered by resource key. */
-    list(orgId: OrgId): Promise<Adoption[]>;
-    /** Moves a row to `state`. A no-op for a row that does not exist. */
-    setState(orgId: OrgId, resourceKey: string, state: AdoptionState): Promise<void>;
-    /**
-     * Replaces a row's `settings` and nothing else: its state, `takenAt` and
-     * `vaultRef` stay (#312). A no-op for a row that does not exist.
-     */
-    setSettings(orgId: OrgId, resourceKey: string, settings: Record<string, unknown>): Promise<void>;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",

package/dist/plan/adopt.d.ts

@@ -1,112 +0,0 @@
-import type { DeclaredOrg, HostingEntry } from '../org.js';
-import type { Adoption } from '../store.js';
-/**
- * Adoption (#311): foundry takes over a hand-made Coolify app or database
- * where it is. Nothing in this file holds an env value: an env var is named,
- * never quoted, in a detail line, an error or a blocked item (rule 6).
- */
-interface AdoptedBase {
-    /** The `foundry_adoptions.resource_key`, and the `coolify:adopt` step's key. */
-    resourceKey: string;
-    uuid: string;
-}
-/**
- * One app (with the entry that adopts it) or database an org declares by uuid,
- * or (#312) its Cloudflare tunnel (`uuid` is the tunnel id) or the Coolify app
- * that runs `cloudflared` for it.
- */
-export type AdoptedResource = (AdoptedBase & {
-    kind: 'database';
-}) | (AdoptedBase & {
-    kind: 'app';
-    entry: HostingEntry;
-}) | (AdoptedBase & {
-    kind: 'tunnel';
-}) | (AdoptedBase & {
-    kind: 'connector';
-});
-/** The `foundry_adoptions.resource_key` of the org's adopted tunnel: also its `serviceIds` key (#312). */
-export declare const adoptedTunnelKey: (org: DeclaredOrg) => string;
-/** The `foundry_adoptions.resource_key` of the org's adopted connector app (#312). */
-export declare const adoptedConnectorKey: (org: DeclaredOrg) => string;
-/** Every resource the org adopts, the database first, then the apps, the tunnel and its connector. */
-export declare function adoptedResources(org: DeclaredOrg): AdoptedResource[];
-/**
- * Every uuid the org declares as adopted, whether or not hosting is enabled
- * now: a uuid in this set is never stopped or deleted by foundry (#311).
- */
-export declare function declaredAdoptUuids(org: DeclaredOrg): Set<string>;
-/**
- * A snapshot is ACTIVE when its row is `adopted` or `confirmed` and the uuid
- * it recorded is the uuid the org declares now (#311). Only then may foundry
- * write to the live resource.
- */
-export declare function isActiveSnapshot(row: Adoption | null | undefined, uuid: string): boolean;
-/**
- * A row in `adopted`, `confirmed` or `restored` protects its key: foundry never
- * manages, stops or deletes that resource as its own. Only `released` lets go (#311).
- */
-export declare function protectsKey(row: Adoption | null | undefined): boolean;
-/** Where the secret part of a snapshot lives in the `AdoptionVault`. */
-export declare function adoptionVaultRef(org: DeclaredOrg, resource: AdoptedResource): string;
-export type LiveApp = Record<string, unknown>;
-export declare function snapshotAppSettings(live: LiveApp): Record<string, unknown>;
-export declare const bareName: (name: string) => string;
-export declare const liveNames: (live: LiveApp) => string[];
-/**
- * What an adopted entry changes on its live app: only a setting it declares
- * that differs from live. The entry cannot tell a declared `branch`,
- * `buildPack` or `autoDeploy` from its default, so those stay as they are; a
- * `null` folder or port and an empty name list declare nothing. Never
- * `custom_network_aliases`.
- */
-export declare function adoptedAppPatch(entry: HostingEntry, names: readonly string[], live: LiveApp): Record<string, unknown>;
-/** One line per setting the patch changes, old value beside new. */
-export declare function adoptedPatchDetails(patch: Record<string, unknown>, live: LiveApp): string[];
-/**
- * The PATCH body that puts an app's snapshot settings back. A field is sent
- * only when the entry's declaration would have changed it from the snapshot
- * (`adoptedAppPatch`), so a setting foundry never touched, or a person edited
- * later, stays. With no entry, a field is sent when `live` differs from the
- * snapshot. Coolify reads `fqdn` but takes `domains`. A field the snapshot had
- * as null is cleared the way the plain app path clears it: a folder back to
- * `/`, domains to the empty list. A port is never cleared, as on that path.
- */
-export declare function restoreAppPatch(entry: HostingEntry | undefined, names: readonly string[], settings: Record<string, unknown>, live: LiveApp): Record<string, unknown>;
-/** One route of a tunnel's ingress list. Other fields (`originRequest`, `path`) ride along untouched. */
-export interface IngressRoute {
-    hostname?: string;
-    service: string;
-    [field: string]: unknown;
-}
-/** A hostname as compared: lower case, no trailing dot (DNS names ignore both). */
-export declare const normalizeHostname: (hostname: string) => string;
-/**
- * What the merge leaves alone: every live route that is not for a declared
- * name and not foundry's own route for a name it dropped. Whatever its shape:
- * a hostname, only a `path`, or neither.
- */
-export declare function foreignRoutes(live: readonly IngressRoute[], declared: readonly string[], service: string, written: ReadonlySet<string>): IngressRoute[];
-/** The declared names whose live routes the merge replaces: there are some, and they are not already foundry's one route. */
-export declare function replacedNames(live: readonly IngressRoute[], declared: readonly string[], service: string): string[];
-/** The names foundry removes from `live`: written, no longer declared, still its own route. */
-export declare const removedNames: (live: readonly IngressRoute[], declared: readonly string[], service: string, written: ReadonlySet<string>) => string[];
-/**
- * The ingress list an adopted tunnel gets (#312): the declared exact names,
- * then every foreign live route in its live order and unchanged, with the
- * snapshot's routes for a name foundry dropped put back among them, then the
- * declared wildcards, then the live catch-all as it is. Only a live list that
- * does not end in a catch-all gets `http_status:404`.
- */
-export declare function mergeIngress(live: readonly IngressRoute[], declared: readonly string[], service: string, written: ReadonlySet<string>, snapshot: readonly IngressRoute[]): IngressRoute[];
-/**
- * The ingress list restore writes (#312): the live list without foundry's own
- * route for a name it wrote (`written` accumulates for the life of the
- * snapshot), plus the snapshot's routes for that name. A name with no live
- * route that is exactly foundry's is left alone, as is a route a person added
- * or edited, and the live catch-all. The `http_status:404` foundry appended is
- * removed only while it is still last and the snapshot had no catch-all; an
- * empty snapshot keeps the live catch-all, or gets one.
- */
-export declare function restoreIngress(live: readonly IngressRoute[], snapshot: readonly IngressRoute[], service: string, written: ReadonlySet<string>): IngressRoute[];
-export {};