@magoz/provision 0.0.0-stage → 0.1.1

package/dist/env/provision.js

@@ -0,0 +1,320 @@
+import { Cause, Console, Effect, Exit, FileSystem, Option, Path } from 'effect';
+import { Prompt } from 'effect/cli';
+import { readLease, writeLease } from '../db/lease.js';
+import { createLease, releaseLease } from '../db/operations.js';
+import { gitOutput } from '../shared/git.js';
+import { readPrivately, writePrivately } from '../shared/private-file.js';
+import { inherit } from '../shared/process.js';
+import { readRepoConfig } from '../shared/repo-config.js';
+import { defaultDatabaseUrlKeys } from '../shared/sandbox-profile.js';
+import { fail } from './domain.js';
+import { installDependencies } from './install.js';
+import { ensureLocalDirectory, ensurePrivateMode, ensureProvisionPaths, ensureSecretPath, resolveAppDirectory, resolveCheckout } from './paths.js';
+import { ensureNoLocalResetConsent, keepExistingDatabaseUrls, stripPulledEnvironment } from './sanitize.js';
+import { ensureVercelLink, listExplicitVercelKeys, pullVercelEnvironment, readVercelIdentity } from './vercel.js';
+const io = (message) => (effect) => Effect.mapError(effect, () => fail(message));
+const resolveEnvConflict = (policy, nonInteractive, localExists, testExists) => Effect.gen(function* () {
+    if (!localExists && !testExists)
+        return 'overwrite';
+    const existing = [localExists ? '.env.local' : undefined, testExists ? '.env.test' : undefined]
+        .filter(file => file !== undefined)
+        .join(' and ');
+    const bothExist = localExists && testExists;
+    const existence = bothExist ? 'already exist' : 'already exists';
+    if (policy === 'error') {
+        return yield* fail(`${existing} ${existence}; use --env-conflict=preserve or --env-conflict=overwrite`);
+    }
+    if (policy === 'preserve') {
+        if (!bothExist) {
+            return yield* fail(`cannot preserve a partial env pair (${existing}); use --env-conflict=overwrite or restore both files`);
+        }
+        return 'preserve';
+    }
+    if (policy === 'overwrite')
+        return 'overwrite';
+    if (nonInteractive || process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+        return yield* fail(`${existing} ${existence} and prompting is unavailable; pass --env-conflict=preserve or --env-conflict=overwrite explicitly`);
+    }
+    const decision = yield* Prompt.run(Prompt.Select({
+        message: `${existing} ${existence}. How should provision env continue?`,
+        choices: [
+            {
+                title: 'Preserve existing env files',
+                value: 'preserve',
+                description: 'Skip both Vercel pulls and continue with the existing files',
+                disabled: !bothExist
+            },
+            {
+                title: 'Overwrite from Vercel',
+                value: 'overwrite',
+                description: 'Snapshot both files, pull fresh values, and restore them if setup fails'
+            },
+            {
+                title: 'Cancel',
+                value: 'cancel',
+                description: 'Exit without changing env files or database leases'
+            }
+        ]
+    })).pipe(Effect.mapError(() => fail('cancelled by user')));
+    if (decision === 'cancel')
+        return yield* fail('cancelled by user');
+    return decision;
+});
+const ensureEnvUnchanged = (file, existed, snapshot) => Effect.gen(function* () {
+    const current = yield* readPrivately(file).pipe(io(`cannot revalidate ${file}`));
+    if ((current !== undefined) !== existed || (current !== undefined && current !== snapshot)) {
+        return yield* fail(`${file} changed while provisioning; refusing to overwrite it`);
+    }
+});
+const replayExit = (exit) => Exit.isSuccess(exit) ? Effect.succeed(exit.value) : Effect.failCause(exit.cause);
+const isUnexpected = (cause) => Cause.hasInterrupts(cause) || Cause.hasDies(cause);
+/**
+ * Holds the checkout lock around `operation`; on failure runs `rollback` before releasing the
+ * lock. Cleanup problems never hide the original cause, and defects or interruption are never
+ * normalized into typed errors.
+ */
+export const withProvisionLifecycleUsing = (acquire, operation, rollback, release) => Effect.suspend(() => {
+    let rollbackExit;
+    let releaseExit;
+    return Effect.acquireUseRelease(acquire, () => operation, (lock, operationExit) => Effect.gen(function* () {
+        if (Exit.isFailure(operationExit))
+            rollbackExit = yield* Effect.exit(rollback);
+        releaseExit = yield* Effect.exit(release(lock));
+    })).pipe(Effect.exit, Effect.flatMap((operationExit) => {
+        const cleanupExits = [rollbackExit, releaseExit].filter(exit => exit !== undefined);
+        const failedCleanup = cleanupExits.find(Exit.isFailure);
+        if (failedCleanup === undefined)
+            return replayExit(operationExit);
+        if (Exit.isSuccess(operationExit))
+            return Effect.failCause(failedCleanup.cause);
+        if (isUnexpected(operationExit.cause))
+            return replayExit(operationExit);
+        const unexpectedCleanup = cleanupExits.find(exit => Exit.isFailure(exit) && isUnexpected(exit.cause));
+        if (unexpectedCleanup !== undefined && Exit.isFailure(unexpectedCleanup)) {
+            return Effect.failCause(unexpectedCleanup.cause);
+        }
+        if (Option.isSome(Cause.findErrorOption(operationExit.cause)) &&
+            Option.isSome(Cause.findErrorOption(failedCleanup.cause))) {
+            return Effect.fail(fail('setup failed and lifecycle cleanup also failed; manual review is required'));
+        }
+        return Effect.failCause(failedCleanup.cause);
+    }));
+});
+/** Release only a lease this invocation created, and restore the record it replaced. */
+const rollBackLease = (repo, slot, before) => Effect.gen(function* () {
+    if (before === undefined)
+        return;
+    const current = yield* readLease(repo, slot);
+    const createdHere = Option.isSome(current) &&
+        (Option.isNone(before) || current.value.branchId !== before.value.branchId);
+    if (createdHere) {
+        yield* releaseLease({ worktree: Option.some(repo), leaseName: slot, keepEnv: true });
+        if (Option.isSome(before))
+            yield* writeLease(before.value);
+    }
+    else if (Option.isNone(current) && Option.isSome(before)) {
+        yield* writeLease(before.value);
+    }
+});
+/** Restores a file to its snapshot, or removes it when it did not exist before. */
+const restoreFile = (file, label, snapshot) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    if (snapshot === undefined)
+        yield* fs.remove(file, { force: true });
+    else
+        yield* writePrivately(file, snapshot);
+    yield* Console.error(`provision env: restored ${label} after setup failure`);
+});
+/** Runs repository-declared setup commands from the checkout root through the user's shell. */
+export const runSetup = (repo, commands) => Effect.forEach(commands, command => Console.log(`provision env: setup: ${command}`).pipe(Effect.andThen(inherit(process.env.SHELL ?? '/bin/sh', ['-lc', command], { cwd: repo })), Effect.mapError(error => fail(`setup command failed (${error.message}): ${command}`))), { discard: true });
+export const provisionEnvironment = (options) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const repo = yield* resolveCheckout(options.repo);
+    // Read and validate repository configuration (including setup) before any mutation.
+    const config = yield* readRepoConfig(repo).pipe(Effect.mapError(error => fail(error.message)));
+    const { appDir, directory } = yield* resolveAppDirectory(repo, options.appDir ?? config.appDir);
+    const vercelLinkRelative = path.join(appDir, '.vercel', 'project.json');
+    // Preflight for callers about to create a worktree: validate or reuse a local link only.
+    if (options.checkVercelLink) {
+        yield* ensureProvisionPaths(directory, ['.vercel/project.json']);
+        yield* ensureSecretPath(repo, vercelLinkRelative);
+        yield* ensureVercelLink({
+            directory,
+            appDir,
+            checkout: repo,
+            source: options.source,
+            vercelProject: undefined
+        });
+        yield* readVercelIdentity(path.join(directory, '.vercel', 'project.json'));
+        return;
+    }
+    const localRelative = path.join(appDir, '.env.local');
+    const testRelative = path.join(appDir, '.env.test');
+    const localEnvFile = path.join(directory, '.env.local');
+    const testEnvFile = path.join(directory, '.env.test');
+    const vercelDirectory = path.join(directory, '.vercel');
+    const lockPath = yield* gitOutput(repo, ['rev-parse', '--git-path', 'provision-env.lock']);
+    if (Option.isNone(lockPath))
+        return yield* fail('cannot resolve the checkout lock path');
+    const lockDirectory = path.resolve(repo, lockPath.value);
+    const acquireLock = fs.makeDirectory(lockDirectory).pipe(Effect.mapError(() => fail(`another provision env process is already using ${repo}; if none is running, remove stale lock ${lockDirectory}`)), Effect.as(lockDirectory));
+    const state = {
+        createdLocalEnv: false,
+        createdTestEnv: false,
+        createdVercelLink: false
+    };
+    const createDatabaseLease = (slot, envRelative, label) => Effect.gen(function* () {
+        const result = yield* createLease({
+            worktree: Option.some(repo),
+            ttl: options.ttl,
+            label: Option.some(label),
+            envFile: envRelative,
+            configEnvFile: Option.some(localRelative),
+            leaseName: slot,
+            keys: defaultDatabaseUrlKeys.join(','),
+            forceNew: false,
+            noWait: false
+        });
+        yield* Console.log(`provision env: ${result.status} ${slot} lease ${result.lease.branchName} (${result.lease.branchId})`);
+    });
+    const pullEnvironments = (localExists, testExists) => Effect.gen(function* () {
+        state.createdVercelLink = yield* ensureVercelLink({
+            directory,
+            appDir,
+            checkout: repo,
+            source: options.source,
+            vercelProject: options.vercelProject
+        });
+        yield* ensureLocalDirectory(vercelDirectory, 'checkout .vercel path');
+        yield* fs.chmod(vercelDirectory, 0o700).pipe(io('cannot protect Vercel staging directory'));
+        yield* ensurePrivateMode(vercelDirectory, 0o700, 'Vercel staging directory');
+        const stage = (name) => path.join(vercelDirectory, `${name}.provision-env.tmp`);
+        const localStage = stage('.env.local');
+        const testStage = stage('.env.test');
+        state.localPullTemporary = localStage;
+        state.testPullTemporary = testStage;
+        for (const file of [localStage, testStage]) {
+            yield* fs.remove(file, { force: true }).pipe(io(`cannot clear staging path ${file}`));
+            yield* writePrivately(file, '').pipe(io(`cannot create staging file ${file}`));
+            yield* ensurePrivateMode(file, 0o600, 'staging file');
+        }
+        const developmentKeys = yield* listExplicitVercelKeys(directory, 'development');
+        const testKeys = yield* listExplicitVercelKeys(directory, options.testEnvironment);
+        const pull = (stageFile, environment, label, explicitKeys, snapshot, removeResetConsent) => Effect.gen(function* () {
+            yield* Console.log(`provision env: pulling Vercel ${environment} variables into ${label}`);
+            yield* pullVercelEnvironment(directory, stageFile, environment);
+            const pulled = yield* readPrivately(stageFile).pipe(io(`cannot inspect pulled ${environment} environment`));
+            const sanitized = stripPulledEnvironment(pulled ?? '', {
+                explicitKeys,
+                replaceDatabaseUrls: options.database,
+                removeResetConsent
+            });
+            const content = options.database || snapshot === undefined
+                ? sanitized.content
+                : keepExistingDatabaseUrls(sanitized.content, snapshot);
+            if (content !== pulled) {
+                yield* writePrivately(stageFile, content).pipe(io(`cannot sanitize pulled ${environment} environment`));
+            }
+            yield* ensurePrivateMode(stageFile, 0o600, `pulled ${environment} environment`);
+            if (sanitized.metadataRemoved > 0) {
+                yield* Console.log(`provision env: removed ${sanitized.metadataRemoved} deployment-only variables from ${environment}`);
+            }
+            if (sanitized.databaseUrlsRemoved > 0) {
+                yield* Console.log(`provision env: removed ${sanitized.databaseUrlsRemoved} Vercel database variables from ${environment}`);
+            }
+        });
+        yield* pull(localStage, 'development', '.env.local', developmentKeys, state.localEnvSnapshot, true);
+        yield* pull(testStage, options.testEnvironment, '.env.test', testKeys, state.testEnvSnapshot, false);
+        yield* ensureEnvUnchanged(localEnvFile, localExists, state.localEnvSnapshot);
+        yield* ensureEnvUnchanged(testEnvFile, testExists, state.testEnvSnapshot);
+        yield* Effect.uninterruptible(Effect.gen(function* () {
+            yield* fs.rename(localStage, localEnvFile).pipe(io('cannot publish .env.local'));
+            state.localPullTemporary = undefined;
+            state.createdLocalEnv = true;
+            yield* fs.rename(testStage, testEnvFile).pipe(io('cannot publish .env.test'));
+            state.testPullTemporary = undefined;
+            state.createdTestEnv = true;
+        }));
+    });
+    const operation = Effect.gen(function* () {
+        if (!options.skipVercel || options.database) {
+            yield* ensureProvisionPaths(directory, ['.env.local', '.env.test', '.vercel/project.json']);
+            yield* ensureSecretPath(repo, localRelative);
+            yield* ensureSecretPath(repo, testRelative);
+        }
+        const localBefore = yield* readPrivately(localEnvFile).pipe(io('cannot read .env.local'));
+        const testBefore = yield* readPrivately(testEnvFile).pipe(io('cannot read .env.test'));
+        const localExists = localBefore !== undefined;
+        const testExists = testBefore !== undefined;
+        const decision = options.skipVercel
+            ? 'preserve'
+            : yield* resolveEnvConflict(options.envConflict, options.nonInteractive, localExists, testExists);
+        const pullVercel = !options.skipVercel && decision === 'overwrite';
+        state.localEnvSnapshot = localBefore;
+        state.testEnvSnapshot = testBefore;
+        if (!options.skipInstall)
+            yield* installDependencies(repo);
+        if (pullVercel)
+            yield* pullEnvironments(localExists, testExists);
+        const currentLocal = yield* readPrivately(localEnvFile).pipe(io('cannot read .env.local'));
+        yield* ensureNoLocalResetConsent(currentLocal ?? '');
+        if (options.database) {
+            const label = options.label ??
+                Option.getOrElse(Option.filter(yield* gitOutput(repo, ['branch', '--show-current']), branch => branch !== ''), () => path.basename(repo));
+            yield* Console.log('provision env: allocating isolated development PostgreSQL');
+            state.defaultLeaseBefore = yield* readLease(repo, 'default').pipe(io('cannot read lease'));
+            state.createdLocalEnv = true;
+            yield* createDatabaseLease('default', localRelative, `${label}-development`);
+            yield* Console.log('provision env: allocating isolated test PostgreSQL');
+            state.testLeaseBefore = yield* readLease(repo, 'test').pipe(io('cannot read lease'));
+            state.createdTestEnv = true;
+            yield* createDatabaseLease('test', testRelative, `${label}-test`);
+        }
+        return pullVercel;
+    });
+    const rollback = Effect.gen(function* () {
+        const failures = [];
+        const attempt = (label, effect) => effect.pipe(Effect.matchEffect({
+            onFailure: () => Effect.sync(() => {
+                failures.push(label);
+            }),
+            onSuccess: () => Effect.void
+        }));
+        yield* attempt('cannot release test lease', rollBackLease(repo, 'test', state.testLeaseBefore));
+        yield* attempt('cannot release default lease', rollBackLease(repo, 'default', state.defaultLeaseBefore));
+        if (state.createdTestEnv) {
+            yield* attempt('cannot restore .env.test', restoreFile(testEnvFile, '.env.test', state.testEnvSnapshot));
+        }
+        if (state.createdLocalEnv) {
+            yield* attempt('cannot restore .env.local', restoreFile(localEnvFile, '.env.local', state.localEnvSnapshot));
+        }
+        for (const temporary of [state.testPullTemporary, state.localPullTemporary]) {
+            if (temporary !== undefined) {
+                yield* attempt(`cannot remove staged environment ${temporary}`, fs.remove(temporary, { force: true }));
+            }
+        }
+        if (state.createdVercelLink) {
+            yield* attempt('cannot remove invocation-created Vercel project identity', fs.remove(path.join(vercelDirectory, 'project.json'), { force: true }));
+        }
+        if (failures.length > 0) {
+            return yield* fail(`rollback could not complete: ${failures.join('; ')}`);
+        }
+    });
+    const pulled = yield* withProvisionLifecycleUsing(acquireLock, operation, rollback, lock => fs.remove(lock, { recursive: true }).pipe(io(`cannot release provision lock ${lock}`)));
+    // Setup runs after the lock is released and never rolls back provisioned env or databases:
+    // they are valid, and setup commands are idempotent, so a re-run resumes.
+    const runsSetup = !options.skipSetup && (!options.skipVercel || options.database);
+    if (runsSetup)
+        yield* runSetup(repo, config.setup);
+    yield* Console.log([
+        '',
+        'provision env: ready',
+        `  repo:       ${repo}`,
+        `  app:        ${directory}`,
+        `  install:    ${options.skipInstall ? 'skipped' : 'complete'}`,
+        `  vercel env: ${pulled ? '.env.local + .env.test' : options.skipVercel ? 'skipped' : 'preserved'}`,
+        `  databases:  ${options.database ? 'development + test ready' : 'skipped'}`,
+        `  setup:      ${runsSetup ? `${config.setup.length} command(s)` : 'skipped'}`
+    ].join('\n'));
+});

package/dist/env/sanitize.js

@@ -0,0 +1,88 @@
+import { Effect } from 'effect';
+import { parseEnvFile } from '../shared/env-file.js';
+import { fail } from './domain.js';
+/** Variables Vercel adds to pulls of deployment targets that do not belong in local env files. */
+const deploymentMetadataKeys = new Set([
+    'CI',
+    'NX_DAEMON',
+    'TURBO_CACHE',
+    'TURBO_DOWNLOAD_LOCAL_ENABLED',
+    'TURBO_REMOTE_ONLY',
+    'TURBO_RUN_SUMMARY',
+    'VERCEL',
+    'VERCEL_AUTOMATION_BYPASS_SECRET',
+    'VERCEL_BRANCH_URL',
+    'VERCEL_DEPLOYMENT_ID',
+    'VERCEL_ENV',
+    'VERCEL_GIT_COMMIT_AUTHOR_LOGIN',
+    'VERCEL_GIT_COMMIT_AUTHOR_NAME',
+    'VERCEL_GIT_COMMIT_MESSAGE',
+    'VERCEL_GIT_COMMIT_REF',
+    'VERCEL_GIT_COMMIT_SHA',
+    'VERCEL_GIT_PREVIOUS_SHA',
+    'VERCEL_GIT_PROVIDER',
+    'VERCEL_GIT_PULL_REQUEST_ID',
+    'VERCEL_GIT_REPO_ID',
+    'VERCEL_GIT_REPO_OWNER',
+    'VERCEL_GIT_REPO_SLUG',
+    'VERCEL_HASH_SALT',
+    'VERCEL_OIDC_TOKEN',
+    'VERCEL_PROJECT_ID',
+    'VERCEL_PROJECT_PRODUCTION_URL',
+    'VERCEL_REGION',
+    'VERCEL_SKEW_PROTECTION_ENABLED',
+    'VERCEL_TARGET_ENV',
+    'VERCEL_URL'
+]);
+export const databaseUrlKeys = new Set(['DATABASE_URL', 'DATABASE_URL_UNPOOLED']);
+/** Destructive E2E reset consent: allowed only in `.env.test`, never in `.env.local`. */
+export const resetConsentKey = 'ALLOW_E2E_DATABASE_RESET';
+const keyOf = (line) => /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(line)?.[1];
+export const stripPulledEnvironment = (content, options) => {
+    let metadataRemoved = 0;
+    let databaseUrlsRemoved = 0;
+    const lines = content.split('\n').filter(line => {
+        const key = keyOf(line);
+        if (key === undefined)
+            return true;
+        if (options.removeResetConsent && key === resetConsentKey) {
+            metadataRemoved += 1;
+            return false;
+        }
+        if (options.replaceDatabaseUrls && databaseUrlKeys.has(key)) {
+            databaseUrlsRemoved += 1;
+            return false;
+        }
+        if (options.explicitKeys.has(key) || !deploymentMetadataKeys.has(key))
+            return true;
+        metadataRemoved += 1;
+        return false;
+    });
+    return { content: lines.join('\n'), databaseUrlsRemoved, metadataRemoved };
+};
+/** Carries database URL lines from `existing` into `pulled` (when databases are not reallocated). */
+export const keepExistingDatabaseUrls = (pulled, existing) => {
+    const retained = new Map();
+    for (const line of existing.split('\n')) {
+        const key = keyOf(line);
+        if (key !== undefined && databaseUrlKeys.has(key))
+            retained.set(key, line);
+    }
+    if (retained.size === 0)
+        return pulled;
+    const trailingNewline = pulled.endsWith('\n');
+    const lines = pulled.split('\n');
+    if (trailingNewline)
+        lines.pop();
+    for (const [key, line] of retained) {
+        const index = lines.findIndex(candidate => candidate.startsWith(`${key}=`));
+        if (index >= 0)
+            lines[index] = line;
+        else
+            lines.push(line);
+    }
+    return `${lines.join('\n')}${trailingNewline ? '\n' : ''}`;
+};
+export const ensureNoLocalResetConsent = (localContent) => parseEnvFile(localContent).has(resetConsentKey)
+    ? Effect.fail(fail(`${resetConsentKey} is forbidden in .env.local`))
+    : Effect.void;

package/dist/env/vercel.js

@@ -0,0 +1,180 @@
+import { Console, Effect, FileSystem, Option, Path, Schema } from 'effect';
+import { gitOutput, gitSucceeds } from '../shared/git.js';
+import { capture, inherit } from '../shared/process.js';
+import { fail, VercelLinkRequired } from './domain.js';
+import { ensureLocalDirectory, ensureProvisionPaths, ensureRegularFile, resolveAppDirectory, resolveCheckout } from './paths.js';
+const VercelProjectIdentity = Schema.fromJsonString(Schema.Struct({ orgId: Schema.String, projectId: Schema.String }));
+/** `orgId:projectId` from a `.vercel/project.json`, which must be a regular local file. */
+export const readVercelIdentity = (projectFile) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    yield* ensureRegularFile(projectFile, 'Vercel project identity');
+    const content = yield* fs
+        .readFileString(projectFile)
+        .pipe(Effect.mapError(() => fail(`cannot read Vercel project identity from ${projectFile}`)));
+    const parsed = yield* Schema.decodeUnknownEffect(VercelProjectIdentity)(content).pipe(Effect.mapError(() => fail(`invalid Vercel project identity in ${projectFile}`)));
+    return `${parsed.orgId}:${parsed.projectId}`;
+});
+const originUrl = (cwd) => gitOutput(cwd, ['remote', 'get-url', 'origin']).pipe(Effect.map(Option.getOrElse(() => '')));
+/**
+ * Copies the selected app's `.vercel/project.json` from another checkout of the same repository.
+ * Returns `false` when the source app is not linked. A failed copy removes the partial link.
+ */
+export const copyProjectIdentity = (directory, source, appDir) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const sourceRoot = yield* resolveCheckout(source);
+    const from = (yield* resolveAppDirectory(sourceRoot, appDir)).directory;
+    yield* ensureProvisionPaths(from, ['.vercel/project.json']);
+    const sourceVercelDirectory = path.join(from, '.vercel');
+    const sourceProjectFile = path.join(sourceVercelDirectory, 'project.json');
+    const sourceLinked = yield* fs.exists(sourceProjectFile).pipe(Effect.orElseSucceed(() => false));
+    if (!sourceLinked)
+        return false;
+    yield* ensureLocalDirectory(sourceVercelDirectory, 'source .vercel path');
+    const sourceIdentity = yield* readVercelIdentity(sourceProjectFile);
+    const [targetRemote, sourceRemote] = yield* Effect.all([originUrl(directory), originUrl(from)]);
+    if (targetRemote.length > 0 && sourceRemote.length > 0 && targetRemote !== sourceRemote) {
+        return yield* fail(`refusing Vercel identity from a different Git remote: ${from}`);
+    }
+    if (!(yield* gitSucceeds(directory, ['check-ignore', '-q', '--', '.vercel/project.json']))) {
+        return yield* fail('refusing to create .vercel/project.json because .vercel is not ignored');
+    }
+    const targetDirectory = path.join(directory, '.vercel');
+    const targetProjectFile = path.join(targetDirectory, 'project.json');
+    yield* Effect.gen(function* () {
+        if (!(yield* fs.exists(targetDirectory).pipe(Effect.orElseSucceed(() => false)))) {
+            yield* fs
+                .makeDirectory(targetDirectory, { recursive: true })
+                .pipe(Effect.mapError(() => fail('cannot create .vercel directory')));
+        }
+        yield* ensureLocalDirectory(targetDirectory, 'checkout .vercel path');
+        yield* fs
+            .chmod(targetDirectory, 0o700)
+            .pipe(Effect.mapError(() => fail('cannot protect .vercel directory')));
+        yield* fs
+            .copyFile(sourceProjectFile, targetProjectFile)
+            .pipe(Effect.mapError(() => fail('cannot copy Vercel project identity')));
+        yield* fs
+            .chmod(targetProjectFile, 0o600)
+            .pipe(Effect.mapError(() => fail('cannot protect Vercel project identity')));
+        const [sourceAfterCopy, targetIdentity] = yield* Effect.all([
+            readVercelIdentity(sourceProjectFile),
+            readVercelIdentity(targetProjectFile)
+        ]);
+        if (sourceAfterCopy !== sourceIdentity || targetIdentity !== sourceIdentity) {
+            return yield* fail('Vercel project identity changed while it was being copied');
+        }
+        yield* Console.log(`provision env: reused Vercel project identity from ${from}`);
+    }).pipe(Effect.catch(operationError => fs.remove(targetProjectFile, { force: true }).pipe(Effect.matchEffect({
+        onFailure: () => Effect.fail(fail('Vercel project identity copy and cleanup both failed; manual review is required')),
+        onSuccess: () => Effect.fail(operationError)
+    }))));
+    return true;
+});
+/**
+ * Ensures the app directory is linked to Vercel. Order: existing link, explicit `--source`, explicit
+ * `--vercel-project`, then the single identity shared by every linked sibling worktree. Returns
+ * whether this invocation created the link.
+ */
+export const ensureVercelLink = (request) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const vercelDirectory = path.join(request.directory, '.vercel');
+    const projectFile = path.join(vercelDirectory, 'project.json');
+    if (yield* fs.exists(vercelDirectory).pipe(Effect.orElseSucceed(() => false))) {
+        yield* ensureLocalDirectory(vercelDirectory, 'checkout .vercel path');
+    }
+    if (yield* fs.exists(projectFile).pipe(Effect.orElseSucceed(() => false))) {
+        yield* readVercelIdentity(projectFile);
+        return false;
+    }
+    // An explicit but unlinked source is not a dead end: try sibling identities next.
+    if (request.source !== undefined &&
+        (yield* copyProjectIdentity(request.directory, request.source, request.appDir))) {
+        return true;
+    }
+    if (request.vercelProject !== undefined) {
+        if (!(yield* gitSucceeds(request.directory, [
+            'check-ignore',
+            '-q',
+            '--',
+            '.vercel/project.json'
+        ]))) {
+            return yield* fail('.vercel must be git-ignored before linking');
+        }
+        yield* Console.log(`provision env: linking to Vercel project ${request.vercelProject}`);
+        yield* inherit('vercel', [
+            'link',
+            '--cwd',
+            request.directory,
+            '--project',
+            request.vercelProject,
+            '--yes',
+            '--no-color'
+        ]).pipe(Effect.mapError(error => fail(error.message)));
+        return true;
+    }
+    const listed = yield* gitOutput(request.checkout, ['worktree', 'list', '--porcelain']);
+    const candidates = [];
+    for (const line of Option.getOrElse(listed, () => '').split('\n')) {
+        if (!line.startsWith('worktree '))
+            continue;
+        const candidate = line.slice('worktree '.length);
+        if (path.resolve(candidate) === request.checkout)
+            continue;
+        const linkedFile = path.join(candidate, request.appDir, '.vercel', 'project.json');
+        if (yield* fs.exists(linkedFile).pipe(Effect.orElseSucceed(() => false))) {
+            yield* resolveAppDirectory(candidate, request.appDir);
+            yield* ensureProvisionPaths(path.join(candidate, request.appDir), ['.vercel/project.json']);
+            candidates.push(candidate);
+        }
+    }
+    const first = candidates[0];
+    if (first !== undefined) {
+        const identities = yield* Effect.forEach(candidates, candidate => readVercelIdentity(path.join(candidate, request.appDir, '.vercel', 'project.json')));
+        if (new Set(identities).size === 1 &&
+            (yield* copyProjectIdentity(request.directory, first, request.appDir))) {
+            return true;
+        }
+        return yield* new VercelLinkRequired({
+            directory: request.directory,
+            reason: 'linked sibling checkouts use different Vercel projects; choose a linked --source explicitly'
+        });
+    }
+    return yield* new VercelLinkRequired({
+        directory: request.source === undefined
+            ? request.directory
+            : (yield* resolveAppDirectory(yield* resolveCheckout(request.source), request.appDir))
+                .directory,
+        reason: 'no Vercel project link found for the selected app'
+    });
+});
+/** Keys explicitly configured for `environment` (so pulled values with those names are kept). */
+export const listExplicitVercelKeys = (directory, environment) => Effect.gen(function* () {
+    const listed = yield* capture('vercel', [
+        'env',
+        'list',
+        environment,
+        '--cwd',
+        directory,
+        '--no-color'
+    ]);
+    if (listed.exitCode !== 0) {
+        return yield* fail(`vercel env list ${environment} failed (exit ${listed.exitCode})`);
+    }
+    return new Set(listed.stdout.split('\n').flatMap(line => {
+        const key = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s+/.exec(line)?.[1];
+        return key === undefined ? [] : [key];
+    }));
+}).pipe(Effect.catchTag('ProcessError', error => Effect.fail(fail(error.message))));
+export const pullVercelEnvironment = (directory, file, environment) => inherit('vercel', [
+    'env',
+    'pull',
+    file,
+    '--environment',
+    environment,
+    '--yes',
+    '--cwd',
+    directory,
+    '--no-color'
+]).pipe(Effect.mapError(error => fail(error.message)));

package/dist/factory/approval.js

@@ -0,0 +1,33 @@
+import { existsSync } from 'node:fs';
+import { Console, Effect } from 'effect';
+import { detectAgent } from '../shared/agent.js';
+/** Where the operator installs the root-owned binary that approved commands must run. */
+export const rootOwnedBinary = '/usr/local/bin/provision';
+const shellSafe = /^[\w/.,:=@%+-]+$/;
+export const shellQuote = (value) => shellSafe.test(value) ? value : `'${value.replaceAll("'", `'\\''`)}'`;
+export const approvalRequired = (input) => ({
+    status: 'approval_required',
+    reason: `this command reads factory admin keys and needs the provision passphrase, typed by a human in a terminal; ${input.agent} cannot approve it`,
+    hint: 'ask the human to run the next command in their own terminal and paste its output; never ask for the passphrase',
+    next: [
+        `cd ${shellQuote(input.cwd)} && ${[input.binary, ...input.args].map(shellQuote).join(' ')}`
+    ]
+});
+/**
+ * Runs `effect` only for humans. Under a detected agent it changes nothing and prints, as JSON on
+ * stderr, the exact command for the human to run instead (exit 4).
+ */
+export const humanOnly = (effect) => Effect.suspend(() => {
+    const agent = detectAgent();
+    if (agent === undefined)
+        return effect;
+    const payload = approvalRequired({
+        agent,
+        cwd: process.cwd(),
+        binary: existsSync(rootOwnedBinary) ? rootOwnedBinary : 'provision',
+        args: process.argv.slice(2)
+    });
+    return Console.error(JSON.stringify(payload)).pipe(Effect.andThen(Effect.sync(() => {
+        process.exitCode = 4;
+    })));
+});