@treeseed/sdk 0.5.3 → 0.6.0

package/dist/reconcile/contracts.d.ts

@@ -0,0 +1,155 @@
+import type { TreeseedDeployConfig } from '../platform/contracts.ts';
+export type TreeseedReconcileProviderId = string;
+export type TreeseedReconcileActionKind = 'noop' | 'create' | 'update' | 'reuse' | 'drift_correct' | 'destroy';
+export type TreeseedReconcileStatusKind = 'pending' | 'ready' | 'drifted' | 'error';
+export type TreeseedReconcileVerificationSource = 'cli' | 'api' | 'sdk' | 'derived';
+export type TreeseedReconcileUnitType = 'web-ui' | 'api-runtime' | 'manager-runtime' | 'worker-runtime' | 'workday-start-runtime' | 'workday-report-runtime' | 'edge-worker' | 'content-store' | 'queue' | 'database' | 'kv-form-guard' | 'kv-session' | 'pages-project' | 'custom-domain:web' | 'custom-domain:api' | 'dns-record' | 'railway-service:api' | 'railway-service:manager' | 'railway-service:worker' | 'railway-service:workday-start' | 'railway-service:workday-report';
+export type TreeseedReconcileTarget = {
+    kind: 'persistent';
+    scope: 'local' | 'staging' | 'prod';
+} | {
+    kind: 'branch';
+    branchName: string;
+};
+export type TreeseedReconcileUnitId = string;
+export interface TreeseedReconcileIdentity {
+    teamId: string;
+    projectId: string;
+    slug: string;
+    environment: string;
+    deploymentKey: string;
+    environmentKey: string;
+}
+export interface TreeseedDesiredUnit {
+    unitId: TreeseedReconcileUnitId;
+    unitType: TreeseedReconcileUnitType;
+    provider: TreeseedReconcileProviderId;
+    identity: TreeseedReconcileIdentity;
+    target: TreeseedReconcileTarget;
+    logicalName: string;
+    dependencies: TreeseedReconcileUnitId[];
+    spec: Record<string, unknown>;
+    secrets: Record<string, string | null | undefined>;
+    metadata: Record<string, unknown>;
+}
+export interface TreeseedObservedUnitState {
+    exists: boolean;
+    status: TreeseedReconcileStatusKind;
+    live: Record<string, unknown>;
+    locators: Record<string, string | null>;
+    warnings: string[];
+}
+export interface TreeseedUnitDiff {
+    action: TreeseedReconcileActionKind;
+    reasons: string[];
+    before: Record<string, unknown>;
+    after: Record<string, unknown>;
+}
+export interface TreeseedUnitPersistedState {
+    unitId: TreeseedReconcileUnitId;
+    unitType: TreeseedReconcileUnitType;
+    provider: TreeseedReconcileProviderId;
+    identity: TreeseedReconcileIdentity;
+    target: TreeseedReconcileTarget;
+    logicalName: string;
+    desiredSpecHash: string;
+    lastObservedAt: string | null;
+    lastReconciledAt: string | null;
+    lastVerifiedAt: string | null;
+    lastStatus: TreeseedReconcileStatusKind;
+    lastObservedState: Record<string, unknown>;
+    lastReconciledState: Record<string, unknown>;
+    lastDiff: TreeseedUnitDiff | null;
+    lastVerification: TreeseedUnitVerificationResult | null;
+    lastAction: TreeseedReconcileActionKind | null;
+    resourceLocators: Record<string, string | null>;
+    warnings: string[];
+    error: string | null;
+}
+export interface TreeseedUnitPostcondition {
+    key: string;
+    description: string;
+}
+export interface TreeseedUnitVerificationCheck {
+    key: string;
+    description: string;
+    source: TreeseedReconcileVerificationSource;
+    exists: boolean;
+    configured: boolean;
+    ready: boolean;
+    verified: boolean;
+    expected?: unknown;
+    observed?: unknown;
+    issues: string[];
+}
+export interface TreeseedUnitVerificationResult {
+    unitId: TreeseedReconcileUnitId;
+    supported: boolean;
+    exists: boolean;
+    configured: boolean;
+    ready: boolean;
+    verified: boolean;
+    checks: TreeseedUnitVerificationCheck[];
+    missing: string[];
+    drifted: string[];
+    warnings: string[];
+}
+export interface TreeseedReconcilePlan {
+    unit: TreeseedDesiredUnit;
+    observed: TreeseedObservedUnitState;
+    diff: TreeseedUnitDiff;
+    persisted: TreeseedUnitPersistedState | null;
+}
+export interface TreeseedReconcileResult {
+    unit: TreeseedDesiredUnit;
+    observed: TreeseedObservedUnitState;
+    diff: TreeseedUnitDiff;
+    action: TreeseedReconcileActionKind;
+    warnings: string[];
+    resourceLocators: Record<string, string | null>;
+    state: Record<string, unknown>;
+    verification: TreeseedUnitVerificationResult | null;
+}
+export interface TreeseedReconcileRunContext {
+    tenantRoot: string;
+    target: TreeseedReconcileTarget;
+    deployConfig: TreeseedDeployConfig;
+    launchEnv: NodeJS.ProcessEnv;
+    write?: (line: string) => void;
+    session: Map<string, unknown>;
+}
+export interface TreeseedReconcileAdapterInput {
+    context: TreeseedReconcileRunContext;
+    unit: TreeseedDesiredUnit;
+    persistedState: TreeseedUnitPersistedState | null;
+}
+export interface TreeseedReconcileAdapter {
+    providerId: TreeseedReconcileProviderId;
+    unitTypes: TreeseedReconcileUnitType[];
+    supports(unitType: TreeseedReconcileUnitType, providerId: TreeseedReconcileProviderId): boolean;
+    validate?(input: TreeseedReconcileAdapterInput): Promise<void> | void;
+    requiredPostconditions?(input: TreeseedReconcileAdapterInput): Promise<TreeseedUnitPostcondition[]> | TreeseedUnitPostcondition[];
+    observe(input: TreeseedReconcileAdapterInput): Promise<TreeseedObservedUnitState> | TreeseedObservedUnitState;
+    plan(input: TreeseedReconcileAdapterInput & {
+        observed: TreeseedObservedUnitState;
+    }): Promise<TreeseedUnitDiff> | TreeseedUnitDiff;
+    reconcile(input: TreeseedReconcileAdapterInput & {
+        observed: TreeseedObservedUnitState;
+        diff: TreeseedUnitDiff;
+    }): Promise<TreeseedReconcileResult> | TreeseedReconcileResult;
+    verify(input: TreeseedReconcileAdapterInput & {
+        observed: TreeseedObservedUnitState;
+        diff: TreeseedUnitDiff;
+        result: TreeseedReconcileResult | null;
+        postconditions: TreeseedUnitPostcondition[];
+    }): Promise<TreeseedUnitVerificationResult> | TreeseedUnitVerificationResult;
+    destroy?(input: TreeseedReconcileAdapterInput & {
+        observed: TreeseedObservedUnitState;
+    }): Promise<TreeseedReconcileResult> | TreeseedReconcileResult;
+}
+export interface TreeseedReconcileStateRecord {
+    version: 1;
+    target: TreeseedReconcileTarget;
+    dependencyGraphVersion: number;
+    units: Record<TreeseedReconcileUnitId, TreeseedUnitPersistedState>;
+}

package/dist/reconcile/desired-state.d.ts

@@ -0,0 +1,179 @@
+import type { TreeseedDesiredUnit, TreeseedReconcileTarget } from './contracts.ts';
+export declare function deriveTreeseedDesiredUnits({ tenantRoot, target, }: {
+    tenantRoot: string;
+    target: TreeseedReconcileTarget;
+}): {
+    deployConfig: {
+        name: string;
+        slug: string;
+        siteUrl: string;
+        contactEmail: string;
+        hosting: {
+            kind: string;
+            registration: any;
+            marketBaseUrl: any;
+            teamId: any;
+            projectId: any;
+        };
+        hub: {
+            mode: string;
+        };
+        runtime: {
+            mode: string;
+            registration: any;
+            marketBaseUrl: any;
+            teamId: any;
+            projectId: any;
+        };
+        cloudflare: {
+            accountId: string;
+            zoneId: string | undefined;
+            workerName: string | undefined;
+            queueName: string | undefined;
+            dlqName: string | undefined;
+            d1Binding: string | undefined;
+            queueBinding: string | undefined;
+            pages: {
+                projectName: string | undefined;
+                previewProjectName: string | undefined;
+                productionBranch: string;
+                stagingBranch: string;
+                buildOutputDir: string | undefined;
+            } | undefined;
+            r2: {
+                binding: string | undefined;
+                bucketName: string | undefined;
+                publicBaseUrl: string | undefined;
+                manifestKeyTemplate: string;
+                previewRootTemplate: string;
+                previewTtlHours: number;
+            } | undefined;
+        };
+        plugins: {
+            package: string;
+            enabled: boolean;
+        }[] | {
+            package: string;
+            enabled: boolean | undefined;
+            config: any;
+        }[];
+        providers: {
+            forms: string;
+            agents: {
+                execution: string;
+                mutation: string;
+                repository: string;
+                verification: string;
+                notification: string;
+                research: string;
+            };
+            deploy: string;
+            dns: string;
+            content: {
+                runtime: string;
+                publish: string;
+                docs: string;
+                serving: any;
+            };
+            site: string;
+        };
+        surfaces: {
+            [k: string]: {
+                enabled: boolean | undefined;
+                provider: string | undefined;
+                rootDir: string | undefined;
+                publicBaseUrl: string | undefined;
+                localBaseUrl: string | undefined;
+                environments: {
+                    local: {
+                        baseUrl: string | undefined;
+                        domain: string | undefined;
+                        railwayEnvironment: string | undefined;
+                    };
+                    staging: {
+                        baseUrl: string | undefined;
+                        domain: string | undefined;
+                        railwayEnvironment: string | undefined;
+                    };
+                    prod: {
+                        baseUrl: string | undefined;
+                        domain: string | undefined;
+                        railwayEnvironment: string | undefined;
+                    };
+                } | undefined;
+                cache: {
+                    sourcePages: {
+                        browserTtlSeconds: number | undefined;
+                        edgeTtlSeconds: number | undefined;
+                        staleWhileRevalidateSeconds: number | undefined;
+                        staleIfErrorSeconds: number | undefined;
+                    } | {
+                        paths: any[];
+                    } | undefined;
+                    contentPages: {
+                        browserTtlSeconds: number | undefined;
+                        edgeTtlSeconds: number | undefined;
+                        staleWhileRevalidateSeconds: number | undefined;
+                        staleIfErrorSeconds: number | undefined;
+                    } | {
+                        paths: any[];
+                    } | undefined;
+                    r2PublishedObjects: {
+                        browserTtlSeconds: number | undefined;
+                        edgeTtlSeconds: number | undefined;
+                        staleWhileRevalidateSeconds: number | undefined;
+                        staleIfErrorSeconds: number | undefined;
+                    } | {
+                        paths: any[];
+                    } | undefined;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+        services: {
+            [k: string]: {
+                enabled: boolean | undefined;
+                provider: string | undefined;
+                rootDir: string | undefined;
+                publicBaseUrl: string | undefined;
+                cloudflare: {
+                    workerName: string | undefined;
+                };
+                railway: {
+                    projectId: string | undefined;
+                    projectName: string | undefined;
+                    serviceId: string | undefined;
+                    serviceName: string | undefined;
+                    rootDir: string | undefined;
+                    buildCommand: string | undefined;
+                    startCommand: string | undefined;
+                    schedule: any;
+                };
+                environments: {
+                    local: {
+                        baseUrl: string | undefined;
+                        domain: string | undefined;
+                        railwayEnvironment: string | undefined;
+                    };
+                    staging: {
+                        baseUrl: string | undefined;
+                        domain: string | undefined;
+                        railwayEnvironment: string | undefined;
+                    };
+                    prod: {
+                        baseUrl: string | undefined;
+                        domain: string | undefined;
+                        railwayEnvironment: string | undefined;
+                    };
+                };
+            } | undefined;
+        } | undefined;
+        smtp: {
+            enabled: boolean | undefined;
+        };
+        turnstile: {
+            enabled: boolean;
+        };
+    };
+    legacyState: any;
+    units: TreeseedDesiredUnit[];
+};

package/dist/reconcile/desired-state.js

@@ -0,0 +1,319 @@
+import { loadCliDeployConfig } from "../operations/services/runtime-tools.js";
+import {
+  loadDeployState,
+  resolveConfiguredSurfaceDomain,
+  resolveTreeseedResourceIdentity
+} from "../operations/services/deploy.js";
+import { configuredRailwayServices } from "../operations/services/railway-deploy.js";
+import { normalizeRailwayEnvironmentName } from "../operations/services/railway-api.js";
+import { createTreeseedReconcileUnitId } from "./units.js";
+function railwayConcreteUnitTypeForServiceKey(serviceKey) {
+  switch (serviceKey) {
+    case "api":
+      return "railway-service:api";
+    case "manager":
+      return "railway-service:manager";
+    case "worker":
+      return "railway-service:worker";
+    case "workdayStart":
+      return "railway-service:workday-start";
+    case "workdayReport":
+      return "railway-service:workday-report";
+    default:
+      return "railway-service:api";
+  }
+}
+function deriveTreeseedDesiredUnits({
+  tenantRoot,
+  target
+}) {
+  const deployConfig = loadCliDeployConfig(tenantRoot);
+  const legacyState = loadDeployState(tenantRoot, deployConfig, { target });
+  const identity = legacyState.identity ?? resolveTreeseedResourceIdentity(deployConfig, target);
+  const units = [];
+  const add = (unit) => {
+    units.push(unit);
+    return unit.unitId;
+  };
+  const queueId = add({
+    unitId: createTreeseedReconcileUnitId("queue", legacyState.queues.agentWork.name),
+    unitType: "queue",
+    provider: "cloudflare",
+    identity,
+    target,
+    logicalName: legacyState.queues.agentWork.name,
+    dependencies: [],
+    spec: {
+      name: legacyState.queues.agentWork.name,
+      dlqName: legacyState.queues.agentWork.dlqName,
+      binding: legacyState.queues.agentWork.binding
+    },
+    secrets: {},
+    metadata: {}
+  });
+  const databaseId = add({
+    unitId: createTreeseedReconcileUnitId("database", legacyState.d1Databases.SITE_DATA_DB.databaseName),
+    unitType: "database",
+    provider: "cloudflare",
+    identity,
+    target,
+    logicalName: legacyState.d1Databases.SITE_DATA_DB.databaseName,
+    dependencies: [],
+    spec: {
+      databaseName: legacyState.d1Databases.SITE_DATA_DB.databaseName,
+      binding: "SITE_DATA_DB"
+    },
+    secrets: {},
+    metadata: {}
+  });
+  const formGuardKvId = add({
+    unitId: createTreeseedReconcileUnitId("kv-form-guard", legacyState.kvNamespaces.FORM_GUARD_KV.name),
+    unitType: "kv-form-guard",
+    provider: "cloudflare",
+    identity,
+    target,
+    logicalName: legacyState.kvNamespaces.FORM_GUARD_KV.name,
+    dependencies: [],
+    spec: { binding: "FORM_GUARD_KV", name: legacyState.kvNamespaces.FORM_GUARD_KV.name },
+    secrets: {},
+    metadata: {}
+  });
+  const sessionKvId = add({
+    unitId: createTreeseedReconcileUnitId("kv-session", legacyState.kvNamespaces.SESSION.name),
+    unitType: "kv-session",
+    provider: "cloudflare",
+    identity,
+    target,
+    logicalName: legacyState.kvNamespaces.SESSION.name,
+    dependencies: [],
+    spec: { binding: "SESSION", name: legacyState.kvNamespaces.SESSION.name },
+    secrets: {},
+    metadata: {}
+  });
+  const contentStoreId = add({
+    unitId: createTreeseedReconcileUnitId("content-store", legacyState.content.bucketName ?? deployConfig.slug),
+    unitType: "content-store",
+    provider: "cloudflare",
+    identity,
+    target,
+    logicalName: legacyState.content.bucketName ?? deployConfig.slug,
+    dependencies: [],
+    spec: {
+      bucketName: legacyState.content.bucketName,
+      binding: legacyState.content.r2Binding,
+      publicBaseUrl: legacyState.content.publicBaseUrl,
+      manifestKeyTemplate: legacyState.content.manifestKeyTemplate,
+      previewRootTemplate: legacyState.content.previewRootTemplate
+    },
+    secrets: {},
+    metadata: { shared: true }
+  });
+  const pagesProjectId = add({
+    unitId: createTreeseedReconcileUnitId("pages-project", legacyState.pages.projectName),
+    unitType: "pages-project",
+    provider: "cloudflare",
+    identity,
+    target,
+    logicalName: legacyState.pages.projectName,
+    dependencies: [],
+    spec: {
+      projectName: legacyState.pages.projectName,
+      productionBranch: legacyState.pages.productionBranch,
+      stagingBranch: legacyState.pages.stagingBranch,
+      buildOutputDir: legacyState.pages.buildOutputDir
+    },
+    secrets: {},
+    metadata: {}
+  });
+  const edgeWorkerId = add({
+    unitId: createTreeseedReconcileUnitId("edge-worker", legacyState.workerName),
+    unitType: "edge-worker",
+    provider: "cloudflare",
+    identity,
+    target,
+    logicalName: legacyState.workerName,
+    dependencies: [queueId, databaseId, formGuardKvId, sessionKvId, contentStoreId, pagesProjectId],
+    spec: {
+      workerName: legacyState.workerName
+    },
+    secrets: {},
+    metadata: {}
+  });
+  if (deployConfig.surfaces?.web?.enabled !== false) {
+    const scope2 = target.kind === "persistent" ? target.scope : "staging";
+    const webDomain = target.kind === "persistent" ? resolveConfiguredSurfaceDomain(deployConfig, target, "web") : null;
+    const webDomainUnitId = webDomain ? add({
+      unitId: createTreeseedReconcileUnitId("custom-domain:web", webDomain),
+      unitType: "custom-domain:web",
+      provider: "cloudflare",
+      identity,
+      target,
+      logicalName: webDomain,
+      dependencies: [pagesProjectId],
+      spec: {
+        domain: webDomain,
+        projectName: legacyState.pages.projectName
+      },
+      secrets: {},
+      metadata: { surface: "web" }
+    }) : null;
+    const webDnsUnitId = webDomain ? add({
+      unitId: createTreeseedReconcileUnitId("dns-record", `web:${webDomain}`),
+      unitType: "dns-record",
+      provider: deployConfig.providers?.dns ?? "cloudflare-dns",
+      identity,
+      target,
+      logicalName: `web:${webDomain}`,
+      dependencies: webDomainUnitId ? [webDomainUnitId] : [],
+      spec: {
+        domain: webDomain,
+        zoneHost: webDomain,
+        recordName: webDomain,
+        recordType: "CNAME",
+        recordContent: scope2 === "prod" ? `${legacyState.pages.projectName}.pages.dev` : `${legacyState.pages.stagingBranch ?? "staging"}.${legacyState.pages.projectName}.pages.dev`,
+        proxied: true,
+        targetKind: "pages-project"
+      },
+      secrets: {},
+      metadata: { surface: "web" }
+    }) : null;
+    add({
+      unitId: createTreeseedReconcileUnitId("web-ui", "web-ui"),
+      unitType: "web-ui",
+      provider: "treeseed",
+      identity,
+      target,
+      logicalName: "web-ui",
+      dependencies: [
+        edgeWorkerId,
+        pagesProjectId,
+        contentStoreId,
+        ...webDomainUnitId ? [webDomainUnitId] : [],
+        ...webDnsUnitId ? [webDnsUnitId] : []
+      ],
+      spec: {
+        publicBaseUrl: deployConfig.surfaces?.web?.publicBaseUrl ?? deployConfig.siteUrl,
+        localBaseUrl: deployConfig.surfaces?.web?.localBaseUrl ?? null
+      },
+      secrets: {},
+      metadata: {}
+    });
+  }
+  const scope = target.kind === "persistent" ? target.scope : "staging";
+  for (const configuredService of configuredRailwayServices(tenantRoot, scope)) {
+    const serviceKey = configuredService.key;
+    const service = deployConfig.services?.[serviceKey];
+    const serviceState = legacyState.services?.[serviceKey];
+    if (!service || service.enabled === false || service.provider !== "railway") {
+      continue;
+    }
+    const concreteType = railwayConcreteUnitTypeForServiceKey(serviceKey);
+    const concreteId = add({
+      unitId: createTreeseedReconcileUnitId(concreteType, serviceState?.serviceName ?? configuredService.serviceName ?? serviceKey),
+      unitType: concreteType,
+      provider: "railway",
+      identity,
+      target,
+      logicalName: serviceState?.serviceName ?? configuredService.serviceName ?? serviceKey,
+      dependencies: [],
+      spec: {
+        projectId: serviceState?.projectId ?? configuredService.projectId,
+        projectName: serviceState?.projectName ?? configuredService.projectName,
+        serviceId: serviceState?.serviceId ?? configuredService.serviceId,
+        serviceName: serviceState?.serviceName ?? configuredService.serviceName,
+        rootDir: serviceState?.rootDir ?? configuredService.rootDir,
+        environment: normalizeRailwayEnvironmentName(serviceState?.environment ?? configuredService.railwayEnvironment),
+        buildCommand: configuredService.buildCommand,
+        startCommand: configuredService.startCommand,
+        healthcheckPath: configuredService.healthcheckPath,
+        healthcheckTimeoutSeconds: configuredService.healthcheckTimeoutSeconds,
+        healthcheckIntervalSeconds: configuredService.healthcheckIntervalSeconds,
+        restartPolicy: configuredService.restartPolicy,
+        runtimeMode: configuredService.runtimeMode,
+        schedule: serviceState?.schedule ?? configuredService.schedule,
+        publicBaseUrl: serviceState?.publicBaseUrl ?? configuredService.publicBaseUrl
+      },
+      secrets: {},
+      metadata: {
+        serviceKey,
+        scheduleManaged: Array.isArray(configuredService.schedule) && configuredService.schedule.length > 0,
+        scheduleBootstrap: false,
+        scheduleDeployScopes: ["prod"]
+      }
+    });
+    const apiDomain = serviceKey === "api" && target.kind === "persistent" ? resolveConfiguredSurfaceDomain(deployConfig, target, "api") : null;
+    const apiCustomDomainId = apiDomain ? add({
+      unitId: createTreeseedReconcileUnitId("custom-domain:api", apiDomain),
+      unitType: "custom-domain:api",
+      provider: "railway",
+      identity,
+      target,
+      logicalName: apiDomain,
+      dependencies: [concreteId],
+      spec: {
+        domain: apiDomain,
+        serviceName: serviceState?.serviceName ?? configuredService.serviceName,
+        projectName: serviceState?.projectName ?? configuredService.projectName,
+        environment: normalizeRailwayEnvironmentName(serviceState?.environment ?? configuredService.railwayEnvironment)
+      },
+      secrets: {},
+      metadata: { surface: "api", serviceKey }
+    }) : null;
+    const apiDnsUnitId = apiDomain ? add({
+      unitId: createTreeseedReconcileUnitId("dns-record", `api:${apiDomain}`),
+      unitType: "dns-record",
+      provider: deployConfig.providers?.dns ?? "cloudflare-dns",
+      identity,
+      target,
+      logicalName: `api:${apiDomain}`,
+      dependencies: apiCustomDomainId ? [apiCustomDomainId] : [concreteId],
+      spec: {
+        domain: apiDomain,
+        zoneHost: apiDomain,
+        targetKind: "railway-service",
+        serviceKey
+      },
+      secrets: {},
+      metadata: { surface: "api", serviceKey }
+    }) : null;
+    const runtimeUnitType = (() => {
+      switch (serviceKey) {
+        case "api":
+          return "api-runtime";
+        case "manager":
+          return "manager-runtime";
+        case "worker":
+          return "worker-runtime";
+        case "workdayStart":
+          return "workday-start-runtime";
+        case "workdayReport":
+          return "workday-report-runtime";
+        default:
+          return "api-runtime";
+      }
+    })();
+    add({
+      unitId: createTreeseedReconcileUnitId(runtimeUnitType, serviceKey),
+      unitType: runtimeUnitType,
+      provider: "treeseed",
+      identity,
+      target,
+      logicalName: serviceKey,
+      dependencies: [
+        concreteId,
+        ...apiCustomDomainId ? [apiCustomDomainId] : [],
+        ...apiDnsUnitId ? [apiDnsUnitId] : []
+      ],
+      spec: {
+        serviceKey,
+        publicBaseUrl: serviceState?.publicBaseUrl ?? null
+      },
+      secrets: {},
+      metadata: {}
+    });
+  }
+  return { deployConfig, legacyState, units };
+}
+export {
+  deriveTreeseedDesiredUnits
+};