@magoz/provision 0.0.0-stage → 0.1.0

package/dist/factory/steps/r2.js

@@ -0,0 +1,70 @@
+import { Console, Effect, Option, Redacted } from 'effect';
+import { decide, envGroups, factoryError, groupHasKeys, mutate, requireProject, writeGroup } from '../context.js';
+import { bucketCorsMatches, bucketExists, createBucket, createBucketToken, deleteToken, findToken, putBucketCors, r2Endpoint } from '../providers/cloudflare.js';
+import { ensureScopedKey } from '../scoped-key.js';
+import { listEnvRecords } from '../vercel-api.js';
+export const r2VariableKeys = [
+    'R2_API_URL',
+    'R2_ACCESS_KEY_ID',
+    'R2_SECRET_ACCESS_KEY',
+    'R2_BUCKET_NAME'
+];
+const ensureBucket = (context, admin, handle, records, target) => Effect.gen(function* () {
+    if (yield* bucketExists(admin, target.bucket)) {
+        yield* decide(context, 'data', `R2 bucket ${target.bucket}`);
+    }
+    else {
+        yield* mutate(context, `create private R2 bucket ${target.bucket}`, createBucket(admin, target.bucket));
+    }
+    if (!(yield* bucketCorsMatches(admin, target.bucket, target.origin))) {
+        yield* mutate(context, `set ${target.bucket} CORS to PUT from ${target.origin}`, putBucketCors(admin, target.bucket, target.origin));
+    }
+    const tokenName = `${target.bucket}-app-rw`;
+    yield* ensureScopedKey(context, {
+        description: `R2 token ${tokenName}`,
+        existing: yield* findToken(admin, tokenName),
+        vercelComplete: groupHasKeys(records, target.group, r2VariableKeys),
+        createAndWrite: Effect.gen(function* () {
+            const token = yield* createBucketToken(admin, tokenName, target.bucket);
+            const [url, accessKey, secretKey, bucketName] = r2VariableKeys;
+            yield* writeGroup(context, handle, target.group, [
+                { key: url, value: Redacted.make(r2Endpoint(admin.accountId)), type: 'encrypted' },
+                { key: accessKey, value: Redacted.make(token.accessKeyId), type: target.secretType },
+                { key: secretKey, value: token.secretAccessKey, type: target.secretType },
+                { key: bucketName, value: Redacted.make(target.bucket), type: 'encrypted' }
+            ]).pipe(Effect.tapError(() => deleteToken(admin, token.id).pipe(Effect.ignore)));
+        }),
+        remove: id => deleteToken(admin, id)
+    });
+});
+/**
+ * Private `<repo>-dev` and `<repo>-prod` buckets with upload CORS (`*` for development, the exact
+ * production origin for production) and one bucket-scoped object read/write token each.
+ */
+export const r2Step = (context) => Effect.gen(function* () {
+    const admin = context.credentials.cloudflare;
+    if (admin === undefined)
+        return yield* factoryError('the factory item has no cloudflare section');
+    if (context.domain === undefined) {
+        return yield* factoryError('the r2 step needs --domain for the production CORS origin');
+    }
+    const handle = yield* requireProject(context);
+    if (Option.isNone(handle)) {
+        yield* Console.log('  would run after the vercel step creates the project');
+        return;
+    }
+    const groups = envGroups(handle.value);
+    const records = yield* listEnvRecords(context.credentials.vercel.teamId, handle.value.project.id);
+    yield* ensureBucket(context, admin, handle.value, records, {
+        bucket: context.names.development,
+        origin: '*',
+        group: groups.preproduction,
+        secretType: 'encrypted'
+    });
+    yield* ensureBucket(context, admin, handle.value, records, {
+        bucket: context.names.production,
+        origin: `https://${context.domain}`,
+        group: groups.production,
+        secretType: 'sensitive'
+    });
+});

package/dist/factory/steps/reports.js

@@ -0,0 +1,44 @@
+import { Console, Effect, Option, Redacted } from 'effect';
+import { envGroups, groupHasKeys, requireProject, writeGroup } from '../context.js';
+import { createReportToken, findReportToken, revokeReportToken } from '../providers/report-receiver.js';
+import { ensureScopedKey } from '../scoped-key.js';
+import { listEnvRecords } from '../vercel-api.js';
+export const reportVariableKeys = ['REPORT_RECEIVER_URL', 'REPORT_RECEIVER_TOKEN'];
+/**
+ * One report token per environment group from the factory's report receiver (its factory API).
+ * Factories without a `report_receiver` section skip this step.
+ */
+export const reportsStep = (context) => Effect.gen(function* () {
+    const receiver = context.credentials.reportReceiver;
+    if (receiver === undefined) {
+        yield* Console.log('  skipped: the factory has no report receiver');
+        return;
+    }
+    const handle = yield* requireProject(context);
+    if (Option.isNone(handle)) {
+        yield* Console.log('  would run after the vercel step creates the project');
+        return;
+    }
+    const groups = envGroups(handle.value);
+    const records = yield* listEnvRecords(context.credentials.vercel.teamId, handle.value.project.id);
+    const [urlKey, tokenKey] = reportVariableKeys;
+    const targets = [
+        { name: context.names.development, group: groups.preproduction, type: 'encrypted' },
+        { name: context.names.production, group: groups.production, type: 'sensitive' }
+    ];
+    for (const target of targets) {
+        yield* ensureScopedKey(context, {
+            description: `report token ${target.name}`,
+            existing: yield* findReportToken(receiver, target.name),
+            vercelComplete: groupHasKeys(records, target.group, reportVariableKeys),
+            createAndWrite: Effect.gen(function* () {
+                const created = yield* createReportToken(receiver, target.name);
+                yield* writeGroup(context, handle.value, target.group, [
+                    { key: urlKey, value: Redacted.make(receiver.url), type: target.type },
+                    { key: tokenKey, value: created.token, type: target.type }
+                ]).pipe(Effect.tapError(() => revokeReportToken(receiver, created.id).pipe(Effect.ignore)));
+            }),
+            remove: id => revokeReportToken(receiver, id)
+        });
+    }
+});

package/dist/factory/steps/resend.js

@@ -0,0 +1,37 @@
+import { Console, Effect, Option } from 'effect';
+import { envGroups, factoryError, groupHasKeys, requireProject, writeGroup } from '../context.js';
+import { createSendingKey, deleteApiKey, findApiKey } from '../providers/resend.js';
+import { ensureScopedKey } from '../scoped-key.js';
+import { listEnvRecords } from '../vercel-api.js';
+const variableKey = 'RESEND_API_KEY';
+/** One sending-only key per environment group (not restricted to a domain). */
+export const resendStep = (context) => Effect.gen(function* () {
+    const resend = context.credentials.resend;
+    if (resend === undefined)
+        return yield* factoryError('the factory item has no resend section');
+    const handle = yield* requireProject(context);
+    if (Option.isNone(handle)) {
+        yield* Console.log('  would run after the vercel step creates the project');
+        return;
+    }
+    const groups = envGroups(handle.value);
+    const records = yield* listEnvRecords(context.credentials.vercel.teamId, handle.value.project.id);
+    const targets = [
+        { name: context.names.development, group: groups.preproduction, type: 'encrypted' },
+        { name: context.names.production, group: groups.production, type: 'sensitive' }
+    ];
+    for (const target of targets) {
+        yield* ensureScopedKey(context, {
+            description: `Resend key ${target.name}`,
+            existing: yield* findApiKey(resend.apiKey, target.name),
+            vercelComplete: groupHasKeys(records, target.group, [variableKey]),
+            createAndWrite: Effect.gen(function* () {
+                const key = yield* createSendingKey(resend.apiKey, target.name);
+                yield* writeGroup(context, handle.value, target.group, [
+                    { key: variableKey, value: key.token, type: target.type }
+                ]).pipe(Effect.tapError(() => deleteApiKey(resend.apiKey, key.id).pipe(Effect.ignore)));
+            }),
+            remove: id => deleteApiKey(resend.apiKey, id)
+        });
+    }
+});

package/dist/factory/steps/secrets.js

@@ -0,0 +1,104 @@
+import { generateKeyPairSync, randomBytes } from 'node:crypto';
+import { Console, Effect, Option, Redacted } from 'effect';
+import { decide, envGroups, factoryError, groupHasKeys, requireProject, writeGroup } from '../context.js';
+import { requireVerifiedDomain } from '../providers/resend.js';
+import { listEnvRecords } from '../vercel-api.js';
+export const usageAlertThresholds = '50,80,95';
+const base64 = (bytes) => Redacted.make(randomBytes(bytes).toString('base64'));
+/** A web-push VAPID pair: uncompressed P-256 public point and raw private scalar, base64url. */
+export const generateVapidKeys = () => {
+    const { privateKey, publicKey } = generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
+    const publicJwk = publicKey.export({ format: 'jwk' });
+    const privateJwk = privateKey.export({ format: 'jwk' });
+    const x = Buffer.from(publicJwk.x ?? '', 'base64url');
+    const y = Buffer.from(publicJwk.y ?? '', 'base64url');
+    return {
+        publicKey: Buffer.concat([Buffer.from([4]), x, y]).toString('base64url'),
+        privateKey: Redacted.make(privateJwk.d ?? '')
+    };
+};
+/** Generated per group: a separate value for pre-production and production. */
+const generatedSets = [
+    {
+        description: 'BETTER_AUTH_SECRET',
+        keys: ['BETTER_AUTH_SECRET'],
+        kind: 'secret',
+        entries: type => [{ key: 'BETTER_AUTH_SECRET', value: base64(32), type }]
+    },
+    {
+        description: 'INTEGRATION_CREDENTIAL_ENCRYPTION_KEY',
+        keys: ['INTEGRATION_CREDENTIAL_ENCRYPTION_KEY'],
+        kind: 'secret',
+        entries: type => [{ key: 'INTEGRATION_CREDENTIAL_ENCRYPTION_KEY', value: base64(32), type }]
+    },
+    {
+        description: 'CRON_SECRET',
+        keys: ['CRON_SECRET'],
+        kind: 'key',
+        entries: type => [
+            { key: 'CRON_SECRET', value: Redacted.make(randomBytes(32).toString('hex')), type }
+        ]
+    },
+    {
+        description: 'VAPID key pair',
+        keys: ['VAPID_PUBLIC_KEY', 'VAPID_PRIVATE_KEY'],
+        kind: 'secret',
+        entries: type => {
+            const pair = generateVapidKeys();
+            return [
+                { key: 'VAPID_PUBLIC_KEY', value: Redacted.make(pair.publicKey), type: 'plain' },
+                { key: 'VAPID_PRIVATE_KEY', value: pair.privateKey, type }
+            ];
+        }
+    }
+];
+const ensureSet = (context, handle, records, group, set, entries) => Effect.gen(function* () {
+    if (groupHasKeys(records, group, set.keys)) {
+        const decision = yield* decide(context, set.kind, `${set.description} (${group.label})`);
+        if (decision === 'reuse')
+            return;
+    }
+    yield* writeGroup(context, handle, group, entries());
+});
+/**
+ * App secrets the CLI generates (never shown or stored elsewhere), plus plain settings shared by
+ * all environments: `AUTH_EMAIL_FROM` and `AI_PROVIDER_USAGE_ALERT_THRESHOLDS`.
+ */
+export const secretsStep = (context) => Effect.gen(function* () {
+    const resend = context.credentials.resend;
+    if (resend === undefined) {
+        return yield* factoryError('the secrets step needs the resend section for AUTH_EMAIL_FROM');
+    }
+    const fromAddress = context.emailFrom ??
+        (resend.sendingDomain === undefined ? undefined : `noreply@${resend.sendingDomain}`);
+    if (fromAddress === undefined) {
+        return yield* factoryError('the secrets step needs a sender: pass --email-from or set resend.sending_domain in the factory item');
+    }
+    yield* requireVerifiedDomain(resend.apiKey, fromAddress.slice(fromAddress.indexOf('@') + 1));
+    const handle = yield* requireProject(context);
+    if (Option.isNone(handle)) {
+        yield* Console.log('  would run after the vercel step creates the project');
+        return;
+    }
+    const groups = envGroups(handle.value);
+    const records = yield* listEnvRecords(context.credentials.vercel.teamId, handle.value.project.id);
+    for (const set of generatedSets) {
+        yield* ensureSet(context, handle.value, records, groups.preproduction, set, () => set.entries('encrypted'));
+        yield* ensureSet(context, handle.value, records, groups.production, set, () => set.entries('sensitive'));
+    }
+    const plain = [
+        {
+            key: 'AUTH_EMAIL_FROM',
+            value: Redacted.make(`${context.senderName} <${fromAddress}>`),
+            type: 'plain'
+        },
+        {
+            key: 'AI_PROVIDER_USAGE_ALERT_THRESHOLDS',
+            value: Redacted.make(usageAlertThresholds),
+            type: 'plain'
+        }
+    ];
+    for (const entry of plain) {
+        yield* ensureSet(context, handle.value, records, groups.all, { description: entry.key, keys: [entry.key], kind: 'key', entries: () => [entry] }, () => [entry]);
+    }
+});

package/dist/factory/steps/upstash.js

@@ -0,0 +1,92 @@
+import { Console, Effect, Option, Redacted } from 'effect';
+import { decide, envGroups, factoryError, groupHasKeys, mutate, requireProject, withTerminal, writeGroup } from '../context.js';
+import { SecretInput } from '../secret-input.js';
+import { createTeam, findTeam } from '../providers/upstash.js';
+import { listEnvRecords } from '../vercel-api.js';
+export const qstashVariableKeys = [
+    'QSTASH_URL',
+    'QSTASH_TOKEN',
+    'QSTASH_CURRENT_SIGNING_KEY',
+    'QSTASH_NEXT_SIGNING_KEY'
+];
+/**
+ * Retained `<repo>-dev` and `<repo>-prod` teams (QStash has one tenancy per team, so separate
+ * teams are the only isolation boundary). A team's QStash credentials are only readable with a key
+ * created inside that team, so the operator pastes them from the console and the step writes them
+ * to Vercel; without a terminal (or when skipped) it reports the manual transfer until Vercel has
+ * them.
+ */
+export const upstashStep = (context) => Effect.gen(function* () {
+    const upstash = context.credentials.upstash;
+    if (upstash === undefined)
+        return yield* factoryError('the factory item has no upstash section');
+    for (const name of [context.names.development, context.names.production]) {
+        const team = yield* findTeam(upstash.email, upstash.apiKey, name);
+        if (Option.isSome(team))
+            yield* decide(context, 'data', `Upstash team ${name}`);
+        else
+            yield* mutate(context, `create Upstash team ${name}`, createTeam(upstash.email, upstash.apiKey, name));
+    }
+    const handle = yield* requireProject(context);
+    if (Option.isNone(handle)) {
+        for (const name of [context.names.development, context.names.production]) {
+            yield* Console.log(`  would ask for ${name}'s QStash credentials (or copy them by hand)`);
+        }
+        return;
+    }
+    const groups = envGroups(handle.value);
+    const records = yield* listEnvRecords(context.credentials.vercel.teamId, handle.value.project.id);
+    const targets = [
+        { team: context.names.development, group: groups.preproduction, type: 'encrypted' },
+        { team: context.names.production, group: groups.production, type: 'sensitive' }
+    ];
+    for (const target of targets) {
+        if (groupHasKeys(records, target.group, qstashVariableKeys))
+            continue;
+        const values = context.dryRun ? Option.none() : yield* askQStash(target.team, target.group);
+        if (Option.isNone(values)) {
+            yield* Console.log(`  manual: copy ${target.team}'s EU QStash ${qstashVariableKeys.join(', ')} into Vercel (${target.group.label})`);
+            continue;
+        }
+        const { url, token, current, next } = values.value;
+        yield* writeGroup(context, handle.value, target.group, [
+            { key: 'QSTASH_URL', value: url, type: 'encrypted' },
+            { key: 'QSTASH_TOKEN', value: token, type: target.type },
+            { key: 'QSTASH_CURRENT_SIGNING_KEY', value: current, type: target.type },
+            { key: 'QSTASH_NEXT_SIGNING_KEY', value: next, type: target.type }
+        ]);
+    }
+});
+/**
+ * Asks the operator to paste a team's QStash `.env` block from the Upstash console (a team's
+ * QStash is only readable with a key created inside that team). An empty line skips.
+ */
+const askQStash = (team, group) => withTerminal(Effect.gen(function* () {
+    const secrets = yield* SecretInput;
+    let problem = '';
+    for (;;) {
+        const pasted = yield* secrets.readEnv(`\nQStash for ${team} → Vercel (${group.label})\n` +
+            `  1. Open https://console.upstash.com/qstash and switch to team ${team}\n` +
+            `     (team menu, top left), EU region (eu-central-1).\n` +
+            `  2. In Quickstart, copy the .env block (all 4 lines) and paste it here, then Enter.\n` +
+            `  Press Enter on an empty line to skip and copy them into Vercel later.\n` +
+            `${problem}QStash .env: `, qstashVariableKeys);
+        if (Option.isNone(pasted))
+            return Option.none();
+        const [url, token, current, next] = qstashVariableKeys.map(key => pasted.value.get(key));
+        const missing = qstashVariableKeys.filter(key => !pasted.value.has(key));
+        if (url === undefined ||
+            token === undefined ||
+            current === undefined ||
+            next === undefined) {
+            problem = `  Missing ${missing.join(', ')}; paste the whole block again.\n`;
+        }
+        else if (!isHttpsUrl(Redacted.value(url))) {
+            problem = '  QSTASH_URL must be an https URL; paste the whole block again.\n';
+        }
+        else {
+            return Option.some({ url, token, current, next });
+        }
+    }
+})).pipe(Effect.mapError(error => factoryError(error.message)));
+const isHttpsUrl = (value) => URL.canParse(value) && new URL(value).protocol === 'https:';

package/dist/factory/steps/vercel.js

@@ -0,0 +1,68 @@
+import { join } from 'node:path';
+import { Console, Effect, Option, Redacted, Schema } from 'effect';
+import { readPrivately } from '../../shared/private-file.js';
+import { decide, envGroups, factoryError, groupHasKeys, mutate, writeGroup } from '../context.js';
+import { createCustomEnvironment, createProject, linkCheckout, linkedRepository, listEnvRecords, setRootDirectory } from '../vercel-api.js';
+import { findProject } from '../context.js';
+/** Destructive E2E reset consent, present only in the custom `test` environment. */
+const resetConsentKey = 'ALLOW_E2E_DATABASE_RESET';
+const LinkedProject = Schema.fromJsonString(Schema.Struct({ projectId: Schema.String }));
+/**
+ * Vercel project `<repo>` linked to the GitHub repository (Root Directory = `provision.appDir`),
+ * its custom `test` environment, the `test`-only reset consent, and the checkout's link.
+ */
+export const vercelStep = (context) => Effect.gen(function* () {
+    const teamId = context.credentials.vercel.teamId;
+    const found = yield* findProject(context);
+    let handle = found;
+    if (Option.isSome(found)) {
+        const linked = linkedRepository(found.value.project);
+        if (linked !== undefined && linked !== context.checkout.repository) {
+            return yield* factoryError(`Vercel project ${context.names.project} is linked to ${linked}, not ${context.checkout.repository}`);
+        }
+        yield* decide(context, 'data', `Vercel project ${context.names.project}`);
+        const rootDirectory = found.value.project.rootDirectory ?? '.';
+        if (rootDirectory !== context.repoConfig.appDir) {
+            yield* mutate(context, `set the project Root Directory to ${context.repoConfig.appDir}`, setRootDirectory(teamId, found.value.project.id, context.repoConfig.appDir));
+        }
+    }
+    else {
+        const created = yield* mutate(context, `create Vercel project ${context.names.project} linked to ${context.checkout.repository}`, createProject(teamId, {
+            name: context.names.project,
+            repository: context.checkout.repository,
+            rootDirectory: context.repoConfig.appDir
+        }));
+        handle = Option.map(created, project => ({ project, testEnvironmentId: undefined }));
+    }
+    if (Option.isNone(handle)) {
+        yield* Console.log('  would create the test environment and its reset consent');
+        return;
+    }
+    let project = handle.value;
+    if (project.testEnvironmentId === undefined) {
+        const environment = yield* mutate(context, 'create the custom test environment', createCustomEnvironment(teamId, project.project.id, 'test'));
+        if (Option.isSome(environment)) {
+            project = { ...project, testEnvironmentId: environment.value.id };
+        }
+    }
+    if (project.testEnvironmentId !== undefined) {
+        const records = yield* listEnvRecords(teamId, project.project.id);
+        const test = envGroups(project).test;
+        if (!groupHasKeys(records, test, [resetConsentKey])) {
+            yield* writeGroup(context, project, test, [
+                { key: resetConsentKey, value: Redacted.make('1'), type: 'plain' }
+            ]);
+        }
+    }
+    const projectFile = join(context.appDirectory, '.vercel', 'project.json');
+    const existingLink = yield* readPrivately(projectFile).pipe(Effect.mapError(error => factoryError(error.message)));
+    const linkedProjectId = existingLink === undefined
+        ? undefined
+        : Option.getOrUndefined(Schema.decodeUnknownOption(LinkedProject)(existingLink))?.projectId;
+    if (linkedProjectId !== project.project.id) {
+        if (linkedProjectId !== undefined) {
+            return yield* factoryError(`${projectFile} links a different Vercel project; remove it and rerun`);
+        }
+        yield* mutate(context, `link ${context.appDirectory} to ${context.names.project}`, linkCheckout(teamId, context.appDirectory, context.names.project));
+    }
+});

package/dist/factory/vercel-api.js

@@ -0,0 +1,165 @@
+import { Effect, Option, Predicate, Redacted, Schema } from 'effect';
+import { capture, inherit } from '../shared/process.js';
+import { ProviderError } from './http.js';
+/**
+ * Vercel REST calls through the operator's authenticated `vercel` CLI (`vercel api`), always
+ * scoped to the factory's immutable `team_*` id. Request bodies go through stdin, so secret values
+ * never appear in argv; responses and diagnostics are never printed.
+ */
+const vercelApi = (teamId, label, path, options = {}) => Effect.gen(function* () {
+    const method = options.method ?? 'GET';
+    const separator = path.includes('?') ? '&' : '?';
+    const scopedPath = `${path}${separator}teamId=${encodeURIComponent(teamId)}`;
+    const args = ['api', scopedPath, '--raw', '--non-interactive', '--no-color', '--scope', teamId];
+    if (method !== 'GET')
+        args.push('-X', method);
+    if (method === 'DELETE')
+        args.push('--dangerously-skip-permissions');
+    if (options.body !== undefined)
+        args.push('--input', '-');
+    const result = yield* capture('vercel', args, options.body === undefined ? {} : { input: JSON.stringify(options.body) }).pipe(Effect.mapError(() => new ProviderError({ message: 'Vercel CLI (vercel) could not be started' })));
+    if (result.exitCode !== 0) {
+        const status = /\(\s*(\d{3})\s*\)\s*$/u.exec(result.stderr.trim())?.[1];
+        if (status === '404')
+            return Option.none();
+        return yield* new ProviderError({
+            message: `${label} failed${status === undefined ? '' : ` (${status})`}; Vercel response suppressed`,
+            ...(status === undefined ? {} : { status: Number(status) })
+        });
+    }
+    if (result.stdout.trim() === '')
+        return Option.some(undefined);
+    return yield* Effect.try({
+        try: () => JSON.parse(result.stdout),
+        catch: () => new ProviderError({ message: `${label}: Vercel returned invalid JSON` })
+    }).pipe(Effect.map(Option.some));
+});
+const decode = (label, schema, value) => Schema.decodeUnknownEffect(schema)(value).pipe(Effect.mapError(() => new ProviderError({ message: `${label}: unexpected Vercel response shape` })));
+const required = (label, value) => Option.match(value, {
+    onNone: () => Effect.fail(new ProviderError({ message: `${label}: not found` })),
+    onSome: Effect.succeed
+});
+// ---------------------------------------------------------------------------
+// projects
+// ---------------------------------------------------------------------------
+export const VercelProject = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    rootDirectory: Schema.optional(Schema.NullOr(Schema.String)),
+    link: Schema.optional(Schema.NullOr(Schema.Struct({
+        type: Schema.optional(Schema.String),
+        org: Schema.optional(Schema.String),
+        repo: Schema.optional(Schema.String)
+    })))
+});
+/** `owner/repo` of a project's Git link, when linked to GitHub. */
+export const linkedRepository = (project) => {
+    const link = project.link;
+    if (link === undefined || link === null || link.type !== 'github')
+        return undefined;
+    return link.org !== undefined && link.repo !== undefined ? `${link.org}/${link.repo}` : link.repo;
+};
+export const getProject = (teamId, name) => vercelApi(teamId, 'project lookup', `/v9/projects/${encodeURIComponent(name)}`).pipe(Effect.flatMap(Option.match({
+    onNone: () => Effect.succeed(Option.none()),
+    onSome: value => decode('project lookup', VercelProject, value).pipe(Effect.map(Option.some))
+})));
+export const createProject = (teamId, options) => vercelApi(teamId, 'project creation', '/v11/projects', {
+    method: 'POST',
+    body: {
+        name: options.name,
+        framework: 'nextjs',
+        gitRepository: { type: 'github', repo: options.repository },
+        ...(options.rootDirectory === '.' ? {} : { rootDirectory: options.rootDirectory })
+    }
+}).pipe(Effect.flatMap(value => required('project creation', value)), Effect.flatMap(value => decode('project creation', VercelProject, value)));
+export const setRootDirectory = (teamId, projectId, rootDirectory) => vercelApi(teamId, 'project update', `/v9/projects/${encodeURIComponent(projectId)}`, {
+    method: 'PATCH',
+    body: { rootDirectory: rootDirectory === '.' ? null : rootDirectory }
+}).pipe(Effect.asVoid);
+// ---------------------------------------------------------------------------
+// custom environments
+// ---------------------------------------------------------------------------
+const CustomEnvironment = Schema.Struct({ id: Schema.String, slug: Schema.String });
+const CustomEnvironmentList = Schema.Struct({ environments: Schema.Array(CustomEnvironment) });
+export const listCustomEnvironments = (teamId, projectId) => vercelApi(teamId, 'custom environment listing', `/v9/projects/${encodeURIComponent(projectId)}/custom-environments`).pipe(Effect.flatMap(value => required('custom environment listing', value)), Effect.flatMap(value => decode('custom environment listing', CustomEnvironmentList, value)), Effect.map(list => list.environments));
+export const createCustomEnvironment = (teamId, projectId, slug) => vercelApi(teamId, 'custom environment creation', `/v9/projects/${encodeURIComponent(projectId)}/custom-environments`, { method: 'POST', body: { slug, description: 'Disposable end-to-end test configuration' } }).pipe(Effect.flatMap(value => required('custom environment creation', value)), Effect.flatMap(value => decode('custom environment creation', CustomEnvironment, value)));
+export const EnvRecord = Schema.Struct({
+    id: Schema.String,
+    key: Schema.String,
+    type: Schema.String,
+    target: Schema.optional(Schema.Union([Schema.String, Schema.Array(Schema.String)])),
+    customEnvironmentIds: Schema.optional(Schema.Array(Schema.String))
+});
+const EnvList = Schema.Struct({
+    envs: Schema.Array(EnvRecord),
+    pagination: Schema.optional(Schema.NullOr(Schema.Struct({
+        next: Schema.optional(Schema.NullOr(Schema.Union([Schema.String, Schema.Number])))
+    })))
+});
+export const recordTargets = (record) => record.target === undefined
+    ? []
+    : Predicate.isString(record.target)
+        ? [record.target]
+        : record.target;
+export const listEnvRecords = (teamId, projectId) => Effect.gen(function* () {
+    const records = [];
+    const seen = new Set();
+    let until;
+    do {
+        const query = new URLSearchParams({ limit: '100' });
+        if (until !== undefined)
+            query.set('until', until);
+        const value = yield* vercelApi(teamId, 'environment variable listing', `/v10/projects/${encodeURIComponent(projectId)}/env?${query.toString()}`).pipe(Effect.flatMap(found => required('environment variable listing', found)));
+        const page = yield* decode('environment variable listing', EnvList, value);
+        records.push(...page.envs);
+        const next = page.pagination?.next;
+        until = next === undefined || next === null ? undefined : String(next);
+        if (until !== undefined && seen.has(until)) {
+            return yield* new ProviderError({ message: 'Vercel environment pagination cycled' });
+        }
+        if (until !== undefined)
+            seen.add(until);
+    } while (until !== undefined);
+    return records;
+});
+export const createEnvRecord = (teamId, projectId, record) => vercelApi(teamId, `environment variable ${record.key}`, `/v10/projects/${encodeURIComponent(projectId)}/env`, {
+    method: 'POST',
+    body: {
+        key: record.key,
+        value: Redacted.value(record.value),
+        type: record.type,
+        ...(record.target.length > 0 ? { target: record.target } : {}),
+        ...(record.customEnvironmentIds.length > 0
+            ? { customEnvironmentIds: record.customEnvironmentIds }
+            : {}),
+        comment: 'Managed by provision factory'
+    }
+}).pipe(Effect.asVoid);
+export const deleteEnvRecord = (teamId, projectId, recordId) => vercelApi(teamId, 'environment variable deletion', `/v9/projects/${encodeURIComponent(projectId)}/env/${encodeURIComponent(recordId)}`, { method: 'DELETE' }).pipe(Effect.asVoid);
+// ---------------------------------------------------------------------------
+// domains and checkout link
+// ---------------------------------------------------------------------------
+const ProjectDomain = Schema.Struct({
+    name: Schema.String,
+    verified: Schema.optional(Schema.Boolean)
+});
+export const getProjectDomain = (teamId, projectId, domain) => vercelApi(teamId, 'domain lookup', `/v9/projects/${encodeURIComponent(projectId)}/domains/${encodeURIComponent(domain)}`).pipe(Effect.flatMap(Option.match({
+    onNone: () => Effect.succeed(Option.none()),
+    onSome: value => decode('domain lookup', ProjectDomain, value).pipe(Effect.map(Option.some))
+})));
+export const addProjectDomain = (teamId, projectId, domain) => vercelApi(teamId, 'domain creation', `/v10/projects/${encodeURIComponent(projectId)}/domains`, {
+    method: 'POST',
+    body: { name: domain }
+}).pipe(Effect.flatMap(value => required('domain creation', value)), Effect.flatMap(value => decode('domain creation', ProjectDomain, value)));
+/** Links an app directory to the project (writes `.vercel/project.json`). */
+export const linkCheckout = (teamId, directory, project) => inherit('vercel', [
+    'link',
+    '--cwd',
+    directory,
+    '--project',
+    project,
+    '--scope',
+    teamId,
+    '--yes',
+    '--no-color'
+]).pipe(Effect.mapError(error => new ProviderError({ message: error.message })));

package/dist/package-info.js

@@ -0,0 +1,15 @@
+import { fileURLToPath } from 'node:url';
+import { Data, Effect, FileSystem, Schema } from 'effect';
+const PackageInfo = Schema.Struct({
+    name: Schema.String,
+    version: Schema.String
+});
+export class PackageInfoError extends Data.TaggedError('PackageInfoError') {
+}
+// `src/` (development) and `dist/` (published) both sit one level below the package root.
+const packageJsonPath = fileURLToPath(new URL('../package.json', import.meta.url));
+export const readPackageInfo = Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const text = yield* fs.readFileString(packageJsonPath);
+    return yield* Schema.decodeUnknownEffect(Schema.fromJsonString(PackageInfo))(text);
+}).pipe(Effect.mapError(cause => new PackageInfoError({ message: `cannot read provision package.json: ${cause.message}` })));

package/dist/shared/agent.js

@@ -0,0 +1,28 @@
+/**
+ * Detects a coding agent from the environment it sets for the commands it runs (the same signals
+ * as `@vercel/detect-agent`). This only shapes the experience: what keeps agents from approving
+ * factory runs is the passphrase read from the terminal, not this check.
+ */
+const agentVariables = [
+    ['CURSOR_TRACE_ID', 'cursor'],
+    ['CURSOR_AGENT', 'cursor-cli'],
+    ['GEMINI_CLI', 'gemini'],
+    ['CODEX_SANDBOX', 'codex'],
+    ['CODEX_CI', 'codex'],
+    ['CODEX_THREAD_ID', 'codex'],
+    ['ANTIGRAVITY_AGENT', 'antigravity'],
+    ['AUGMENT_AGENT', 'augment-cli'],
+    ['OPENCODE', 'opencode'],
+    ['OPENCODE_CLIENT', 'opencode'],
+    ['CLAUDECODE', 'claude'],
+    ['CLAUDE_CODE', 'claude'],
+    ['COPILOT_MODEL', 'github-copilot'],
+    ['COPILOT_ALLOW_ALL', 'github-copilot']
+];
+/** The agent running this process, or `undefined` for a human. `AI_AGENT` names it explicitly. */
+export const detectAgent = (env = process.env) => {
+    const named = env['AI_AGENT']?.trim();
+    if (named !== undefined && named !== '')
+        return named;
+    return agentVariables.find(([variable]) => (env[variable] ?? '') !== '')?.[1];
+};