@treeseed/sdk 0.10.28 → 0.11.0

package/dist/reconcile/contracts.d.ts

@@ -1,9 +1,9 @@
 import type { TreeseedDeployConfig } from '../platform/contracts.ts';
 export type TreeseedReconcileProviderId = string;
-export type TreeseedReconcileActionKind = 'noop' | 'create' | 'update' | 'reuse' | 'drift_correct' | 'destroy';
+export type TreeseedReconcileActionKind = 'noop' | 'create' | 'update' | 'replace' | 'delete' | 'adopt' | 'rename' | 'reattach' | 'retain' | 'taint' | 'blocked';
 export type TreeseedReconcileStatusKind = 'pending' | 'ready' | 'drifted' | 'error';
 export type TreeseedReconcileVerificationSource = 'cli' | 'api' | 'sdk' | 'derived';
-export type TreeseedReconcileUnitType = 'web-ui' | 'api-runtime' | 'market-operations-runner-runtime' | 'workday-manager-runtime' | 'worker-runner-runtime' | 'edge-worker' | 'content-store' | 'queue' | 'database' | 'kv-form-guard' | 'turnstile-widget' | 'pages-project' | 'custom-domain:web' | 'custom-domain:api' | 'dns-record' | 'railway-service:api' | 'railway-service:market-operations-runner' | 'railway-service:workday-manager' | 'railway-service:worker-runner';
+export type TreeseedReconcileUnitType = 'web-ui' | 'api-runtime' | 'operations-runner-runtime' | 'workday-manager-runtime' | 'worker-runner-runtime' | 'edge-worker' | 'content-store' | 'queue' | 'database' | 'kv-form-guard' | 'turnstile-widget' | 'pages-project' | 'custom-domain:web' | 'custom-domain:api' | 'dns-record' | 'railway-service:api' | 'railway-service:operations-runner' | 'railway-service:workday-manager' | 'railway-service:worker-runner';
 export type TreeseedReconcileTarget = {
     kind: 'persistent';
     scope: 'local' | 'staging' | 'prod';
@@ -115,6 +115,7 @@ export interface TreeseedReconcileRunContext {
     target: TreeseedReconcileTarget;
     deployConfig: TreeseedDeployConfig;
     launchEnv: NodeJS.ProcessEnv;
+    dryRun?: boolean;
     write?: (line: string) => void;
     session: Map<string, unknown>;
 }
@@ -129,11 +130,11 @@ export interface TreeseedReconcileAdapter {
     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 & {
+    refresh(input: TreeseedReconcileAdapterInput): Promise<TreeseedObservedUnitState> | TreeseedObservedUnitState;
+    diff(input: TreeseedReconcileAdapterInput & {
         observed: TreeseedObservedUnitState;
     }): Promise<TreeseedUnitDiff> | TreeseedUnitDiff;
-    reconcile(input: TreeseedReconcileAdapterInput & {
+    apply(input: TreeseedReconcileAdapterInput & {
         observed: TreeseedObservedUnitState;
         diff: TreeseedUnitDiff;
     }): Promise<TreeseedReconcileResult> | TreeseedReconcileResult;
@@ -146,6 +147,9 @@ export interface TreeseedReconcileAdapter {
     destroy?(input: TreeseedReconcileAdapterInput & {
         observed: TreeseedObservedUnitState;
     }): Promise<TreeseedReconcileResult> | TreeseedReconcileResult;
+    importOrAdopt?(input: TreeseedReconcileAdapterInput & {
+        observed: TreeseedObservedUnitState;
+    }): Promise<TreeseedReconcileResult> | TreeseedReconcileResult;
 }
 export interface TreeseedReconcileStateRecord {
     version: 1;

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

@@ -38,6 +38,7 @@ export declare function deriveTreeseedDesiredUnits({ tenantRoot, target, }: {
                 previewProjectName: string | undefined;
                 productionBranch: string;
                 stagingBranch: string;
+                buildCommand: string | undefined;
                 buildOutputDir: string | undefined;
             } | undefined;
             r2: {

package/dist/reconcile/desired-state.js

@@ -11,8 +11,8 @@ function railwayConcreteUnitTypeForServiceKey(serviceKey) {
   switch (serviceKey) {
     case "api":
       return "railway-service:api";
-    case "marketOperationsRunner":
-      return "railway-service:market-operations-runner";
+    case "operationsRunner":
+      return "railway-service:operations-runner";
     case "workdayManager":
       return "railway-service:workday-manager";
     case "workerRunner":
@@ -204,7 +204,7 @@ function deriveTreeseedDesiredUnits({
   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 service = configuredService.serviceConfig ?? deployConfig.services?.[serviceKey];
     const serviceState = legacyState.services?.[serviceKey];
     if (!service || service.enabled === false || service.provider !== "railway") {
       continue;
@@ -284,8 +284,8 @@ function deriveTreeseedDesiredUnits({
       switch (serviceKey) {
         case "api":
           return "api-runtime";
-        case "marketOperationsRunner":
-          return "market-operations-runner-runtime";
+        case "operationsRunner":
+          return "operations-runner-runtime";
         case "workdayManager":
           return "workday-manager-runtime";
         case "workerRunner":

package/dist/reconcile/engine.d.ts

@@ -1,7 +1,7 @@
 import type { TreeseedObservedUnitState, TreeseedReconcilePlan, TreeseedReconcileResult, TreeseedReconcileStateRecord, TreeseedReconcileTarget, TreeseedUnitVerificationResult } from './contracts.ts';
 import { type TreeseedRunnableBootstrapSystem } from './bootstrap-systems.ts';
 import { type TreeseedTimingEntry } from '../timing.ts';
-export declare function observeTreeseedUnits({ tenantRoot, target, env, systems, write, }: {
+export declare function refreshTreeseedUnits({ tenantRoot, target, env, systems, write, }: {
     tenantRoot: string;
     target: TreeseedReconcileTarget;
     env?: NodeJS.ProcessEnv;
@@ -46,6 +46,7 @@ export declare function observeTreeseedUnits({ tenantRoot, target, env, systems,
                 previewProjectName: string | undefined;
                 productionBranch: string;
                 stagingBranch: string;
+                buildCommand: string | undefined;
                 buildOutputDir: string | undefined;
             } | undefined;
             r2: {
@@ -249,6 +250,7 @@ export declare function planTreeseedReconciliation({ tenantRoot, target, env, sy
                 previewProjectName: string | undefined;
                 productionBranch: string;
                 stagingBranch: string;
+                buildCommand: string | undefined;
                 buildOutputDir: string | undefined;
             } | undefined;
             r2: {
@@ -406,12 +408,13 @@ export declare function planTreeseedReconciliation({ tenantRoot, target, env, sy
         };
     };
 }>;
-export declare function reconcileTreeseedTarget({ tenantRoot, target, env, systems, write, }: {
+export declare function reconcileTreeseedTarget({ tenantRoot, target, env, systems, write, dryRun, }: {
     tenantRoot: string;
     target: TreeseedReconcileTarget;
     env?: NodeJS.ProcessEnv;
     systems?: TreeseedRunnableBootstrapSystem[];
     write?: (line: string) => void;
+    dryRun?: boolean;
 }): Promise<{
     target: TreeseedReconcileTarget;
     units: import("./contracts.ts").TreeseedDesiredUnit[];

package/dist/reconcile/engine.js

@@ -26,13 +26,14 @@ function formatVerificationFailure(verification) {
   ].filter(Boolean);
   return details.length > 0 ? `Verification failed (${details.join(" | ")})` : "Verification failed.";
 }
-function createRunContext(tenantRoot, target, launchEnv, write) {
+function createRunContext(tenantRoot, target, launchEnv, write, dryRun = false) {
   const { deployConfig } = deriveTreeseedDesiredUnits({ tenantRoot, target });
   return {
     tenantRoot,
     target,
     deployConfig,
     launchEnv,
+    dryRun,
     write,
     session: /* @__PURE__ */ new Map()
   };
@@ -123,7 +124,7 @@ async function verifyPlanUnits({
   }
   return verificationResults;
 }
-async function observeTreeseedUnits({
+async function refreshTreeseedUnits({
   tenantRoot,
   target,
   env = process.env,
@@ -138,18 +139,18 @@ async function observeTreeseedUnits({
   const context = createRunContext(tenantRoot, target, env, write);
   const observations = /* @__PURE__ */ new Map();
   await runByDependencyLevel(topologicallySortDesiredUnits(units), async (unit) => {
-    write?.(`Observing ${unit.provider}:${unit.unitType}...`);
+    write?.(`Refreshing ${unit.provider}:${unit.unitType}...`);
     const adapter = registry.get(unit.unitType, unit.provider);
     const persisted = ensureTreeseedPersistedUnitState(reconcileState, unit);
     let observed;
     try {
-      observed = await Promise.resolve(adapter.observe({
+      observed = await Promise.resolve(adapter.refresh({
         context,
         unit,
         persistedState: persisted
       }));
     } catch (error) {
-      wrapAdapterFailure("observe", unit.provider, unit.unitType, unit.unitId, error);
+      wrapAdapterFailure("refresh", unit.provider, unit.unitType, unit.unitId, error);
     }
     observations.set(unit.unitId, observed);
   });
@@ -167,7 +168,7 @@ async function planTreeseedReconciliation({
   systems,
   write
 }) {
-  const observed = await observeTreeseedUnits({ tenantRoot, target, env, systems, write });
+  const observed = await refreshTreeseedUnits({ tenantRoot, target, env, systems, write });
   const registry = createTreeseedReconcileRegistry(observed.deployConfig);
   const context = createRunContext(tenantRoot, target, env, write);
   const plans = [];
@@ -177,14 +178,14 @@ async function planTreeseedReconciliation({
     const observation = observed.observations.get(unit.unitId);
     let diff;
     try {
-      diff = await Promise.resolve(adapter.plan({
+      diff = await Promise.resolve(adapter.diff({
         context,
         unit,
         persistedState: persisted,
         observed: observation
       }));
     } catch (error) {
-      wrapAdapterFailure("plan", unit.provider, unit.unitType, unit.unitId, error);
+      wrapAdapterFailure("diff", unit.provider, unit.unitType, unit.unitId, error);
     }
     plans.push({
       unit,
@@ -203,11 +204,12 @@ async function reconcileTreeseedTarget({
   target,
   env = process.env,
   systems,
-  write
+  write,
+  dryRun = false
 }) {
   const planned = await planTreeseedReconciliation({ tenantRoot, target, env, systems, write });
   const registry = createTreeseedReconcileRegistry(planned.deployConfig);
-  const context = createRunContext(tenantRoot, target, env, write);
+  const context = createRunContext(tenantRoot, target, env, write, dryRun);
   const results = [];
   const verificationMap = /* @__PURE__ */ new Map();
   const timingEntries = [];
@@ -225,7 +227,7 @@ async function reconcileTreeseedTarget({
   await runByDependencyLevel(topologicallySortDesiredUnits(planned.units), async (unit) => {
     const plan = planByUnitId.get(unit.unitId);
     const unitTiming = {
-      name: `reconcile:${plan.unit.provider}:${plan.unit.unitType}:${plan.unit.logicalName}`,
+      name: `apply:${plan.unit.provider}:${plan.unit.unitType}:${plan.unit.logicalName}`,
       durationMs: 0,
       status: "running",
       children: [],
@@ -233,7 +235,7 @@ async function reconcileTreeseedTarget({
     };
     const unitStartMs = performance.now();
     timingEntries.push(unitTiming);
-    write?.(`Reconciling ${plan.unit.provider}:${plan.unit.unitType} (${plan.unit.logicalName})...`);
+    write?.(`Applying ${plan.unit.provider}:${plan.unit.unitType} (${plan.unit.logicalName})...`);
     const adapter = registry.get(plan.unit.unitType, plan.unit.provider);
     const persisted = ensureTreeseedPersistedUnitState(planned.state, plan.unit);
     try {
@@ -261,27 +263,40 @@ async function reconcileTreeseedTarget({
     let result;
     try {
       const stageStartMs = performance.now();
-      result = await Promise.resolve(adapter.reconcile({
-        context,
-        unit: plan.unit,
-        persistedState: persisted,
-        observed: plan.observed,
-        diff: plan.diff
-      }));
+      if (dryRun) {
+        result = {
+          unit: plan.unit,
+          observed: plan.observed,
+          diff: plan.diff,
+          action: plan.diff.action,
+          warnings: [...plan.observed.warnings, "dry run: apply skipped"],
+          resourceLocators: plan.observed.locators,
+          state: plan.observed.live,
+          verification: null
+        };
+      } else {
+        result = await Promise.resolve(adapter.apply({
+          context,
+          unit: plan.unit,
+          persistedState: persisted,
+          observed: plan.observed,
+          diff: plan.diff
+        }));
+      }
       unitTiming.children?.push({
-        name: `${unitTiming.name}:reconcile`,
+        name: `${unitTiming.name}:apply`,
         durationMs: elapsedMs(stageStartMs),
-        status: "success"
+        status: dryRun ? "skipped" : "success"
       });
     } catch (error) {
       unitTiming.children?.push({
-        name: `${unitTiming.name}:reconcile`,
+        name: `${unitTiming.name}:apply`,
         durationMs: elapsedMs(unitStartMs),
         status: "failed"
       });
       unitTiming.durationMs = elapsedMs(unitStartMs);
       unitTiming.status = "failed";
-      wrapAdapterFailure("reconcile", plan.unit.provider, plan.unit.unitType, plan.unit.unitId, error);
+      wrapAdapterFailure("apply", plan.unit.provider, plan.unit.unitType, plan.unit.unitId, error);
     }
     write?.(`Verifying ${plan.unit.provider}:${plan.unit.unitType} (${plan.unit.logicalName})...`);
     const postconditions = await Promise.resolve(adapter.requiredPostconditions?.({
@@ -329,13 +344,19 @@ async function reconcileTreeseedTarget({
     unitTiming.status = verification.verified ? "success" : "failed";
     write?.(`Finished ${plan.unit.provider}:${plan.unit.unitType} (${plan.unit.logicalName}) in ${formatDurationMs(unitTiming.durationMs)}.`);
     if (!verification.verified) {
-      await persistVerifiedResult(persisted, verifiedResult);
+      if (!dryRun) {
+        await persistVerifiedResult(persisted, verifiedResult);
+      }
       throw new Error(`Treeseed reconcile verification failed for ${plan.unit.provider}:${plan.unit.unitType} (${plan.unit.unitId}): ${formatVerificationFailure(verification)}`);
     }
-    await persistVerifiedResult(persisted, verifiedResult);
+    if (!dryRun) {
+      await persistVerifiedResult(persisted, verifiedResult);
+    }
     results.push(verifiedResult);
   });
-  writeTreeseedReconcileState(tenantRoot, planned.state);
+  if (!dryRun) {
+    writeTreeseedReconcileState(tenantRoot, planned.state);
+  }
   return {
     target,
     units: planned.units,
@@ -365,13 +386,13 @@ async function destroyTreeseedTargetUnits({
     const persisted = ensureTreeseedPersistedUnitState(reconcileState, unit);
     let observed;
     try {
-      observed = await Promise.resolve(adapter.observe({
+      observed = await Promise.resolve(adapter.refresh({
         context,
         unit,
         persistedState: persisted
       }));
     } catch (error) {
-      wrapAdapterFailure("observe", unit.provider, unit.unitType, unit.unitId, error);
+      wrapAdapterFailure("refresh", unit.provider, unit.unitType, unit.unitId, error);
     }
     let result;
     try {
@@ -394,14 +415,14 @@ async function collectTreeseedReconcileStatus({
   env = process.env,
   systems
 }) {
-  const observed = await observeTreeseedUnits({ tenantRoot, target, env, systems });
+  const observed = await refreshTreeseedUnits({ tenantRoot, target, env, systems });
   const registry = createTreeseedReconcileRegistry(observed.deployConfig);
   const context = createRunContext(tenantRoot, target, env);
   const plans = await Promise.all(observed.units.map(async (unit) => {
     const adapter = registry.get(unit.unitType, unit.provider);
     const persisted = ensureTreeseedPersistedUnitState(observed.state, unit);
     const observation = observed.observations.get(unit.unitId);
-    const diff = await Promise.resolve(adapter.plan({
+    const diff = await Promise.resolve(adapter.diff({
       context,
       unit,
       persistedState: persisted,
@@ -448,7 +469,7 @@ async function collectTreeseedReconcileStatus({
 export {
   collectTreeseedReconcileStatus,
   destroyTreeseedTargetUnits,
-  observeTreeseedUnits,
   planTreeseedReconciliation,
-  reconcileTreeseedTarget
+  reconcileTreeseedTarget,
+  refreshTreeseedUnits
 };

package/dist/reconcile/index.d.ts

@@ -1,8 +1,10 @@
 export * from './contracts.ts';
+export * from './platform.ts';
 export * from './bootstrap-systems.ts';
 export * from './desired-state.ts';
 export * from './engine.ts';
 export * from './errors.ts';
+export * from './live-acceptance.ts';
 export * from './registry.ts';
 export * from './state.ts';
 export * from './units.ts';

package/dist/reconcile/index.js

@@ -1,8 +1,10 @@
 export * from "./contracts.js";
+export * from "./platform.js";
 export * from "./bootstrap-systems.js";
 export * from "./desired-state.js";
 export * from "./engine.js";
 export * from "./errors.js";
+export * from "./live-acceptance.js";
 export * from "./registry.js";
 export * from "./state.js";
 export * from "./units.js";

package/dist/reconcile/live-acceptance.d.ts

@@ -0,0 +1,79 @@
+import { type TreeseedCanonicalAction, type TreeseedCanonicalDrift, type TreeseedCanonicalGraphNode, type TreeseedCanonicalReconcileReport } from './platform.ts';
+export type TreeseedLiveReconcileProvider = 'railway' | 'cloudflare' | 'github' | 'local';
+export type TreeseedLiveReconcileMode = 'smoke' | 'acceptance' | 'cleanup';
+export type TreeseedLiveReconcileEnvironment = 'local' | 'staging' | 'prod';
+export interface TreeseedLiveReconcileScenarioResult {
+    id: string;
+    provider: TreeseedLiveReconcileProvider;
+    capability: string;
+    mode: TreeseedLiveReconcileMode;
+    ok: boolean;
+    phase: 'smoke' | 'validate' | 'create' | 'update' | 'replace' | 'verify' | 'destroy' | 'cleanup' | 'blocked';
+    action: TreeseedCanonicalAction['kind'];
+    reason: string;
+    startedAt: string;
+    completedAt: string;
+    durationMs: number;
+    locators: Record<string, string | null>;
+    createdResources: TreeseedCanonicalGraphNode[];
+    updatedResources: TreeseedCanonicalGraphNode[];
+    replacedResources: TreeseedCanonicalGraphNode[];
+    destroyedResources: TreeseedCanonicalGraphNode[];
+    retainedResources: TreeseedCanonicalGraphNode[];
+    issues: string[];
+}
+export interface TreeseedLiveReconcileProviderReport {
+    provider: TreeseedLiveReconcileProvider;
+    mode: TreeseedLiveReconcileMode;
+    runId: string;
+    resourcePrefix: string;
+    scenarioResults: TreeseedLiveReconcileScenarioResult[];
+    coverage: {
+        total: number;
+        passed: number;
+        failed: number;
+        capabilities: string[];
+    };
+    createdResources: TreeseedCanonicalGraphNode[];
+    updatedResources: TreeseedCanonicalGraphNode[];
+    replacedResources: TreeseedCanonicalGraphNode[];
+    destroyedResources: TreeseedCanonicalGraphNode[];
+    retainedResources: TreeseedCanonicalGraphNode[];
+    cleanupDrift: TreeseedCanonicalDrift[];
+    report: TreeseedCanonicalReconcileReport;
+    ok: boolean;
+}
+export interface TreeseedLiveReconcileRunResult {
+    command: 'reconcile test-live';
+    mode: TreeseedLiveReconcileMode;
+    environment: TreeseedLiveReconcileEnvironment;
+    runId: string;
+    resourcePrefix: string;
+    providers: TreeseedLiveReconcileProviderReport[];
+    ok: boolean;
+}
+export interface TreeseedLiveReconcileProgressEvent {
+    provider: TreeseedLiveReconcileProvider;
+    mode: TreeseedLiveReconcileMode;
+    environment: TreeseedLiveReconcileEnvironment;
+    runId: string;
+    resourcePrefix: string;
+    capability?: string;
+    phase: 'start' | 'cleanup' | 'create' | 'verify' | 'destroy' | 'complete' | 'blocked';
+    message: string;
+    elapsedMs?: number;
+}
+export interface RunTreeseedLiveReconcileTestsOptions {
+    cwd: string;
+    environment: TreeseedLiveReconcileEnvironment;
+    providers: TreeseedLiveReconcileProvider[];
+    mode?: TreeseedLiveReconcileMode;
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+    runId?: string;
+    now?: Date;
+    fetchImpl?: typeof fetch;
+    onProgress?: (event: TreeseedLiveReconcileProgressEvent) => void;
+}
+export declare function treeseedLiveReconcileProviderCapabilities(provider: TreeseedLiveReconcileProvider): string[];
+export declare function treeseedLiveReconcileResourcePrefix(environment: TreeseedLiveReconcileEnvironment, provider: TreeseedLiveReconcileProvider, runId: string): string;
+export declare function runTreeseedLiveReconcileTests(options: RunTreeseedLiveReconcileTestsOptions): Promise<TreeseedLiveReconcileRunResult>;