@wtfalch/foundry 0.63.0 → 0.65.0

package/dist/apps/index.d.ts

@@ -7,3 +7,4 @@ export { type ApplyWorkerAppMigrationsDeps, type ApplyWorkerAppMigrationsInput,
 export { type ReleaseAsset, ReleaseAssetError, fetchReleaseAsset, parseAppRepo, releaseAssetOf, } from './github.js';
 export { type WorkerAppMigrationRunner, migrationsUrl } from '../worker-app-migrations.js';
 export { APPS_CLOUDFLARE_TOKEN_PERMISSIONS, type AppsCloudflare, type HyperdriveConnection, } from './cloudflare.js';
+export { type ServerEntryContext, ServerEntryError, processUrlEnvName, serverEntriesOf, } from './server-entry.js';

package/dist/apps/index.js

@@ -7,3 +7,4 @@ export { RELEASE_MIGRATION_SOURCE, applyWorkerAppMigrations, migrationChecksum,
 export { ReleaseAssetError, fetchReleaseAsset, parseAppRepo, releaseAssetOf, } from './github.js';
 export { migrationsUrl } from '../worker-app-migrations.js';
 export { APPS_CLOUDFLARE_TOKEN_PERMISSIONS, } from './cloudflare.js';
+export { ServerEntryError, processUrlEnvName, serverEntriesOf, } from './server-entry.js';

package/dist/apps/server-entry.d.ts

@@ -0,0 +1,43 @@
+import { type ServerBuildJson } from '../build-json.js';
+import { type AppManifest, type AppModules } from '../modules/index.js';
+import { type EnvValue, type HostingEntry } from '../org.js';
+/** Thrown by {@link serverEntriesOf}. The message is plain words for the company and never carries a secret. */
+export declare class ServerEntryError extends Error {
+    constructor(message: string);
+}
+/** What {@link serverEntriesOf} needs to know about the company and where the app runs. */
+export interface ServerEntryContext {
+    /** The company's slug: an entry reaches another on the company network as `<slug>-<entry key>` (`<slug>` for `app`). */
+    slug: string;
+    /** The platform registry host (`registry.<platform domain>`), with a port when it has one. */
+    registryHost: string;
+    /** The app's repository, `<github owner>/<repo>`. The images must sit at `<registryHost>/<owner>/<repo>[-<process>]`, lowercased. */
+    repo: string;
+    /** The entry key of the app. Default `app`. A process entry is keyed `<appKey>-<process key>`. */
+    appKey?: string;
+    /** The names the app entry is served at (see `HostingEntry.hostnames`). Processes are internal. */
+    hostnames: string[];
+    /** The port the app listens on. */
+    port: number;
+    healthPath?: string | null;
+    /** The app copy's own public origin (`https://host`), which each process gets as `APP_URL` to call the app back. */
+    appUrl: string;
+    /** The manifest `values` as env, resolved by the caller. Every entry gets the same map. */
+    env?: Record<string, EnvValue>;
+    /** The modules with the company's answers applied (`checkManifestAnswers`). Default: the manifest's own. */
+    modules?: AppModules;
+}
+/** `PROCESS_<KEY>_URL`: the key uppercased, `-` as `_`. */
+export declare const processUrlEnvName: (key: string) => string;
+/**
+ * The hosting entries of one server app: the `app` entry and one internal entry per declared process, each
+ * running its image from `build`. Throws {@link ServerEntryError} in plain words when the build does not match
+ * the manifest, when an image is not at the app's own registry path (a company never points at another's
+ * image), or when a module refuses the entry.
+ *
+ * - The app entry is served at `ctx.hostnames`, gets the modules, `ctx.env`, and `PROCESS_<KEY>_URL` for each
+ *   process that has a port (`http://<slug>-<entry key>:<port>`).
+ * - A process entry has no hostnames. It gets the same modules and `ctx.env`, and `APP_URL`. Its `database`
+ *   stays false: foundry allows one database entry per company, so a process cannot hold a second one.
+ */
+export declare function serverEntriesOf(manifest: AppManifest, build: ServerBuildJson, ctx: ServerEntryContext): HostingEntry[];

package/dist/apps/server-entry.js

@@ -0,0 +1,99 @@
+import { checkServerBuild } from '../build-json.js';
+import { applyModules } from '../modules/index.js';
+import { APP_ENTRY_KEY, ENTRY_IMAGE_REPOSITORY } from '../org.js';
+/** Thrown by {@link serverEntriesOf}. The message is plain words for the company and never carries a secret. */
+export class ServerEntryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ServerEntryError';
+    }
+}
+const HOST = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[0-9]{1,5})?$/;
+const SLUG = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+const OWNER_REPO = /^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\/[A-Za-z0-9._-]+$/;
+const ENTRY_KEY_MAX = 63;
+/** `PROCESS_<KEY>_URL`: the key uppercased, `-` as `_`. */
+export const processUrlEnvName = (key) => `PROCESS_${key.toUpperCase().replace(/-/g, '_')}_URL`;
+const refuse = (message) => {
+    throw new ServerEntryError(message);
+};
+/**
+ * The hosting entries of one server app: the `app` entry and one internal entry per declared process, each
+ * running its image from `build`. Throws {@link ServerEntryError} in plain words when the build does not match
+ * the manifest, when an image is not at the app's own registry path (a company never points at another's
+ * image), or when a module refuses the entry.
+ *
+ * - The app entry is served at `ctx.hostnames`, gets the modules, `ctx.env`, and `PROCESS_<KEY>_URL` for each
+ *   process that has a port (`http://<slug>-<entry key>:<port>`).
+ * - A process entry has no hostnames. It gets the same modules and `ctx.env`, and `APP_URL`. Its `database`
+ *   stays false: foundry allows one database entry per company, so a process cannot hold a second one.
+ */
+export function serverEntriesOf(manifest, build, ctx) {
+    if (manifest.runtime !== 'server')
+        refuse('This app does not run on a server.');
+    const processes = manifest.processes ?? [];
+    const problem = checkServerBuild(build, processes);
+    if (problem)
+        refuse(`The build does not match the app: ${problem}`);
+    const appKey = ctx.appKey ?? APP_ENTRY_KEY;
+    if (!SLUG.test(ctx.slug) || !HOST.test(ctx.registryHost) || !OWNER_REPO.test(ctx.repo)) {
+        refuse('The company name, registry or repository for this app is not written the way it must be.');
+    }
+    if (!/^https:\/\/[^/\s]+$/.test(ctx.appUrl)) {
+        refuse('The app address must be an https address with no path.');
+    }
+    const [owner = '', name = ''] = ctx.repo.split('/');
+    const base = `${ctx.registryHost}/${owner.toLowerCase()}/${name.toLowerCase()}`;
+    const imageFor = (processKey, suffix) => {
+        const image = build.images.find((i) => i.process === processKey);
+        if (!image)
+            return refuse(`The build has no image for "${processKey}".`);
+        // Exactly the app's own path: another owner's, another repo's or another host's image is never run.
+        if (image.repository !== `${base}${suffix}` || !ENTRY_IMAGE_REPOSITORY.test(image.repository)) {
+            return refuse(`The image for "${processKey}" is not at this app's own place in the registry, so it is not used.`);
+        }
+        return { repository: image.repository, digest: image.digest };
+    };
+    const internalName = (entryKey) => entryKey === APP_ENTRY_KEY ? ctx.slug : `${ctx.slug}-${entryKey}`;
+    const modules = ctx.modules ?? manifest.modules;
+    const make = (key, image, port, hostnames, env, healthPath) => {
+        if (key.length > ENTRY_KEY_MAX)
+            refuse(`The name "${key}" is too long.`);
+        const base = {
+            key,
+            // The app's source, as metadata: the image is what runs, and `uses.repo` makes its deploy key from this.
+            repo: ctx.repo,
+            folder: null,
+            branch: 'main',
+            buildPack: 'nixpacks',
+            port,
+            healthPath,
+            hostnames,
+            database: false,
+            autoDeploy: false,
+            gates: [],
+            env: { ...(ctx.env ?? {}), ...env },
+            ...(image ? { image } : {}),
+        };
+        return base;
+    };
+    const processEntryKey = (processKey) => `${appKey}-${processKey}`;
+    const processEnv = {};
+    for (const p of processes) {
+        if (p.port !== undefined) {
+            processEnv[processUrlEnvName(p.key)] =
+                `http://${internalName(processEntryKey(p.key))}:${p.port}`;
+        }
+    }
+    const draft = [
+        make(appKey, imageFor('app', ''), ctx.port, ctx.hostnames, processEnv, ctx.healthPath ?? null),
+        ...processes.map((p) => make(processEntryKey(p.key), imageFor(p.key, `-${p.key}`), p.port ?? null, [], { APP_URL: ctx.appUrl }, null)),
+    ];
+    return draft.map((entry, index) => {
+        const applied = applyModules(entry, modules, { runtime: 'server' });
+        if (!applied.ok)
+            return refuse(applied.message);
+        // One database entry per company: a process reaches the app's, never a second one.
+        return index === 0 ? applied.entry : { ...applied.entry, database: false };
+    });
+}

package/dist/build-json.d.ts

@@ -26,3 +26,28 @@ export declare class BuildJsonError extends Error {
 export declare const buildJsonSchema: z.ZodType<BuildJson>;
 /** Parses a build.json. Throws {@link BuildJsonError} for the first problem. */
 export declare function parseBuildJson(input: unknown): BuildJson;
+/** One image of a server app's build: `process` is `app` or the key of a declared helper process. */
+export interface ServerBuildImage {
+    process: string;
+    repository: string;
+    digest: `sha256:${string}`;
+}
+/** The `build.json` of a server app: the images its GitHub built, chosen by `runtime: 'server'`. */
+export interface ServerBuildJson {
+    runtime: 'server';
+    repo: string;
+    commit: string;
+    images: ServerBuildImage[];
+}
+export declare const serverBuildJsonSchema: z.ZodType<ServerBuildJson>;
+/** Parses a server build.json. Throws {@link BuildJsonError} for the first problem; never carries a value. */
+export declare function parseServerBuildJson(input: unknown): ServerBuildJson;
+/** Parses either shape: `runtime: 'server'` picks the server one, anything else the Worker one. */
+export declare function parseAnyBuildJson(input: unknown): BuildJson | ServerBuildJson;
+/**
+ * Null when the build holds exactly one `app` image and one image per declared process, no more.
+ * Else a plain message naming the process key, never an image value.
+ */
+export declare function checkServerBuild(build: ServerBuildJson, processes: readonly {
+    key: string;
+}[]): string | null;

package/dist/build-json.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { ENTRY_IMAGE_REPOSITORY } from './org.js';
 import { WORKER_APP_COMPATIBILITY_FLAGS, WORKER_APP_INSTANCE_TYPES, WORKER_APP_MAX_INSTANCES, } from './worker-app-config.js';
 /** Thrown by {@link parseBuildJson}. `path` is dotted into the build.json; the message never carries a value. */
 export class BuildJsonError extends Error {
@@ -93,3 +94,63 @@ export function parseBuildJson(input) {
         throw new BuildJsonError('missing_field', path);
     throw new BuildJsonError('wrong_type', path);
 }
+const IMAGE_REPOSITORY = ENTRY_IMAGE_REPOSITORY;
+export const serverBuildJsonSchema = z.strictObject({
+    runtime: z.literal('server'),
+    repo: text,
+    commit: text,
+    images: z.array(z.strictObject({
+        process: z.string().regex(/^[a-z][a-z0-9-]{0,30}$/, { message: 'wrong_type' }),
+        repository: z.string().regex(IMAGE_REPOSITORY, { message: 'wrong_type' }),
+        digest: z.string().regex(DIGEST, { message: 'wrong_type' }),
+    })),
+});
+function refuseBuildJson(input, error) {
+    const issue = error.issues[0];
+    if (!issue)
+        throw new BuildJsonError('wrong_type', '');
+    if (issue.code === 'unrecognized_keys') {
+        const base = dotted(issue.path);
+        const key = issue.keys[0] ?? '';
+        throw new BuildJsonError('unknown_field', base ? `${base}.${key}` : key);
+    }
+    const path = dotted(issue.path);
+    if (valueAt(input, issue.path) === undefined)
+        throw new BuildJsonError('missing_field', path);
+    throw new BuildJsonError('wrong_type', path);
+}
+/** Parses a server build.json. Throws {@link BuildJsonError} for the first problem; never carries a value. */
+export function parseServerBuildJson(input) {
+    const result = serverBuildJsonSchema.safeParse(input);
+    if (result.success)
+        return result.data;
+    return refuseBuildJson(input, result.error);
+}
+/** Parses either shape: `runtime: 'server'` picks the server one, anything else the Worker one. */
+export function parseAnyBuildJson(input) {
+    const runtime = input !== null && typeof input === 'object'
+        ? input.runtime
+        : undefined;
+    return runtime === 'server' ? parseServerBuildJson(input) : parseBuildJson(input);
+}
+/**
+ * Null when the build holds exactly one `app` image and one image per declared process, no more.
+ * Else a plain message naming the process key, never an image value.
+ */
+export function checkServerBuild(build, processes) {
+    const wanted = new Set(['app', ...processes.map((p) => p.key)]);
+    const seen = new Set();
+    for (const image of build.images) {
+        if (!wanted.has(image.process)) {
+            return `the build has an image for "${image.process}", which the app does not declare.`;
+        }
+        if (seen.has(image.process))
+            return `the build has two images for "${image.process}".`;
+        seen.add(image.process);
+    }
+    for (const key of wanted) {
+        if (!seen.has(key))
+            return `the build has no image for "${key}".`;
+    }
+    return null;
+}

package/dist/catalogue/copy-en.js

@@ -82,6 +82,16 @@ const INTEGRATION_COPY = {
         summary: 'Companies sign their own people in to the app.',
         ours: 'Run by us',
     },
+    'customer-grants': {
+        name: 'Permissions for customers',
+        summary: 'Your team gives each customer the permissions they need in the app, and we keep them in step.',
+        ours: 'Run by us',
+    },
+    repository: {
+        name: 'Repository',
+        summary: 'The app reads or updates the files in its repository, such as the pages it keeps there.',
+        ours: 'Run by us',
+    },
 };
 const SHARED_OUTPUTS = {
     app: { url: "The app's web address.", host: "The app's host name.", name: "The app's name." },

package/dist/catalogue/integrations.js

@@ -81,6 +81,16 @@ const EXTRA = {
         price: { class: 'free', meters: [] },
         advanced: [],
     },
+    'customer-grants': {
+        providers: [ours('customer-grants')],
+        price: { class: 'free', meters: [] },
+        advanced: [],
+    },
+    repository: {
+        providers: [ours('repository')],
+        price: { class: 'free', meters: [] },
+        advanced: [],
+    },
 };
 /** Every integration, one per app module, in the order modules are applied. */
 export function integrations() {

package/dist/index.d.ts

@@ -8,8 +8,8 @@ import { type PinnedVersions } from './bootstrap/versions.js';
 export type { PinnedVersions };
 export declare const PINNED_VERSIONS: Readonly<PinnedVersions>;
 export type { RequestableField, CallsChange, CustomersChange, StorageLimitChange, AiLimitChange, DomainChange, MailTierChange, RequestedChangeValue, ChangeClassification, RequestedChangeState, RequestedChange, AppChange, BuildChange, FailureCode, RequestedBy, } from './requested-changes.js';
-export type { BuildJson, BuildJsonErrorCode } from './build-json.js';
-export { buildJsonSchema, parseBuildJson, BuildJsonError } from './build-json.js';
+export type { BuildJson, BuildJsonErrorCode, ServerBuildImage, ServerBuildJson, } from './build-json.js';
+export { buildJsonSchema, parseBuildJson, BuildJsonError, serverBuildJsonSchema, parseServerBuildJson, parseAnyBuildJson, checkServerBuild, } from './build-json.js';
 export { REQUESTABLE_FIELDS, classifyChange, RequestedChangeError } from './requested-changes.js';
 export type { SlugRejectionReason, SlugRejection } from './slug.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';

package/dist/index.js

@@ -7,7 +7,7 @@ export { PLATFORM_SERVICE_KEYS, HEARTBEATS_PROVIDERS, defaultPlatformHostname, v
 // object, not a copy.
 import { VERSIONS } from './bootstrap/versions.js';
 export const PINNED_VERSIONS = VERSIONS;
-export { buildJsonSchema, parseBuildJson, BuildJsonError } from './build-json.js';
+export { buildJsonSchema, parseBuildJson, BuildJsonError, serverBuildJsonSchema, parseServerBuildJson, parseAnyBuildJson, checkServerBuild, } from './build-json.js';
 export { REQUESTABLE_FIELDS, classifyChange, RequestedChangeError } from './requested-changes.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
 export { NATIVE_BUILD_REPO, NATIVE_BUILD_WORKFLOW_FILE, NATIVE_BUILD_WORKFLOW_REF, NATIVE_BUILD_DISPATCH_TIMEOUT_MS, NATIVE_BUILD_KEY_ENV, NATIVE_BUILD_KEY_BYTES, NativeBuildDispatchError, dispatchNativeBuild, } from './native-build.js';

package/dist/modules/customer-grants.d.ts

@@ -0,0 +1,3 @@
+import type { AppModule } from './types.js';
+/** `uses.customerGrants`: the company's team gives customers permissions in the app. */
+export declare const customerGrants: AppModule;

package/dist/modules/customer-grants.js

@@ -0,0 +1,28 @@
+import { problem, setUse } from './entry-parts.js';
+/** `uses.customerGrants`: the company's team gives customers permissions in the app. */
+export const customerGrants = {
+    view: {
+        id: 'customer-grants',
+        name: 'Permissions for customers',
+        line: 'Your team gives each customer the permissions they need in the app, and we keep them in step.',
+        category: 'People',
+        icon: 'shield',
+        runtimes: ['server'],
+        requires: ['sign-in'],
+        availability: 'ready',
+        fields: [],
+        adds: [
+            {
+                name: 'Permissions your team manages',
+                hint: 'Your team gives and takes back customer permissions without changing the app.',
+            },
+        ],
+    },
+    toEntry: (entry, values) => setUse(entry, 'customerGrants', values === null ? undefined : true),
+    fromEntry: (entry) => (entry.uses?.customerGrants === true ? {} : null),
+    check(_values, modules) {
+        if (modules['sign-in']?.users === 'customers')
+            return null;
+        return problem(null, 'Permissions for customers are for an app whose customers sign in. Set Sign-in to "Your customers".');
+    },
+};

package/dist/modules/index.js

@@ -2,6 +2,7 @@ import { SECRET_LIKE_NAME, WORKER_APP_ENV_NAME, WORKER_APP_RESERVED_NAMES, } fro
 import { ai } from './ai.js';
 import { assistants } from './assistants.js';
 import { audit } from './audit.js';
+import { customerGrants } from './customer-grants.js';
 import { database } from './database.js';
 import { email } from './email.js';
 import { clone, isProblem } from './entry-parts.js';
@@ -9,6 +10,7 @@ import { files } from './files.js';
 import { jobs } from './jobs.js';
 import { organisations } from './organisations.js';
 import { SECRET_OUTPUTS, referenceProblem } from './outputs.js';
+import { repository } from './repository.js';
 import { signIn } from './sign-in.js';
 import { signedRecords } from './signed-records.js';
 import { workspaces } from './workspaces.js';
@@ -29,6 +31,8 @@ export const MODULES = [
     ai,
     organisations,
     audit,
+    customerGrants,
+    repository,
 ];
 const byId = new Map(MODULES.map((module) => [module.view.id, module]));
 /** The views of every module, JSON-safe, for Boule to render. */
@@ -340,7 +344,7 @@ function manifestV1AsV2(v1) {
     }
     return { v: 2, runtime: v1.runtime, modules: v1.modules, values };
 }
-const MANIFEST_V2_KEYS = ['v', 'runtime', 'modules', 'values', 'access'];
+const MANIFEST_V2_KEYS = ['v', 'runtime', 'modules', 'values', 'access', 'processes'];
 const VALUE_KEYS = {
     generate: ['source', 'kind'],
     reference: ['source', 'to', 'secret'],
@@ -368,11 +372,21 @@ const COPY_KEY = /^[a-z][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)+$/;
 const REFERENCE = /^[a-z][a-z0-9-]*\.[A-Za-z][A-Za-z0-9-]*$/;
 const HOST = /^(\*\.)?([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
 const HOST_MAX = 20;
+const PROCESS_MAX = 4;
+const PROCESS_KEY = /^[a-z][a-z0-9-]{0,30}$/;
 const WHY_MAX = 200;
 const CHOICES_MAX = 50;
 const ASKABLE_KINDS = ['text', 'longtext', 'path', 'choice', 'list'];
 const isText = (value, max) => typeof value === 'string' && value.trim() !== '' && value.length <= max;
 /** A plain sentence when `copy` is not a good label, help or copy key, else null. */
+function isProcessFolder(folder) {
+    return (typeof folder === 'string' &&
+        folder.length > 0 &&
+        folder.length <= 200 &&
+        !folder.startsWith('/') &&
+        !folder.startsWith('\\') &&
+        !folder.split(/[\\/]/).includes('..'));
+}
 function copyProblem(name, raw, labelRequired) {
     const { label, help, labelKey, helpKey } = raw;
     if (labelRequired
@@ -670,9 +684,43 @@ function parseManifestV2(json) {
         }
         hosts.push({ host, why });
     }
+    const processes = [];
+    if (json.processes !== undefined) {
+        if (runtime !== 'server') {
+            return refuse('"processes" is only for an app that runs on a server, not a Worker app.');
+        }
+        const raw = json.processes;
+        if (!Array.isArray(raw) || raw.length > PROCESS_MAX) {
+            return refuse(`"processes" must list at most ${PROCESS_MAX} helper processes.`);
+        }
+        const keys = new Set();
+        for (const item of raw) {
+            if (!isRecord(item) ||
+                Object.keys(item).some((k) => k !== 'key' && k !== 'folder' && k !== 'port')) {
+                return refuse('every helper process needs a "key" and a "folder", and may have a "port".');
+            }
+            const { key, folder, port } = item;
+            if (typeof key !== 'string' || !PROCESS_KEY.test(key) || key === 'app') {
+                return refuse('every helper process "key" must be 1 to 31 lowercase letters, digits or dashes, start with a letter, and not be "app".');
+            }
+            if (keys.has(key))
+                return refuse(`"processes" lists the key "${key}" twice.`);
+            keys.add(key);
+            if (!isProcessFolder(folder)) {
+                return refuse(`the "folder" of helper process "${key}" must be a path inside the repository, without "..", and not start with "/" or "\\".`);
+            }
+            if (port !== undefined &&
+                !(Number.isInteger(port) && port >= 1 && port <= 65535)) {
+                return refuse(`the "port" of helper process "${key}" must be a whole number from 1 to 65535.`);
+            }
+            processes.push(port === undefined ? { key, folder } : { key, folder, port: port });
+        }
+    }
     const manifest = { v: 2, runtime, modules: clone(modules), values };
     if (json.access !== undefined)
         manifest.access = { hosts };
+    if (json.processes !== undefined)
+        manifest.processes = processes;
     return { ok: true, manifest };
 }
 /** `company-app.json` (v1 or v2) read and checked: what the app's code asks for. */

package/dist/modules/repository.d.ts

@@ -0,0 +1,6 @@
+import type { AppModule } from './types.js';
+/**
+ * `uses.repo`: the app gets a key for its own repository. The entry's `repo` names the repository (it comes
+ * from the install, not from this module); `access` says whether the app may only read or also push.
+ */
+export declare const repository: AppModule;

package/dist/modules/repository.js

@@ -0,0 +1,40 @@
+import { setUse } from './entry-parts.js';
+/**
+ * `uses.repo`: the app gets a key for its own repository. The entry's `repo` names the repository (it comes
+ * from the install, not from this module); `access` says whether the app may only read or also push.
+ */
+export const repository = {
+    view: {
+        id: 'repository',
+        name: 'Repository',
+        line: 'The app reads or updates the files in its repository, such as the pages it keeps there.',
+        category: 'Data',
+        icon: 'git-branch',
+        runtimes: ['server'],
+        requires: [],
+        availability: 'ready',
+        fields: [
+            {
+                key: 'access',
+                label: 'What the app may do',
+                kind: 'choice',
+                default: 'read',
+                choices: [
+                    { value: 'read', label: 'Read', help: 'The app reads the files.' },
+                    { value: 'write', label: 'Read and update', help: 'The app also saves changes.' },
+                ],
+            },
+        ],
+        adds: [
+            {
+                name: 'A key for the repository',
+                hint: 'Only this app holds it, and it opens only this repository.',
+            },
+        ],
+    },
+    toEntry: (entry, values) => setUse(entry, 'repo', values === null ? undefined : { access: values.access === 'write' ? 'write' : 'read' }),
+    fromEntry(entry) {
+        const used = entry.uses?.repo;
+        return used ? { access: used.access } : null;
+    },
+};

package/dist/modules/types.d.ts

@@ -181,6 +181,12 @@ export interface ManifestHost {
 export interface ManifestAccess {
     hosts: ManifestHost[];
 }
+/** A helper process of a server app: built from `<folder>/Dockerfile`, next to the app itself. */
+export interface ManifestProcess {
+    key: string;
+    folder: string;
+    port?: number;
+}
 /** `company-app.json` v2, and what every manifest (v1 too) is read as. */
 export interface AppManifest {
     v: 2;
@@ -189,6 +195,8 @@ export interface AppManifest {
     values: Record<string, ManifestValue>;
     /** Optional. Absent means the app may connect anywhere. */
     access?: ManifestAccess;
+    /** Optional, server apps only: at most 4 helper processes. */
+    processes?: ManifestProcess[];
 }
 /** An answer to an `ask`: text, or a list of texts for `multiple`. */
 export type ManifestAnswer = string | string[];

package/dist/org.d.ts

@@ -301,7 +301,7 @@ export type AccessRule = {
 /** The key of the entry that is today's one app: the Coolify app named `<slug>`. */
 export declare const APP_ENTRY_KEY = "app";
 /** Why a validator refused. `code` is stable and never reworded; `message` is for people. */
-export type OrgRefusalCode = 'hosting_tunnel_needs_hosting' | 'issuer_app_name_missing' | 'issuer_app_name_not_unique' | 'issuer_app_kind_unknown' | 'issuer_app_name_reserved_agora' | 'issuer_app_name_reserved_boule' | 'issuer_app_name_reserved_kosmos' | 'hosting_needs_entry' | 'hosting_main_count' | 'entry_key_not_unique' | 'ai_webhook_path_not_unique' | 'worker_route_not_unique' | 'database_not_unique' | 'access_hostname_not_unique' | 'access_hostname_invalid' | 'access_needs_hosting' | 'access_kind_unknown' | 'access_service_token_name_missing' | 'access_hostname_locked' | 'access_hostname_not_served' | 'gate_limit_invalid' | 'hosting_repo_invalid' | 'hosting_github_invalid' | 'gate_needs_domain' | 'gate_key_invalid' | 'gate_key_not_unique' | 'gate_needs_hostname' | 'gate_hostname_not_entry_hostname' | 'gate_hostname_held_twice' | 'gate_hostname_locked' | 'gate_limit_exceeded' | 'wildcard_needs_domain' | 'wildcard_held_twice' | 'hostnames_need_domain' | 'hostname_needed' | 'hostname_invalid' | 'hostname_not_unique' | 'hostname_locked' | 'hosted_name_invalid' | 'hosted_name_not_unique' | 'hosted_name_worker_app' | 'entry_workspace_invalid' | 'entry_workspace_unsupported' | 'entry_live_needs_workspace' | 'entry_live_commit_invalid' | 'gate_key_taken_by_workspace' | 'gate_key_taken_by_private_page' | 'private_page_invalid' | 'private_page_path_invalid' | 'private_page_duplicate' | 'private_page_limit' | 'private_page_needs_hosting' | 'private_page_roles_invalid' | 'private_page_people_invalid' | 'entry_key_invalid' | 'entry_key_reserved' | 'entry_repo_invalid' | 'entry_folder_invalid' | 'entry_branch_empty' | 'entry_build_pack_unknown' | 'entry_build_pack_unavailable' | 'entry_port_invalid' | 'entry_health_path_invalid' | 'entry_capabilities_invalid' | 'entry_database_needs_hosting' | 'blue_green_needs_hostname' | 'env_name_empty' | 'env_name_reserved' | 'env_source_platform_mail_key' | 'env_source_unknown' | 'env_shared_secret_name_invalid' | 'env_held_secret_name_mismatch' | 'env_held_secret_name_invalid' | 'env_looks_like_secret' | 'builtin_app_invalid' | 'blue_green_not_object' | 'blue_green_steps_length' | 'blue_green_steps_range' | 'blue_green_steps_order' | 'blue_green_steps_end' | 'blue_green_hold_invalid' | 'blue_green_advance_invalid' | 'blue_green_min_requests_invalid' | 'blue_green_error_margin_invalid' | 'blue_green_staff_first_invalid' | 'volumes_not_list' | 'volumes_too_many' | 'volume_name_invalid' | 'volume_name_logs' | 'volume_name_not_unique' | 'volume_mount_path_invalid' | 'volume_mount_path_too_long' | 'volume_mount_path_log_dir' | 'volume_mount_path_forbidden' | 'volume_mount_path_not_unique' | 'auth_needs_hosting' | 'auth_users_invalid' | 'auth_registration_invalid' | 'registration_open_needs_customers' | 'auth_replaces_broker_entry_invalid' | 'auth_replaces_broker_entry_owned' | 'auth_needs_exact_hostname' | 'mcp_needs_open_customers' | 'mcp_path_invalid' | 'mcp_onboarding_path_invalid' | 'auth_sign_in_invalid' | 'email_code_needs_customers' | 'auth_room_invalid' | 'auth_room_needs_customers' | 'auth_room_not_unique' | 'client_name_taken' | 'workspaces_needs_customers' | 'workspaces_needs_server' | 'workspaces_roles_invalid' | 'workspaces_role_reserved' | 'workspaces_invite_path_invalid' | 'workspaces_env_clash' | 'ai_needs_hosting' | 'ai_offerings_invalid' | 'ai_permissions_invalid' | 'ai_webhook_path_invalid' | 'ai_webhook_needs_exact_hostname' | 'ai_env_clash' | 'files_needs_hosting' | 'files_collections_invalid' | 'files_permissions_invalid' | 'files_share_host_invalid' | 'files_share_host_needs_domain' | 'files_env_clash' | 'worker_needs_hosting' | 'worker_needs_repo' | 'worker_needs_own_repo' | 'worker_key_too_long' | 'worker_artifact_invalid' | 'worker_route_invalid' | 'worker_route_off_domain' | 'worker_rate_limit_name_missing' | 'worker_rate_limit_namespace_missing' | 'worker_rate_limit_invalid' | 'worker_rate_limit_period_invalid' | 'worker_app_invalid' | 'edge_not_true' | 'edge_needs_hosting' | 'edge_needs_domain' | 'edge_env_clash' | 'mail_not_true' | 'mail_needs_hosting' | 'mail_env_clash' | 'jobs_not_true' | 'jobs_needs_hosting' | 'jobs_env_clash' | 'customer_grants_not_true' | 'customer_grants_needs_customers' | 'customer_grants_env_clash' | 'repo_use_invalid' | 'repo_use_needs_repo' | 'repo_use_env_clash' | 'audit_not_true' | 'audit_needs_hosting' | 'audit_needs_worker_database' | 'customers_invalid' | 'customers_sign_up_needs_enabled' | 'registration_open_needs_sign_up';
+export type OrgRefusalCode = 'hosting_tunnel_needs_hosting' | 'issuer_app_name_missing' | 'issuer_app_name_not_unique' | 'issuer_app_kind_unknown' | 'issuer_app_name_reserved_agora' | 'issuer_app_name_reserved_boule' | 'issuer_app_name_reserved_kosmos' | 'hosting_needs_entry' | 'hosting_main_count' | 'entry_key_not_unique' | 'entry_image_invalid' | 'ai_webhook_path_not_unique' | 'worker_route_not_unique' | 'database_not_unique' | 'access_hostname_not_unique' | 'access_hostname_invalid' | 'access_needs_hosting' | 'access_kind_unknown' | 'access_service_token_name_missing' | 'access_hostname_locked' | 'access_hostname_not_served' | 'gate_limit_invalid' | 'hosting_repo_invalid' | 'hosting_github_invalid' | 'gate_needs_domain' | 'gate_key_invalid' | 'gate_key_not_unique' | 'gate_needs_hostname' | 'gate_hostname_not_entry_hostname' | 'gate_hostname_held_twice' | 'gate_hostname_locked' | 'gate_limit_exceeded' | 'wildcard_needs_domain' | 'wildcard_held_twice' | 'hostnames_need_domain' | 'hostname_needed' | 'hostname_invalid' | 'hostname_not_unique' | 'hostname_locked' | 'hosted_name_invalid' | 'hosted_name_not_unique' | 'hosted_name_worker_app' | 'entry_workspace_invalid' | 'entry_workspace_unsupported' | 'entry_live_needs_workspace' | 'entry_live_commit_invalid' | 'gate_key_taken_by_workspace' | 'gate_key_taken_by_private_page' | 'private_page_invalid' | 'private_page_path_invalid' | 'private_page_duplicate' | 'private_page_limit' | 'private_page_needs_hosting' | 'private_page_roles_invalid' | 'private_page_people_invalid' | 'entry_key_invalid' | 'entry_key_reserved' | 'entry_repo_invalid' | 'entry_folder_invalid' | 'entry_branch_empty' | 'entry_build_pack_unknown' | 'entry_build_pack_unavailable' | 'entry_port_invalid' | 'entry_health_path_invalid' | 'entry_capabilities_invalid' | 'entry_database_needs_hosting' | 'blue_green_needs_hostname' | 'env_name_empty' | 'env_name_reserved' | 'env_source_platform_mail_key' | 'env_source_unknown' | 'env_shared_secret_name_invalid' | 'env_held_secret_name_mismatch' | 'env_held_secret_name_invalid' | 'env_looks_like_secret' | 'builtin_app_invalid' | 'blue_green_not_object' | 'blue_green_steps_length' | 'blue_green_steps_range' | 'blue_green_steps_order' | 'blue_green_steps_end' | 'blue_green_hold_invalid' | 'blue_green_advance_invalid' | 'blue_green_min_requests_invalid' | 'blue_green_error_margin_invalid' | 'blue_green_staff_first_invalid' | 'volumes_not_list' | 'volumes_too_many' | 'volume_name_invalid' | 'volume_name_logs' | 'volume_name_not_unique' | 'volume_mount_path_invalid' | 'volume_mount_path_too_long' | 'volume_mount_path_log_dir' | 'volume_mount_path_forbidden' | 'volume_mount_path_not_unique' | 'auth_needs_hosting' | 'auth_users_invalid' | 'auth_registration_invalid' | 'registration_open_needs_customers' | 'auth_replaces_broker_entry_invalid' | 'auth_replaces_broker_entry_owned' | 'auth_needs_exact_hostname' | 'mcp_needs_open_customers' | 'mcp_path_invalid' | 'mcp_onboarding_path_invalid' | 'auth_sign_in_invalid' | 'email_code_needs_customers' | 'auth_room_invalid' | 'auth_room_needs_customers' | 'auth_room_not_unique' | 'client_name_taken' | 'workspaces_needs_customers' | 'workspaces_needs_server' | 'workspaces_roles_invalid' | 'workspaces_role_reserved' | 'workspaces_invite_path_invalid' | 'workspaces_env_clash' | 'ai_needs_hosting' | 'ai_offerings_invalid' | 'ai_permissions_invalid' | 'ai_webhook_path_invalid' | 'ai_webhook_needs_exact_hostname' | 'ai_env_clash' | 'files_needs_hosting' | 'files_collections_invalid' | 'files_permissions_invalid' | 'files_share_host_invalid' | 'files_share_host_needs_domain' | 'files_env_clash' | 'worker_needs_hosting' | 'worker_needs_repo' | 'worker_needs_own_repo' | 'worker_key_too_long' | 'worker_artifact_invalid' | 'worker_route_invalid' | 'worker_route_off_domain' | 'worker_rate_limit_name_missing' | 'worker_rate_limit_namespace_missing' | 'worker_rate_limit_invalid' | 'worker_rate_limit_period_invalid' | 'worker_app_invalid' | 'edge_not_true' | 'edge_needs_hosting' | 'edge_needs_domain' | 'edge_env_clash' | 'mail_not_true' | 'mail_needs_hosting' | 'mail_env_clash' | 'jobs_not_true' | 'jobs_needs_hosting' | 'jobs_env_clash' | 'customer_grants_not_true' | 'customer_grants_needs_customers' | 'customer_grants_env_clash' | 'repo_use_invalid' | 'repo_use_needs_repo' | 'repo_use_env_clash' | 'audit_not_true' | 'audit_needs_hosting' | 'audit_needs_worker_database' | 'customers_invalid' | 'customers_sign_up_needs_enabled' | 'registration_open_needs_sign_up';
 /**
  * One refusal: a stable `code`, the dotted `path` into {@link DeclaredOrg} it is about
  * (`hosting.entries.terminal.uses.auth.registration`) and the sentence for people.
@@ -311,6 +311,19 @@ export interface OrgRefusal {
     path: string;
     message: string;
 }
+/**
+ * A built image a server entry runs instead of building from a repository: `repository` is
+ * `<host>[:port]/<owner>/<name>`, `digest` is `sha256:` and 64 lowercase hex digits. Same shapes as a server
+ * `build.json` (`build-json.ts`).
+ */
+export interface EntryImage {
+    repository: string;
+    digest: `sha256:${string}`;
+}
+/** The registry path of an {@link EntryImage}: `<host>[:port]/<owner>/<name>`, any host. */
+export declare const ENTRY_IMAGE_REPOSITORY: RegExp;
+/** The digest of an {@link EntryImage}. */
+export declare const ENTRY_IMAGE_DIGEST: RegExp;
 /**
  * One app the org runs. `database` and `gates` are meaningless without
  * `HostingConfig.enabled`, so `validateHosting` requires it before either is
@@ -334,6 +347,11 @@ export interface HostingEntry {
     buildPack: HostingBuildPack;
     /** The port the app listens on. `null` is Coolify's default. */
     port: number | null;
+    /**
+     * A built image the app runs, pulled as `repository@digest`, instead of a build from `repo`. Then `folder` is `null`, `branch` and `buildPack` stay at their defaults;
+     * `validateEntryImage` states the rest. A new digest redeploys the app.
+     */
+    image?: EntryImage;
     /**
      * The app's live address on the platform's apps domain: `<hostedName>.companyincluded.app`. A
      * label {@link hostedLabelRefusal} accepts; unique within the org (the host checks it across orgs).

package/dist/org.js

@@ -16,6 +16,10 @@ export const APP_ENTRY_KEY = 'app';
 function refusal(code, path, message) {
     return { code, path, message };
 }
+/** The registry path of an {@link EntryImage}: `<host>[:port]/<owner>/<name>`, any host. */
+export const ENTRY_IMAGE_REPOSITORY = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[0-9]{1,5})?\/[a-z0-9]([a-z0-9-]*[a-z0-9])?\/[a-z0-9][a-z0-9._-]*$/;
+/** The digest of an {@link EntryImage}. */
+export const ENTRY_IMAGE_DIGEST = /^sha256:[0-9a-f]{64}$/;
 export const MAX_PRIVATE_PAGES = 20;
 export const MAX_PRIVATE_PAGE_ROLES = 50;
 export const MAX_PRIVATE_PAGE_PEOPLE = 200;
@@ -211,6 +215,9 @@ export function refuseHosting(hosting, names) {
             return refusal('entry_key_not_unique', `hosting.entries.${entry.key}.key`, `hosting.entries key '${entry.key}' is not unique`);
         }
         seenKeys.add(entry.key);
+        const invalidImage = validateEntryImage(entry);
+        if (invalidImage)
+            return invalidImage;
         const invalid = validateHostingEntry(entry, hosting.enabled, reserveKeys, hosting.github);
         if (invalid)
             return invalid;
@@ -513,8 +520,8 @@ export function companyGithubFor(hosting, repo) {
     const github = hosting.github;
     return github && repo !== null && repoUnderAccount(repo, github.account) ? github : undefined;
 }
-// The env names `pushAppEnv` and `pushDatabaseUrl` set themselves.
-const FOUNDRY_ENV_NAME = /^(APP_URL|LOG_DIR|OWNER_USER_ID|AUTH_.*|DATABASE_URL.*)$/;
+// The env names `pushAppEnv` and `pushDatabaseUrl` set themselves. `APP_URL` is also set, but only on the main entry.
+const FOUNDRY_ENV_NAME = /^(LOG_DIR|OWNER_USER_ID|AUTH_.*|DATABASE_URL.*)$/;
 // Set only on the colors of a blueGreen entry; any other entry may declare them.
 const BLUE_GREEN_ENV_NAME = /^(REPORTING_(COLOR|RELEASE|HEALTH_TOKEN)|NEXT_SERVER_ACTIONS_ENCRYPTION_KEY)$/;
 const SECRET_ENV_NAME = /_(KEY|SECRET|TOKEN|PASSWORD)$/;
@@ -626,6 +633,39 @@ function validateEntryPrivatePages(entry, at, hostingEnabled) {
     }
     return null;
 }
+/** Why an entry's `image` is refused, or `null`. Read wherever hosting is read, so a stored entry is checked too. */
+function validateEntryImage(entry) {
+    const value = entry.image;
+    if (value === undefined)
+        return null;
+    const path = `hosting.entries.${entry.key}.image`;
+    const at = `hosting.entries '${entry.key}'`;
+    const invalid = (message) => refusal('entry_image_invalid', path, `${at} ${message}`);
+    const isObject = typeof value === 'object' && value !== null && !Array.isArray(value);
+    const { repository, digest } = (isObject ? value : {});
+    if (!isObject ||
+        Object.keys(value).some((k) => k !== 'repository' && k !== 'digest') ||
+        typeof repository !== 'string' ||
+        !ENTRY_IMAGE_REPOSITORY.test(repository) ||
+        repository.split('/').some((part) => /^\.+$/.test(part)) ||
+        typeof digest !== 'string' ||
+        !ENTRY_IMAGE_DIGEST.test(digest)) {
+        return invalid('image must be { repository, digest }: a registry path like registry.example.com/owner/name, and a digest of sha256: and 64 lowercase letters a-f or digits');
+    }
+    if (entry.folder !== null || entry.branch !== 'main' || entry.buildPack !== 'nixpacks') {
+        return invalid("runs a built image, so it cannot also build from a repository: remove the image, or set folder to null and keep the default branch and build pack (repo may stay, as the app's source)");
+    }
+    if (entry.worker !== undefined || entry.workerApp !== undefined) {
+        return invalid('runs a built image on a server, so it cannot also be a Worker or a Worker app');
+    }
+    if (entry.blueGreen !== undefined ||
+        entry.workspace !== undefined ||
+        entry.live === false ||
+        entry.liveCommit !== undefined) {
+        return invalid('runs a built image, which does not support a workspace, blue/green releases or a promote yet: remove them, or build from a repository');
+    }
+    return null;
+}
 function validateHostingEntry(entry, enabled, reserveKeys, github) {
     const at = `hosting.entries '${entry.key}'`;
     if (!ENTRY_KEY.test(entry.key)) {
@@ -689,7 +729,9 @@ function validateHostingEntry(entry, enabled, reserveKeys, github) {
         if (!name) {
             return refusal('env_name_empty', `hosting.entries.${entry.key}.env`, `${at} env needs a non-empty env var name`);
         }
-        if (FOUNDRY_ENV_NAME.test(name) || (entry.blueGreen && BLUE_GREEN_ENV_NAME.test(name))) {
+        if (FOUNDRY_ENV_NAME.test(name) ||
+            (name === 'APP_URL' && isMainEntry(entry)) ||
+            (entry.blueGreen && BLUE_GREEN_ENV_NAME.test(name))) {
             return refusal('env_name_reserved', `hosting.entries.${entry.key}.env.${name}`, `${at} env '${name}' is set by foundry and cannot be declared`);
         }
         if (typeof value !== 'string') {

package/dist/plan/diff.js

@@ -43,7 +43,7 @@ import { OWN_AUTH_BLOCKED_KEY, OWN_FILES_BLOCKED_KEY, OWN_FILES_R2_BLOCKED_KEY,
 import { ownDnsHostnames } from './own-dns.js';
 import { ownHostnames } from './own-hostnames.js';
 import { platformMailMxHost } from './platform-diff.js';
-import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, ORG_MAIL_APPLIED_MODE_SCOPE_KEY, ORG_MAIL_APPLIED_USES_DOMAIN_SCOPE_KEY, PLATFORM_AUTH_MCP_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, appEnvAppliedScopeKey, appFolderDiffers, appSecretAvailability, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, serviceDbEnvAppliedScopeKey, versionNotAppliedLine, zitadelAppIdTokenUserinfoAppliedScopeKey, } from './platform-diff.js';
+import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, ORG_MAIL_APPLIED_MODE_SCOPE_KEY, ORG_MAIL_APPLIED_USES_DOMAIN_SCOPE_KEY, PLATFORM_AUTH_MCP_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, appEnvAppliedScopeKey, appFolderDiffers, appImageAppliedScopeKey, appSecretAvailability, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, entryImageRef, resolveAppEnv, serviceDbEnvAppliedScopeKey, versionNotAppliedLine, zitadelAppIdTokenUserinfoAppliedScopeKey, } from './platform-diff.js';
 import { DEFAULT_ORG_PLATFORM_READINESS, } from './platform-org.js';
 import { PLATFORM_AUTH_BROKER_MAIL_KEY_REF } from './platform-providers.js';
 import { companyAppPostLogoutUris, postLogoutUpdateOwed, zitadelAppPostLogoutAppliedScopeKey, } from './post-logout-uris.js';
@@ -3566,7 +3566,7 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
     // #447: no shared default app any more. Migration 0029 wrote `repo: null`
     // for every org without a bespoke app and nothing rewrites that data, so
     // the entry stays declared but is blocked here and never provisioned.
-    const noRepo = entry !== undefined && entry.repo === null;
+    const noRepo = entry !== undefined && entry.repo === null && entry.image === undefined;
     if (noRepo) {
         blocked.push({
             description: `${org.slug}'s ${label} repo is blocked, not planned: there is no shared default app any more (#447)`,
@@ -3819,6 +3819,21 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
             blocked,
         };
     }
+    // A new image digest (or repository): the app is pointed at it and redeployed. The line names no secret.
+    if (entry.image &&
+        recordedIds[appImageAppliedScopeKey(entryKey)] !== entryImageRef(entry.image)) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `run ${org.slug}'s ${label} on image ${entry.image.repository} at ${entry.image.digest.slice(0, 19)} and redeploy the app`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked,
+        };
+    }
     // A changed `folder`, `port` or `autoDeploy` reaches an app that is already live.
     const want = appSettingsOf(entry);
     const have = appliedAppSettings(recordedIds, entryKey);

package/dist/plan/executor.d.ts

@@ -1765,7 +1765,7 @@ export interface FoundryStepExecutorPorts {
     /**
      * The stage copy (`copy_prod_to_stage`, run by the release tick). The host supplies the dump download and the
      * backup storage; foundry builds the restore port itself and reads production's address live from Coolify.
-     * Without it a copy request is refused with `no-copy-port`. The host needs `pg_restore` (Postgres 16) on PATH.
+     * Without it a copy request is refused with `no-copy-port`. The host needs `pg_restore` on PATH, of the production database's Postgres version or newer (platform-archon-db runs 18).
      */
     stageCopy?: StageCopyHostConfig;
     /**

package/dist/plan/executor.js

@@ -68,7 +68,7 @@ import { LIMITS, limited } from './own-limits.js';
 import { OWN_FILES_R2_SCOPE_KEY, OWN_FILES_R2_UNDELIVERED_SCOPE_KEY, OWN_SERVICES_APPLIED_SCOPE_KEY, OwnServicesBlockedError, orgNetwork, orgTarget, platformTarget, scopeFromOrg, } from './own-services.js';
 import { ownSfuUrls, provisionSfuApp } from './own-sfu.js';
 import { JOBS_INTERNAL_URL_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, } from './platform-diff.js';
-import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, ORG_MAIL_APPLIED_MODE_SCOPE_KEY, ORG_MAIL_APPLIED_USES_DOMAIN_SCOPE_KEY, appDomainsAppliedScopeKey, appEnvAppliedScopeKey, appFolderDiffers, appNameFor, appSettingsAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, orgDeclaresMcp, resolveAppEnv, serviceDbEnvAppliedScopeKey, zitadelAppIdTokenUserinfoAppliedScopeKey, } from './platform-diff.js';
+import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, ORG_MAIL_APPLIED_MODE_SCOPE_KEY, ORG_MAIL_APPLIED_USES_DOMAIN_SCOPE_KEY, appDomainsAppliedScopeKey, appEnvAppliedScopeKey, appFolderDiffers, appImageAppliedScopeKey, appNameFor, appSettingsAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, entryImageFields, entryImageRef, orgDeclaresMcp, resolveAppEnv, serviceDbEnvAppliedScopeKey, zitadelAppIdTokenUserinfoAppliedScopeKey, } from './platform-diff.js';
 import { AUTH_LOGIN_PORT, PLATFORM_AUTH_BROKER_MAIL_KEY_REF, PLATFORM_AUTH_LOGIN_INTERNAL_NAME, PLATFORM_AUTH_LOGIN_SCOPE_KEY, PLATFORM_AUTH_PROJECT, PLATFORM_MAIL_SERVER_SCOPE_KEY, defaultStalwartForInstance, filesDepsInvalid, filesShareDomains, provisionAuthStack, provisionDatabaseBackup, provisionFilesHost, provisionJobsHost, provisionMailServer, resolveOwnFilesKeys, } from './platform-providers.js';
 import { companyAppPostLogoutUris, postLogoutAppliedValue, postLogoutUrisFor, zitadelAppPostLogoutAppliedScopeKey, } from './post-logout-uris.js';
 import { CLOUDFLARE_TUNNEL_APPS_HOSTNAMES_SCOPE_KEY, CLOUDFLARE_TUNNEL_ENTRY_ROUTES_SCOPE_KEY, CLOUDFLARE_TUNNEL_OIKOS_HOSTNAMES_SCOPE_KEY, ENTRY_CONTAINER_LABELS, appLabelsAppliedScopeKey, builtinRoutes, entryAppsHostnames, entryLabelHash, entryLabelSpec, entryOikosHostnames, entryProxyLabels, entryRoutes, entryRoutesMarker, ownsAppsZoneName, ownsOikosName, routesWithoutToken, sameLabelSets, } from './proxy-labels.js';
@@ -3963,7 +3963,7 @@ export class FoundryStepExecutor {
             throw new Error(`coolify:app for ${org.slug}: no hosting entry for ${action.key}`);
         // `planApp` blocks a `repo: null` entry at plan time; reaching here with
         // one means a stale or hand-built plan.
-        if (entry.repo === null) {
+        if (entry.repo === null && entry.image === undefined) {
             throw new Error(`coolify:app for ${org.slug}: entry '${entry.key}' has no repo`);
         }
         const appRepo = entry.repo;
@@ -4052,35 +4052,55 @@ export class FoundryStepExecutor {
         }
         else {
             const server = await this.resolveServer(org, context);
-            const githubAppUuid = await this.githubAppUuidFor(org, appRepo, context.recordedIds());
-            if (isServerWorkspace(entry)) {
-                pinnedCommit =
-                    entry.liveCommit ?? (await this.workspaceCommit(org, entry, server.uuid, context));
+            if (entry.image) {
+                // A built image: pulled by digest, nothing to build. Coolify never deploys it by itself on create.
+                const created = await this.ports.coolify.createDockerImageApplication({
+                    project_uuid: projectUuid,
+                    server_uuid: server.uuid,
+                    environment_name: environment.name,
+                    environment_uuid: environment.uuid,
+                    ...entryImageFields(entry.image),
+                    // Coolify needs a port to create the app; a helper with none listens on none, so 80 is only its label.
+                    ports_exposes: String(entry.port ?? 80),
+                    name: appName,
+                    description: `${org.slug}'s ${entry.key} app, run from a built image`,
+                    instant_deploy: false,
+                });
+                appId = created.uuid;
+                have = appSettingsOf(entry);
+                haveDomains = wantDomains;
+            }
+            else {
+                const githubAppUuid = await this.githubAppUuidFor(org, appRepo, context.recordedIds());
+                if (isServerWorkspace(entry)) {
+                    pinnedCommit =
+                        entry.liveCommit ?? (await this.workspaceCommit(org, entry, server.uuid, context));
+                }
+                const created = await this.ports.coolify.createGithubAppApplication({
+                    is_preview_deployments_enabled: false,
+                    project_uuid: projectUuid,
+                    server_uuid: server.uuid,
+                    environment_name: environment.name,
+                    environment_uuid: environment.uuid,
+                    github_app_uuid: githubAppUuid,
+                    git_repository: appRepo,
+                    git_branch: entry.branch,
+                    build_pack: entry.buildPack,
+                    name: appName,
+                    autogenerate_domain: false,
+                    // A static site is served by Coolify's own web server on port 80.
+                    ports_exposes: isStatic ? '80' : entry.port === null ? undefined : String(entry.port),
+                    is_auto_deploy_enabled: appSettingsOf(entry).autoDeploy,
+                    // Also the folder a static entry serves: Coolify's static build
+                    // copies `base_directory`, and reads `publish_directory` only for a
+                    // built app.
+                    base_directory: entry.folder === null ? undefined : `/${entry.folder}`,
+                });
+                appId = created.uuid;
+                // Create sent every setting, so nothing is left to patch.
+                have = appSettingsOf(entry);
+                haveDomains = wantDomains;
             }
-            const created = await this.ports.coolify.createGithubAppApplication({
-                is_preview_deployments_enabled: false,
-                project_uuid: projectUuid,
-                server_uuid: server.uuid,
-                environment_name: environment.name,
-                environment_uuid: environment.uuid,
-                github_app_uuid: githubAppUuid,
-                git_repository: appRepo,
-                git_branch: entry.branch,
-                build_pack: entry.buildPack,
-                name: appName,
-                autogenerate_domain: false,
-                // A static site is served by Coolify's own web server on port 80.
-                ports_exposes: isStatic ? '80' : entry.port === null ? undefined : String(entry.port),
-                is_auto_deploy_enabled: appSettingsOf(entry).autoDeploy,
-                // Also the folder a static entry serves: Coolify's static build
-                // copies `base_directory`, and reads `publish_directory` only for a
-                // built app.
-                base_directory: entry.folder === null ? undefined : `/${entry.folder}`,
-            });
-            appId = created.uuid;
-            // Create sent every setting, so nothing is left to patch.
-            have = appSettingsOf(entry);
-            haveDomains = wantDomains;
         }
         // Patch what differs from what the app has. A crash before the marker is
         // recorded below leaves the old one, so the retry patches the same
@@ -4100,6 +4120,13 @@ export class FoundryStepExecutor {
             patch.is_preview_deployments_enabled = false;
         if (pinnedCommit)
             patch.git_commit_sha = pinnedCommit;
+        // A new image reference reaches a live app: the digest is patched and the app deploys below.
+        const imageRef = entry.image ? entryImageRef(entry.image) : null;
+        const imageChanged = entry.image !== undefined &&
+            existing !== null &&
+            context.recordedIds()[appImageAppliedScopeKey(entry.key)] !== imageRef;
+        if (entry.image && imageChanged)
+            Object.assign(patch, entryImageFields(entry.image));
         // #543: the health-check quartet too, every run -- the same reason
         // Archon's own doc comment gives (without one, Coolify's rolling update
         // has nothing to wait on and stops the old container immediately). The
@@ -4148,7 +4175,8 @@ export class FoundryStepExecutor {
         if (Object.keys(patch).length > 0)
             await this.ports.coolify.updateApplication(appId, patch);
         // The container builds and listens from these only at its next deploy.
-        const settingsNeedDeploy = Boolean(patch.base_directory ||
+        const settingsNeedDeploy = Boolean(imageChanged ||
+            patch.base_directory ||
             patch.ports_exposes ||
             patch.domains !== undefined ||
             patch.custom_internal_name ||
@@ -4218,7 +4246,10 @@ export class FoundryStepExecutor {
                     entryRoutesMarker(org, context.recordedIds())
                 ? publicHealthCheck(org, context.recordedIds(), hostname, healthPath)
                 : { kind: 'deployment-only' }, runtime, runtime.sleep ?? defaultSleep, `coolify:app:${entry.key}`, `${org.slug}'s ${entry.key === APP_ENTRY_KEY ? 'app' : `${entry.key} app`} stays at its previous deploy`);
-            await recordBuiltCommit(this.ports.coolify, { appId: appId, deploymentUuid: built.deploymentUuid, name: entry.key }, (key, value) => context.recordScopeId(key, value));
+            // An image app has no commit to read: its digest is the build.
+            if (!entry.image) {
+                await recordBuiltCommit(this.ports.coolify, { appId: appId, deploymentUuid: built.deploymentUuid, name: entry.key }, (key, value) => context.recordScopeId(key, value));
+            }
         }
         else if ((appEnv.changed || dbNeedsRestart) && existing) {
             await this.ports.coolify.restart(appId);
@@ -4230,6 +4261,8 @@ export class FoundryStepExecutor {
         context.recordScopeId(settingsKey, JSON.stringify({ ...want, port: want.port ?? have.port }));
         context.recordScopeId(domainsKey, JSON.stringify(wantDomains));
         context.recordScopeId(labelsKey, wantLabelsHash);
+        if (imageRef)
+            context.recordScopeId(appImageAppliedScopeKey(entry.key), imageRef);
         if (pinnedCommit && pinnedCommit === entry.liveCommit) {
             context.recordScopeId(wsKey.liveCommit(entry.key), pinnedCommit);
         }

package/dist/plan/platform-diff.d.ts

@@ -1,4 +1,4 @@
-import type { DeclaredOrg, EnvSharedSecret, HostingEntry, OrgId } from '../org.js';
+import type { DeclaredOrg, EntryImage, EnvSharedSecret, HostingEntry, OrgId } from '../org.js';
 import { type Plan, type PlanNote, type UnmanagedItem, type VersionChangeItem } from '../plan.js';
 import type { DeclaredPlatform } from '../platform.js';
 import { type BlueGreenServer } from './blue-green.js';
@@ -725,6 +725,22 @@ export declare const DEFAULT_APP_SETTINGS: AppSettings;
 export declare function appSettingsAppliedScopeKey(entryKey: string): string;
 /** The settings the app has: the marker, or the defaults when there is none. */
 export declare function appliedAppSettings(recorded: Readonly<Record<string, string>>, entryKey: string): AppSettings;
+/**
+ * The image an entry's app last ran, as `repository@digest` (no secret). `planApp` plans the step again, with a
+ * redeploy, when the entry's `image` differs from it.
+ */
+export declare function appImageAppliedScopeKey(entryKey: string): string;
+/** An entry image as one pull reference. */
+export declare function entryImageRef(image: EntryImage): string;
+/**
+ * The two image fields Coolify accepts for an entry image. Its tag rule has no `@` or `:`, so the digest goes in
+ * the name as `<repository>@sha256` and the tag holds the bare 64 hex digits (Coolify pulls `<name>:<tag>`),
+ * the same way `coolifyImageFor` writes a pinned platform image.
+ */
+export declare function entryImageFields(image: EntryImage): {
+    docker_registry_image_name: string;
+    docker_registry_image_tag: string;
+};
 /**
  * The URLs `coolifyApp` last put in the entry's Coolify `domains`
  * (`tunnelDomainList`), as a JSON array (`[]` for an internal entry). `planApp`

package/dist/plan/platform-diff.js

@@ -812,6 +812,28 @@ export function appliedAppSettings(recorded, entryKey) {
     const marker = recorded[appSettingsAppliedScopeKey(entryKey)];
     return marker ? JSON.parse(marker) : DEFAULT_APP_SETTINGS;
 }
+/**
+ * The image an entry's app last ran, as `repository@digest` (no secret). `planApp` plans the step again, with a
+ * redeploy, when the entry's `image` differs from it.
+ */
+export function appImageAppliedScopeKey(entryKey) {
+    return `app_image_applied.${entryKey}`;
+}
+/** An entry image as one pull reference. */
+export function entryImageRef(image) {
+    return `${image.repository}@${image.digest}`;
+}
+/**
+ * The two image fields Coolify accepts for an entry image. Its tag rule has no `@` or `:`, so the digest goes in
+ * the name as `<repository>@sha256` and the tag holds the bare 64 hex digits (Coolify pulls `<name>:<tag>`),
+ * the same way `coolifyImageFor` writes a pinned platform image.
+ */
+export function entryImageFields(image) {
+    return {
+        docker_registry_image_name: `${image.repository}@sha256`,
+        docker_registry_image_tag: image.digest.replace(/^sha256:/, ''),
+    };
+}
 /**
  * The URLs `coolifyApp` last put in the entry's Coolify `domains`
  * (`tunnelDomainList`), as a JSON array (`[]` for an internal entry). `planApp`

package/dist/plan/platform-providers.js

@@ -6237,7 +6237,7 @@ function assertSameDatabaseHost(key, liveUrl, dbInternalUrl) {
 /**
  * Throws when `liveUrl`, kept as it is on the app, names another database than
  * {@link ARCHON_POSTGRES_DB}: a hand-set URL on the wrong path, or a platform
- * still on the retired `archon_v2`. Names the two databases only, never the URL.
+ * still on a retired database. Names the two databases only, never the URL.
  */
 function assertArchonDatabasePath(key, liveUrl) {
     let database;

package/dist/release/run.js

@@ -1,5 +1,5 @@
 import { decide, healthRange, } from './decide.js';
-import { formatWeights, formatWindow, recordedFrom, releaseKeys, } from './state.js';
+import { formatRefusals, formatWeights, formatWindow, recordedFrom, releaseKeys, } from './state.js';
 import { isStageCopyAction } from './types.js';
 const REFUSAL_TEXT = {
     'no-copy-port': 'copy refused: this host cannot restore',
@@ -79,6 +79,10 @@ export async function runRelease(input) {
         [k.window]: formatWindow(next.window, next.release),
         [k.signal]: decision.signal ? JSON.stringify(decision.signal) : null,
     };
+    // Part of the run's writes: persisted with them, so a failed persist leaves neither. A run with none keeps it.
+    const lines = [...refused, ...decision.blocked];
+    if (lines.length > 0)
+        writes[k.refused] = formatRefusals(stamp, lines);
     for (const d of recorded.held)
         if (!next.held.includes(d))
             writes[k.held(d)] = null;
@@ -132,6 +136,7 @@ export function settleStageCopy(input) {
         writes[k.stageCopy] = `${stamp}|refused|${result.reason}`;
         writes[k.stageCopyRetry] = null;
         refused.push(REFUSAL_TEXT[result.reason] ?? `copy refused: ${result.reason}`);
+        writes[k.refused] = formatRefusals(stamp, refused);
         return { writes, refused, consume: true };
     }
     writes[k.stageCopy] = `${stamp}|failed|${result.step}`;

package/dist/release/state.d.ts

@@ -48,6 +48,8 @@ export declare function releaseKeys(entry: string): {
     stageCopyHandled: string;
     /** The id of a request whose copy failed once; a second failure consumes it. */
     stageCopyRetry: string;
+    /** JSON `{ at, lines }`: the latest run that refused or blocked something (see {@link formatRefusals}). */
+    refused: string;
 };
 export declare function formatWeights(w: Record<Color, number>): string;
 export declare function parseWeights(value: string | undefined): Record<Color, number> | null;
@@ -60,6 +62,13 @@ export declare function formatWindow(window: WindowState, release: Recorded['rel
 export declare function recordedFrom(ids: Record<string, string>, entryKey: string): Recorded | null;
 /** Reads `bg.<id>.stagecopy`; a damaged value reads as absent. */
 export declare function parseStageCopy(value: string | undefined): StageCopyState | undefined;
+/**
+ * The value of `bg.<id>.refused`: the run time and its refused lines, then its blocked lines. Capped at 20 lines
+ * of 300 characters so a bad run cannot grow the row. Callers write it only when `lines` is not empty.
+ */
+export declare function formatRefusals(at: string, lines: readonly string[]): string;
+/** Reads `bg.<id>.refused`; a damaged value reads as absent. */
+export declare function parseRefusals(value: string | undefined): ReleaseState['refused'];
 export declare function readSignal(ids: Record<string, string>, entryKey: string): ReleaseSignal | null;
 /** C2: the release state of one hosting entry, or null before blue/green recorded anything. */
 export declare function readReleaseState(store: ReleaseStore, input: {

package/dist/release/state.js

@@ -25,6 +25,8 @@ export function releaseKeys(entry) {
         stageCopyHandled: `${p}.stagecopyhandled`,
         /** The id of a request whose copy failed once; a second failure consumes it. */
         stageCopyRetry: `${p}.stagecopyretry`,
+        /** JSON `{ at, lines }`: the latest run that refused or blocked something (see {@link formatRefusals}). */
+        refused: `${p}.refused`,
     };
 }
 export function formatWeights(w) {
@@ -122,6 +124,26 @@ export function parseStageCopy(value) {
     }
     return undefined;
 }
+const REFUSED_MAX_LINES = 20;
+const REFUSED_MAX_LINE = 300;
+const refusedSchema = z.object({ at: z.string(), lines: z.array(z.string()) });
+/**
+ * The value of `bg.<id>.refused`: the run time and its refused lines, then its blocked lines. Capped at 20 lines
+ * of 300 characters so a bad run cannot grow the row. Callers write it only when `lines` is not empty.
+ */
+export function formatRefusals(at, lines) {
+    return JSON.stringify({
+        at,
+        lines: lines.slice(0, REFUSED_MAX_LINES).map((l) => l.slice(0, REFUSED_MAX_LINE)),
+    });
+}
+/** Reads `bg.<id>.refused`; a damaged value reads as absent. */
+export function parseRefusals(value) {
+    const parsed = refusedSchema.safeParse(parseJson(value));
+    if (!parsed.success || Number.isNaN(Date.parse(parsed.data.at)))
+        return undefined;
+    return parsed.data;
+}
 export function readSignal(ids, entryKey) {
     const parsed = signalSchema.safeParse(parseJson(ids[releaseKeys(entryKey).signal]));
     return parsed.success ? parsed.data : null;
@@ -133,6 +155,7 @@ export async function readReleaseState(store, input) {
     if (!r)
         return null;
     const stageCopy = parseStageCopy(ids[releaseKeys(input.entryKey).stageCopy]);
+    const refused = parseRefusals(ids[releaseKeys(input.entryKey).refused]);
     return {
         entryKey: input.entryKey,
         live: r.live,
@@ -144,6 +167,7 @@ export async function readReleaseState(store, input) {
         held: r.held,
         config: resolveReleaseConfig(input.entry),
         ...(stageCopy ? { stageCopy } : {}),
+        ...(refused ? { refused } : {}),
         ...stageDeployOf(ids[releaseKeys(input.entryKey).stageDeploy]),
     };
 }

package/dist/release/types.d.ts

@@ -59,6 +59,14 @@ export interface ReleaseState {
         outcome: 'ok' | 'failed';
         detail: string;
     };
+    /**
+     * The latest run that refused or blocked something (`bg.<id>.refused`): its time and its refused lines then its
+     * blocked lines, as decide's fixed texts (at most 20 lines of 300 characters). A run with none leaves it as is.
+     */
+    refused?: {
+        at: string;
+        lines: string[];
+    };
 }
 /** C3: what the last `copy_prod_to_stage` or `undo_stage_copy` request did. `detail` is fixed text or an id. */
 export interface StageCopyState {

package/package.json

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