@wtfalch/foundry 0.29.0 → 0.31.0

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.29.0",
+  "version": "0.31.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",
@@ -44,7 +45,7 @@
     "@wtfalch/audit": "0.6.0",
     "@wtfalch/auth": "0.16.0",
     "@wtfalch/edge": "0.12.0",
-    "@wtfalch/email": "^0.17.0",
+    "@wtfalch/email": "^0.20.0",
     "@wtfalch/providers": "0.7.5",
     "ssh2": "1.17.0",
     "zod": "4.6.5"