@wtfalch/foundry 0.28.0 → 0.30.0

package/dist/plan/version-status.d.ts

@@ -0,0 +1,200 @@
+import type { OrgId } from '../org.js';
+import type { VersionChangeItem } from '../plan.js';
+/**
+ * #263: a read-only view of which `@wtfalch/*` versions each org's hosted
+ * app is actually running, beside the platform's own version-change lines
+ * (`plan.ts`'s {@link VersionChangeItem}, #251) -- the data behind Archon's
+ * "Shared platform page" (wtfalch/archon#133). Nothing here mutates
+ * anything; it only reads.
+ *
+ * The problem this exists for: a shared service (ZITADEL, Synapse, the
+ * jobs scheduler, ...) has one declared version on `DeclaredPlatform`, but
+ * each org's own hosted app pulls its `@wtfalch/*` dependencies from
+ * whatever its own `pnpm-lock.yaml` pinned the day it was last deployed --
+ * and nothing before this listed who is actually on what.
+ */
+/**
+ * One org app this reads status for. The caller resolves `repo` and
+ * `coolifyApplicationUuid` itself, the same way every other reader in this
+ * package is handed an already-resolved scope id rather than resolving one
+ * itself (`providers-readers.ts`'s `ScopeResolver` doc comment) --
+ * `coolifyApplicationUuid` is the id `plan/diff.ts`'s `appStepKey` keys an
+ * org's hosting entry under in `AppliedState.serviceIds`
+ * (`` `coolify:app:${appStepKey(org, entry.key)}` ``, `org.ts`); `repo` is
+ * `HostingEntry.repo`, falling back to whatever default an app with none
+ * declared resolves to (`plan/executor.ts`'s own `DEFAULT_APP_REPO`).
+ */
+export interface OrgAppVersionRef {
+    orgId: OrgId;
+    orgSlug: string;
+    /** The hosting entry's own key, e.g. `'app'` (`org.ts`'s `APP_ENTRY_KEY`). */
+    entryKey: string;
+    /** The repo under `wtfalch` this app builds from, e.g. `'wtfalch/lokessmie'`. */
+    repo: string;
+    coolifyApplicationUuid: string;
+}
+/** One org app's read status: what is actually deployed, and what it depends on. */
+export interface OrgAppVersionStatus {
+    orgId: OrgId;
+    orgSlug: string;
+    entryKey: string;
+    repo: string;
+    /**
+     * The full 40-character commit sha Coolify's own deployment history
+     * reports as currently deployed (Choice A, #263's "Decide": Coolify's
+     * application record is live truth over foundry's own last-applied
+     * record, at the cost of a Coolify call this function always makes).
+     * `null` when there is no finished deployment yet -- a brand new app, or
+     * one whose only deploy so far failed.
+     */
+    deployedSha: string | null;
+    /**
+     * `@wtfalch/*` package name to resolved version, read from this app's
+     * `pnpm-lock.yaml` at {@link deployedSha}. `null` when there is nothing to
+     * read it from yet (`deployedSha` is `null`) or the read itself failed --
+     * {@link error} says which.
+     */
+    wtfalchVersions: Record<string, string> | null;
+    /** Set when this app's status could not be fully read; `wtfalchVersions` is `null` in this case too. */
+    error: string | null;
+}
+/** Across every app a call named, one `@wtfalch/*` package's spread of versions. */
+export interface WtfalchPackageDrift {
+    package: string;
+    /** Every distinct version seen, each with the org slugs running it, so a human reads who's on what with no cross-reference against `apps`. */
+    versionsBySlug: Record<string, string[]>;
+    /**
+     * The version a caller declared as the intended one for this package, if
+     * it passed one in `declaredVersions` (#263's "or from the declared
+     * one") -- never guessed here: this package has no fixed mapping from a
+     * `PlatformServiceKey` to an npm package name, so a caller that has one
+     * (or none) decides.
+     */
+    declaredVersion?: string;
+    /** True once more than one version is in use across `apps`, or an app's version differs from `declaredVersion`. */
+    drifted: boolean;
+}
+/** The combined view {@link readPlatformVersionStatus} returns. */
+export interface PlatformVersionStatus {
+    apps: OrgAppVersionStatus[];
+    /** Sorted by package name. */
+    packageDrift: WtfalchPackageDrift[];
+    /**
+     * The platform's own version-change lines (#251), carried through
+     * unchanged so a caller can render them on the same page with one call
+     * instead of two -- `toPlatformPlan`'s own `Plan.versionChanges`, or
+     * `PlatformPlanDetail.versionChanges` directly.
+     */
+    platformVersionChanges: VersionChangeItem[];
+}
+/**
+ * Reads one application's currently deployed commit sha.
+ *
+ * Narrow on purpose, the same shape every other port in `executor.ts`
+ * takes (`CoolifyPort`, `CloudflarePort`, ...): a real implementation is
+ * {@link providersStatusCoolifyPort}, over `@wtfalch/providers/coolify`'s
+ * `CoolifyClient`; a fake satisfies this directly in a test.
+ */
+export interface StatusCoolifyPort {
+    /**
+     * `null` when there is no *finished* deployment yet
+     * (`@wtfalch/providers/coolify`'s own doc comment on
+     * `CoolifyDeploymentRecord`: an application's bare `status` field reports
+     * on the container that is currently *running*, not on whether the last
+     * deploy actually landed, so a failed build leaves the previous image
+     * running and healthy with nothing in that field to say so -- this reads
+     * the deployment history instead, exactly as that doc comment advises).
+     */
+    deployedSha(applicationUuid: string): Promise<string | null>;
+}
+/**
+ * Reads one file's text contents in a GitHub repo, at a git ref.
+ *
+ * `@wtfalch/providers` 0.6.0's `GitHubClient` (`dist/github.d.ts`) has no
+ * such method yet, and this repo cannot add one to that published package
+ * from here -- so this is foundry's own minimal port for exactly the one
+ * capability #263 needs, built the same injectable way `GitHubClient`
+ * itself is (its own `GhExec`), so a host can later swap in a real
+ * `providers` method with no change to anything that depends on this
+ * interface.
+ */
+export interface StatusGithubPort {
+    /** `null` when `path` does not exist at `ref` (or `ref` itself does not exist). */
+    getFileContents(repo: string, path: string, ref: string): Promise<string | null>;
+}
+/**
+ * Extracts every `@wtfalch/*` package's resolved version out of a pnpm
+ * lockfile's text, without parsing YAML in general.
+ *
+ * pnpm lockfile v9 (`lockfileVersion: '9.0'`, this estate's own) writes each
+ * resolved package as a two-space-indented, single-quoted
+ * `'<name>@<version>'` key in its `packages:` section, and again --
+ * peer-qualified, e.g. `'<name>@<version>(<peer>@<peer-version>...)'` -- in
+ * its `snapshots:` section. Both carry the same base version for a given
+ * package, so reading either (or both, as this does) and keeping the last
+ * value seen per package name is lossless for what this exists to compare:
+ * *which version* an app is on, never which peer graph it resolved to.
+ * Verified against this very repo's own `pnpm-lock.yaml`.
+ */
+export declare function wtfalchVersionsFromPnpmLockfile(lockfile: string): Record<string, string>;
+export interface ReadPlatformVersionStatusOptions {
+    /** Default `'pnpm-lock.yaml'`. */
+    lockfilePath?: string;
+    /**
+     * The intended version for a package, keyed by its `@wtfalch/*` name --
+     * #263's "or from the declared one". Optional: without it, drift is
+     * computed across `apps` alone.
+     */
+    declaredVersions?: Readonly<Record<string, string>>;
+    /** Carried straight through onto {@link PlatformVersionStatus.platformVersionChanges}; defaults to none. */
+    platformVersionChanges?: readonly VersionChangeItem[];
+}
+/**
+ * Reads every named app's deployed sha and the `@wtfalch/*` versions its
+ * lockfile pins at that sha, then flags which packages have drifted --
+ * across the named apps, or against a declared version when the caller
+ * passes one (#263's "Done when": two orgs on different `@wtfalch/auth`
+ * versions is flagged).
+ *
+ * One app's read failing (its sha cannot be found, or its lockfile fetch
+ * errors) is recorded on that app alone (`OrgAppVersionStatus.error`) and
+ * never stops another app's read, or the drift computed from whichever
+ * apps did resolve.
+ */
+export declare function readPlatformVersionStatus(apps: readonly OrgAppVersionRef[], ports: {
+    coolify: StatusCoolifyPort;
+    github: StatusGithubPort;
+}, options?: ReadPlatformVersionStatusOptions): Promise<PlatformVersionStatus>;
+/**
+ * The real {@link StatusCoolifyPort}, over `@wtfalch/providers/coolify`'s
+ * `CoolifyClient` (Choice A, #263's "Decide"). Narrowed to the one method
+ * this needs, the same `Pick`-shaped narrowing nothing else in this package
+ * happened to need before -- `CoolifyClient` itself is never imported as a
+ * type here, so a fake in a test needs no part of its surface this doesn't use.
+ */
+export declare function providersStatusCoolifyPort(client: {
+    listApplicationDeployments(uuid: string, take?: number): Promise<Array<{
+        commit: string;
+        status: string;
+    }>>;
+}): StatusCoolifyPort;
+/**
+ * The `gh` CLI call {@link ghCliStatusGithubPort} makes -- same shape as
+ * `@wtfalch/providers/github`'s own `GhExec`, so a host that already has a
+ * real one wired for `GitHubClient` can hand the identical function to
+ * both. Injectable so a test never spawns a real process.
+ */
+export type GhExec = (args: string[]) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * The real {@link StatusGithubPort}, built on `gh api repos/{repo}/contents/{path}`
+ * the way GitHub's own REST API serves a file's contents at a ref --
+ * `{ content: '<base64>' }` on success, a non-zero exit with `404` in `gh`'s
+ * own error text when `path` or `ref` doesn't exist (checked against a real
+ * `gh` CLI, not GitHub's docs, matching this package's `coolify.ts`'s own
+ * "verified against a live instance, not the docs" standard for an API this
+ * cannot run against the network in CI).
+ */
+export declare function ghCliStatusGithubPort(exec?: GhExec): StatusGithubPort;

package/dist/plan/version-status.js

@@ -0,0 +1,213 @@
+import { execFile } from 'node:child_process';
+/**
+ * Extracts every `@wtfalch/*` package's resolved version out of a pnpm
+ * lockfile's text, without parsing YAML in general.
+ *
+ * pnpm lockfile v9 (`lockfileVersion: '9.0'`, this estate's own) writes each
+ * resolved package as a two-space-indented, single-quoted
+ * `'<name>@<version>'` key in its `packages:` section, and again --
+ * peer-qualified, e.g. `'<name>@<version>(<peer>@<peer-version>...)'` -- in
+ * its `snapshots:` section. Both carry the same base version for a given
+ * package, so reading either (or both, as this does) and keeping the last
+ * value seen per package name is lossless for what this exists to compare:
+ * *which version* an app is on, never which peer graph it resolved to.
+ * Verified against this very repo's own `pnpm-lock.yaml`.
+ */
+export function wtfalchVersionsFromPnpmLockfile(lockfile) {
+    const PACKAGE_LINE = /^ {2}'(@wtfalch\/[^@']+)@([^'()]+)(?:\(.*\))?':$/;
+    const versions = {};
+    for (const line of lockfile.split('\n')) {
+        const match = PACKAGE_LINE.exec(line);
+        const name = match?.[1];
+        const version = match?.[2];
+        if (name !== undefined && version !== undefined) {
+            versions[name] = version;
+        }
+    }
+    return versions;
+}
+/** `pnpm-lock.yaml` at the repo root -- every repo in this estate pins with pnpm (root `CLAUDE.md`). */
+const DEFAULT_LOCKFILE_PATH = 'pnpm-lock.yaml';
+/**
+ * Reads every named app's deployed sha and the `@wtfalch/*` versions its
+ * lockfile pins at that sha, then flags which packages have drifted --
+ * across the named apps, or against a declared version when the caller
+ * passes one (#263's "Done when": two orgs on different `@wtfalch/auth`
+ * versions is flagged).
+ *
+ * One app's read failing (its sha cannot be found, or its lockfile fetch
+ * errors) is recorded on that app alone (`OrgAppVersionStatus.error`) and
+ * never stops another app's read, or the drift computed from whichever
+ * apps did resolve.
+ */
+export async function readPlatformVersionStatus(apps, ports, options = {}) {
+    const lockfilePath = options.lockfilePath ?? DEFAULT_LOCKFILE_PATH;
+    const statuses = await Promise.all(apps.map((app) => readOneAppVersionStatus(app, ports, lockfilePath)));
+    return {
+        apps: statuses,
+        packageDrift: computeWtfalchPackageDrift(statuses, options.declaredVersions ?? {}),
+        platformVersionChanges: options.platformVersionChanges
+            ? [...options.platformVersionChanges]
+            : [],
+    };
+}
+async function readOneAppVersionStatus(app, ports, lockfilePath) {
+    const base = {
+        orgId: app.orgId,
+        orgSlug: app.orgSlug,
+        entryKey: app.entryKey,
+        repo: app.repo,
+    };
+    try {
+        const deployedSha = await ports.coolify.deployedSha(app.coolifyApplicationUuid);
+        if (!deployedSha) {
+            return { ...base, deployedSha: null, wtfalchVersions: null, error: null };
+        }
+        const lockfile = await ports.github.getFileContents(app.repo, lockfilePath, deployedSha);
+        if (lockfile === null) {
+            return {
+                ...base,
+                deployedSha,
+                wtfalchVersions: null,
+                error: `${lockfilePath} not found in ${app.repo} at ${deployedSha}`,
+            };
+        }
+        return {
+            ...base,
+            deployedSha,
+            wtfalchVersions: wtfalchVersionsFromPnpmLockfile(lockfile),
+            error: null,
+        };
+    }
+    catch (error) {
+        return {
+            ...base,
+            deployedSha: null,
+            wtfalchVersions: null,
+            error: `read failed: ${error instanceof Error ? error.name : 'unknown error'}`,
+        };
+    }
+}
+function computeWtfalchPackageDrift(statuses, declaredVersions) {
+    const byPackage = new Map();
+    for (const status of statuses) {
+        if (!status.wtfalchVersions)
+            continue;
+        for (const [pkg, version] of Object.entries(status.wtfalchVersions)) {
+            const versions = byPackage.get(pkg) ?? new Map();
+            byPackage.set(pkg, versions);
+            const slugs = versions.get(version) ?? new Set();
+            versions.set(version, slugs);
+            slugs.add(status.orgSlug);
+        }
+    }
+    // A package only named in `declaredVersions`, with no app running it yet,
+    // is still worth a row: it is the simplest drift there is -- declared,
+    // and nobody on it.
+    for (const pkg of Object.keys(declaredVersions)) {
+        if (!byPackage.has(pkg))
+            byPackage.set(pkg, new Map());
+    }
+    const packages = [...byPackage.keys()].sort();
+    return packages.map((pkg) => {
+        const versions = byPackage.get(pkg) ?? new Map();
+        const versionsBySlug = {};
+        for (const [version, slugs] of versions) {
+            versionsBySlug[version] = [...slugs].sort();
+        }
+        const declaredVersion = declaredVersions[pkg];
+        const distinct = new Set(versions.keys());
+        if (declaredVersion !== undefined)
+            distinct.add(declaredVersion);
+        return {
+            package: pkg,
+            versionsBySlug,
+            ...(declaredVersion !== undefined ? { declaredVersion } : {}),
+            drifted: distinct.size > 1,
+        };
+    });
+}
+/**
+ * The real {@link StatusCoolifyPort}, over `@wtfalch/providers/coolify`'s
+ * `CoolifyClient` (Choice A, #263's "Decide"). Narrowed to the one method
+ * this needs, the same `Pick`-shaped narrowing nothing else in this package
+ * happened to need before -- `CoolifyClient` itself is never imported as a
+ * type here, so a fake in a test needs no part of its surface this doesn't use.
+ */
+export function providersStatusCoolifyPort(client) {
+    return {
+        async deployedSha(applicationUuid) {
+            const deployments = await client.listApplicationDeployments(applicationUuid);
+            const finished = deployments.find((d) => d.status === 'finished');
+            return finished?.commit ?? null;
+        },
+    };
+}
+const GH_TIMEOUT_MS = 30_000;
+const REPO_PATTERN = /^[\w.-]+\/[\w.-]+$/;
+const REF_PATTERN = /^[\w./-]+$/;
+/**
+ * The default {@link GhExec}: shells out to the real `gh` CLI, exactly the
+ * dependency `@wtfalch/providers/github`'s own `GitHubClient` already takes
+ * on. Real process I/O, left untested here the same as `ssh2`'s `Client` in
+ * `scripts/calls-sfu-deploy.mjs` -- {@link ghCliStatusGithubPort}'s own
+ * decision logic (404 -> `null`, base64 decode) is what is unit-tested,
+ * against a fake `GhExec`.
+ */
+function spawnGh(args) {
+    return new Promise((resolve, reject) => {
+        execFile('gh', args, { maxBuffer: 32 * 1024 * 1024, timeout: GH_TIMEOUT_MS }, (error, stdout, stderr) => {
+            if (error) {
+                reject(Object.assign(error, { stdout, stderr }));
+                return;
+            }
+            resolve({ stdout, stderr });
+        });
+    });
+}
+/**
+ * The real {@link StatusGithubPort}, built on `gh api repos/{repo}/contents/{path}`
+ * the way GitHub's own REST API serves a file's contents at a ref --
+ * `{ content: '<base64>' }` on success, a non-zero exit with `404` in `gh`'s
+ * own error text when `path` or `ref` doesn't exist (checked against a real
+ * `gh` CLI, not GitHub's docs, matching this package's `coolify.ts`'s own
+ * "verified against a live instance, not the docs" standard for an API this
+ * cannot run against the network in CI).
+ */
+export function ghCliStatusGithubPort(exec = spawnGh) {
+    return {
+        async getFileContents(repo, path, ref) {
+            if (!REPO_PATTERN.test(repo) || !REF_PATTERN.test(ref) || path.includes('..')) {
+                throw new Error('invalid repo, path or ref');
+            }
+            try {
+                const { stdout } = await exec([
+                    'api',
+                    `repos/${repo}/contents/${path}`,
+                    '--method',
+                    'GET',
+                    '-f',
+                    `ref=${ref}`,
+                    '--jq',
+                    '.content',
+                ]);
+                const base64 = stdout.trim();
+                if (!base64 || base64 === 'null')
+                    return null;
+                return Buffer.from(base64, 'base64').toString('utf8');
+            }
+            catch (error) {
+                if (isGhNotFoundError(error))
+                    return null;
+                throw error;
+            }
+        },
+    };
+}
+function isGhNotFoundError(error) {
+    const record = error;
+    const text = [record?.message, record?.stderr]
+        .filter((value) => typeof value === 'string')
+        .join('\n');
+    return /\b404\b|not found/i.test(text);
+}

package/dist/plan/zitadel-login-policy.d.ts

@@ -0,0 +1,23 @@
+import type { ZitadelPort } from './executor.js';
+export interface ZitadelLoginPolicyOptions {
+    /** The ZITADEL instance's base URL. */
+    url: string;
+    /** Bearer token allowed to read and write an org's login policy. */
+    token: string;
+    fetchImpl?: typeof fetch;
+    instanceHost?: string;
+}
+/**
+ * The real {@link ZitadelPort.closeSelfRegistration}: the mirror of
+ * `ZitadelClient.allowSelfRegistration` in `@wtfalch/providers`, with
+ * `allowRegister` forced off instead of on. It speaks ZITADEL's v1 management
+ * API (`GET`/`POST`/`PUT /management/v1/policies/login`, org-scoped by
+ * `x-zitadel-orgid`) and has not been run against a live instance.
+ *
+ * Neither write merges: a field left out resets to false or empty. So every
+ * setting of the policy in force is copied back and only `allowRegister`
+ * changes. An org that inherits the instance default always gets its own
+ * policy (POST), so a later change to the default cannot turn registration
+ * back on. A custom policy keeps its own factors and IdPs (PUT).
+ */
+export declare function createZitadelLoginPolicy(options: ZitadelLoginPolicyOptions): Pick<ZitadelPort, 'closeSelfRegistration'>;

package/dist/plan/zitadel-login-policy.js

@@ -0,0 +1,103 @@
+import { ZitadelHttpError } from './zitadel-machine-user.js';
+/** The settings both AddCustomLoginPolicy and UpdateCustomLoginPolicy accept. */
+const LOGIN_POLICY_SETTINGS = [
+    'allowUsernamePassword',
+    'allowRegister',
+    'allowExternalIdp',
+    'forceMfa',
+    'passwordlessType',
+    'hidePasswordReset',
+    'ignoreUnknownUsernames',
+    'defaultRedirectUri',
+    'passwordCheckLifetime',
+    'externalLoginCheckLifetime',
+    'mfaInitSkipLifetime',
+    'secondFactorCheckLifetime',
+    'multiFactorCheckLifetime',
+    'allowDomainDiscovery',
+    'disableLoginWithEmail',
+    'disableLoginWithPhone',
+    'forceMfaLocalOnly',
+];
+const CALL_TIMEOUT_MS = 30_000;
+/**
+ * The real {@link ZitadelPort.closeSelfRegistration}: the mirror of
+ * `ZitadelClient.allowSelfRegistration` in `@wtfalch/providers`, with
+ * `allowRegister` forced off instead of on. It speaks ZITADEL's v1 management
+ * API (`GET`/`POST`/`PUT /management/v1/policies/login`, org-scoped by
+ * `x-zitadel-orgid`) and has not been run against a live instance.
+ *
+ * Neither write merges: a field left out resets to false or empty. So every
+ * setting of the policy in force is copied back and only `allowRegister`
+ * changes. An org that inherits the instance default always gets its own
+ * policy (POST), so a later change to the default cannot turn registration
+ * back on. A custom policy keeps its own factors and IdPs (PUT).
+ */
+export function createZitadelLoginPolicy(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    async function call(method, orgId, body) {
+        const path = '/management/v1/policies/login';
+        const response = await fetchImpl(`${options.url}${path}`, {
+            method,
+            signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+            headers: {
+                authorization: `Bearer ${options.token}`,
+                'content-type': 'application/json',
+                'x-zitadel-orgid': orgId,
+                ...(options.instanceHost
+                    ? {
+                        'x-zitadel-instance-host': options.instanceHost,
+                        'x-forwarded-host': options.instanceHost,
+                        'x-forwarded-proto': 'https',
+                    }
+                    : {}),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await response.text();
+        let data = {};
+        try {
+            data = text ? JSON.parse(text) : {};
+        }
+        catch {
+            throw new ZitadelHttpError(response.status, `non-JSON response from ${path}`);
+        }
+        if (!response.ok) {
+            throw new ZitadelHttpError(response.status, String(data.message ?? response.statusText), typeof data.code === 'number' ? data.code : undefined);
+        }
+        return data;
+    }
+    return {
+        async closeSelfRegistration(orgId) {
+            if (!orgId)
+                throw new Error('closeSelfRegistration: orgId is required');
+            const data = await call('GET', orgId, undefined);
+            const policy = data.policy ?? {};
+            const isDefault = data.isDefault === true || policy.isDefault === true;
+            if (!isDefault && policy.allowRegister === false) {
+                return { changed: false };
+            }
+            const settings = {};
+            for (const key of LOGIN_POLICY_SETTINGS) {
+                if (policy[key] !== undefined)
+                    settings[key] = policy[key];
+            }
+            settings.allowRegister = false;
+            if (isDefault) {
+                await call('POST', orgId, {
+                    ...settings,
+                    secondFactors: policy.secondFactors ?? [],
+                    multiFactors: policy.multiFactors ?? [],
+                    idps: (policy.idps ?? []).map((idp) => ({
+                        idpId: idp.idpId,
+                        ownerType: 'IDP_OWNER_TYPE_SYSTEM',
+                    })),
+                });
+            }
+            else {
+                await call('PUT', orgId, settings);
+            }
+            return { changed: true };
+        },
+    };
+}

package/dist/plan/zitadel-machine-user.d.ts

@@ -84,4 +84,4 @@ export interface ZitadelMinterOptions {
     fetchImpl?: typeof fetch;
     instanceHost?: string;
 }
-export declare function createZitadelAdminMinter(options: ZitadelMinterOptions): Pick<ZitadelPort, 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats'>;
+export declare function createZitadelAdminMinter(options: ZitadelMinterOptions): Pick<ZitadelPort, 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'reserveUserName'>;

package/dist/plan/zitadel-machine-user.js

@@ -230,6 +230,39 @@ export function createZitadelAdminMinter(options) {
         }
         return { userId, token: pat.token, patId: patId ?? '', revokedPriorPat };
     }
+    /**
+     * Find-or-create only: the first two steps of the sequence above, with no
+     * IAM role grant and no PAT. The user holds no secret; it exists so
+     * ZITADEL's per-org username uniqueness refuses the name to anyone later.
+     */
+    async function reserveUserName(orgId, userName) {
+        if (!orgId || !userName.trim()) {
+            throw new Error('reserveUserName: orgId and userName are required');
+        }
+        const found = await call('POST', '/management/v1/users/_search', {
+            queries: [
+                {
+                    userNameQuery: {
+                        userName,
+                        method: 'TEXT_QUERY_METHOD_EQUALS_IGNORE_CASE',
+                    },
+                },
+            ],
+        }, orgId);
+        const existing = found.result?.[0]?.id;
+        if (existing)
+            return { userId: existing };
+        const created = await call('POST', '/management/v1/users/machine', {
+            userName,
+            name: `Foundry (reserved: ${userName})`,
+            accessTokenType: 'ACCESS_TOKEN_TYPE_BEARER',
+        }, orgId);
+        const userId = typeof created.userId === 'string' ? created.userId : undefined;
+        if (!userId) {
+            throw new Error(`ZITADEL did not return the machine user id reserving username ${userName}`);
+        }
+        return { userId };
+    }
     return {
         mintAdminMachineUser: (orgId, input) => mintMachineUser(orgId, input, 'IAM_OWNER').then(({ userId, token }) => ({ userId, token })),
         mintLoginClientMachineUser: (orgId, input) => mintMachineUser(orgId, input, 'IAM_LOGIN_CLIENT'),
@@ -238,5 +271,6 @@ export function createZitadelAdminMinter(options) {
         // the user -- see `ZitadelPort.listLoginClientPats`'s own doc comment for
         // the race this closes.
         listLoginClientPats: (orgId, userId) => listPats(orgId, userId),
+        reserveUserName,
     };
 }

package/dist/platform.d.ts

@@ -95,7 +95,7 @@ export interface DeclaredPlatform {
     /**
      * #540: a self-hosted heartbeat server (Healthchecks) for the platform,
      * for now -- whether it stays the platform's heartbeat server long-term,
-     * instead of or alongside the hand-set-up `hc.wtfalch.dev` instance, and
+     * instead of or alongside the hand-set-up heartbeat instance, and
      * what happens to that instance's own data, are both still open "Decide"
      * items on issue #540's own thread, not settled by this field. `gitRef`
      * is the Docker image tag it runs (the same overload `mail.gitRef`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",
@@ -34,7 +34,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "db:provision": "node scripts/foundry-db-provision.mjs",
-    "calls-sfu:deploy": "node scripts/calls-sfu-deploy.mjs"
+    "calls-sfu:deploy": "node scripts/calls-sfu-deploy.mjs",
+    "status": "node scripts/status.mjs"
   },
   "peerDependencies": {
     "@wtfalch/providers": ">=0.7.4",