@magoz/provision 0.0.0-stage → 0.1.1

package/dist/db/operations.js

@@ -0,0 +1,246 @@
+import { randomBytes } from 'node:crypto';
+import { Console, Effect, FileSystem, Option, Path } from 'effect';
+import { envKeyPattern, removeEnvKeys, writeEnvKeys } from '../shared/env-file.js';
+import { ensureIgnored, resolveWorkspace } from '../shared/git.js';
+import { readPrivately, writePrivately } from '../shared/private-file.js';
+import { readRepoConfig } from '../shared/repo-config.js';
+import { sandboxProfileKeys } from '../shared/sandbox-profile.js';
+import { withBranchLifecycleUsing } from './branch-lifecycle.js';
+import { loadConfig } from './config.js';
+import { BRANCH_PREFIX, LifecycleError, NeonError, PolicyError } from './domain.js';
+import { readLease, removeLease, withLeaseLock, writeLease } from './lease.js';
+import { attestSandboxProfile, createBranch, deleteVerifiedBranch, getBranch, getConnectionUris, setExpiration, waitUntilReady } from './neon.js';
+import { ensureLeaseProfile, parseTtl, validateDeletionTarget, validateLeaseName } from './policy.js';
+export const timestamp = (offsetSeconds = 0) => new Date(Date.now() + offsetSeconds * 1000).toISOString().replace(/\.\d{3}Z$/, 'Z');
+const slugify = (value) => value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 60) || 'worktree';
+const reservedKeys = new Set(sandboxProfileKeys);
+const urlFor = (key, connection) => key.toUpperCase().endsWith('UNPOOLED') ? connection.direct : connection.pooled;
+/**
+ * Repositories that declare `provision.factory.neon.sandboxParent: "empty-baseline"` get their
+ * profile attested against the factory-created project and baseline before any mutation.
+ */
+export const attestIfDeclared = (config, workspace) => Effect.gen(function* () {
+    const repo = yield* readRepoConfig(workspace.root);
+    if (repo.factory.neon.sandboxParent === 'empty-baseline') {
+        yield* attestSandboxProfile(config, workspace.repository);
+    }
+});
+export const parseEnvKeys = (keys) => Effect.gen(function* () {
+    const envKeys = keys
+        .split(',')
+        .map(key => key.trim())
+        .filter(key => key.length > 0);
+    if (envKeys.length === 0) {
+        return yield* new PolicyError({ message: '--keys must name at least one variable' });
+    }
+    const invalid = envKeys.filter(key => !envKeyPattern.test(key));
+    if (invalid.length > 0) {
+        return yield* new PolicyError({
+            message: `--keys contains invalid environment names: ${invalid.join(', ')}`
+        });
+    }
+    const duplicates = envKeys.filter((key, index) => envKeys.indexOf(key) !== index);
+    if (duplicates.length > 0) {
+        return yield* new PolicyError({
+            message: `--keys contains duplicates: ${[...new Set(duplicates)].join(', ')}`
+        });
+    }
+    const reserved = envKeys.filter(key => reservedKeys.has(key));
+    if (reserved.length > 0) {
+        return yield* new PolicyError({
+            message: `--keys cannot overwrite sandbox configuration: ${reserved.join(', ')}`
+        });
+    }
+    return envKeys;
+});
+/** Refreshes a compatible live lease in place: TTL extended, connection URLs restored. */
+const reuseLiveLease = (config, existing, ttlSeconds) => Effect.gen(function* () {
+    const live = yield* getBranch(config, existing.branchId);
+    if (Option.isNone(live))
+        return Option.none();
+    yield* validateDeletionTarget(existing, live.value);
+    const { databaseName, roleName } = existing;
+    const connection = yield* getConnectionUris(config, existing.branchId, databaseName !== undefined && roleName !== undefined ? { databaseName, roleName } : undefined);
+    const expiresAt = timestamp(ttlSeconds);
+    yield* setExpiration(config, existing, expiresAt);
+    yield* writeEnvKeys(existing.envFile, existing.envKeys.map(key => [key, urlFor(key, connection)]));
+    const lease = {
+        ...existing,
+        databaseName: connection.databaseName,
+        roleName: connection.roleName,
+        expiresAt
+    };
+    yield* writeLease(lease);
+    return Option.some({
+        status: 'reused',
+        lease,
+        report: {
+            status: 'reused',
+            lease: lease.leaseName,
+            branch_name: lease.branchName,
+            branch_id: lease.branchId,
+            expires_at: expiresAt,
+            config_env_file: lease.configEnvFile,
+            env_file: lease.envFile,
+            note: 'connection URLs were restored and the existing live lease TTL was refreshed'
+        }
+    });
+});
+/** Creates (or reuses) the lease for one worktree slot and writes its connection URLs. */
+export const createLease = (options) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const workspace = yield* resolveWorkspace(options.worktree);
+    const leaseName = yield* validateLeaseName(options.leaseName);
+    return yield* withLeaseLock(workspace.root, leaseName, Effect.gen(function* () {
+        const envPath = path.resolve(workspace.root, options.envFile);
+        const configEnvPath = path.resolve(workspace.root, Option.getOrElse(options.configEnvFile, () => options.envFile));
+        const config = yield* loadConfig(configEnvPath);
+        yield* attestIfDeclared(config, workspace);
+        const envKeys = yield* parseEnvKeys(options.keys);
+        yield* ensureIgnored(workspace.root, envPath);
+        const ttlSeconds = yield* parseTtl(options.ttl);
+        const existing = yield* readLease(workspace.root, leaseName);
+        if (Option.isSome(existing) && !options.forceNew) {
+            const lease = existing.value;
+            const compatible = lease.projectId === config.projectId &&
+                lease.parentBranch === config.parentBranch &&
+                lease.envFile === envPath &&
+                lease.configEnvFile === configEnvPath &&
+                lease.envKeys.length === envKeys.length &&
+                lease.envKeys.every((key, index) => key === envKeys[index]) &&
+                (lease.databaseName === undefined) === (lease.roleName === undefined);
+            if (compatible) {
+                const reused = yield* reuseLiveLease(config, lease, ttlSeconds);
+                if (Option.isSome(reused))
+                    return reused.value;
+            }
+            else {
+                yield* Console.error(`provision db: ignoring stale ${leaseName} lease record; its branch will expire automatically`);
+            }
+        }
+        const label = slugify(Option.getOrElse(options.label, () => path.basename(workspace.root)));
+        const repositoryName = slugify(workspace.repository.split('/').pop() ?? workspace.repository);
+        const branchName = `${BRANCH_PREFIX}${repositoryName}-${label}-${randomBytes(3).toString('hex')}`;
+        const expiresAt = timestamp(ttlSeconds);
+        const envExisted = yield* fs.exists(envPath).pipe(Effect.orElseSucceed(() => false));
+        const previousEnv = envExisted
+            ? yield* readPrivately(envPath).pipe(Effect.mapError(() => new PolicyError({ message: `cannot snapshot ${envPath}` })))
+            : undefined;
+        const leaseFor = (created) => ({
+            version: 2,
+            leaseName,
+            projectId: config.projectId,
+            parentBranch: config.parentBranch,
+            branchId: created.branch.id,
+            branchName: created.branch.name,
+            worktree: workspace.root,
+            repository: workspace.repository,
+            label,
+            configEnvFile: configEnvPath,
+            envFile: envPath,
+            envKeys,
+            databaseName: created.databaseName,
+            roleName: created.roleName,
+            createdAt: timestamp(),
+            expiresAt
+        });
+        const publish = (created) => Effect.gen(function* () {
+            const lease = leaseFor(created);
+            yield* writeEnvKeys(envPath, envKeys.map(key => [key, urlFor(key, created)]));
+            yield* writeLease(lease);
+            const state = options.noWait
+                ? 'not-checked'
+                : yield* waitUntilReady(config, created.branch.id);
+            if (!options.noWait && state !== 'ready') {
+                return yield* new NeonError({
+                    message: 'new branch did not become ready before the bounded timeout'
+                });
+            }
+            return {
+                status: 'created',
+                lease,
+                report: {
+                    status: 'created',
+                    lease: lease.leaseName,
+                    branch_name: lease.branchName,
+                    branch_id: lease.branchId,
+                    state,
+                    expires_at: lease.expiresAt,
+                    env_file: lease.envFile,
+                    env_keys: envKeys.join(','),
+                    config_source: config.backend,
+                    config_env_file: lease.configEnvFile,
+                    parent_branch: config.parentBranch,
+                    note: 'connection string written to env file; not printed'
+                }
+            };
+        });
+        /** Undo everything this run created: branch, env changes, and lease record. */
+        const rollback = (created) => Effect.gen(function* () {
+            const lease = leaseFor(created);
+            let cleanupFailed = false;
+            const attempt = (cleanup) => cleanup.pipe(Effect.matchEffect({
+                onFailure: () => Effect.sync(() => {
+                    cleanupFailed = true;
+                }),
+                onSuccess: () => Effect.void
+            }));
+            yield* attempt(deleteVerifiedBranch(config, lease, lease.expiresAt));
+            if (previousEnv === undefined)
+                yield* attempt(fs.remove(envPath));
+            else
+                yield* attempt(writePrivately(envPath, previousEnv));
+            const currentLease = yield* readLease(workspace.root, leaseName);
+            if (Option.isSome(currentLease)) {
+                if (currentLease.value.branchId === lease.branchId) {
+                    yield* attempt(removeLease(workspace.root, leaseName));
+                    if (Option.isSome(existing))
+                        yield* attempt(writeLease(existing.value));
+                }
+                else if (Option.isNone(existing) ||
+                    currentLease.value.branchId !== existing.value.branchId) {
+                    cleanupFailed = true;
+                }
+            }
+            else if (Option.isSome(existing)) {
+                yield* attempt(writeLease(existing.value));
+            }
+            if (cleanupFailed) {
+                return yield* new LifecycleError({
+                    message: 'new branch setup cleanup could not be fully verified; manual review is required'
+                });
+            }
+        });
+        return yield* withBranchLifecycleUsing(createBranch(config, { name: branchName, expiresAt }), publish, rollback);
+    }));
+});
+/** Deletes a lease's branch (after re-verifying its exact identity), env keys, and record. */
+export const releaseLease = (options) => Effect.gen(function* () {
+    const workspace = yield* resolveWorkspace(options.worktree);
+    const name = yield* validateLeaseName(options.leaseName);
+    return yield* withLeaseLock(workspace.root, name, Effect.gen(function* () {
+        const lease = yield* readLease(workspace.root, name);
+        if (Option.isNone(lease)) {
+            return { status: 'none', lease: name, worktree: workspace.root };
+        }
+        const config = yield* loadConfig(lease.value.configEnvFile);
+        yield* ensureLeaseProfile(config, lease.value);
+        yield* attestIfDeclared(config, workspace);
+        const deleted = yield* deleteVerifiedBranch(config, lease.value);
+        if (!options.keepEnv)
+            yield* removeEnvKeys(lease.value.envFile, lease.value.envKeys);
+        yield* removeLease(workspace.root, lease.value.leaseName);
+        return {
+            status: deleted ? 'released' : 'already-gone',
+            lease: lease.value.leaseName,
+            branch_name: lease.value.branchName,
+            branch_id: lease.value.branchId,
+            env_keys_removed: options.keepEnv ? 'no' : 'yes'
+        };
+    }));
+});

package/dist/db/policy.js

@@ -0,0 +1,59 @@
+import { Effect } from 'effect';
+import { BRANCH_PREFIX, MAX_TTL_SECONDS, PolicyError } from './domain.js';
+const ttlUnits = { s: 1, m: 60, h: 3600, d: 86400 };
+const isTtlUnit = (unit) => unit in ttlUnits;
+export const parseTtl = (value) => Effect.gen(function* () {
+    const match = /^(\d+)([smhd])$/.exec(value.trim().toLowerCase());
+    const amount = match?.[1];
+    const unit = match?.[2];
+    if (amount === undefined || unit === undefined || !isTtlUnit(unit)) {
+        return yield* new PolicyError({
+            message: `invalid ttl ${value}; use forms like 12h, 3d, 90m`
+        });
+    }
+    const seconds = Number(amount) * ttlUnits[unit];
+    if (seconds <= 0)
+        return yield* new PolicyError({ message: 'ttl must be positive' });
+    if (seconds > MAX_TTL_SECONDS) {
+        return yield* new PolicyError({
+            message: `ttl exceeds policy maximum of ${MAX_TTL_SECONDS / 86400}d`
+        });
+    }
+    return seconds;
+});
+export const validateLeaseName = (leaseName) => /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(leaseName)
+    ? Effect.succeed(leaseName)
+    : Effect.fail(new PolicyError({
+        message: '--lease must be 1-64 letters, digits, dots, underscores, or hyphens'
+    }));
+export const ensureLeaseProfile = (config, lease) => {
+    if (config.projectId !== lease.projectId) {
+        return Effect.fail(new PolicyError({
+            message: `lease belongs to Neon project ${lease.projectId}, but the resolved profile selects ${config.projectId}\n` +
+                'restore the original worktree environment before managing this lease'
+        }));
+    }
+    if (config.parentBranch !== lease.parentBranch) {
+        return Effect.fail(new PolicyError({
+            message: `lease belongs to parent branch ${lease.parentBranch}, but the resolved profile selects ${config.parentBranch}\n` +
+                'release the existing lease before changing its parent branch'
+        }));
+    }
+    return Effect.void;
+};
+/** The provider branch is exactly the recorded, non-default, unprotected agent branch. */
+export const branchMatchesExactIdentity = (expected, branch, expiresAt) => expected.branchId.length > 0 &&
+    expected.branchId !== expected.parentBranch &&
+    expected.branchName.startsWith(BRANCH_PREFIX) &&
+    branch.id === expected.branchId &&
+    branch.name === expected.branchName &&
+    branch.parent_id === expected.parentBranch &&
+    branch.default === false &&
+    branch.protected === false &&
+    (expiresAt === undefined || branch.expires_at === expiresAt);
+export const validateBranchIdentity = (expected, branch, expiresAt) => branchMatchesExactIdentity(expected, branch, expiresAt)
+    ? Effect.void
+    : Effect.fail(new PolicyError({
+        message: 'provider branch does not exactly match the recorded non-default, unprotected agent lease'
+    }));
+export const validateDeletionTarget = (lease, branch) => validateBranchIdentity(lease, branch);

package/dist/env/commands.js

@@ -0,0 +1,39 @@
+import { Console, Effect, Option } from 'effect';
+import { Command, Flag } from 'effect/cli';
+import { detectAgent } from '../shared/agent.js';
+import { envConflictPolicies } from './domain.js';
+import { provisionEnvironment } from './provision.js';
+const optionalText = (name, description) => Flag.String(name).pipe(Flag.withDescription(description), Flag.optional);
+const booleanFlag = (name, description) => Flag.Boolean(name).pipe(Flag.withDescription(description), Flag.withDefault(false));
+const setExitCode = (code) => Effect.sync(() => {
+    process.exitCode = code;
+});
+export const envCommand = Command.make('env', {
+    repo: Flag.String('repo').pipe(Flag.withDescription('target Git checkout (default: current directory)'), Flag.withDefault('.')),
+    checkVercelLink: booleanFlag('check-vercel-link', 'check/reuse a local app link only; missing or ambiguous links emit JSON on stderr and exit 3'),
+    appDir: optionalText('app-dir', 'checkout-relative app directory (default: package.json provision.appDir or ".")'),
+    source: optionalText('source', "linked checkout to copy the selected app's .vercel/project.json from"),
+    vercelProject: optionalText('vercel-project', 'link explicitly to this Vercel project'),
+    database: booleanFlag('database', 'allocate independent development and test databases'),
+    testEnvironment: Flag.String('test-environment').pipe(Flag.withDescription('Vercel environment for .env.test (default: test)'), Flag.withDefault('test')),
+    label: optionalText('label', 'database label prefix (default: branch or directory name)'),
+    ttl: Flag.String('ttl').pipe(Flag.withDescription('database lifetime (default: 7d; maximum: 7d)'), Flag.withDefault('7d')),
+    skipInstall: booleanFlag('skip-install', 'do not install dependencies'),
+    skipVercel: booleanFlag('skip-vercel', 'do not pull either Vercel environment'),
+    skipSetup: booleanFlag('skip-setup', 'do not run package.json provision.setup commands'),
+    nonInteractive: booleanFlag('non-interactive', 'never prompt; unresolved env conflicts fail safely'),
+    envConflict: Flag.Literals('env-conflict', envConflictPolicies).pipe(Flag.withDescription('existing env policy (default: refresh from Vercel)'), Flag.withDefault('overwrite'))
+}, options => provisionEnvironment({
+    ...options,
+    // Agents cannot answer prompts; fail safely instead, as with --non-interactive.
+    nonInteractive: options.nonInteractive || detectAgent() !== undefined,
+    appDir: Option.getOrUndefined(options.appDir),
+    source: Option.getOrUndefined(options.source),
+    vercelProject: Option.getOrUndefined(options.vercelProject),
+    label: Option.getOrUndefined(options.label)
+}).pipe(Effect.catchTag('VercelLinkRequired', error => Console.error(JSON.stringify({
+    status: 'vercel_link_required',
+    directory: error.directory,
+    reason: error.reason
+})).pipe(Effect.andThen(setExitCode(3)))), Effect.catch(error => Console.error(`provision env: ${error.message}`).pipe(Effect.andThen(setExitCode(2)))))).pipe(Command.withDescription('Make a checkout runnable: install dependencies, link Vercel, pull Development and test env ' +
+    'files, optionally allocate isolated databases, then run package.json provision.setup.'));

package/dist/env/domain.js

@@ -0,0 +1,14 @@
+import { Data } from 'effect';
+export class EnvError extends Data.TaggedError('EnvError') {
+}
+/**
+ * The selected app has no usable Vercel link. Reported as one JSON object on stderr with exit code
+ * 3 so a calling agent can link the project and retry.
+ */
+export class VercelLinkRequired extends Data.TaggedError('VercelLinkRequired') {
+    get message() {
+        return `Vercel link required in ${this.directory}: ${this.reason}`;
+    }
+}
+export const envConflictPolicies = ['ask', 'error', 'preserve', 'overwrite'];
+export const fail = (message) => new EnvError({ message });

package/dist/env/install.js

@@ -0,0 +1,25 @@
+import { Console, Effect, FileSystem, Path } from 'effect';
+import { capture, inherit } from '../shared/process.js';
+import { fail } from './domain.js';
+/** Installs dependencies from the checkout root's committed lockfile, never updating it. */
+export const installDependencies = (repo) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const exists = (file) => fs.exists(path.join(repo, file)).pipe(Effect.orElseSucceed(() => false));
+    const run = (label, command, args) => Console.log(`provision env: installing dependencies with ${label}`).pipe(Effect.andThen(inherit(command, args, { cwd: repo })), Effect.mapError(error => fail(error.message)));
+    if (yield* exists('pnpm-lock.yaml')) {
+        return yield* run('pnpm --frozen-lockfile', 'pnpm', ['install', '--frozen-lockfile']);
+    }
+    if ((yield* exists('bun.lock')) || (yield* exists('bun.lockb'))) {
+        return yield* run('bun --frozen-lockfile', 'bun', ['install', '--frozen-lockfile']);
+    }
+    if (yield* exists('package-lock.json'))
+        return yield* run('npm ci', 'npm', ['ci']);
+    if (yield* exists('yarn.lock')) {
+        const version = yield* capture('yarn', ['--version'], { cwd: repo }).pipe(Effect.mapError(error => fail(error.message)));
+        const major = Number(version.stdout.trim().split('.')[0]);
+        const flag = Number.isInteger(major) && major >= 2 ? '--immutable' : '--frozen-lockfile';
+        return yield* run(`yarn ${flag}`, 'yarn', ['install', flag]);
+    }
+    return yield* fail(`no supported lockfile found in ${repo}`);
+});

package/dist/env/paths.js

@@ -0,0 +1,105 @@
+import * as NodeFs from 'node:fs/promises';
+import { Effect, FileSystem, Option, Path } from 'effect';
+import { gitOutput, gitSucceeds } from '../shared/git.js';
+import { ensureNotSymlink } from '../shared/private-file.js';
+import { normalizeAppDir } from '../shared/repo-config.js';
+import { EnvError, fail } from './domain.js';
+/** Resolves and validates a Git checkout root. */
+export const resolveCheckout = (requested) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const candidate = path.resolve(requested);
+    const isDirectory = yield* fs.stat(candidate).pipe(Effect.map(info => info.type === 'Directory'), Effect.orElseSucceed(() => false));
+    if (!isDirectory)
+        return yield* fail(`not a directory: ${candidate}`);
+    const inside = yield* gitOutput(candidate, ['rev-parse', '--is-inside-work-tree']);
+    if (Option.getOrUndefined(inside) !== 'true') {
+        return yield* fail(`not a Git checkout: ${candidate}`);
+    }
+    const top = yield* gitOutput(candidate, ['rev-parse', '--show-toplevel']);
+    if (Option.isNone(top))
+        return yield* fail(`cannot resolve checkout root: ${candidate}`);
+    return path.resolve(top.value);
+});
+/**
+ * Resolves the selected application directory without changing checkout or lease identity. The
+ * app must exist, contain `package.json` (unless it is the root), and be reached without symlinks.
+ */
+export const resolveAppDirectory = (repo, requested) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const appDir = normalizeAppDir(requested);
+    if (appDir === undefined || appDir.includes(':')) {
+        return yield* fail("app directory must be '.' or a checkout-relative path without traversal");
+    }
+    const directory = path.join(repo, appDir);
+    const canonicalRoot = yield* fs
+        .realPath(repo)
+        .pipe(Effect.mapError(() => fail('cannot resolve checkout directory')));
+    const canonicalApp = yield* fs
+        .realPath(directory)
+        .pipe(Effect.mapError(() => fail(`app directory does not exist: ${appDir}`)));
+    if (canonicalApp !== path.join(canonicalRoot, appDir)) {
+        return yield* fail('app directory must not traverse symlinks');
+    }
+    const info = yield* fs
+        .stat(directory)
+        .pipe(Effect.mapError(() => fail(`cannot inspect app directory: ${appDir}`)));
+    if (info.type !== 'Directory')
+        return yield* fail(`not an app directory: ${appDir}`);
+    if (appDir !== '.') {
+        const manifest = yield* fs
+            .stat(path.join(directory, 'package.json'))
+            .pipe(Effect.mapError(() => fail('app directory must contain package.json')));
+        if (manifest.type !== 'File')
+            return yield* fail('app directory must contain package.json');
+    }
+    return { appDir, directory };
+});
+/**
+ * Fails when any existing component of `directory/file` is a symlink (dangling links included).
+ * Preflight validation, not a sandbox against concurrent same-user mutation.
+ */
+export const ensureProvisionPaths = (directory, files) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    for (const file of files) {
+        let parent = directory;
+        for (const component of file.split('/')) {
+            const entries = yield* fs
+                .readDirectory(parent)
+                .pipe(Effect.mapError(() => fail(`cannot inspect provisioning path: ${file}`)));
+            if (!entries.includes(component))
+                break;
+            const child = path.join(parent, component);
+            const symbolic = yield* Effect.tryPromise({
+                try: async () => (await NodeFs.lstat(child)).isSymbolicLink(),
+                catch: () => fail(`cannot inspect provisioning path: ${file}`)
+            });
+            if (symbolic)
+                return yield* fail(`provisioning path must not traverse symlinks: ${file}`);
+            parent = child;
+        }
+    }
+});
+/** Env files and Vercel links may only be written to untracked, ignored, non-symlink paths. */
+export const ensureSecretPath = (repo, relativeFile) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    yield* ensureNotSymlink(path.join(repo, relativeFile)).pipe(Effect.mapError(() => fail(`refusing symbolic-link environment path: ${relativeFile}`)));
+    if (yield* gitSucceeds(repo, ['ls-files', '--error-unmatch', '--', relativeFile])) {
+        return yield* fail(`refusing to write ${relativeFile} because it is tracked`);
+    }
+    if (!(yield* gitSucceeds(repo, ['check-ignore', '-q', '--', relativeFile]))) {
+        return yield* fail(`refusing to write ${relativeFile} because it is not git-ignored`);
+    }
+});
+const lstatCheck = (file, check, message) => Effect.tryPromise({
+    try: async () => {
+        if (!check(await NodeFs.lstat(file)))
+            throw new Error('unsafe path');
+    },
+    catch: () => new EnvError({ message })
+});
+export const ensureLocalDirectory = (directory, label) => lstatCheck(directory, info => !info.isSymbolicLink() && info.isDirectory(), `${label} is not a local directory`);
+export const ensureRegularFile = (file, label) => lstatCheck(file, info => !info.isSymbolicLink() && info.isFile(), `${label} is not a regular local file`);
+export const ensurePrivateMode = (file, mode, label) => lstatCheck(file, info => !info.isSymbolicLink() && (Number(info.mode) & 0o777) === mode, `${label} does not have the required private mode`);