anhedral 0.10.0 → 0.11.0

package/dist/project-state.js

@@ -1,7 +1,10 @@
 import { randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { existsSync, lstatSync, fstatSync, openSync, closeSync, unlinkSync, rmdirSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
 import { spawn } from 'node:child_process';
 import path from 'node:path';
+import { hostname } from 'node:os';
+import { readBoundedFile } from './bounded-file.js';
 import { parse } from 'jsonc-parser';
 import { resolveCommand } from './command.js';
 const manifestName = 'anhedral.project.json';
@@ -204,23 +207,248 @@ export async function authenticate(root, project, run) {
         !identity.accounts.some((account) => account.id === project.accountId))
         throw new Error('Wrangler cannot access the registered Cloudflare account. Run wrangler login or configure scoped credentials.');
 }
-export async function withApplicationLock(root, operation) {
-    root = realpathSync(root);
+const applicationLocks = new AsyncLocalStorage();
+const lockBusy = () => new Error('Another delivery is running or was interrupted. Inspect provider status and use anhedral recover --lock only after reviewing the recorded operation.');
+const ownerChanged = () => new Error('Delivery lock ownership changed or is invalid. Preserve the lock and inspect local operation evidence before retrying.');
+function privateState(root) {
     const state = path.join(root, stateDirectory);
-    mkdirSync(state, { recursive: true });
-    if (realpathSync(state) !== path.join(root, stateDirectory))
-        throw new Error('Delivery state directory must not be a symbolic link.');
-    const lock = path.join(state, 'ship.lock');
     try {
-        mkdirSync(lock);
+        mkdirSync(state, { recursive: true, mode: 0o700 });
+        const stat = lstatSync(state);
+        if (!stat.isDirectory() ||
+            stat.isSymbolicLink() ||
+            realpathSync(state) !== state ||
+            (process.platform !== 'win32' && stat.mode & 0o022))
+            throw new Error();
+        return state;
+    }
+    catch {
+        throw new Error('Delivery state must be a regular directory without shared write permissions.');
+    }
+}
+function lockOwner() {
+    return {
+        schemaVersion: 1,
+        pid: process.pid,
+        host: hostname(),
+        token: randomUUID(),
+        createdAt: new Date().toISOString(),
+    };
+}
+function privateOwner(file) {
+    try {
+        const stat = lstatSync(file);
+        if (!stat.isFile() ||
+            stat.isSymbolicLink() ||
+            (process.platform !== 'win32' && (stat.mode & 0o077 || stat.uid !== process.getuid?.())))
+            throw new Error();
+        const value = JSON.parse(readBoundedFile(file, 4096).toString('utf8'));
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error();
+        const owner = value;
+        if (Object.keys(owner).some((key) => !['schemaVersion', 'pid', 'host', 'token', 'createdAt'].includes(key)) ||
+            owner.schemaVersion !== 1 ||
+            !Number.isSafeInteger(owner.pid) ||
+            owner.pid < 1 ||
+            owner.pid > 2147483647 ||
+            typeof owner.host !== 'string' ||
+            !owner.host ||
+            owner.host.length > 255 ||
+            /[\x00-\x1f\x7f]/.test(owner.host) ||
+            typeof owner.token !== 'string' ||
+            !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(owner.token) ||
+            typeof owner.createdAt !== 'string' ||
+            !/^\d{4}-\d{2}-\d{2}T/.test(owner.createdAt) ||
+            !Number.isFinite(Date.parse(owner.createdAt)))
+            throw new Error();
+        return owner;
+    }
+    catch {
+        throw ownerChanged();
+    }
+}
+function snapshotLock(lock) {
+    try {
+        const stat = lstatSync(lock);
+        if (!stat.isDirectory() ||
+            stat.isSymbolicLink() ||
+            (process.platform !== 'win32' && (stat.mode & 0o077 || stat.uid !== process.getuid?.())) ||
+            readdirSync(lock).join(',') !== 'owner.json')
+            throw new Error();
+        const file = path.join(lock, 'owner.json');
+        const owner = privateOwner(file);
+        const ownerStat = lstatSync(file);
+        return {
+            identity: {
+                device: stat.dev,
+                inode: stat.ino,
+                ownerDevice: ownerStat.dev,
+                ownerInode: ownerStat.ino,
+                owner,
+            },
+            owner,
+        };
+    }
+    catch {
+        throw ownerChanged();
+    }
+}
+function sameOwner(left, right) {
+    return (left.pid === right.pid &&
+        left.host === right.host &&
+        left.token === right.token &&
+        left.createdAt === right.createdAt);
+}
+function sameIdentity(left, right) {
+    return (left.device === right.device &&
+        left.inode === right.inode &&
+        left.ownerDevice === right.ownerDevice &&
+        left.ownerInode === right.ownerInode &&
+        sameOwner(left.owner, right.owner));
+}
+class DeliveryGuardBusyError extends Error {
+    constructor() {
+        super('Delivery lock acquisition or recovery is busy. Inspect .anhedral/ship.guard before retrying.');
+    }
+}
+/** This synchronous guard covers only filesystem transitions. An uncertain guard
+ * after process termination is preserved for operator inspection, never auto-unlinked. */
+function withLockGuard(state, operation) {
+    try {
+        const stat = lstatSync(state);
+        if (!stat.isDirectory() ||
+            stat.isSymbolicLink() ||
+            realpathSync(state) !== state ||
+            (process.platform !== 'win32' && stat.mode & 0o022))
+            throw new Error();
     }
     catch {
-        throw new Error('Another delivery is running or was interrupted. Inspect provider status and remove .anhedral/ship.lock only after confirming no delivery is active.');
+        throw ownerChanged();
+    }
+    const file = path.join(state, 'ship.guard');
+    let descriptor;
+    try {
+        descriptor = openSync(file, 'wx', 0o600);
     }
+    catch {
+        throw new DeliveryGuardBusyError();
+    }
+    const stat = fstatSync(descriptor);
+    const owner = lockOwner();
+    try {
+        writeFileSync(descriptor, JSON.stringify(owner) + '\n');
+        return operation();
+    }
+    finally {
+        closeSync(descriptor);
+        // Another process must never lose its guard because this invocation finishes.
+        let current;
+        try {
+            current = lstatSync(file);
+        }
+        catch {
+            throw ownerChanged();
+        }
+        if (current.isSymbolicLink() ||
+            current.dev !== stat.dev ||
+            current.ino !== stat.ino ||
+            !sameOwner(privateOwner(file), owner))
+            throw ownerChanged();
+        unlinkSync(file);
+    }
+}
+function removeOwnedLock(lock, identity) {
+    if (!sameIdentity(snapshotLock(lock).identity, identity))
+        throw ownerChanged();
+    // Never recursively remove a lock: unknown additional files are evidence.
+    unlinkSync(path.join(lock, 'owner.json'));
+    rmdirSync(lock);
+}
+async function releaseApplicationLock(state, lock, identity) {
+    // A simultaneous operator inspection may briefly hold the guard. Preserve our
+    // lock while waiting; never bypass a guard or reinterpret uncertain ownership.
+    for (let attempt = 0;; attempt++) {
+        try {
+            withLockGuard(state, () => removeOwnedLock(lock, identity));
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof DeliveryGuardBusyError) || attempt >= 4)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+    }
+}
+/** Explicit local cleanup only. A dead same-host PID is required; live, foreign,
+ * malformed and legacy locks remain intact. Provider operations are never replayed. */
+export function recoverDeliveryLock(root) {
+    root = realpathSync(root);
+    const state = privateState(root);
+    return withLockGuard(state, () => {
+        const lock = path.join(state, 'ship.lock');
+        if (!lstatSync(lock, { throwIfNoEntry: false }))
+            return {
+                schemaVersion: 1,
+                state: 'unlocked',
+                recovered: false,
+                mutation: 'local-lock-only',
+                providerReplay: false,
+            };
+        const snapshot = snapshotLock(lock);
+        if (snapshot.owner.host !== hostname())
+            throw new Error('Delivery lock belongs to another host; preserve it and inspect operation evidence.');
+        let dead = false;
+        try {
+            process.kill(snapshot.owner.pid, 0);
+        }
+        catch (error) {
+            if (error.code === 'ESRCH')
+                dead = true;
+            else
+                throw new Error('Cannot prove the delivery lock owner exited; preserve the lock.');
+        }
+        if (!dead)
+            throw new Error('Delivery lock owner is still running; no lock or provider state was changed.');
+        removeOwnedLock(lock, snapshot.identity);
+        return {
+            schemaVersion: 1,
+            state: 'lock-recovered',
+            recovered: true,
+            mutation: 'local-lock-only',
+            providerReplay: false,
+            nextAction: 'Inspect provider status and recorded receipts before retrying ship. No provider operation was replayed.',
+        };
+    });
+}
+export async function withApplicationLock(root, operation) {
+    root = realpathSync(root);
+    const held = applicationLocks.getStore();
+    const state = privateState(root);
+    const lock = path.join(state, 'ship.lock');
+    if (held?.active && held.root === root) {
+        if (!sameIdentity(snapshotLock(lock).identity, held.identity))
+            throw ownerChanged();
+        return operation();
+    }
+    const identity = withLockGuard(state, () => {
+        try {
+            mkdirSync(lock, { mode: 0o700 });
+        }
+        catch {
+            throw lockBusy();
+        }
+        writeFileSync(path.join(lock, 'owner.json'), JSON.stringify(lockOwner()) + '\n', {
+            flag: 'wx',
+            mode: 0o600,
+        });
+        return snapshotLock(lock).identity;
+    });
+    const context = { root, active: true, identity };
     try {
-        return await operation();
+        return await applicationLocks.run(context, operation);
     }
     finally {
-        rmSync(lock, { recursive: true, force: true });
+        context.active = false;
+        await releaseApplicationLock(state, lock, identity);
     }
 }

package/dist/provider-auth.d.ts

@@ -0,0 +1,41 @@
+import type { StandardProduct } from './stack-registry.js';
+import { type DeliveryRunner } from './project-state.js';
+export interface ProviderAuth {
+    id: string;
+    products: readonly StandardProduct[];
+    login?: readonly string[];
+    identity?: readonly string[];
+    credential?: string;
+    endpoint?: string;
+    runtime?: {
+        credential: string;
+        endpoint: string;
+    };
+    regionalEndpoints?: Readonly<Record<string, string>>;
+    setup: string;
+}
+/** Deployment access is separate from application-user authentication. */
+export declare const PROVIDER_AUTH: readonly ProviderAuth[];
+export declare function requiredProviders(root: string): ProviderAuth[];
+export type AuthState = 'verified' | 'missing' | 'insufficient-permissions' | 'unverified';
+export interface AuthCheck {
+    provider: string;
+    state: AuthState;
+    evidence: 'cli-session' | 'api-access' | 'none';
+    access: 'session' | 'management' | 'runtime' | 'none';
+    nextAction: string;
+}
+export interface AuthOptions {
+    provider?: string;
+    status?: boolean;
+    interactive?: boolean;
+}
+export type LoginRunner = (command: readonly string[], root: string) => Promise<void>;
+/** Never return provider output, tokens, user addresses or response bodies. */
+export declare function authenticateProviders(root: string, options?: AuthOptions, run?: DeliveryRunner, send?: typeof fetch, startLogin?: LoginRunner, environment?: NodeJS.ProcessEnv): Promise<{
+    schemaVersion: number;
+    checks: AuthCheck[];
+    authenticated: boolean;
+    provisioningReady: boolean;
+    note: string;
+}>;

package/dist/provider-auth.js

@@ -0,0 +1,210 @@
+import path from 'node:path';
+import { EAS_CLI_VERSION, STACK_DEPENDENCIES } from './dependencies.js';
+import { realpathSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { readBoundedFile, MAX_PROJECT_JSON_BYTES } from './bounded-file.js';
+import { validateSetupPlan } from './readiness.js';
+import { resolveCommand } from './command.js';
+import { defaultRunner } from './project-state.js';
+import { providerConfiguration } from './providers/config.js';
+import { INTEGRATION_PROVIDERS, PROVIDER_DEFINITIONS, } from './providers/definitions.js';
+/** Deployment access is separate from application-user authentication. */
+export const PROVIDER_AUTH = [
+    {
+        id: 'cloudflare',
+        products: [
+            'vinext',
+            'hono',
+            'd1',
+            'r2',
+            'kv',
+            'realtime',
+            'queues',
+            'cron',
+            'workflows',
+            'workers-ai',
+            'basin',
+        ],
+        login: ['pnpm', 'dlx', `wrangler@${STACK_DEPENDENCIES.wrangler}`, 'login'],
+        identity: ['pnpm', 'dlx', `wrangler@${STACK_DEPENDENCIES.wrangler}`, 'whoami', '--json'],
+        setup: 'Select and connect the intended Cloudflare account before shipping.',
+    },
+    {
+        id: 'vercel',
+        products: [],
+        login: ['pnpm', 'dlx', 'vercel@62.7.0', 'login'],
+        identity: ['pnpm', 'dlx', 'vercel@62.7.0', 'whoami'],
+        setup: 'Connect the intended Vercel team and project before shipping.',
+    },
+    ...INTEGRATION_PROVIDERS.map((id) => {
+        const definition = PROVIDER_DEFINITIONS[id];
+        const { auth } = definition;
+        return {
+            id,
+            products: auth.products ?? [id],
+            credential: definition.credential,
+            endpoint: `${definition.origin}${auth.path}`,
+            ...(auth.runtime
+                ? {
+                    runtime: {
+                        credential: auth.runtime.credential,
+                        endpoint: `${definition.origin}${auth.runtime.path}`,
+                    },
+                }
+                : {}),
+            ...(definition.regionalOrigins
+                ? {
+                    regionalEndpoints: Object.fromEntries(Object.entries(definition.regionalOrigins).map(([region, origin]) => [
+                        region,
+                        `${origin}${auth.path}`,
+                    ])),
+                }
+                : {}),
+            setup: `Supply ${definition.credential} for management access.${auth.runtime ? ` ${auth.runtime.credential} checks runtime access only.` : ''} ${definition.ownerSteps.join(' ')} A successful probe does not establish all write permissions.`,
+        };
+    }),
+    {
+        id: 'expo',
+        products: ['expo'],
+        login: ['pnpm', 'dlx', `eas-cli@${EAS_CLI_VERSION}`, 'login'],
+        identity: ['pnpm', 'dlx', `eas-cli@${EAS_CLI_VERSION}`, 'whoami'],
+        setup: 'Authenticate the intended Expo account; store signing and enrollment are separate from EAS access.',
+    },
+];
+export function requiredProviders(root) {
+    root = realpathSync(root);
+    let plan;
+    try {
+        plan = JSON.parse(readBoundedFile(path.join(root, 'anhedral.setup.json'), MAX_PROJECT_JSON_BYTES).toString('utf8'));
+        validateSetupPlan(plan);
+    }
+    catch {
+        throw new Error('A valid Anhedral setup plan is required before authentication.');
+    }
+    validateSetupPlan(plan);
+    const providers = PROVIDER_AUTH.filter((provider) => provider.products.some((product) => plan.products.includes(product)) ||
+        (provider.id === 'cloudflare' &&
+            plan.products.includes('next') &&
+            plan.hosting === 'cloudflare') ||
+        (provider.id === 'vercel' && plan.products.includes('next') && plan.hosting === 'vercel'));
+    return providers;
+}
+async function login(command, root) {
+    const resolved = resolveCommand(command[0], command.slice(1));
+    await new Promise((resolve, reject) => {
+        const child = spawn(resolved.command, resolved.args, {
+            cwd: root,
+            stdio: 'inherit',
+            shell: false,
+        });
+        child.once('error', () => reject(new Error('Provider login tool is unavailable.')));
+        child.once('exit', (code) => code === 0 ? resolve() : reject(new Error('Provider login did not complete.')));
+    });
+}
+/** Never return provider output, tokens, user addresses or response bodies. */
+export async function authenticateProviders(root, options = {}, run = defaultRunner, send = fetch, startLogin = login, environment = process.env) {
+    root = realpathSync(root);
+    const required = requiredProviders(root);
+    if (options.provider && !required.some((item) => item.id === options.provider))
+        throw new Error('Requested provider is not required by this project.');
+    const selected = required.filter((item) => !options.provider || item.id === options.provider);
+    const configuration = providerConfiguration(root);
+    const checks = [];
+    for (const provider of selected) {
+        let state = 'unverified';
+        let evidence = 'none';
+        let access = 'none';
+        if (provider.identity) {
+            const inspect = async () => {
+                const output = await run(provider.identity[0], [...provider.identity.slice(1)], root, {
+                    ...environment,
+                    CI: '1',
+                    NO_COLOR: '1',
+                });
+                if (provider.id === 'cloudflare') {
+                    const identity = JSON.parse(output);
+                    return (identity.loggedIn === true &&
+                        Array.isArray(identity.accounts) &&
+                        identity.accounts.some((account) => typeof account?.id === 'string' && /^[a-f0-9]{32}$/i.test(account.id)));
+                }
+                return (output.length <= 1024 &&
+                    /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,99}$/.test(output.trim()) &&
+                    !/^(?:unauthenticated|anonymous|null|undefined|error|false)$/i.test(output.trim()));
+            };
+            try {
+                if (await inspect()) {
+                    state = 'verified';
+                    evidence = 'cli-session';
+                    access = 'session';
+                }
+                else
+                    state = 'missing';
+            }
+            catch {
+                state = 'missing';
+            }
+            if (state === 'missing' && !options.status && options.interactive && provider.login) {
+                try {
+                    await startLogin(provider.login, root);
+                    if (await inspect()) {
+                        state = 'verified';
+                        evidence = 'cli-session';
+                        access = 'session';
+                    }
+                }
+                catch {
+                    state = 'missing';
+                }
+            }
+        }
+        else if (provider.credential) {
+            let credential = environment[provider.credential];
+            let endpoint = provider.endpoint;
+            let credentialAccess = 'management';
+            if (!credential && provider.runtime) {
+                credential = environment[provider.runtime.credential];
+                endpoint = provider.runtime.endpoint;
+                credentialAccess = 'runtime';
+            }
+            if (provider.regionalEndpoints) {
+                const region = configuration.providers.posthog?.region;
+                endpoint = region ? provider.regionalEndpoints[region] : undefined;
+            }
+            if (!credential)
+                state = 'missing';
+            else if (endpoint) {
+                try {
+                    const response = await send(endpoint, {
+                        headers: { Authorization: `Bearer ${credential}` },
+                        redirect: 'error',
+                        signal: AbortSignal.timeout(30_000),
+                    });
+                    if (response.ok) {
+                        state = 'verified';
+                        evidence = 'api-access';
+                        access = credentialAccess;
+                    }
+                    else
+                        state =
+                            response.status === 403
+                                ? 'insufficient-permissions'
+                                : response.status === 401
+                                    ? 'missing'
+                                    : 'unverified';
+                    await response.body?.cancel();
+                }
+                catch {
+                    state = 'unverified';
+                }
+            }
+        }
+        checks.push({ provider: provider.id, state, evidence, access, nextAction: provider.setup });
+    }
+    return {
+        schemaVersion: 1,
+        checks,
+        authenticated: checks.every((check) => check.state === 'verified'),
+        provisioningReady: false,
+        note: 'Authentication checks do not establish selected account ownership, all provisioning permissions, configured runtime secrets or product readiness.',
+    };
+}

package/dist/providers/adapters.d.ts

@@ -0,0 +1,17 @@
+import { type ApiRequest } from './api.js';
+import { type IntegrationProvider, type ProviderSettings } from './config.js';
+import type { ProvisioningState } from './state.js';
+export interface AdapterContext {
+    id: IntegrationProvider;
+    settings: ProviderSettings;
+    api: ApiRequest;
+    state: ProvisioningState;
+    environment: NodeJS.ProcessEnv;
+}
+export interface AdapterResult {
+    resources: Record<string, string>;
+    runtime: Record<string, string>;
+    ready: boolean;
+    nextActions: string[];
+}
+export declare const PROVIDER_ADAPTERS: Record<IntegrationProvider, (context: AdapterContext) => Promise<AdapterResult>>;