@treeseed/sdk 0.5.2 → 0.6.0

package/dist/reconcile/engine.js

@@ -0,0 +1,356 @@
+import { createTreeseedReconcileRegistry } from "./registry.js";
+import { deriveTreeseedDesiredUnits } from "./desired-state.js";
+import { ensureTreeseedPersistedUnitState, desiredUnitSpecHash, loadTreeseedReconcileState, updateTreeseedPersistedUnitState, writeTreeseedReconcileState } from "./state.js";
+import { reverseTopologicallySortedUnits, topologicallySortDesiredUnits } from "./units.js";
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function toErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function wrapAdapterFailure(stage, provider, unitType, unitId, error) {
+  const message = `Treeseed reconcile adapter failed during ${stage} for ${provider}:${unitType} (${unitId}): ${toErrorMessage(error)}`;
+  const wrapped = new Error(message);
+  if (error instanceof Error && "stack" in error && typeof error.stack === "string") {
+    wrapped.stack = error.stack;
+  }
+  throw wrapped;
+}
+function formatVerificationFailure(verification) {
+  const details = [
+    verification.missing.length > 0 ? `missing: ${verification.missing.join("; ")}` : null,
+    verification.drifted.length > 0 ? `drifted: ${verification.drifted.join("; ")}` : null,
+    verification.warnings.length > 0 ? `warnings: ${verification.warnings.join("; ")}` : null
+  ].filter(Boolean);
+  return details.length > 0 ? `Verification failed (${details.join(" | ")})` : "Verification failed.";
+}
+function createRunContext(tenantRoot, target, launchEnv, write) {
+  const { deployConfig } = deriveTreeseedDesiredUnits({ tenantRoot, target });
+  return {
+    tenantRoot,
+    target,
+    deployConfig,
+    launchEnv,
+    write,
+    session: /* @__PURE__ */ new Map()
+  };
+}
+function persistResult(reconcileState, previous, result) {
+  updateTreeseedPersistedUnitState(reconcileState, {
+    ...previous,
+    desiredSpecHash: desiredUnitSpecHash(result.unit),
+    lastObservedAt: nowIso(),
+    lastReconciledAt: nowIso(),
+    lastVerifiedAt: result.verification?.verified ? nowIso() : previous.lastVerifiedAt,
+    lastStatus: result.verification?.verified ? "ready" : result.observed.status,
+    lastObservedState: result.observed.live,
+    lastReconciledState: result.state,
+    lastDiff: result.diff,
+    lastVerification: result.verification,
+    lastAction: result.action,
+    resourceLocators: result.resourceLocators,
+    warnings: [...result.warnings, ...result.verification?.warnings ?? []],
+    error: result.verification?.verified === false ? formatVerificationFailure(result.verification) : null
+  });
+}
+async function verifyPlanUnits({
+  plans,
+  registry,
+  context,
+  state,
+  write
+}) {
+  const verificationMap = /* @__PURE__ */ new Map();
+  context.session.set("treeseed:verification-results", verificationMap);
+  const verificationResults = /* @__PURE__ */ new Map();
+  for (const plan of plans) {
+    write?.(`Verifying ${plan.unit.provider}:${plan.unit.unitType}...`);
+    const adapter = registry.get(plan.unit.unitType, plan.unit.provider);
+    const persisted = ensureTreeseedPersistedUnitState(state, plan.unit);
+    const postconditions = await Promise.resolve(adapter.requiredPostconditions?.({
+      context,
+      unit: plan.unit,
+      persistedState: persisted
+    }) ?? []);
+    let verification;
+    try {
+      verification = await Promise.resolve(adapter.verify({
+        context,
+        unit: plan.unit,
+        persistedState: persisted,
+        observed: plan.observed,
+        diff: plan.diff,
+        result: null,
+        postconditions
+      }));
+    } catch (error) {
+      wrapAdapterFailure("verify", plan.unit.provider, plan.unit.unitType, plan.unit.unitId, error);
+    }
+    verificationMap.set(plan.unit.unitId, verification);
+    verificationResults.set(plan.unit.unitId, {
+      postconditions,
+      verification
+    });
+  }
+  return verificationResults;
+}
+async function observeTreeseedUnits({
+  tenantRoot,
+  target,
+  env = process.env,
+  write
+}) {
+  const { units, deployConfig } = deriveTreeseedDesiredUnits({ tenantRoot, target });
+  const registry = createTreeseedReconcileRegistry(deployConfig);
+  const reconcileState = loadTreeseedReconcileState(tenantRoot, target);
+  const context = createRunContext(tenantRoot, target, env, write);
+  const observations = /* @__PURE__ */ new Map();
+  for (const unit of topologicallySortDesiredUnits(units)) {
+    write?.(`Observing ${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({
+        context,
+        unit,
+        persistedState: persisted
+      }));
+    } catch (error) {
+      wrapAdapterFailure("observe", unit.provider, unit.unitType, unit.unitId, error);
+    }
+    observations.set(unit.unitId, observed);
+  }
+  return {
+    units,
+    observations,
+    state: reconcileState,
+    deployConfig
+  };
+}
+async function planTreeseedReconciliation({
+  tenantRoot,
+  target,
+  env = process.env,
+  write
+}) {
+  const observed = await observeTreeseedUnits({ tenantRoot, target, env, write });
+  const registry = createTreeseedReconcileRegistry(observed.deployConfig);
+  const context = createRunContext(tenantRoot, target, env, write);
+  const plans = [];
+  for (const unit of topologicallySortDesiredUnits(observed.units)) {
+    const adapter = registry.get(unit.unitType, unit.provider);
+    const persisted = ensureTreeseedPersistedUnitState(observed.state, unit);
+    const observation = observed.observations.get(unit.unitId);
+    let diff;
+    try {
+      diff = await Promise.resolve(adapter.plan({
+        context,
+        unit,
+        persistedState: persisted,
+        observed: observation
+      }));
+    } catch (error) {
+      wrapAdapterFailure("plan", unit.provider, unit.unitType, unit.unitId, error);
+    }
+    plans.push({
+      unit,
+      observed: observation,
+      diff,
+      persisted
+    });
+  }
+  return {
+    ...observed,
+    plans
+  };
+}
+async function reconcileTreeseedTarget({
+  tenantRoot,
+  target,
+  env = process.env,
+  write
+}) {
+  const planned = await planTreeseedReconciliation({ tenantRoot, target, env, write });
+  const registry = createTreeseedReconcileRegistry(planned.deployConfig);
+  const context = createRunContext(tenantRoot, target, env, write);
+  const results = [];
+  const verificationMap = /* @__PURE__ */ new Map();
+  context.session.set("treeseed:verification-results", verificationMap);
+  for (const plan of planned.plans) {
+    write?.(`Reconciling ${plan.unit.provider}:${plan.unit.unitType}...`);
+    const adapter = registry.get(plan.unit.unitType, plan.unit.provider);
+    const persisted = ensureTreeseedPersistedUnitState(planned.state, plan.unit);
+    try {
+      await Promise.resolve(adapter.validate?.({
+        context,
+        unit: plan.unit,
+        persistedState: persisted
+      }));
+    } catch (error) {
+      wrapAdapterFailure("validate", plan.unit.provider, plan.unit.unitType, plan.unit.unitId, error);
+    }
+    let result;
+    try {
+      result = await Promise.resolve(adapter.reconcile({
+        context,
+        unit: plan.unit,
+        persistedState: persisted,
+        observed: plan.observed,
+        diff: plan.diff
+      }));
+    } catch (error) {
+      wrapAdapterFailure("reconcile", plan.unit.provider, plan.unit.unitType, plan.unit.unitId, error);
+    }
+    write?.(`Verifying ${plan.unit.provider}:${plan.unit.unitType}...`);
+    const postconditions = await Promise.resolve(adapter.requiredPostconditions?.({
+      context,
+      unit: plan.unit,
+      persistedState: persisted
+    }) ?? []);
+    let verification;
+    try {
+      verification = await Promise.resolve(adapter.verify({
+        context,
+        unit: plan.unit,
+        persistedState: persisted,
+        observed: result.observed,
+        diff: plan.diff,
+        result,
+        postconditions
+      }));
+    } catch (error) {
+      wrapAdapterFailure("verify", plan.unit.provider, plan.unit.unitType, plan.unit.unitId, error);
+    }
+    const verifiedResult = {
+      ...result,
+      verification,
+      warnings: [
+        ...result.warnings,
+        ...verification.warnings ?? []
+      ]
+    };
+    verificationMap.set(plan.unit.unitId, verification);
+    if (!verification.verified) {
+      persistResult(planned.state, persisted, verifiedResult);
+      writeTreeseedReconcileState(tenantRoot, planned.state);
+      throw new Error(`Treeseed reconcile verification failed for ${plan.unit.provider}:${plan.unit.unitType} (${plan.unit.unitId}): ${formatVerificationFailure(verification)}`);
+    }
+    persistResult(planned.state, persisted, verifiedResult);
+    results.push(verifiedResult);
+  }
+  writeTreeseedReconcileState(tenantRoot, planned.state);
+  return {
+    target,
+    units: planned.units,
+    plans: planned.plans,
+    results,
+    state: planned.state
+  };
+}
+async function destroyTreeseedTargetUnits({
+  tenantRoot,
+  target,
+  env = process.env,
+  write
+}) {
+  const { units, deployConfig } = deriveTreeseedDesiredUnits({ tenantRoot, target });
+  const registry = createTreeseedReconcileRegistry(deployConfig);
+  const reconcileState = loadTreeseedReconcileState(tenantRoot, target);
+  const context = createRunContext(tenantRoot, target, env, write);
+  const results = [];
+  for (const unit of reverseTopologicallySortedUnits(units)) {
+    const adapter = registry.get(unit.unitType, unit.provider);
+    if (!adapter.destroy) {
+      continue;
+    }
+    write?.(`Destroying ${unit.provider}:${unit.unitType}...`);
+    const persisted = ensureTreeseedPersistedUnitState(reconcileState, unit);
+    let observed;
+    try {
+      observed = await Promise.resolve(adapter.observe({
+        context,
+        unit,
+        persistedState: persisted
+      }));
+    } catch (error) {
+      wrapAdapterFailure("observe", unit.provider, unit.unitType, unit.unitId, error);
+    }
+    let result;
+    try {
+      result = await Promise.resolve(adapter.destroy({
+        context,
+        unit,
+        persistedState: persisted,
+        observed
+      }));
+    } catch (error) {
+      wrapAdapterFailure("destroy", unit.provider, unit.unitType, unit.unitId, error);
+    }
+    results.push(result);
+  }
+  return { target, results };
+}
+async function collectTreeseedReconcileStatus({
+  tenantRoot,
+  target,
+  env = process.env
+}) {
+  const observed = await observeTreeseedUnits({ tenantRoot, target, env });
+  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({
+      context,
+      unit,
+      persistedState: persisted,
+      observed: observation
+    }));
+    return {
+      unit,
+      observed: observation,
+      diff,
+      persisted
+    };
+  }));
+  const verificationResults = await verifyPlanUnits({
+    plans,
+    registry,
+    context,
+    state: observed.state
+  });
+  const units = observed.units.map((unit) => {
+    const observation = observed.observations.get(unit.unitId);
+    const verification = verificationResults.get(unit.unitId)?.verification ?? null;
+    return {
+      unitId: unit.unitId,
+      unitType: unit.unitType,
+      provider: unit.provider,
+      status: observation.status,
+      exists: observation.exists,
+      locators: observation.locators,
+      warnings: [...observation.warnings, ...verification?.warnings ?? []],
+      verification
+    };
+  });
+  const ready = units.every((unit) => unit.verification?.verified === true);
+  const blockers = units.filter((unit) => unit.verification?.verified !== true).map((unit) => `Reconcile unit ${unit.provider}:${unit.unitType} is unverified: ${formatVerificationFailure(unit.verification)}.`);
+  const warnings = units.flatMap((unit) => unit.warnings);
+  return {
+    target,
+    ready,
+    blockers,
+    warnings,
+    units
+  };
+}
+export {
+  collectTreeseedReconcileStatus,
+  destroyTreeseedTargetUnits,
+  observeTreeseedUnits,
+  planTreeseedReconciliation,
+  reconcileTreeseedTarget
+};

package/dist/reconcile/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class TreeseedReconcileError extends Error {
+    code: string;
+    unitId: string | null;
+    constructor(code: string, message: string, unitId?: string | null);
+}

package/dist/reconcile/errors.js

@@ -0,0 +1,13 @@
+class TreeseedReconcileError extends Error {
+  code;
+  unitId;
+  constructor(code, message, unitId = null) {
+    super(message);
+    this.name = "TreeseedReconcileError";
+    this.code = code;
+    this.unitId = unitId;
+  }
+}
+export {
+  TreeseedReconcileError
+};

package/dist/reconcile/index.d.ts

@@ -0,0 +1,7 @@
+export * from './contracts.ts';
+export * from './desired-state.ts';
+export * from './engine.ts';
+export * from './errors.ts';
+export * from './registry.ts';
+export * from './state.ts';
+export * from './units.ts';

package/dist/reconcile/index.js

@@ -0,0 +1,7 @@
+export * from "./contracts.js";
+export * from "./desired-state.js";
+export * from "./engine.js";
+export * from "./errors.js";
+export * from "./registry.js";
+export * from "./state.js";
+export * from "./units.js";

package/dist/reconcile/registry.d.ts

@@ -0,0 +1,7 @@
+import type { TreeseedDeployConfig } from '../platform/contracts.ts';
+import type { TreeseedReconcileAdapter, TreeseedReconcileProviderId, TreeseedReconcileUnitType } from './contracts.ts';
+export type TreeseedReconcileRegistry = {
+    adapters: TreeseedReconcileAdapter[];
+    get(unitType: TreeseedReconcileUnitType, providerId: TreeseedReconcileProviderId): TreeseedReconcileAdapter;
+};
+export declare function createTreeseedReconcileRegistry(config: TreeseedDeployConfig): TreeseedReconcileRegistry;

package/dist/reconcile/registry.js

@@ -0,0 +1,64 @@
+import { loadTreeseedPlugins } from "../platform/plugins/runtime.js";
+import { createCloudflareReconcileAdapters, createRailwayReconcileAdapters } from "./builtin-adapters.js";
+function normalizeAdapterContribution(contribution, context) {
+  if (typeof contribution === "function") {
+    return contribution(context);
+  }
+  return contribution;
+}
+function loadPluginReconcileAdapters(config) {
+  const tenantRoot = config.__tenantRoot ?? process.cwd();
+  const plugins = loadTreeseedPlugins(config);
+  const adapters = [];
+  for (const entry of plugins) {
+    const plugin = entry.plugin;
+    const contributions = plugin.reconcileAdapters;
+    if (!contributions || typeof contributions !== "object") {
+      continue;
+    }
+    for (const contribution of Object.values(contributions)) {
+      const resolved = normalizeAdapterContribution(contribution, {
+        projectRoot: tenantRoot,
+        deployConfig: config,
+        tenantConfig: void 0,
+        pluginConfig: entry.config ?? {}
+      });
+      if (!resolved) {
+        continue;
+      }
+      adapters.push(resolved);
+    }
+  }
+  return adapters;
+}
+function createTreeseedReconcileRegistry(config) {
+  const adapters = [
+    ...createCloudflareReconcileAdapters(),
+    ...createRailwayReconcileAdapters(),
+    ...loadPluginReconcileAdapters(config)
+  ];
+  const seenBindings = /* @__PURE__ */ new Map();
+  for (const adapter of adapters) {
+    for (const unitType of adapter.unitTypes) {
+      const bindingKey = `${adapter.providerId}:${unitType}`;
+      const existing = seenBindings.get(bindingKey);
+      if (existing) {
+        throw new Error(`Duplicate Treeseed reconcile adapter binding for ${bindingKey} (${existing}, ${adapter.providerId}).`);
+      }
+      seenBindings.set(bindingKey, adapter.providerId);
+    }
+  }
+  return {
+    adapters,
+    get(unitType, providerId) {
+      const adapter = adapters.find((candidate) => candidate.supports(unitType, providerId));
+      if (!adapter) {
+        throw new Error(`Treeseed reconcile adapter missing for ${providerId}:${unitType}.`);
+      }
+      return adapter;
+    }
+  };
+}
+export {
+  createTreeseedReconcileRegistry
+};

package/dist/reconcile/state.d.ts

@@ -0,0 +1,7 @@
+import type { TreeseedDesiredUnit, TreeseedReconcileStateRecord, TreeseedReconcileTarget, TreeseedUnitPersistedState } from './contracts.ts';
+export declare function migrateLegacyDeployStateUnits(legacyState: Record<string, any>, target: TreeseedReconcileTarget): Record<string, TreeseedUnitPersistedState>;
+export declare function loadTreeseedReconcileState(tenantRoot: string, target: TreeseedReconcileTarget): TreeseedReconcileStateRecord;
+export declare function writeTreeseedReconcileState(tenantRoot: string, reconcileState: TreeseedReconcileStateRecord): void;
+export declare function ensureTreeseedPersistedUnitState(reconcileState: TreeseedReconcileStateRecord, unit: TreeseedDesiredUnit): TreeseedUnitPersistedState;
+export declare function updateTreeseedPersistedUnitState(reconcileState: TreeseedReconcileStateRecord, state: TreeseedUnitPersistedState): void;
+export declare function desiredUnitSpecHash(unit: TreeseedDesiredUnit): string;