@magoz/provision 0.0.0-stage → 0.1.0

package/dist/factory/commands.js

@@ -0,0 +1,173 @@
+import { format } from 'node:util';
+import { Console, Effect, Option, Result } from 'effect';
+import { Command, Flag } from 'effect/cli';
+import { resolveAppDirectory } from '../env/paths.js';
+import { resolveWorkspace } from '../shared/git.js';
+import { factorySteps, readRepoConfig } from '../shared/repo-config.js';
+import { humanOnly } from './approval.js';
+import { factoryError, onExistingPolicies, withTerminal } from './context.js';
+import { decodeCredentials, readItemFields } from './onepassword.js';
+import { resolveOpAuth } from './op-credential.js';
+import { readRegistry } from './registry.js';
+import { domainStep } from './steps/domain.js';
+import { neonStep } from './steps/neon.js';
+import { r2Step } from './steps/r2.js';
+import { reportsStep } from './steps/reports.js';
+import { resendStep } from './steps/resend.js';
+import { secretsStep } from './steps/secrets.js';
+import { upstashStep } from './steps/upstash.js';
+import { vercelStep } from './steps/vercel.js';
+const steps = {
+    vercel: vercelStep,
+    neon: neonStep,
+    r2: r2Step,
+    upstash: upstashStep,
+    resend: resendStep,
+    reports: reportsStep,
+    secrets: secretsStep,
+    domain: domainStep
+};
+/**
+ * Runs one step with its output buffered and printed as one block when it ends, so concurrent
+ * steps do not interleave. A failing step never interrupts the others mid-mutation.
+ */
+const runStep = (step, context) => Effect.gen(function* () {
+    const lines = [`\n[${step}]`];
+    const console = yield* Console.Console;
+    const buffered = {
+        ...console,
+        log: (...args) => {
+            lines.push(format(...args));
+        }
+    };
+    yield* steps[step](context).pipe(Effect.provideService(Console.Console, buffered), Effect.tapError(error => Effect.sync(() => lines.push(`  failed: ${error.message}`))), 
+    // Waits while another step is prompting, so output never lands in the middle of a prompt.
+    Effect.ensuring(Effect.suspend(() => withTerminal(Console.log(lines.join('\n'))))));
+});
+const isFactoryStep = (value) => factorySteps.some(step => step === value);
+/** `--only` narrows the repository's steps; execution order is always the canonical order. */
+export const selectSteps = (configured, only) => Effect.gen(function* () {
+    if (Option.isNone(only))
+        return configured;
+    const requested = only.value
+        .split(',')
+        .map(step => step.trim())
+        .filter(step => step.length > 0);
+    const unknown = requested.filter(step => !isFactoryStep(step));
+    if (unknown.length > 0 || requested.length === 0) {
+        return yield* factoryError(`--only accepts ${factorySteps.join(', ')}${unknown.length > 0 ? `; unknown: ${unknown.join(', ')}` : ''}`);
+    }
+    const outside = requested.filter(step => !configured.some(candidate => candidate === step));
+    if (outside.length > 0) {
+        return yield* factoryError(`--only names steps this repository does not declare in provision.factory.steps: ${outside.join(', ')}`);
+    }
+    return configured.filter(step => requested.includes(step));
+});
+/** Reads one factory's item with that factory's own credentials. */
+const readFactory = (name, entry) => resolveOpAuth(name).pipe(Effect.flatMap(auth => readItemFields(entry, auth)), Effect.flatMap(decodeCredentials), Effect.map(credentials => ({ name, credentials })));
+/**
+ * The explicit factory, or the single registered factory for the checkout's GitHub owner. The
+ * owner recorded by `config add` selects without reading any other factory's item; entries
+ * without it fall back to reading their items.
+ */
+const selectFactory = (registry, requested, owner) => Effect.gen(function* () {
+    const entries = Object.entries(registry.factories);
+    if (entries.length === 0) {
+        return yield* factoryError('no factories registered; run: provision config add');
+    }
+    if (Option.isSome(requested)) {
+        const entry = registry.factories[requested.value];
+        if (entry === undefined) {
+            return yield* factoryError(`no factory named ${requested.value}`);
+        }
+        return yield* readFactory(requested.value, entry);
+    }
+    const recorded = entries.filter(([, entry]) => entry.githubOwner === owner);
+    const unrecorded = entries.filter(([, entry]) => entry.githubOwner === undefined);
+    const matches = [];
+    for (const [name, entry] of recorded)
+        matches.push(yield* readFactory(name, entry));
+    if (matches.length === 0) {
+        for (const [name, entry] of unrecorded) {
+            const factory = yield* readFactory(name, entry);
+            if (factory.credentials.githubOwner === owner)
+                matches.push(factory);
+        }
+    }
+    const match = matches.length === 1 ? matches[0] : undefined;
+    if (match === undefined) {
+        return yield* factoryError(matches.length === 0
+            ? `no registered factory has github.owner ${owner}; pass --factory`
+            : `several factories have github.owner ${owner}; pass --factory`);
+    }
+    return match;
+});
+const domainPattern = /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+export const runFactory = (options) => Effect.gen(function* () {
+    const workspace = yield* resolveWorkspace(Option.some(options.checkout));
+    const [owner, name] = workspace.repository.split('/');
+    if (owner === undefined || name === undefined || name === '') {
+        return yield* factoryError('the checkout needs a GitHub origin remote (owner/repository)');
+    }
+    const repoConfig = yield* readRepoConfig(workspace.root);
+    const selected = yield* selectSteps(repoConfig.factory.steps, options.only);
+    const domain = Option.getOrUndefined(options.domain)?.toLowerCase();
+    if (domain !== undefined && !domainPattern.test(domain)) {
+        return yield* factoryError(`--domain must be a host name such as app.example.com`);
+    }
+    const needsDomain = selected.filter(step => step === 'r2' || step === 'domain');
+    if (domain === undefined && needsDomain.length > 0) {
+        return yield* factoryError(`--domain is required for ${needsDomain.join(', ')}`);
+    }
+    const emailFrom = Option.getOrUndefined(options.emailFrom)?.trim().toLowerCase();
+    if (emailFrom !== undefined && !/^[^\s@<>]+@[a-z0-9.-]+\.[a-z]{2,}$/.test(emailFrom)) {
+        return yield* factoryError('--email-from must be an address such as noreply@acme.com');
+    }
+    const factory = yield* selectFactory(yield* readRegistry, options.factory, owner);
+    if (factory.credentials.githubOwner !== owner) {
+        return yield* factoryError(`factory ${factory.name} serves GitHub owner ${factory.credentials.githubOwner}, not ${owner}`);
+    }
+    const app = yield* resolveAppDirectory(workspace.root, repoConfig.appDir);
+    const context = {
+        factory: factory.name,
+        credentials: factory.credentials,
+        checkout: { root: workspace.root, owner, name, repository: workspace.repository },
+        repoConfig,
+        appDirectory: app.directory,
+        domain,
+        senderName: Option.getOrElse(options.senderName, () => name),
+        emailFrom,
+        neonParentBranch: Option.getOrUndefined(options.neonParentBranch),
+        dryRun: options.dryRun,
+        onExisting: options.onExisting,
+        names: { project: name, development: `${name}-dev`, production: `${name}-prod` }
+    };
+    yield* Console.log(`provision factory: ${workspace.repository} with factory ${factory.name}` +
+        `${options.dryRun ? ' (dry run: nothing is changed)' : ''}\n` +
+        `  steps: ${selected.join(', ')}`);
+    // Every other step needs the Vercel project, so `vercel` runs alone first.
+    if (selected.includes('vercel'))
+        yield* runStep('vercel', context);
+    const results = yield* Effect.forEach(selected.filter(step => step !== 'vercel'), step => runStep(step, context).pipe(Effect.result), { concurrency: 'unbounded' });
+    const failed = results.flatMap(result => (Result.isFailure(result) ? [result.failure] : []));
+    if (failed.length === 1 && failed[0] !== undefined)
+        return yield* failed[0];
+    if (failed.length > 1) {
+        return yield* factoryError(`${failed.length} steps failed: ${failed.map(error => error.message).join('; ')}`);
+    }
+    yield* Console.log(`\nprovision factory: ${options.dryRun ? 'dry run complete' : 'done'}` +
+        `\n  next: provision env --repo ${workspace.root} --database`);
+});
+export const factoryCommand = Command.make('factory', {
+    checkout: Flag.String('checkout').pipe(Flag.withDescription('company checkout (default: current directory)'), Flag.withDefault('.')),
+    domain: Flag.String('domain').pipe(Flag.withDescription('production host, e.g. app.example.com (r2 and domain steps)'), Flag.optional),
+    senderName: Flag.String('sender-name').pipe(Flag.withDescription('AUTH_EMAIL_FROM display name (default: repository name)'), Flag.optional),
+    emailFrom: Flag.String('email-from').pipe(Flag.withDescription('AUTH_EMAIL_FROM address, e.g. noreply@acme.com (default: noreply@<resend.sending_domain>)'), Flag.optional),
+    factory: Flag.String('factory').pipe(Flag.withDescription('factory name (default: the factory whose github.owner matches)'), Flag.optional),
+    only: Flag.String('only').pipe(Flag.withDescription(`comma-separated subset of: ${factorySteps.join(', ')}`), Flag.optional),
+    onExisting: Flag.Literals('on-existing', onExistingPolicies).pipe(Flag.withDescription('what to do when a resource exists (data is only ever reused)'), Flag.withDefault('ask')),
+    neonParentBranch: Flag.String('neon-parent-branch').pipe(Flag.withDescription('existing-branch mode: sandbox parent branch id'), Flag.optional),
+    dryRun: Flag.Boolean('dry-run').pipe(Flag.withDescription('inspect and print planned changes without making them'), Flag.withDefault(false))
+}, options => humanOnly(runFactory(options).pipe(Effect.catch(error => Console.error(`provision factory: ${error.message}`).pipe(Effect.andThen(Effect.sync(() => {
+    process.exitCode = 2;
+}))))))).pipe(Command.withDescription('Create provider projects and resources with factory admin keys, mint scoped keys, and write them to Vercel.'));

package/dist/factory/config-commands.js

@@ -0,0 +1,215 @@
+import { Console, Effect, Option, Redacted, Result } from 'effect';
+import { Argument, Command, Flag, Prompt } from 'effect/cli';
+import { humanOnly } from './approval.js';
+import { report } from '../shared/output.js';
+import { decodeCredentials, describeSections, parseItemFields, readItemFields, readItemJson } from './onepassword.js';
+import { ensureFactoryItem, missingTemplateFields, onboardFactory } from './onboarding.js';
+import { readHiddenLine } from './passphrase.js';
+import { describeOpAuth, opAuthKind, opCredentialFile, parseServiceAccountToken, removeServiceAccountToken, resolveOpAuth, storeServiceAccountToken } from './op-credential.js';
+import { readRegistry, RegistryError, validateFactoryName, writeRegistry } from './registry.js';
+const setExitCode = (code) => Effect.sync(() => {
+    process.exitCode = code;
+});
+const handled = (effect) => effect.pipe(Effect.catch(error => Console.error(`provision config: ${error.message}`).pipe(Effect.andThen(setExitCode(2)))));
+/** `handled`, for commands that read factory items: only a human can approve them. */
+const approved = (effect) => humanOnly(handled(effect));
+const jsonFlag = Flag.Boolean('json').pipe(Flag.withDescription('machine-readable output'), Flag.withDefault(false));
+/** Uses the flag value, or prompts when interactive; agents must pass every flag. */
+const valueOrPrompt = (value, message, fallback) => Option.isSome(value)
+    ? Effect.succeed(value.value)
+    : process.stdin.isTTY === true && process.stdout.isTTY === true
+        ? Prompt.run(Prompt.String(fallback === undefined ? { message } : { message, default: fallback })).pipe(Effect.mapError(() => new RegistryError({ message: 'cancelled' })))
+        : fallback === undefined
+            ? Effect.fail(new RegistryError({ message: `${message}: pass it as a flag` }))
+            : Effect.succeed(fallback);
+const requiredSections = new Set(['github', 'vercel']);
+/** One line per section: status plus the fields still to fill. */
+const sectionTable = (sections) => sections
+    .map(section => {
+    const status = section.status === 'complete'
+        ? '✓ complete'
+        : section.status === 'partial'
+            ? `partial: also fill ${section.missing.join(', ')}`
+            : `empty: ${section.missing.join(', ')}${requiredSections.has(section.section) ? ' (required)' : ''}`;
+    return `  ${section.section.padEnd(16)} ${status}`;
+})
+    .join('\n');
+/** Whether `op` already has a service-account credential for this factory. */
+const hasServiceAccount = (factory) => Effect.map(opAuthKind(factory), kind => kind !== 'session');
+const listFactories = (json) => Effect.gen(function* () {
+    const registry = yield* readRegistry;
+    if (json)
+        return yield* Console.log(JSON.stringify(registry, null, 2));
+    const entries = Object.entries(registry.factories);
+    if (entries.length === 0) {
+        return yield* Console.log('no factories registered; run: provision config add');
+    }
+    yield* Console.log(entries
+        .map(([name, entry]) => `${name}  vault=${entry.vault} item=${entry.item}${entry.account === undefined ? '' : ` account=${entry.account}`}`)
+        .join('\n'));
+});
+/** Reads the factory item and summarizes it without revealing any value. */
+const inspectFactory = (entry, auth) => Effect.gen(function* () {
+    const fields = yield* readItemFields(entry, auth);
+    const credentials = yield* decodeCredentials(fields);
+    return {
+        githubOwner: credentials.githubOwner,
+        vercelTeamId: credentials.vercel.teamId,
+        sections: describeSections(fields)
+    };
+});
+const add = Command.make('add', {
+    name: Flag.String('name').pipe(Flag.withDescription('factory name, e.g. acme'), Flag.optional),
+    vault: Flag.String('vault').pipe(Flag.withDescription('1Password vault'), Flag.optional),
+    item: Flag.String('item').pipe(Flag.withDescription('1Password item (default: provision)'), Flag.optional),
+    account: Flag.String('account').pipe(Flag.withDescription('1Password account (default: the CLI default)'), Flag.optional),
+    yes: Flag.Boolean('yes').pipe(Flag.withDescription('create a missing vault or item without asking'), Flag.withDefault(false))
+}, options => approved(Effect.gen(function* () {
+    const name = yield* valueOrPrompt(options.name, 'Factory name').pipe(Effect.flatMap(validateFactoryName));
+    const vault = yield* valueOrPrompt(options.vault, '1Password vault', `provision-${name}`);
+    const item = yield* valueOrPrompt(options.item, '1Password item', 'provision');
+    const location = Option.match(options.account, {
+        onNone: () => ({ vault, item }),
+        onSome: account => ({ vault, item, account })
+    });
+    // First run: create the vault, item, and read-only service account with the operator's
+    // own sign-in. Reruns reuse the stored token and only need the passphrase.
+    if (!(yield* hasServiceAccount(name))) {
+        yield* onboardFactory(name, vault, item, { assumeYes: options.yes });
+    }
+    const auth = yield* resolveOpAuth(name);
+    const first = yield* Effect.result(readItemJson(location, auth));
+    if (Result.isFailure(first) && first.failure.notFound !== true) {
+        return yield* first.failure;
+    }
+    const problem = Result.isFailure(first)
+        ? `Item ${item} does not exist in ${vault} yet; signing in to 1Password to create it.`
+        : missingTemplateFields(first.success).length > 0
+            ? `Item ${item} is missing ${missingTemplateFields(first.success).length} field(s); signing in to 1Password to add them.`
+            : undefined;
+    // A missing or hand-made item: create it, or add the missing fields (empty), with the
+    // operator's sign-in. Existing values are never touched.
+    if (problem !== undefined) {
+        yield* Console.log(problem);
+        yield* ensureFactoryItem(vault, item, { assumeYes: options.yes });
+    }
+    const json = problem === undefined && Result.isSuccess(first)
+        ? first.success
+        : yield* readItemJson(location, auth);
+    const fields = yield* parseItemFields(json);
+    const sections = describeSections(fields);
+    const credentials = yield* Effect.result(decodeCredentials(fields));
+    const incomplete = sections.some(section => section.status === 'partial' ||
+        (section.status === 'absent' && requiredSections.has(section.section)));
+    // Every section is filled but a value is invalid: say which, not "fill in the item".
+    if (Result.isFailure(credentials) && !incomplete) {
+        yield* Console.log(sectionTable(sections));
+        return yield* new RegistryError({
+            message: `${credentials.failure.message} (item ${item} in vault ${vault})`
+        });
+    }
+    if (Result.isFailure(credentials)) {
+        yield* Console.log([
+            '',
+            `Next: fill in item ${item} in vault ${vault} (1Password app or web).`,
+            'github and vercel are required; fill the other sections for the providers this factory uses.',
+            '',
+            sectionTable(sections),
+            '',
+            `Then run: provision config add --name ${name}${vault === `provision-${name}` ? '' : ` --vault ${vault}`}`
+        ].join('\n'));
+        return yield* setExitCode(1);
+    }
+    const registry = yield* readRegistry;
+    const entry = { ...location, githubOwner: credentials.success.githubOwner };
+    yield* writeRegistry({ factories: { ...registry.factories, [name]: entry } });
+    yield* Console.log(sectionTable(sections));
+    yield* report(false, {
+        status: name in registry.factories ? 'updated' : 'added',
+        factory: name,
+        auth: describeAuth(auth),
+        github_owner: credentials.success.githubOwner,
+        vercel_team: credentials.success.vercel.teamId
+    });
+}))).pipe(Command.withDescription('Set up a factory: create its vault, item, and read-only service account if needed, then register it.'));
+const list = Command.make('list', { json: jsonFlag }, ({ json }) => handled(listFactories(json))).pipe(Command.withDescription('List registered factories.'));
+const remove = Command.make('remove', { name: Argument.String('name').pipe(Argument.withDescription('factory name')) }, ({ name }) => handled(Effect.gen(function* () {
+    const registry = yield* readRegistry;
+    if (!(name in registry.factories)) {
+        return yield* new RegistryError({ message: `no factory named ${name}` });
+    }
+    const { [name]: _removed, ...rest } = registry.factories;
+    yield* writeRegistry({ factories: rest });
+    yield* Console.log(`removed factory ${name}`);
+}))).pipe(Command.withDescription('Unregister a factory (the 1Password item is untouched).'));
+const verify = Command.make('verify', {
+    name: Argument.String('name').pipe(Argument.withDescription('factory name (default: all)'), Argument.optional),
+    json: jsonFlag
+}, ({ json, name }) => approved(Effect.gen(function* () {
+    const registry = yield* readRegistry;
+    const selected = Object.entries(registry.factories).filter(([candidate]) => Option.match(name, { onNone: () => true, onSome: wanted => wanted === candidate }));
+    if (selected.length === 0) {
+        return yield* new RegistryError({ message: 'no matching factory registered' });
+    }
+    const results = yield* Effect.forEach(selected, ([factory, entry]) => Effect.gen(function* () {
+        const auth = yield* resolveOpAuth(factory);
+        const inspected = yield* inspectFactory(entry, auth);
+        return { auth: describeAuth(auth), ...inspected };
+    }).pipe(Effect.map(inspected => ({ factory, ok: true, ...inspected })), Effect.catch(error => Effect.succeed({ factory, ok: false, error: error.message }))));
+    if (json)
+        yield* Console.log(JSON.stringify(results, null, 2));
+    else {
+        for (const result of results) {
+            yield* Console.log(result.ok
+                ? `${result.factory}: ok (github ${result.githubOwner}, vercel ${result.vercelTeamId}, auth ${result.auth})\n` +
+                    result.sections
+                        .map(section => `  ${section.section.padEnd(16)} ${section.status}${section.missing.length > 0 && section.status === 'partial' ? ` (missing ${section.missing.join(', ')})` : ''}`)
+                        .join('\n')
+                : `${result.factory}: ${result.error}`);
+        }
+    }
+    if (results.some(result => !result.ok))
+        yield* setExitCode(1);
+}))).pipe(Command.withDescription("Read each factory's 1Password item and report its sections."));
+const describeAuth = (auth) => auth.kind === 'environment'
+    ? 'service account (OP_SERVICE_ACCOUNT_TOKEN)'
+    : auth.kind === 'credential'
+        ? `passphrase-protected service account (${auth.file})`
+        : 'op session or desktop app';
+const readStdin = Effect.promise(async () => {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        if (chunk instanceof Uint8Array)
+            chunks.push(chunk);
+        else if (typeof chunk === 'string')
+            chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+});
+const factoryFlag = Flag.String('factory').pipe(Flag.withDescription('factory the token belongs to (it may be registered afterwards)'));
+const opTokenSet = Command.make('set', { factory: factoryFlag }, ({ factory }) => approved(Effect.gen(function* () {
+    const name = yield* validateFactoryName(factory);
+    const raw = process.stdin.isTTY === true
+        ? Redacted.value(yield* readHiddenLine('1Password service-account token: '))
+        : yield* readStdin;
+    const token = yield* parseServiceAccountToken(raw);
+    const file = yield* storeServiceAccountToken(name, token);
+    yield* Console.log(`stored the ${name} service-account token encrypted at ${file}`);
+}))).pipe(Command.withDescription('Store a factory service-account token (stdin or hidden prompt), sealed with the provision passphrase and systemd-creds.'));
+const opTokenStatus = Command.make('status', {}, () => handled(Effect.gen(function* () {
+    const registry = yield* readRegistry;
+    const names = Object.keys(registry.factories);
+    if (names.length === 0)
+        return yield* Console.log('no factories registered');
+    for (const name of names) {
+        yield* Console.log(`${name}: ${yield* describeOpAuth(name)}`);
+    }
+}))).pipe(Command.withDescription('Show how provision authenticates 1Password for each factory.'));
+const opTokenRemove = Command.make('remove', { factory: factoryFlag }, ({ factory }) => handled(Effect.gen(function* () {
+    const name = yield* validateFactoryName(factory);
+    const file = yield* opCredentialFile(name);
+    const removed = yield* removeServiceAccountToken(name);
+    yield* Console.log(removed ? `removed ${file}` : `no stored token at ${file}`);
+}))).pipe(Command.withDescription('Delete the stored token (revoke it in 1Password: Developer > Service accounts).'));
+const opToken = Command.make('op-token').pipe(Command.withDescription("Manage each factory's 1Password service-account token."), Command.withSubcommands([opTokenSet, opTokenStatus, opTokenRemove]));
+export const configCommand = Command.make('config', { json: jsonFlag }, ({ json }) => handled(listFactories(json))).pipe(Command.withDescription('Manage factories: which 1Password item holds each factory account set.'), Command.withSubcommands([add, list, remove, verify, opToken]));

package/dist/factory/context.js

@@ -0,0 +1,129 @@
+import { Console, Data, Effect, Option, Semaphore } from 'effect';
+import { Prompt } from 'effect/cli';
+import { createEnvRecord, deleteEnvRecord, getProject, listCustomEnvironments, listEnvRecords, recordTargets } from './vercel-api.js';
+export class FactoryError extends Data.TaggedError('FactoryError') {
+}
+export const onExistingPolicies = ['ask', 'reuse', 'overwrite', 'abort'];
+export const factoryError = (message) => new FactoryError({ message });
+const interactive = () => process.stdin.isTTY === true && process.stdout.isTTY === true;
+/** Concurrent steps share one terminal: one prompt (or group of prompts) at a time. */
+const promptLock = Semaphore.makeUnsafe(1);
+export const withTerminal = (effect) => promptLock.withPermits(1)(effect);
+/** Decides what to do with an existing resource: `reuse` or `overwrite` (abort fails). */
+export const decide = (context, kind, description) => Effect.gen(function* () {
+    if (context.dryRun) {
+        yield* Console.log(`  exists: ${description} (on-existing=${context.onExisting})`);
+        return 'reuse';
+    }
+    if (context.onExisting === 'abort') {
+        return yield* factoryError(`${description} already exists (--on-existing=abort)`);
+    }
+    if (context.onExisting === 'reuse')
+        return 'reuse';
+    if (context.onExisting === 'overwrite') {
+        if (kind === 'data') {
+            yield* Console.log(`  reusing ${description}: data is never overwritten`);
+            return 'reuse';
+        }
+        return 'overwrite';
+    }
+    if (!interactive()) {
+        return yield* factoryError(`${description} already exists and prompting is unavailable; pass --on-existing`);
+    }
+    const warning = kind === 'secret'
+        ? ' (overwriting invalidates sessions, encrypted data, or subscriptions that depend on it)'
+        : kind === 'key'
+            ? ' (overwriting rotates the key)'
+            : '';
+    const choice = yield* Prompt.run(Prompt.Select({
+        message: `${description} already exists${warning}`,
+        choices: [
+            { title: 'Reuse', value: 'reuse' },
+            ...(kind === 'data' ? [] : [{ title: 'Overwrite', value: 'overwrite' }]),
+            { title: 'Abort', value: 'abort' }
+        ]
+    })).pipe(Effect.mapError(() => factoryError('cancelled')), withTerminal);
+    if (choice === 'abort')
+        return yield* factoryError(`aborted at ${description}`);
+    return choice;
+});
+/** Runs a mutation, or only describes it in a dry run (`None`). */
+export const mutate = (context, description, effect) => context.dryRun
+    ? Console.log(`  would ${description}`).pipe(Effect.as(Option.none()))
+    : Console.log(`  ${description}`).pipe(Effect.andThen(effect), Effect.map(Option.some));
+/** The company Vercel project and its `test` environment, created by the `vercel` step. */
+export const findProject = (context) => Effect.gen(function* () {
+    const teamId = context.credentials.vercel.teamId;
+    const project = yield* getProject(teamId, context.names.project);
+    if (Option.isNone(project))
+        return Option.none();
+    const environments = yield* listCustomEnvironments(teamId, project.value.id);
+    return Option.some({
+        project: project.value,
+        testEnvironmentId: environments.find(environment => environment.slug === 'test')?.id
+    });
+});
+/** Steps after `vercel` need the project; in a dry run on a fresh repository it does not exist. */
+export const requireProject = (context) => findProject(context).pipe(Effect.flatMap(Option.match({
+    onNone: () => context.dryRun
+        ? Effect.succeed(Option.none())
+        : Effect.fail(factoryError(`Vercel project ${context.names.project} does not exist; run the vercel step first`)),
+    onSome: handle => handle.testEnvironmentId === undefined && !context.dryRun
+        ? Effect.fail(factoryError('Vercel project has no test environment; run the vercel step'))
+        : Effect.succeed(Option.some(handle))
+})));
+/** Development + Preview + `test` vs Production, plus single-target groups. */
+export const envGroups = (handle) => {
+    const test = handle.testEnvironmentId === undefined ? [] : [handle.testEnvironmentId];
+    return {
+        preproduction: {
+            label: 'Development, Preview, test',
+            target: ['development', 'preview'],
+            customEnvironmentIds: test
+        },
+        production: { label: 'Production', target: ['production'], customEnvironmentIds: [] },
+        development: { label: 'Development', target: ['development'], customEnvironmentIds: [] },
+        test: { label: 'test', target: [], customEnvironmentIds: test },
+        all: {
+            label: 'all environments',
+            target: ['development', 'preview', 'production'],
+            customEnvironmentIds: test
+        }
+    };
+};
+const covers = (record, group) => {
+    const targets = recordTargets(record);
+    const custom = record.customEnvironmentIds ?? [];
+    return (group.target.every(target => targets.includes(target)) &&
+        group.customEnvironmentIds.every(id => custom.includes(id)));
+};
+const overlaps = (record, group) => recordTargets(record).some(target => group.target.some(wanted => wanted === target)) ||
+    (record.customEnvironmentIds ?? []).some(id => group.customEnvironmentIds.includes(id));
+const containedIn = (record, group) => recordTargets(record).every(target => group.target.some(wanted => wanted === target)) &&
+    (record.customEnvironmentIds ?? []).every(id => group.customEnvironmentIds.includes(id));
+/** Whether every key has a record covering the whole group. */
+export const groupHasKeys = (records, group, keys) => keys.every(key => records.some(record => record.key === key && covers(record, group)));
+/**
+ * Replaces the group's records for each key: overlapping records are deleted, then one record per
+ * key is created. A record that spans environments outside the group is never touched.
+ */
+export const writeGroup = (context, handle, group, entries) => mutate(context, `write ${entries.map(entry => entry.key).join(', ')} to Vercel (${group.label})`, Effect.gen(function* () {
+    const teamId = context.credentials.vercel.teamId;
+    const records = yield* listEnvRecords(teamId, handle.project.id);
+    for (const entry of entries) {
+        const existing = records.filter(record => record.key === entry.key && overlaps(record, group));
+        const spanning = existing.filter(record => !containedIn(record, group));
+        if (spanning.length > 0) {
+            return yield* factoryError(`Vercel ${entry.key} has a record that also targets environments outside ${group.label}; split it manually`);
+        }
+        for (const record of existing)
+            yield* deleteEnvRecord(teamId, handle.project.id, record.id);
+        yield* createEnvRecord(teamId, handle.project.id, {
+            key: entry.key,
+            value: entry.value,
+            type: entry.type,
+            target: group.target,
+            customEnvironmentIds: group.customEnvironmentIds
+        });
+    }
+}));

package/dist/factory/http.js

@@ -0,0 +1,37 @@
+import { Data, Effect, Option, Schema } from 'effect';
+import { HttpClient, HttpClientRequest } from 'effect/http';
+export class ProviderError extends Data.TaggedError('ProviderError') {
+}
+/**
+ * A provider JSON request. Failures name only the action and status: response bodies, URLs with
+ * query strings, and credentials never reach errors or output.
+ */
+export const requestJson = (label, url, schema, options) => Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const base = HttpClientRequest.make(options.method ?? 'GET')(url).pipe(HttpClientRequest.setHeaders({ Accept: 'application/json', ...options.headers }));
+    const request = options.body === undefined
+        ? base
+        : yield* HttpClientRequest.bodyJson(base, options.body).pipe(Effect.mapError(() => new ProviderError({ message: `${label}: invalid request body` })));
+    const response = yield* client
+        .execute(request)
+        .pipe(Effect.mapError(() => new ProviderError({ message: `${label}: provider unreachable` })));
+    if (options.allowNotFound === true && response.status === 404) {
+        return Option.none();
+    }
+    if (response.status >= 400) {
+        return yield* new ProviderError({
+            message: `${label} failed (${response.status}); provider response suppressed`,
+            status: response.status
+        });
+    }
+    if (response.status === 204) {
+        return yield* Schema.decodeUnknownEffect(schema)(undefined).pipe(Effect.map(Option.some), Effect.mapError(() => new ProviderError({ message: `${label}: unexpected empty provider response` })));
+    }
+    const json = yield* response.json.pipe(Effect.mapError(() => new ProviderError({ message: `${label}: provider returned invalid JSON` })));
+    return yield* Schema.decodeUnknownEffect(schema)(json).pipe(Effect.map(Option.some), Effect.mapError(() => new ProviderError({ message: `${label}: unexpected provider response shape` })));
+});
+/** `requestJson` for calls where 404 is an error: returns the decoded body. */
+export const requestJsonRequired = (label, url, schema, options) => requestJson(label, url, schema, options).pipe(Effect.flatMap(Option.match({
+    onNone: () => Effect.fail(new ProviderError({ message: `${label}: not found` })),
+    onSome: Effect.succeed
+})));