@wtfalch/foundry 0.16.15 → 0.17.0

package/dist/plan/live.d.ts

@@ -48,6 +48,11 @@ export interface ZitadelReader {
 }
 export interface CoolifyReader {
     listResources(orgId: OrgId): Promise<LiveResource[]>;
+    /**
+     * Reads one Coolify project by its uuid, for an org that records none yet
+     * (adopt, archon#271). Optional: without it nothing can be adopted.
+     */
+    listProject?(projectUuid: string): Promise<LiveResource[]>;
 }
 export interface CloudflareReader {
     listResources(orgId: OrgId): Promise<LiveResource[]>;

package/dist/plan/login-host.d.ts

@@ -66,7 +66,7 @@ export interface LoginHostBindingsPort {
  * on the next run.
  */
 export declare const LOGIN_BINDING_SCOPE_KEY = "login_host_binding";
-/** The org's recorded app client ids (hosted app, each entry's own, cms, agora), sorted. */
+/** The org's recorded app client ids (hosted app, each entry's own, cms, agora, boule), deduplicated and sorted. */
 export declare function loginHostClientIds(recorded: Readonly<Record<string, string>>): string[];
 /** The host plus its sorted client ids, as recorded under {@link LOGIN_BINDING_SCOPE_KEY}. */
 export declare function loginBindingState(host: string, clientIds: readonly string[]): string;

package/dist/plan/login-host.js

@@ -1,4 +1,5 @@
 import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, } from './agora.js';
+import { BOULE_CLIENT_ID_SCOPE_KEY } from './boule.js';
 /**
  * #267: what both the planner (`diff.ts`) and the executor (`executor.ts`)
  * need to agree on for an org's own company login host -- the hostname and
@@ -36,18 +37,18 @@ export function loginHostnameFor(org) {
  * on the next run.
  */
 export const LOGIN_BINDING_SCOPE_KEY = 'login_host_binding';
-/** The org's recorded app client ids (hosted app, each entry's own, cms, agora), sorted. */
+/** The org's recorded app client ids (hosted app, each entry's own, cms, agora, boule), deduplicated and sorted. */
 export function loginHostClientIds(recorded) {
-    return [
+    const ids = [
         recorded[APP_CLIENT_ID_SCOPE_KEY],
         recorded[CMS_CLIENT_ID_SCOPE_KEY],
         recorded[AGORA_CLIENT_ID_SCOPE_KEY],
+        recorded[BOULE_CLIENT_ID_SCOPE_KEY],
         ...Object.entries(recorded)
             .filter(([key]) => key.startsWith(ENTRY_CLIENT_ID_SCOPE_PREFIX))
             .map(([, id]) => id),
-    ]
-        .filter((id) => Boolean(id))
-        .sort();
+    ].filter((id) => Boolean(id));
+    return [...new Set(ids)].sort();
 }
 /** The host plus its sorted client ids, as recorded under {@link LOGIN_BINDING_SCOPE_KEY}. */
 export function loginBindingState(host, clientIds) {

package/dist/plan/plan-apply.d.ts

@@ -1,9 +1,11 @@
-import type { PlanApply } from '../apply.js';
+import type { DestroyProgress, PlanApply } from '../apply.js';
 import type { DeclaredOrg, OrgId } from '../org.js';
 import type { Plan, PlanStep } from '../plan.js';
 import type { DeclaredPlatform } from '../platform.js';
+import type { JobRunner } from '../runner/types.js';
 import type { AppliedState } from '../state.js';
-import type { AppliedVersionsStore, DeclaredOrgStore, PlatformStore } from '../store.js';
+import { type AppliedVersionsStore, type DeclaredOrgStore, type PlatformStore } from '../store.js';
+import { type AdoptCandidate, type AdoptInput, type AdoptPlan } from './adopt.js';
 import { type AgoraHostPort } from './agora.js';
 import { type StepAction } from './diff.js';
 import { type LiveReaders, type LiveResource, type PlatformLiveReaders } from './live.js';
@@ -50,6 +52,16 @@ export interface AuditLog {
         target?: 'platform';
         at: Date;
     }): Promise<void>;
+    /** `FoundryPlanApply.adopt` and `release` (archon#271): no `Plan` is applied, so this is its own entry. `entryKey` names the hosting entry. */
+    recordAdoption(entry: {
+        actor: AuditActor;
+        orgId: OrgId;
+        action: 'adopt' | 'release';
+        entryKey: string;
+        outcome: 'adopted' | 'released' | 'refused';
+        reason?: string;
+        at: Date;
+    }): Promise<void>;
     /** `FoundryPlanApply.destroy`'s own record -- no `Plan` involved, so this is its own entry shape rather than a reuse of `recordApply`'s. */
     recordDestroy(entry: {
         actor: AuditActor;
@@ -210,6 +222,12 @@ export interface PlatformStepExecutor {
         /** #257 fix round 4: see `PlanPlatformOptions.drifted.backupStorageBlocked` (`platform-diff.ts`). */
         backupStorageBlocked?: string;
     }>;
+    /**
+     * Gives the platform files runner a changed share-domain set and touches
+     * nothing else. Returns the scope ids to record (only the share-domains
+     * one), or `null` when nothing changed.
+     */
+    refreshFilesShare?(platform: DeclaredPlatform, recordedIds: Readonly<Record<string, string>>): Promise<Record<string, string> | null>;
     execute(action: StepAction, context: PlatformStepExecutionContext): Promise<{
         resourceId?: string;
     } | undefined>;
@@ -243,6 +261,13 @@ export interface StepDestroyer {
         readonly recordedIds: Readonly<Record<string, string>>;
     }): Promise<void>;
 }
+/** #441: another apply, destroy, adopt or release holds the lease for this company or the platform. Nothing ran; try again when it finishes. */
+export declare class MutationInProgressError extends Error {
+    readonly scope: string;
+    readonly heldUntil: Date;
+    /** @param heldUntil when the holder's lease runs out if it is never released. */
+    constructor(scope: string, heldUntil: Date);
+}
 export declare class DeclaredOrgNotFoundError extends Error {
     constructor(orgId: OrgId);
 }
@@ -317,6 +342,27 @@ export interface FoundryPlanApplyOptions {
     aiOrganisation?: boolean;
     /** Overridable for tests; defaults to `() => new Date()`. */
     now?: () => Date;
+    /** #441: how long a mutation lease lasts before another caller may take it over. Defaults to 30 minutes. */
+    leaseTtlMs?: number;
+    /**
+     * #441 (part b): a durable, DB-row-backed record of `apply`, `destroy`,
+     * `adopt` and `release` for one org, held under the same mutation lease
+     * above rather than instead of it -- the lease is what actually keeps two
+     * holders from running `fn` at once (`withRunnerSerialization`'s own doc
+     * comment explains why the runner cannot safely take that job on its
+     * own). Optional, and a no-op without it -- every existing caller of this
+     * constructor is unaffected, and the lease alone still serializes every
+     * mutation the way it already did (#441, part a).
+     *
+     * What it adds: a row that never expires on a timer the way the lease
+     * does, so a crashed holder leaves something a host can see and query
+     * (`JobRunner.currentRun`/`getRun`) rather than nothing but a scope that
+     * quietly frees itself. Resuming after a crash reuses that row's id
+     * rather than starting a fresh one. Pass the same host-supplied
+     * `JobRunner` (`createJobRunner`, migrated with `runner/schema.ts`) that a
+     * host may also poll directly for progress.
+     */
+    runner?: JobRunner;
     /**
      * #253: appends a history row every time `runSteps` records a new
      * version as applied, beside the single-snapshot `store.putAppliedState`
@@ -373,11 +419,62 @@ export declare class FoundryPlanApply implements PlanApply {
     private readonly hostFiles;
     private readonly hostAi;
     private readonly now;
+    private readonly leaseTtlMs;
     private readonly appliedVersions;
     private readonly platformDeps;
+    private readonly runner;
     constructor(options: FoundryPlanApplyOptions);
     plan(id: OrgId): Promise<Plan>;
+    /**
+     * Archon#271: what adopting a live app and database into entry
+     * `input.entryKey` would do. A read, like {@link plan}: it reads the project
+     * through the reader and changes nothing. A mismatch is reported in the
+     * result, with no steps. Needs the apply permission, since it reads a
+     * project the caller names.
+     */
+    planAdopt(id: OrgId, input: AdoptInput): Promise<AdoptPlan>;
+    /**
+     * Archon#271: the live apps and databases in `projectUuid` this org has not
+     * recorded, for Changes' "Live, not theirs". A read, but it needs the apply
+     * permission: it reads a project the caller names.
+     */
+    adoptCandidates(id: OrgId, entryKey: string, projectUuid?: string): Promise<AdoptCandidate[]>;
+    /**
+     * Archon#271: records an app and database that already run in Coolify as
+     * entry `input.entryKey`'s resources, so the next plan finds them and plans
+     * no create. Verifies first and refuses on a mismatch or an entry that is
+     * already applied or held by another org. Same permission as {@link apply}.
+     * It never calls an executor: nothing in Coolify changes. Nothing redeploys
+     * here, but the next normal plan may propose updates to the adopted app
+     * that do (see `adopt.ts`); show that plan before applying it. Two
+     * concurrent adopts of one resource are not locked against each other.
+     */
+    adopt(id: OrgId, input: AdoptInput): Promise<AppliedState>;
+    /**
+     * Archon#271: the undo of {@link adopt}. Drops the entry's recorded Coolify
+     * ids and its `adopted.<entryKey>` snapshot (and `coolify_project` when
+     * adopt recorded it and no other Coolify id remains). It leaves the
+     * declaration alone: the entry goes back to declared and not applied, so the
+     * next plan creates it, exactly as before adopt. The host then adopts it
+     * again or removes the entry from the declaration. Deletes and stops nothing
+     * in Coolify. Only an adopted entry can be released. Same permission as
+     * {@link apply}. Every path writes an audit row.
+     */
+    release(id: OrgId, entryKey: string): Promise<AppliedState>;
+    private computeAdopt;
     apply(plan: Plan, confirmedOrgName: string): Promise<AppliedState>;
+    /**
+     * After an org apply: gives the platform files runner a changed share-domain
+     * set (its Coolify `domains` and `FILES_PUBLIC_HOSTS`, derived from the
+     * declared orgs) without a platform pass. Touches only the share hosts and
+     * redeploys the runner; the platform files step itself never runs here.
+     * Skips quietly for an actor who may not apply the platform, and when the
+     * platform files step was never applied. It holds the platform lease for
+     * the refresh and fences its write with it; while another platform change
+     * holds the lease it skips (this class has no log), and the next platform
+     * apply does the refresh. Only the share-domains key is recorded. A failure is rethrown naming that the org part succeeded.
+     */
+    private refreshPlatformFilesShare;
     /**
      * #167: {@link plan}, for the shared platform (#166) rather than an org --
      * there is no id to pass, since `DeclaredPlatform` is one singleton record.
@@ -404,7 +501,60 @@ export declare class FoundryPlanApply implements PlanApply {
      * declared org in place with whatever remains recorded in its applied
      * state, so a retried `destroy` only tears down what's left.
      */
-    destroy(id: OrgId, confirmedOrgName: string): Promise<void>;
+    destroy(id: OrgId, confirmedOrgName: string, options?: {
+        onProgress?: (event: DestroyProgress) => void;
+    }): Promise<void>;
+    /** The steps `destroy` runs for `id`, in order. Refuses a non-test org like `destroy` does; writes no audit row since it changes nothing. */
+    planDestroy(id: OrgId): Promise<{
+        steps: string[];
+        kept: string[];
+    }>;
+    /**
+     * #441 (part b): records `fn`'s run in the durable runner, when one is
+     * configured, and calls it. Must run with the mutation lease already
+     * held -- every one of this method's four callers (`apply`, `destroy`,
+     * `adopt`, `release`) calls it from inside its own `withMutationLease`
+     * callback, never around it. The reason is `JobRunner.runSteps` itself:
+     * it checkpoints a run's one step (the literal id `'mutate'`, the same
+     * for all four callers so they share one row per org) by a plain read of
+     * the row followed by a later blind write, with nothing to stop two
+     * concurrent calls for the same `runId` from both reading "not yet
+     * checkpointed" and both calling `fn` -- the runner sequences and
+     * checkpoints (its own doc comment), it does not itself exclude a second
+     * caller the way the lease's atomic acquire does. Holding the lease first
+     * is what makes it safe to reuse an existing, not-yet-succeeded run
+     * ({@link JobRunner.currentRun}) rather than refuse it outright: by the
+     * time this method runs, this caller is already the lease's sole holder,
+     * so any row `currentRun` finds can only be a previous, now-abandoned
+     * attempt (the lease's own atomic acquire already refused a second live
+     * caller before either of them got here) -- reusing it is the resume #9
+     * calls "a human decides when to call it again", not a race.
+     *
+     * Two *first* attempts for the same org can still race the insert itself
+     * when neither has an existing row yet -- `JobRunner.enqueueApply`'s own
+     * unique constraint decides it at the database level, a real race rather
+     * than one decided by this process's await order, and the loser's
+     * {@link AlreadyRunningError} is refused and audited through `refuse`,
+     * the same as a lost lease. In practice this needs two lease holders at
+     * once to reach it, which the lease itself already prevents; it is this
+     * method's defence against a bug in the lease's own acquire path, not
+     * the primary lock.
+     *
+     * `fn`'s result is threaded out through a closure, since
+     * {@link RunnerStep.run} returns nothing.
+     */
+    private withRunnerSerialization;
+    /**
+     * #441: runs `fn` while holding the one mutation lease for `scope`, so two
+     * `FoundryPlanApply` instances on one store never run provider steps for the
+     * same company or platform at once. A second caller is refused with
+     * {@link MutationInProgressError}; `fn` gets the lease as the fence its
+     * store writes carry, so a worker that lost the lease cannot overwrite the
+     * newer holder's state. Both refusals are audited through `refuse`.
+     */
+    private withMutationLease;
+    /** #441: before each provider step, extends the lease; a holder that lost it stops here, before the step runs. */
+    private renewLease;
     private refuse;
     private refusePlatform;
     private refuseDestroy;