anhedral 0.10.0 → 0.11.0

package/dist/providers/config.js

@@ -0,0 +1,184 @@
+import path from 'node:path';
+import { existsSync, realpathSync } from 'node:fs';
+import { readBoundedFile, MAX_PROJECT_JSON_BYTES } from '../bounded-file.js';
+import { validateSetupPlan } from '../readiness.js';
+import { INTEGRATION_PROVIDERS, PROVIDER_DEFINITIONS, PROVIDER_EVENT_PATTERN, PROVIDER_IDENTITY_PATTERN, PROVIDER_TEXT_PATTERN, PROVIDER_WEBHOOK_PATTERN, } from './definitions.js';
+export { INTEGRATION_PROVIDERS } from './definitions.js';
+/** Validate untrusted JSON before assigning provider-specific types. */
+export function validateProviderConfiguration(value, selected = INTEGRATION_PROVIDERS) {
+    if (!value ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        !('schemaVersion' in value) ||
+        value.schemaVersion !== 1 ||
+        !('providers' in value) ||
+        !value.providers ||
+        typeof value.providers !== 'object' ||
+        Array.isArray(value.providers) ||
+        Object.keys(value).some((key) => !['schemaVersion', 'providers'].includes(key)))
+        throw new Error('Invalid provider configuration schema.');
+    for (const [id, settings] of Object.entries(value.providers)) {
+        if (!INTEGRATION_PROVIDERS.includes(id) ||
+            !selected.includes(id))
+            throw new Error('Provider configuration includes an unsupported or unselected provider.');
+        if (!settings || typeof settings !== 'object' || Array.isArray(settings))
+            throw new Error(`Invalid ${id} settings.`);
+        const definition = PROVIDER_DEFINITIONS[id];
+        for (const [key, entry] of Object.entries(settings)) {
+            const field = definition.fields[key];
+            if (!Object.hasOwn(definition.fields, key) || !field)
+                throw new Error(`Unsupported ${id} setting. Credentials belong in the environment.`);
+            if (field.kind === 'events') {
+                if (!Array.isArray(entry) ||
+                    entry.length < 1 ||
+                    entry.length > 100 ||
+                    new Set(entry).size !== entry.length ||
+                    entry.some((event) => typeof event !== 'string' || !new RegExp(PROVIDER_EVENT_PATTERN).test(event)))
+                    throw new Error('Stripe webhook events must be explicit unique event names.');
+                continue;
+            }
+            if (typeof entry !== 'string' || entry.length > 255 || /[\x00-\x1f\x7f]/.test(entry))
+                throw new Error(`Invalid ${id} setting.`);
+            if (field.choices && !field.choices.includes(entry))
+                throw new Error(`Invalid ${id} ${key} choice.`);
+            if (field.kind === 'https-url') {
+                let url;
+                try {
+                    url = new URL(entry);
+                }
+                catch {
+                    throw new Error('Webhook URL must use HTTPS.');
+                }
+                if (!new RegExp(PROVIDER_WEBHOOK_PATTERN).test(entry) ||
+                    url.protocol !== 'https:' ||
+                    !url.hostname ||
+                    url.username ||
+                    url.password ||
+                    url.hash ||
+                    url.search)
+                    throw new Error('Webhook URL must use HTTPS without credentials, query or fragment.');
+            }
+            else if (!new RegExp(field.kind === 'identity' ? PROVIDER_IDENTITY_PATTERN : PROVIDER_TEXT_PATTERN).test(entry))
+                throw new Error(`Invalid ${id} ${field.kind === 'identity' ? 'resource identity' : 'setting'}.`);
+        }
+    }
+}
+export function providerConfiguration(root) {
+    root = realpathSync(root);
+    const file = path.join(root, 'anhedral.providers.json');
+    const selected = selectedIntegrations(root);
+    if (!existsSync(file))
+        return { schemaVersion: 1, providers: {} };
+    let value;
+    try {
+        value = JSON.parse(readBoundedFile(file, MAX_PROJECT_JSON_BYTES).toString('utf8'));
+    }
+    catch {
+        throw new Error('Invalid anhedral.providers.json.');
+    }
+    validateProviderConfiguration(value, selected);
+    return value;
+}
+export function setting(settings, key) {
+    const value = settings[key];
+    return typeof value === 'string' ? value : '';
+}
+/** No identities, domains, prices or organizations are inferred from a user's last session. */
+export function providerRequirements(id, config) {
+    const missing = [];
+    const need = (key) => {
+        if (!setting(config, key))
+            missing.push(key);
+    };
+    const existingOrNew = () => {
+        if (!setting(config, 'projectId'))
+            need('name');
+    };
+    switch (id) {
+        case 'neon':
+            existingOrNew();
+            need('organizationId');
+            need('database');
+            need('role');
+            if (!setting(config, 'projectId'))
+                need('region');
+            break;
+        case 'clerk':
+            need('workspaceId');
+            if (!setting(config, 'applicationId'))
+                need('name');
+            if (!['development', 'production'].includes(setting(config, 'environment')))
+                missing.push('environment');
+            break;
+        case 'resend':
+            need('domain');
+            break;
+        case 'stripe':
+            need('accountId');
+            if (!['test', 'live'].includes(setting(config, 'mode')))
+                missing.push('mode');
+            if (setting(config, 'webhookUrl') && !config.webhookEvents)
+                missing.push('webhookEvents');
+            if (config.webhookEvents && !setting(config, 'webhookUrl'))
+                missing.push('webhookUrl');
+            break;
+        case 'revenuecat':
+            existingOrNew();
+            if (![
+                'iosAppId',
+                'androidAppId',
+                'webAppId',
+                'stripeAccountId',
+                'bundleId',
+                'packageName',
+            ].some((key) => setting(config, key)))
+                missing.push('store app identifiers or a connected stripeAccountId');
+            break;
+        case 'sentry':
+            need('organization');
+            need('team');
+            need('project');
+            need('platform');
+            break;
+        case 'posthog':
+            existingOrNew();
+            need('organizationId');
+            if (!['us', 'eu'].includes(setting(config, 'region')))
+                missing.push('region');
+            break;
+        case 'openai':
+            existingOrNew();
+            need('serviceAccountName');
+            break;
+    }
+    return missing;
+}
+export function selectedIntegrations(root) {
+    const setup = JSON.parse(readBoundedFile(path.join(root, 'anhedral.setup.json'), MAX_PROJECT_JSON_BYTES).toString('utf8'));
+    validateSetupPlan(setup);
+    return INTEGRATION_PROVIDERS.filter((id) => setup.products.includes(id) || (id === 'openai' && setup.products.includes('ai-sdk')));
+}
+export function providerConfigurationTemplate(products, name) {
+    const templates = {
+        neon: { name, organizationId: '', region: '', database: 'app', role: 'app_owner' },
+        clerk: { name, workspaceId: '', environment: 'development' },
+        resend: { domain: '' },
+        stripe: { accountId: '', mode: 'test' },
+        revenuecat: products.includes('expo')
+            ? { name, bundleId: '', packageName: '' }
+            : { name, stripeAccountId: '' },
+        sentry: {
+            name,
+            organization: '',
+            team: '',
+            project: name,
+            platform: products.includes('next') || products.includes('vinext') ? 'javascript-nextjs' : 'node',
+        },
+        posthog: { name, organizationId: '', region: '' },
+        openai: { name, serviceAccountName: 'anhedral-runtime' },
+    };
+    return {
+        schemaVersion: 1,
+        providers: Object.fromEntries(INTEGRATION_PROVIDERS.filter((id) => products.includes(id) || (id === 'openai' && products.includes('ai-sdk'))).map((id) => [id, templates[id]])),
+    };
+}

package/dist/providers/definitions.d.ts

@@ -0,0 +1,318 @@
+import type { StandardProduct } from '../stack-registry.js';
+/** Public provider configuration describes resources, never credentials. Empty strings are
+ * permitted for scaffolding; provisioning separately checks the required choices. */
+export interface NeonSettings {
+    projectId?: string;
+    name?: string;
+    organizationId?: string;
+    region?: string;
+    database?: string;
+    role?: string;
+}
+export interface ClerkSettings {
+    workspaceId?: string;
+    applicationId?: string;
+    name?: string;
+    environment?: '' | 'development' | 'production';
+}
+export interface ResendSettings {
+    domainId?: string;
+    domain?: string;
+    region?: string;
+}
+export interface StripeSettings {
+    accountId?: string;
+    mode?: '' | 'test' | 'live';
+    webhookUrl?: string;
+    webhookEvents?: string[];
+}
+export interface RevenueCatSettings {
+    projectId?: string;
+    name?: string;
+    iosAppId?: string;
+    androidAppId?: string;
+    webAppId?: string;
+    stripeAccountId?: string;
+    bundleId?: string;
+    packageName?: string;
+}
+export interface SentrySettings {
+    organization?: string;
+    team?: string;
+    project?: string;
+    name?: string;
+    platform?: string;
+}
+export interface PostHogSettings {
+    organizationId?: string;
+    projectId?: string;
+    name?: string;
+    region?: '' | 'us' | 'eu';
+}
+export interface OpenAISettings {
+    projectId?: string;
+    name?: string;
+    serviceAccountName?: string;
+}
+export interface ProviderSettingsById {
+    neon: NeonSettings;
+    clerk: ClerkSettings;
+    resend: ResendSettings;
+    stripe: StripeSettings;
+    revenuecat: RevenueCatSettings;
+    sentry: SentrySettings;
+    posthog: PostHogSettings;
+    openai: OpenAISettings;
+}
+export type IntegrationProvider = keyof ProviderSettingsById;
+/** Shared adapter access remains bounded to known fields; provider configuration itself
+ * uses ProviderSettingsById so fields cannot leak between providers. */
+export type ProviderSettings = Omit<NeonSettings & ClerkSettings & ResendSettings & StripeSettings & RevenueCatSettings & SentrySettings & PostHogSettings & OpenAISettings, 'region'> & {
+    region?: string;
+};
+export type ProviderField = keyof ProviderSettings;
+export type FieldKind = 'text' | 'identity' | 'https-url' | 'events';
+export interface ProviderFieldDefinition {
+    kind: FieldKind;
+    choices?: readonly string[];
+}
+export interface ProviderDefinition {
+    credential: string;
+    auth: {
+        path: string;
+        products?: readonly StandardProduct[];
+        runtime?: {
+            credential: string;
+            path: string;
+        };
+    };
+    origin: string;
+    regionalOrigins?: Readonly<Record<string, string>>;
+    fields: Partial<Record<ProviderField, ProviderFieldDefinition>>;
+    /** Describes adapter scope, not account permissions or production readiness. */
+    resources: readonly string[];
+    ownerSteps: readonly string[];
+}
+export declare const PROVIDER_DEFINITIONS: {
+    readonly neon: {
+        readonly credential: "NEON_API_KEY";
+        readonly auth: {
+            readonly path: "/api/v2/projects";
+        };
+        readonly origin: "https://console.neon.tech";
+        readonly fields: {
+            readonly projectId: {
+                readonly kind: "identity";
+            };
+            readonly name: {
+                readonly kind: "text";
+            };
+            readonly organizationId: {
+                readonly kind: "identity";
+            };
+            readonly region: {
+                readonly kind: "text";
+            };
+            readonly database: {
+                readonly kind: "text";
+            };
+            readonly role: {
+                readonly kind: "text";
+            };
+        };
+        readonly resources: readonly ["project", "database connection"];
+        readonly ownerSteps: readonly ["Choose an organization and region; approve any provider billing requirements."];
+    };
+    readonly clerk: {
+        readonly credential: "CLERK_PLATFORM_API_KEY";
+        readonly auth: {
+            readonly path: "/v1/platform/me";
+            readonly runtime: {
+                readonly credential: "CLERK_SECRET_KEY";
+                readonly path: "/v1/users/count";
+            };
+        };
+        readonly origin: "https://api.clerk.com";
+        readonly fields: {
+            readonly workspaceId: {
+                readonly kind: "identity";
+            };
+            readonly applicationId: {
+                readonly kind: "identity";
+            };
+            readonly name: {
+                readonly kind: "text";
+            };
+            readonly environment: {
+                readonly kind: "text";
+                readonly choices: readonly ["", "development", "production"];
+            };
+        };
+        readonly resources: readonly ["application", "environment keys"];
+        readonly ownerSteps: readonly ["Obtain Platform API access; configure production domains, DNS, and OAuth credentials."];
+    };
+    readonly resend: {
+        readonly credential: "RESEND_API_KEY";
+        readonly auth: {
+            readonly path: "/domains";
+        };
+        readonly origin: "https://api.resend.com";
+        readonly fields: {
+            readonly domainId: {
+                readonly kind: "identity";
+            };
+            readonly domain: {
+                readonly kind: "text";
+            };
+            readonly region: {
+                readonly kind: "text";
+            };
+        };
+        readonly resources: readonly ["domain", "sending key"];
+        readonly ownerSteps: readonly ["Publish domain verification DNS records and wait for verification."];
+    };
+    readonly stripe: {
+        readonly credential: "STRIPE_SECRET_KEY";
+        readonly auth: {
+            readonly path: "/v1/account";
+        };
+        readonly origin: "https://api.stripe.com";
+        readonly fields: {
+            readonly accountId: {
+                readonly kind: "identity";
+            };
+            readonly mode: {
+                readonly kind: "text";
+                readonly choices: readonly ["", "test", "live"];
+            };
+            readonly webhookUrl: {
+                readonly kind: "https-url";
+            };
+            readonly webhookEvents: {
+                readonly kind: "events";
+            };
+        };
+        readonly resources: readonly ["account verification", "webhook"];
+        readonly ownerSteps: readonly ["Complete account activation; define products, prices, and purchase behavior."];
+    };
+    readonly revenuecat: {
+        readonly credential: "RC_API_KEY";
+        readonly auth: {
+            readonly path: "/v2/projects";
+        };
+        readonly origin: "https://api.revenuecat.com";
+        readonly fields: {
+            readonly projectId: {
+                readonly kind: "identity";
+            };
+            readonly name: {
+                readonly kind: "text";
+            };
+            readonly iosAppId: {
+                readonly kind: "identity";
+            };
+            readonly androidAppId: {
+                readonly kind: "identity";
+            };
+            readonly webAppId: {
+                readonly kind: "identity";
+            };
+            readonly stripeAccountId: {
+                readonly kind: "identity";
+            };
+            readonly bundleId: {
+                readonly kind: "text";
+            };
+            readonly packageName: {
+                readonly kind: "text";
+            };
+        };
+        readonly resources: readonly ["project", "application", "SDK keys"];
+        readonly ownerSteps: readonly ["Configure store credentials or Stripe, products, offerings, and entitlements; verify purchases."];
+    };
+    readonly sentry: {
+        readonly credential: "SENTRY_AUTH_TOKEN";
+        readonly auth: {
+            readonly path: "/api/0/organizations/";
+        };
+        readonly origin: "https://sentry.io";
+        readonly fields: {
+            readonly organization: {
+                readonly kind: "identity";
+            };
+            readonly team: {
+                readonly kind: "identity";
+            };
+            readonly project: {
+                readonly kind: "identity";
+            };
+            readonly name: {
+                readonly kind: "text";
+            };
+            readonly platform: {
+                readonly kind: "text";
+            };
+        };
+        readonly resources: readonly ["project", "DSN"];
+        readonly ownerSteps: readonly ["Choose organization and team access; configure source maps and application instrumentation."];
+    };
+    readonly posthog: {
+        readonly credential: "POSTHOG_PERSONAL_API_KEY";
+        readonly auth: {
+            readonly path: "/api/organizations/";
+        };
+        readonly origin: "https://us.posthog.com";
+        readonly regionalOrigins: {
+            readonly us: "https://us.posthog.com";
+            readonly eu: "https://eu.posthog.com";
+        };
+        readonly fields: {
+            readonly organizationId: {
+                readonly kind: "identity";
+            };
+            readonly projectId: {
+                readonly kind: "identity";
+            };
+            readonly name: {
+                readonly kind: "text";
+            };
+            readonly region: {
+                readonly kind: "text";
+                readonly choices: readonly ["", "us", "eu"];
+            };
+        };
+        readonly resources: readonly ["project", "ingestion configuration"];
+        readonly ownerSteps: readonly ["Choose organization and region; define analytics events and consent behavior."];
+    };
+    readonly openai: {
+        readonly credential: "OPENAI_ADMIN_KEY";
+        readonly auth: {
+            readonly path: "/v1/organization/projects";
+            readonly products: readonly ["openai", "ai-sdk"];
+            readonly runtime: {
+                readonly credential: "OPENAI_API_KEY";
+                readonly path: "/v1/models";
+            };
+        };
+        readonly origin: "https://api.openai.com";
+        readonly fields: {
+            readonly projectId: {
+                readonly kind: "identity";
+            };
+            readonly name: {
+                readonly kind: "text";
+            };
+            readonly serviceAccountName: {
+                readonly kind: "text";
+            };
+        };
+        readonly resources: readonly ["project", "service account", "runtime key"];
+        readonly ownerSteps: readonly ["Obtain organization administration access; configure billing and application usage limits."];
+    };
+};
+export declare const INTEGRATION_PROVIDERS: IntegrationProvider[];
+export declare const PROVIDER_TEXT_PATTERN = "^(?:[a-zA-Z0-9][a-zA-Z0-9_. -]*)?$";
+export declare const PROVIDER_IDENTITY_PATTERN = "^(?:[a-zA-Z0-9][a-zA-Z0-9_-]{0,254})?$";
+export declare const PROVIDER_EVENT_PATTERN = "^[a-z][a-z0-9_.]{0,100}$";
+/** Schema and runtime use the same pattern; URL parsing also verifies normalization. */
+export declare const PROVIDER_WEBHOOK_PATTERN = "^https://[^/?#@\\\\\\s]+(?:/[^?#\\\\\\s]*)?$";

package/dist/providers/definitions.js

@@ -0,0 +1,127 @@
+const text = { kind: 'text' };
+const identity = { kind: 'identity' };
+export const PROVIDER_DEFINITIONS = {
+    neon: {
+        credential: 'NEON_API_KEY',
+        auth: { path: '/api/v2/projects' },
+        origin: 'https://console.neon.tech',
+        fields: {
+            projectId: identity,
+            name: text,
+            organizationId: identity,
+            region: text,
+            database: text,
+            role: text,
+        },
+        resources: ['project', 'database connection'],
+        ownerSteps: ['Choose an organization and region; approve any provider billing requirements.'],
+    },
+    clerk: {
+        credential: 'CLERK_PLATFORM_API_KEY',
+        auth: {
+            path: '/v1/platform/me',
+            runtime: { credential: 'CLERK_SECRET_KEY', path: '/v1/users/count' },
+        },
+        origin: 'https://api.clerk.com',
+        fields: {
+            workspaceId: identity,
+            applicationId: identity,
+            name: text,
+            environment: { kind: 'text', choices: ['', 'development', 'production'] },
+        },
+        resources: ['application', 'environment keys'],
+        ownerSteps: [
+            'Obtain Platform API access; configure production domains, DNS, and OAuth credentials.',
+        ],
+    },
+    resend: {
+        credential: 'RESEND_API_KEY',
+        auth: { path: '/domains' },
+        origin: 'https://api.resend.com',
+        fields: { domainId: identity, domain: text, region: text },
+        resources: ['domain', 'sending key'],
+        ownerSteps: ['Publish domain verification DNS records and wait for verification.'],
+    },
+    stripe: {
+        credential: 'STRIPE_SECRET_KEY',
+        auth: { path: '/v1/account' },
+        origin: 'https://api.stripe.com',
+        fields: {
+            accountId: identity,
+            mode: { kind: 'text', choices: ['', 'test', 'live'] },
+            webhookUrl: { kind: 'https-url' },
+            webhookEvents: { kind: 'events' },
+        },
+        resources: ['account verification', 'webhook'],
+        ownerSteps: ['Complete account activation; define products, prices, and purchase behavior.'],
+    },
+    revenuecat: {
+        credential: 'RC_API_KEY',
+        auth: { path: '/v2/projects' },
+        origin: 'https://api.revenuecat.com',
+        fields: {
+            projectId: identity,
+            name: text,
+            iosAppId: identity,
+            androidAppId: identity,
+            webAppId: identity,
+            stripeAccountId: identity,
+            bundleId: text,
+            packageName: text,
+        },
+        resources: ['project', 'application', 'SDK keys'],
+        ownerSteps: [
+            'Configure store credentials or Stripe, products, offerings, and entitlements; verify purchases.',
+        ],
+    },
+    sentry: {
+        credential: 'SENTRY_AUTH_TOKEN',
+        auth: { path: '/api/0/organizations/' },
+        origin: 'https://sentry.io',
+        fields: {
+            organization: identity,
+            team: identity,
+            project: identity,
+            name: text,
+            platform: text,
+        },
+        resources: ['project', 'DSN'],
+        ownerSteps: [
+            'Choose organization and team access; configure source maps and application instrumentation.',
+        ],
+    },
+    posthog: {
+        credential: 'POSTHOG_PERSONAL_API_KEY',
+        auth: { path: '/api/organizations/' },
+        origin: 'https://us.posthog.com',
+        regionalOrigins: { us: 'https://us.posthog.com', eu: 'https://eu.posthog.com' },
+        fields: {
+            organizationId: identity,
+            projectId: identity,
+            name: text,
+            region: { kind: 'text', choices: ['', 'us', 'eu'] },
+        },
+        resources: ['project', 'ingestion configuration'],
+        ownerSteps: ['Choose organization and region; define analytics events and consent behavior.'],
+    },
+    openai: {
+        credential: 'OPENAI_ADMIN_KEY',
+        auth: {
+            path: '/v1/organization/projects',
+            products: ['openai', 'ai-sdk'],
+            runtime: { credential: 'OPENAI_API_KEY', path: '/v1/models' },
+        },
+        origin: 'https://api.openai.com',
+        fields: { projectId: identity, name: text, serviceAccountName: text },
+        resources: ['project', 'service account', 'runtime key'],
+        ownerSteps: [
+            'Obtain organization administration access; configure billing and application usage limits.',
+        ],
+    },
+};
+export const INTEGRATION_PROVIDERS = Object.keys(PROVIDER_DEFINITIONS);
+export const PROVIDER_TEXT_PATTERN = '^(?:[a-zA-Z0-9][a-zA-Z0-9_. -]*)?$';
+export const PROVIDER_IDENTITY_PATTERN = '^(?:[a-zA-Z0-9][a-zA-Z0-9_-]{0,254})?$';
+export const PROVIDER_EVENT_PATTERN = '^[a-z][a-z0-9_.]{0,100}$';
+/** Schema and runtime use the same pattern; URL parsing also verifies normalization. */
+export const PROVIDER_WEBHOOK_PATTERN = '^https://[^/?#@\\\\\\s]+(?:/[^?#\\\\\\s]*)?$';

package/dist/providers/provision.d.ts

@@ -0,0 +1,24 @@
+import { type DeliveryRunner } from '../project-state.js';
+export declare function planProviderProvisioning(root: string): {
+    schemaVersion: number;
+    providers: {
+        provider: keyof import("./definitions.js").ProviderSettingsById;
+        settings: import("./definitions.js").NeonSettings | import("./definitions.js").ClerkSettings | import("./definitions.js").ResendSettings | import("./definitions.js").StripeSettings | import("./definitions.js").RevenueCatSettings | import("./definitions.js").SentrySettings | import("./definitions.js").PostHogSettings | import("./definitions.js").OpenAISettings;
+        credential: string;
+        missing: string[];
+    }[];
+    configured: boolean;
+    mutation: boolean;
+};
+export declare function provisionSelectedProviders(root: string, dryRun?: boolean, run?: DeliveryRunner, send?: typeof fetch, environment?: NodeJS.ProcessEnv): Promise<{
+    schemaVersion: number;
+    results: {
+        provider: string;
+        resources: Record<string, string>;
+        ready: boolean;
+        nextActions: string[];
+    }[];
+    ready: boolean;
+    configuredFiles: string[];
+    mutation: boolean;
+}>;