@magoz/provision 0.0.0-stage → 0.1.1

package/dist/db/commands.js

@@ -0,0 +1,303 @@
+import { createHash } from 'node:crypto';
+import { Console, Effect, Option, Path, Predicate, Redacted, Result } from 'effect';
+import { Command, Flag, Prompt } from 'effect/cli';
+import { resolveWorkspace } from '../shared/git.js';
+import { report } from '../shared/output.js';
+import { defaultDatabaseUrlKeys } from '../shared/sandbox-profile.js';
+import { loadConfig } from './config.js';
+import { API_KEY_ENV, clearSecret, readSettings, settingsLocation, storeSecret, writeSettings } from './credentials.js';
+import { ConfigurationError, PolicyError } from './domain.js';
+import { allLeases, expiredBeyondGrace, readLease, removeLease, withLeaseLock, writeLease } from './lease.js';
+import { describeProject, findDefaultBranch, getBranch, setExpiration } from './neon.js';
+import { attestIfDeclared, createLease, releaseLease, timestamp } from './operations.js';
+import { ensureLeaseProfile, parseTtl, validateDeletionTarget, validateLeaseName } from './policy.js';
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+const setExitCode = (code) => Effect.sync(() => {
+    process.exitCode = code;
+});
+/** Expected failures print one line on stderr and exit 2; defects stay defects. */
+const handled = (effect) => effect.pipe(Effect.catch(error => Console.error(`provision db: ${error.message}`).pipe(Effect.andThen(setExitCode(2)))));
+/** Identifies which credential is in use without revealing any of it. */
+const fingerprint = (secret) => createHash('sha256').update(Redacted.value(secret)).digest('hex').slice(0, 8);
+const readStdin = Effect.promise(async () => {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        if (Predicate.isString(chunk))
+            chunks.push(Buffer.from(chunk));
+        else if (chunk instanceof Uint8Array)
+            chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8').trim();
+});
+// ---------------------------------------------------------------------------
+// shared flags
+// ---------------------------------------------------------------------------
+const worktreeFlag = Flag.String('worktree').pipe(Flag.withDescription('worktree path (default: current directory)'), Flag.optional);
+const jsonFlag = Flag.Boolean('json').pipe(Flag.withDescription('machine-readable output'), Flag.withDefault(false));
+const ttlFlag = Flag.String('ttl').pipe(Flag.withDescription('lifetime such as 12h or 7d (default 7d)'), Flag.withDefault('7d'));
+const leaseFlag = Flag.String('lease').pipe(Flag.withDescription('lease slot within the worktree (default: default)'), Flag.withDefault('default'));
+// ---------------------------------------------------------------------------
+// auth
+// ---------------------------------------------------------------------------
+const authLogin = Command.make('login', {
+    json: jsonFlag,
+    projectId: Flag.String('project-id').pipe(Flag.withDescription('neon sandbox project id'), Flag.optional),
+    parentBranch: Flag.String('parent-branch').pipe(Flag.withDescription('parent branch id (default: project default branch)'), Flag.optional),
+    tokenStdin: Flag.Boolean('token-stdin').pipe(Flag.withDescription('read the api key from stdin instead of prompting'), Flag.withDefault(false))
+}, ({ json, parentBranch, projectId, tokenStdin }) => handled(Effect.gen(function* () {
+    const existing = yield* readSettings;
+    // The credential is Redacted from the moment it is captured.
+    const apiKey = tokenStdin
+        ? Redacted.make(yield* readStdin)
+        : yield* Prompt.run(Prompt.Password({ message: 'Neon API key (input hidden)' })).pipe(Effect.mapError(() => new ConfigurationError({ message: 'cancelled' })));
+    if (Redacted.value(apiKey).trim().length === 0) {
+        return yield* new ConfigurationError({ message: 'no api key provided' });
+    }
+    const resolvedProject = Option.isSome(projectId)
+        ? projectId.value
+        : Option.isSome(existing.projectId)
+            ? existing.projectId.value
+            : yield* Prompt.run(Prompt.String({ message: 'Neon sandbox project id' })).pipe(Effect.mapError(() => new ConfigurationError({ message: 'cancelled' })));
+    // Validate before persisting anything.
+    const access = { apiKey, projectId: resolvedProject };
+    const project = yield* describeProject(access);
+    const parent = Option.isSome(parentBranch)
+        ? parentBranch.value
+        : (yield* findDefaultBranch(access)).id;
+    if (Option.isNone(yield* getBranch(access, parent))) {
+        return yield* new ConfigurationError({
+            message: `parent branch ${parent} does not exist in project ${resolvedProject}`
+        });
+    }
+    const backend = yield* storeSecret(apiKey);
+    yield* writeSettings({ projectId: project.id, parentBranch: parent });
+    return yield* report(json, {
+        status: 'authenticated',
+        backend,
+        project: `${project.name} (${project.id})`,
+        parent_branch: parent,
+        fingerprint: fingerprint(apiKey),
+        note: 'credential stored; it is never printed'
+    });
+}))).pipe(Command.withDescription('Store a global Neon key and sandbox project.'));
+const authStatus = Command.make('status', { json: jsonFlag, worktree: worktreeFlag }, ({ json, worktree }) => handled(Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const workspace = Option.isSome(worktree)
+        ? Result.succeed(yield* resolveWorkspace(worktree))
+        : yield* Effect.result(resolveWorkspace(Option.none()));
+    const envFile = path.join(Result.isSuccess(workspace) ? workspace.success.root : path.resolve(process.cwd()), '.env.local');
+    const resolved = yield* Effect.result(loadConfig(envFile));
+    if (Result.isFailure(resolved)) {
+        yield* report(json, {
+            status: 'unauthenticated',
+            settings_file: envFile,
+            note: resolved.failure.message
+        });
+        return yield* setExitCode(1);
+    }
+    const config = resolved.success;
+    const settingsFile = config.backend === 'worktree-env' ? envFile : yield* settingsLocation;
+    const verification = yield* Effect.result(Effect.gen(function* () {
+        const project = yield* describeProject(config);
+        if (Option.isNone(yield* getBranch(config, config.parentBranch))) {
+            return yield* new ConfigurationError({
+                message: `parent branch ${config.parentBranch} does not exist in project ${config.projectId}`
+            });
+        }
+        return project;
+    }));
+    if (Result.isFailure(verification)) {
+        yield* report(json, {
+            status: 'invalid',
+            backend: config.backend,
+            fingerprint: fingerprint(config.apiKey),
+            project: config.projectId,
+            parent_branch: `${config.parentBranch} (unverified)`,
+            settings_file: settingsFile,
+            note: verification.failure.message
+        });
+        return yield* setExitCode(1);
+    }
+    yield* report(json, {
+        status: 'authenticated',
+        backend: config.backend,
+        fingerprint: fingerprint(config.apiKey),
+        project: `${verification.success.name} (${verification.success.id})`,
+        parent_branch: config.parentBranch,
+        settings_file: settingsFile
+    });
+}))).pipe(Command.withDescription('Show the resolved worktree or global auth.'));
+const authLogout = Command.make('logout', { json: jsonFlag }, ({ json }) => handled(Effect.gen(function* () {
+    const removed = yield* clearSecret;
+    return yield* report(json, {
+        status: removed.length > 0 ? 'cleared' : 'nothing-stored',
+        backends: removed.join(', ') || 'none',
+        note: `an ${API_KEY_ENV} environment variable or complete worktree .env.local profile, if set, still applies`
+    });
+}))).pipe(Command.withDescription('Remove the stored global Neon key.'));
+const auth = Command.make('auth').pipe(Command.withDescription('Manage global Neon auth and inspect resolved worktree auth.'), Command.withSubcommands([authLogin, authStatus, authLogout]));
+// ---------------------------------------------------------------------------
+// create
+// ---------------------------------------------------------------------------
+const create = Command.make('create', {
+    worktree: worktreeFlag,
+    json: jsonFlag,
+    ttl: ttlFlag,
+    label: Flag.String('label').pipe(Flag.withDescription('short label, e.g. issue-4'), Flag.optional),
+    envFile: Flag.String('env-file').pipe(Flag.withDescription('env file that receives database URLs'), Flag.withDefault('.env.local')),
+    configEnvFile: Flag.String('config-env-file').pipe(Flag.withDescription('env file containing the sandbox database profile (default: --env-file)'), Flag.optional),
+    leaseName: leaseFlag,
+    keys: Flag.String('keys').pipe(Flag.withDescription('comma-separated env keys to write'), Flag.withDefault(defaultDatabaseUrlKeys.join(','))),
+    forceNew: Flag.Boolean('force-new').pipe(Flag.withDescription('ignore any existing lease'), Flag.withDefault(false)),
+    noWait: Flag.Boolean('no-wait').pipe(Flag.withDescription('do not wait for the branch to become ready'), Flag.withDefault(false))
+}, ({ json, ...options }) => handled(Effect.flatMap(createLease(options), result => report(json, result.report)))).pipe(Command.withDescription('Create or reuse a disposable database branch for a worktree.'));
+// ---------------------------------------------------------------------------
+// status / renew / release
+// ---------------------------------------------------------------------------
+const status = Command.make('status', { worktree: worktreeFlag, json: jsonFlag, leaseName: leaseFlag }, ({ json, leaseName, worktree }) => handled(Effect.gen(function* () {
+    const workspace = yield* resolveWorkspace(worktree);
+    const name = yield* validateLeaseName(leaseName);
+    const lease = yield* readLease(workspace.root, name);
+    if (Option.isNone(lease)) {
+        yield* report(json, { status: 'none', lease: name, worktree: workspace.root });
+        return yield* setExitCode(1);
+    }
+    const config = yield* loadConfig(lease.value.configEnvFile);
+    yield* ensureLeaseProfile(config, lease.value);
+    const branch = yield* getBranch(config, lease.value.branchId);
+    yield* report(json, {
+        status: Option.isSome(branch) ? 'live' : 'missing',
+        lease: lease.value.leaseName,
+        branch_name: lease.value.branchName,
+        branch_id: lease.value.branchId,
+        state: Option.match(branch, {
+            onNone: () => 'gone',
+            onSome: value => value.current_state ?? 'unknown'
+        }),
+        expires_at: Option.match(branch, {
+            onNone: () => lease.value.expiresAt,
+            onSome: value => value.expires_at ?? lease.value.expiresAt
+        }),
+        repository: lease.value.repository,
+        parent_branch: lease.value.parentBranch,
+        config_source: config.backend,
+        config_env_file: lease.value.configEnvFile,
+        env_file: lease.value.envFile,
+        worktree: lease.value.worktree
+    });
+    if (Option.isNone(branch))
+        yield* setExitCode(1);
+}))).pipe(Command.withDescription('Show a lease and its branch state.'));
+const renew = Command.make('renew', { worktree: worktreeFlag, json: jsonFlag, leaseName: leaseFlag, ttl: ttlFlag }, ({ json, leaseName, ttl, worktree }) => handled(Effect.gen(function* () {
+    const workspace = yield* resolveWorkspace(worktree);
+    const name = yield* validateLeaseName(leaseName);
+    return yield* withLeaseLock(workspace.root, name, Effect.gen(function* () {
+        const lease = yield* readLease(workspace.root, name);
+        if (Option.isNone(lease)) {
+            return yield* new PolicyError({
+                message: `no ${name} lease recorded for ${workspace.root}`
+            });
+        }
+        const config = yield* loadConfig(lease.value.configEnvFile);
+        yield* ensureLeaseProfile(config, lease.value);
+        yield* attestIfDeclared(config, workspace);
+        const ttlSeconds = yield* parseTtl(ttl);
+        const recorded = yield* getBranch(config, lease.value.branchId);
+        if (Option.isNone(recorded)) {
+            return yield* new PolicyError({
+                message: `recorded branch ${lease.value.branchId} no longer exists`
+            });
+        }
+        yield* validateDeletionTarget(lease.value, recorded.value);
+        const expiresAt = timestamp(ttlSeconds);
+        yield* setExpiration(config, lease.value, expiresAt);
+        const updated = { ...lease.value, expiresAt };
+        yield* writeLease(updated);
+        return yield* report(json, {
+            status: 'renewed',
+            lease: updated.leaseName,
+            branch_name: updated.branchName,
+            branch_id: updated.branchId,
+            expires_at: updated.expiresAt
+        });
+    }));
+}))).pipe(Command.withDescription("Extend a lease's TTL."));
+const release = Command.make('release', {
+    worktree: worktreeFlag,
+    json: jsonFlag,
+    leaseName: leaseFlag,
+    keepEnv: Flag.Boolean('keep-env').pipe(Flag.withDescription('leave env keys in place'), Flag.withDefault(false))
+}, ({ json, keepEnv, leaseName, worktree }) => handled(Effect.flatMap(releaseLease({ worktree, leaseName, keepEnv }), payload => report(json, payload)))).pipe(Command.withDescription('Delete a lease branch and remove its env keys.'));
+// ---------------------------------------------------------------------------
+// list / gc
+// ---------------------------------------------------------------------------
+const list = Command.make('list', { json: jsonFlag }, ({ json }) => handled(Effect.gen(function* () {
+    const leases = yield* allLeases;
+    if (json)
+        return yield* Console.log(JSON.stringify(leases, null, 2));
+    if (leases.length === 0)
+        return yield* Console.log('no leases');
+    return yield* Console.log(leases
+        .map(lease => `${lease.leaseName}  ${lease.branchName}  ${lease.expiresAt}  ${lease.worktree}`)
+        .join('\n'));
+}))).pipe(Command.withDescription('List local lease records.'));
+/** `gc --prune-expired`: how long past its expiry a record must be before it is pruned blind. */
+const EXPIRED_GRACE_MS = 24 * 60 * 60 * 1000;
+const gc = Command.make('gc', {
+    json: jsonFlag,
+    dryRun: Flag.Boolean('dry-run').pipe(Flag.withDescription('report without removing lease records'), Flag.withDefault(false)),
+    pruneExpired: Flag.Boolean('prune-expired').pipe(Flag.withDescription('also remove records whose expiry passed over a day ago, without Neon credentials (Neon already deleted those branches)'), Flag.withDefault(false))
+}, ({ dryRun, json, pruneExpired }) => handled(Effect.gen(function* () {
+    const leases = yield* allLeases;
+    const stale = [];
+    const expired = [];
+    const inaccessible = [];
+    let live = 0;
+    const now = Date.now();
+    for (const lease of leases) {
+        if (pruneExpired && expiredBeyondGrace(lease, now, EXPIRED_GRACE_MS)) {
+            expired.push(lease.branchName);
+            if (!dryRun)
+                yield* removeLease(lease.worktree, lease.leaseName);
+            continue;
+        }
+        const resolved = yield* Effect.result(loadConfig(lease.configEnvFile));
+        if (Result.isFailure(resolved) ||
+            resolved.success.projectId !== lease.projectId ||
+            resolved.success.parentBranch !== lease.parentBranch) {
+            inaccessible.push(lease.branchName);
+            continue;
+        }
+        const lookedUp = yield* Effect.result(getBranch(resolved.success, lease.branchId));
+        if (Result.isFailure(lookedUp)) {
+            inaccessible.push(lease.branchName);
+            continue;
+        }
+        if (Option.isSome(lookedUp.success)) {
+            live += 1;
+            continue;
+        }
+        stale.push(lease.branchName);
+        if (!dryRun)
+            yield* removeLease(lease.worktree, lease.leaseName);
+    }
+    yield* report(json, {
+        status: inaccessible.length > 0 ? 'partial' : dryRun ? 'dry-run' : 'pruned',
+        live_leases: live,
+        stale_leases: stale.length,
+        expired_leases: expired.length,
+        inaccessible_leases: inaccessible.length,
+        pruned: [...stale, ...expired].join(', ') || 'none',
+        inaccessible: inaccessible.join(', ') || 'none'
+    });
+    // With --prune-expired every remaining unverifiable record expires within the TTL cap and
+    // is pruned by a later run, so it is reported but does not fail the run (daily timer).
+    if (inaccessible.length > 0 && !pruneExpired)
+        yield* setExitCode(1);
+}))).pipe(Command.withDescription('Prune lease records whose branches are gone.'));
+// ---------------------------------------------------------------------------
+// root
+// ---------------------------------------------------------------------------
+export const dbCommand = Command.make('db').pipe(Command.withDescription('Manage disposable Neon database branches for local checkouts.'), Command.withSubcommands([auth, create, status, renew, release, list, gc]));

package/dist/db/config.js

@@ -0,0 +1,75 @@
+import { Effect, Option, Redacted } from 'effect';
+import { parseEnvFile } from '../shared/env-file.js';
+import { readPrivately } from '../shared/private-file.js';
+import { sandboxProfileKeys } from '../shared/sandbox-profile.js';
+import { readSecret, readSettings } from './credentials.js';
+import { ConfigurationError } from './domain.js';
+const missing = (what) => new ConfigurationError({
+    message: `${what}\n` +
+        "run: provision db auth login, or configure the worktree's Vercel Development environment"
+});
+/**
+ * A worktree profile is atomic: once any local key is present, all three must be present. This
+ * prevents accidentally combining one account's credential with another account's globally
+ * configured project.
+ */
+const readWorktreeConfig = (envFile) => Effect.gen(function* () {
+    const content = yield* readPrivately(envFile).pipe(Effect.mapError(error => new ConfigurationError({
+        message: error.reason === 'symbolic-link'
+            ? `refusing symbolic-link environment path: ${envFile}`
+            : `cannot read local environment ${envFile}`
+    })));
+    if (content === undefined)
+        return Option.none();
+    const entries = parseEnvFile(content);
+    const declared = sandboxProfileKeys.filter(key => entries.has(key));
+    if (declared.length === 0)
+        return Option.none();
+    const absent = sandboxProfileKeys.filter(key => !entries.has(key));
+    const value = (key) => (entries.get(key) ?? '').trim();
+    const empty = sandboxProfileKeys.filter(key => entries.has(key) && value(key).length === 0);
+    if (absent.length > 0 || empty.length > 0) {
+        const details = [
+            absent.length > 0 ? `missing ${absent.join(', ')}` : '',
+            empty.length > 0 ? `empty ${empty.join(', ')}` : ''
+        ]
+            .filter(detail => detail.length > 0)
+            .join('; ');
+        return yield* new ConfigurationError({
+            message: `incomplete sandbox database profile in ${envFile}; ${details}\n` +
+                'local profiles are not combined with global authentication'
+        });
+    }
+    const [apiKey, projectId, parentBranch] = sandboxProfileKeys;
+    return Option.some({
+        apiKey: Redacted.make(value(apiKey)),
+        projectId: value(projectId),
+        parentBranch: value(parentBranch),
+        backend: 'worktree-env'
+    });
+});
+/**
+ * Resolves one complete credential/project/parent tuple. A complete profile in the worktree env
+ * takes precedence; otherwise global auth is used as a fallback.
+ */
+export const loadConfig = (envFile) => Effect.gen(function* () {
+    if (envFile !== undefined) {
+        const local = yield* readWorktreeConfig(envFile);
+        if (Option.isSome(local))
+            return local.value;
+    }
+    const secret = yield* readSecret;
+    if (Option.isNone(secret))
+        return yield* missing('no neon api key configured');
+    const settings = yield* readSettings;
+    if (Option.isNone(settings.projectId))
+        return yield* missing('no sandbox project configured');
+    if (Option.isNone(settings.parentBranch))
+        return yield* missing('no parent branch configured');
+    return {
+        apiKey: secret.value.value,
+        projectId: settings.projectId.value,
+        parentBranch: settings.parentBranch.value,
+        backend: secret.value.backend
+    };
+});

package/dist/db/credentials.js

@@ -0,0 +1,177 @@
+import { Effect, FileSystem, Option, Predicate, Redacted, Schema } from 'effect';
+import { parseEnvFile } from '../shared/env-file.js';
+import { readPrivately, writePrivately } from '../shared/private-file.js';
+import { capture } from '../shared/process.js';
+import { ConfigurationError } from './domain.js';
+import { DbEnvironment } from './environment.js';
+/**
+ * Global credential storage behind `provision db auth`. Backends, in read precedence order:
+ *
+ *   1. environment - explicit override, useful for CI or a parent process
+ *   2. keychain    - encrypted at rest (macOS)
+ *   3. config file - `0600` fallback for machines without a keychain
+ */
+const SERVICE = 'sandbox-db';
+const ACCOUNT = 'neon-api-key';
+export const API_KEY_ENV = 'NEON_AGENTS_SANDBOX_API_KEY';
+const PROJECT_ENV = 'NEON_AGENTS_SANDBOX_PROJECT_ID';
+const PARENT_ENV = 'NEON_AGENTS_SANDBOX_PARENT_BRANCH';
+export const settingsLocation = Effect.gen(function* () {
+    return `${(yield* DbEnvironment).configDirectory}/sandbox-db.json`;
+});
+export const secretFileLocation = Effect.gen(function* () {
+    return `${(yield* DbEnvironment).configDirectory}/sandbox-db.env`;
+});
+const ensureConfigDirectory = Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const environment = yield* DbEnvironment;
+    yield* fs
+        .makeDirectory(environment.configDirectory, { recursive: true })
+        .pipe(Effect.orElseSucceed(() => undefined));
+});
+// ---------------------------------------------------------------------------
+// keychain backend
+// ---------------------------------------------------------------------------
+const keychainAvailable = Effect.gen(function* () {
+    const environment = yield* DbEnvironment;
+    if (!environment.keychain)
+        return false;
+    return yield* capture('which', ['security']).pipe(Effect.map(result => result.exitCode === 0), Effect.orElseSucceed(() => false));
+});
+const keychainRead = capture('security', [
+    'find-generic-password',
+    '-s',
+    SERVICE,
+    '-a',
+    ACCOUNT,
+    '-w'
+]).pipe(Effect.map(result => {
+    const trimmed = result.stdout.trim();
+    return result.exitCode === 0 && trimmed.length > 0 ? Option.some(trimmed) : Option.none();
+}), Effect.orElseSucceed(() => Option.none()));
+/**
+ * `security` takes the secret as an argument, so it is briefly visible in the process table to
+ * this user. That is the same trust boundary as the `0600` file it replaces; the win is
+ * encryption at rest, not process isolation.
+ */
+const keychainWrite = (secret) => capture('security', [
+    'add-generic-password',
+    '-s',
+    SERVICE,
+    '-a',
+    ACCOUNT,
+    '-w',
+    Redacted.value(secret),
+    '-U',
+    '-D',
+    'sandbox-db neon api key'
+]).pipe(Effect.mapError(() => new ConfigurationError({ message: 'keychain unavailable; provider output suppressed' })), Effect.flatMap(result => result.exitCode === 0
+    ? Effect.void
+    : Effect.fail(new ConfigurationError({ message: `keychain write failed (exit ${result.exitCode})` }))));
+const keychainDelete = capture('security', [
+    'delete-generic-password',
+    '-s',
+    SERVICE,
+    '-a',
+    ACCOUNT
+]).pipe(Effect.map(result => result.exitCode === 0), Effect.orElseSucceed(() => false));
+// ---------------------------------------------------------------------------
+// file backend
+// ---------------------------------------------------------------------------
+const readSecretFile = Effect.gen(function* () {
+    const file = yield* secretFileLocation;
+    const content = yield* readPrivately(file).pipe(Effect.orElseSucceed(() => undefined));
+    return new Map(parseEnvFile(content ?? ''));
+});
+const writeSecretFile = (entries) => Effect.gen(function* () {
+    yield* ensureConfigDirectory;
+    const file = yield* secretFileLocation;
+    const body = [...entries].map(([key, value]) => `${key}=${value}`).join('\n');
+    yield* writePrivately(file, body.length > 0 ? `${body}\n` : '').pipe(Effect.mapError(() => new ConfigurationError({ message: `private config write failed: ${file}` })));
+});
+// ---------------------------------------------------------------------------
+// secret api
+// ---------------------------------------------------------------------------
+const nonEmpty = (value) => {
+    const trimmed = value?.trim();
+    return trimmed === undefined || trimmed.length === 0 ? undefined : trimmed;
+};
+export const readSecret = Effect.gen(function* () {
+    const environment = yield* DbEnvironment;
+    const fromEnvironment = nonEmpty(environment.variable(API_KEY_ENV));
+    if (fromEnvironment !== undefined) {
+        return Option.some({
+            value: Redacted.make(fromEnvironment),
+            backend: 'environment'
+        });
+    }
+    if (yield* keychainAvailable) {
+        const stored = yield* keychainRead;
+        if (Option.isSome(stored)) {
+            return Option.some({
+                value: Redacted.make(stored.value),
+                backend: 'keychain'
+            });
+        }
+    }
+    const fromFile = nonEmpty((yield* readSecretFile).get(API_KEY_ENV));
+    return fromFile === undefined
+        ? Option.none()
+        : Option.some({ value: Redacted.make(fromFile), backend: 'file' });
+});
+export const storeSecret = (secret) => Effect.gen(function* () {
+    if (yield* keychainAvailable) {
+        yield* keychainWrite(secret);
+        // Do not leave an older plaintext copy behind once the keychain owns it.
+        const entries = yield* readSecretFile;
+        if (entries.delete(API_KEY_ENV))
+            yield* writeSecretFile(entries);
+        return 'keychain';
+    }
+    const entries = yield* readSecretFile;
+    entries.set(API_KEY_ENV, Redacted.value(secret));
+    yield* writeSecretFile(entries);
+    return 'file';
+});
+export const clearSecret = Effect.gen(function* () {
+    const removed = [];
+    if ((yield* keychainAvailable) && (yield* keychainDelete))
+        removed.push('keychain');
+    const entries = yield* readSecretFile;
+    if (entries.delete(API_KEY_ENV)) {
+        yield* writeSecretFile(entries);
+        removed.push('file');
+    }
+    return removed;
+});
+// ---------------------------------------------------------------------------
+// non-secret settings
+// ---------------------------------------------------------------------------
+const decodeJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Unknown));
+/** Only string fields count; anything else (including deep structures) is skipped, not decoded. */
+const storedString = (stored, key) => Predicate.hasProperty(stored, key) && Predicate.isString(stored[key]) ? stored[key] : undefined;
+export const readSettings = Effect.gen(function* () {
+    const environment = yield* DbEnvironment;
+    const file = yield* settingsLocation;
+    const content = yield* readPrivately(file).pipe(Effect.orElseSucceed(() => undefined));
+    const stored = content === undefined ? undefined : Option.getOrUndefined(decodeJson(content));
+    const legacy = yield* readSecretFile;
+    const pick = (variable, key) => Option.fromUndefinedOr(nonEmpty(environment.variable(variable)) ??
+        nonEmpty(storedString(stored, key)) ??
+        nonEmpty(legacy.get(variable)));
+    return {
+        projectId: pick(PROJECT_ENV, 'projectId'),
+        parentBranch: pick(PARENT_ENV, 'parentBranch')
+    };
+});
+export const writeSettings = (settings) => Effect.gen(function* () {
+    yield* ensureConfigDirectory;
+    const file = yield* settingsLocation;
+    yield* writePrivately(file, `${JSON.stringify(settings, null, 2)}\n`).pipe(Effect.mapError(() => new ConfigurationError({ message: `settings write failed: ${file}` })));
+    // Retire legacy plaintext settings now that the JSON store owns them.
+    const entries = yield* readSecretFile;
+    const hadProject = entries.delete(PROJECT_ENV);
+    const hadParent = entries.delete(PARENT_ENV);
+    if (hadProject || hadParent)
+        yield* writeSecretFile(entries);
+});

package/dist/db/domain.js

@@ -0,0 +1,106 @@
+import { Data, Schema } from 'effect';
+/** Policy: leases are short-lived by construction. */
+export const BRANCH_PREFIX = 'agent/';
+export const MAX_TTL_SECONDS = 7 * 24 * 3600;
+export const SUSPEND_TIMEOUT_SECONDS = 300;
+export const READY_TIMEOUT_SECONDS = 90;
+export class ConfigurationError extends Data.TaggedError('ConfigurationError') {
+}
+export class PolicyError extends Data.TaggedError('PolicyError') {
+}
+export class NeonError extends Data.TaggedError('NeonError') {
+}
+export class LeaseError extends Data.TaggedError('LeaseError') {
+}
+export class LifecycleError extends Data.TaggedError('LifecycleError') {
+}
+/** Neon branch, narrowed to the fields this tool relies on. */
+export const Branch = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    parent_id: Schema.optional(Schema.String),
+    current_state: Schema.optional(Schema.String),
+    default: Schema.optional(Schema.Boolean),
+    protected: Schema.optional(Schema.Boolean),
+    expires_at: Schema.optional(Schema.String),
+    ttl_interval_seconds: Schema.optional(Schema.Number)
+});
+/**
+ * Connection material stays `Redacted` end to end. It is unwrapped only at the single boundary
+ * that writes the worktree env file.
+ */
+const RedactedString = Schema.RedactedFromValue(Schema.String);
+export const BranchResponse = Schema.Struct({ branch: Branch });
+export const Project = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String
+});
+export const ProjectResponse = Schema.Struct({ project: Project });
+export const CreateBranchResponse = Schema.Struct({ branch: Branch });
+export const BranchListResponse = Schema.Struct({
+    branches: Schema.Array(Branch),
+    pagination: Schema.optional(Schema.Struct({ cursor: Schema.optional(Schema.String) }))
+});
+export const Database = Schema.Struct({
+    name: Schema.String,
+    owner_name: Schema.String
+});
+export const DatabaseListResponse = Schema.Struct({
+    databases: Schema.Array(Database)
+});
+export const ConnectionUriResponse = Schema.Struct({ uri: RedactedString });
+/** Legacy single-lease records remain readable as the `default` lease. */
+const LegacyLease = Schema.Struct({
+    version: Schema.Literal(1),
+    projectId: Schema.String,
+    parentBranch: Schema.String,
+    branchId: Schema.String,
+    branchName: Schema.String,
+    worktree: Schema.String,
+    repository: Schema.String,
+    label: Schema.String,
+    envFile: Schema.String,
+    envKeys: Schema.Array(Schema.String),
+    createdAt: Schema.String,
+    expiresAt: Schema.String
+});
+/** Lease records are persisted outside the repository and hold no secrets. */
+export const Lease = Schema.Struct({
+    version: Schema.Literal(2),
+    leaseName: Schema.String,
+    projectId: Schema.String,
+    parentBranch: Schema.String,
+    branchId: Schema.String,
+    branchName: Schema.String,
+    worktree: Schema.String,
+    repository: Schema.String,
+    label: Schema.String,
+    configEnvFile: Schema.String,
+    envFile: Schema.String,
+    envKeys: Schema.Array(Schema.String),
+    databaseName: Schema.optionalKey(Schema.String),
+    roleName: Schema.optionalKey(Schema.String),
+    createdAt: Schema.String,
+    expiresAt: Schema.String
+});
+export const LeaseRecord = Schema.Union([LegacyLease, Lease]);
+export const LeaseRecordFromJson = Schema.fromJsonString(LeaseRecord);
+export const LeaseFromJson = Schema.fromJsonString(Lease);
+export const normalizeLease = (lease) => lease.version === 2
+    ? lease
+    : {
+        version: 2,
+        leaseName: 'default',
+        projectId: lease.projectId,
+        parentBranch: lease.parentBranch,
+        branchId: lease.branchId,
+        branchName: lease.branchName,
+        worktree: lease.worktree,
+        repository: lease.repository,
+        label: lease.label,
+        configEnvFile: lease.envFile,
+        envFile: lease.envFile,
+        envKeys: lease.envKeys,
+        createdAt: lease.createdAt,
+        expiresAt: lease.expiresAt
+    };

package/dist/db/environment.js

@@ -0,0 +1,14 @@
+import { join } from 'node:path';
+import { Context, Layer } from 'effect';
+export class DbEnvironment extends Context.Service()('provision/db/DbEnvironment') {
+}
+export const makeDbEnvironment = (env, platform) => {
+    const home = env.HOME ?? '';
+    return {
+        configDirectory: join(env.XDG_CONFIG_HOME ?? join(home, '.config'), 'pi'),
+        stateDirectory: join(env.XDG_STATE_HOME ?? join(home, '.local', 'state'), 'pi', 'sandbox-db'),
+        variable: name => env[name],
+        keychain: platform === 'darwin'
+    };
+};
+export const DbEnvironmentLive = Layer.sync(DbEnvironment, () => makeDbEnvironment(process.env, process.platform));