@treeseed/sdk 0.12.26 → 0.12.27

package/README.md

@@ -283,7 +283,7 @@ await treeDx.syncMirror({
 await treeDx.createMigration({
   targetNodeId: 'node_mirror',
   mode: 'primary_transfer',
-  dryRun: true,
+  planOnly: true,
   requireMirrorSynced: false,
 });
 

package/dist/guarantees/index.js

@@ -699,11 +699,25 @@ function apiAcceptanceEnvironment(environment) {
   };
 }
 function apiAcceptanceBaseUrl(environment) {
-  if (process.env.TREESEED_API_BASE_URL?.trim()) return process.env.TREESEED_API_BASE_URL.trim().replace(/\/+$/u, "");
+  if (process.env.TREESEED_API_BASE_URL?.trim()) {
+    const configured = process.env.TREESEED_API_BASE_URL.trim().replace(/\/+$/u, "");
+    if (environment !== "local" && isLoopbackUrl(configured)) {
+      throw new Error(`API guarantee environment ${environment} must target a live hosted API URL, not ${configured}.`);
+    }
+    return configured;
+  }
   if (environment === "staging") return "https://api.preview.treeseed.dev";
   if (environment === "prod") return "https://api.treeseed.dev";
   return "http://127.0.0.1:3000";
 }
+function isLoopbackUrl(value) {
+  try {
+    const url = new URL(value);
+    return ["localhost", "127.0.0.1", "0.0.0.0", "::1", "[::1]"].includes(url.hostname);
+  } catch {
+    return false;
+  }
+}
 async function defaultTreeseedGuaranteeVerifierExecutor(input) {
   const definition = input.definition;
   const ownerPackage = definition.ownerPackage ?? input.guarantee.manifest.ownerPackage;

package/dist/hosting/builtins.js

@@ -18,7 +18,7 @@ function syntheticStatus(input) {
       unitId: input.unit.id,
       serviceType: input.unit.serviceType.id,
       placement: input.unit.placement,
-      dryRun: input.dryRun === true
+      planOnly: input.planOnly === true
     },
     warnings: []
   };
@@ -85,10 +85,10 @@ function createSyntheticHostAdapter(id, label, capabilityIds, environments = ALL
     apply(input) {
       return {
         ...syntheticStatus(input),
-        status: input.dryRun ? "pending" : "ready",
+        status: input.planOnly ? "pending" : "ready",
         state: {
           ...syntheticStatus(input).state,
-          applied: input.dryRun !== true
+          applied: input.planOnly !== true
         }
       };
     },
@@ -327,7 +327,7 @@ function createCloudflareHostAdapter() {
     },
     verify(input) {
       if (!isPagesSite(input)) return base.verify(input);
-      if (input.dryRun) return base.verify(input);
+      if (input.planOnly) return base.verify(input);
       const projectName = cloudflarePagesProjectName(input);
       const branchName = projectName ? cloudflarePagesBranchName(input) : null;
       const domain = cloudflarePagesDomain(input);

package/dist/hosting/contracts.d.ts

@@ -13,7 +13,7 @@ export interface TreeseedHostAdapterOperationInput {
     environment: TreeseedHostingEnvironment;
     unit: TreeseedHostingUnit;
     graph: TreeseedHostingGraph;
-    dryRun?: boolean;
+    planOnly?: boolean;
 }
 export interface TreeseedHostAdapterOperationResult {
     status: TreeseedHostingStatus;
@@ -161,7 +161,7 @@ export interface TreeseedHostingVerification {
 }
 export interface TreeseedHostingPlan {
     environment: TreeseedHostingEnvironment;
-    dryRun: boolean;
+    planOnly: boolean;
     units: Array<{
         unit: TreeseedHostingUnit;
         observed: TreeseedHostAdapterOperationResult;
@@ -173,7 +173,7 @@ export interface TreeseedHostingPlan {
 }
 export interface TreeseedHostingApplyResult {
     environment: TreeseedHostingEnvironment;
-    dryRun: boolean;
+    planOnly: boolean;
     selectedApps?: string[];
     selectedSystems?: string[];
     skippedSystems?: Array<{

package/dist/hosting/graph.d.ts

@@ -3,13 +3,13 @@ import type { TreeseedRunnableBootstrapSystem } from '../reconcile/bootstrap-sys
 import type { TreeseedHostingApplyResult, TreeseedHostingEnvironment, TreeseedHostingGraph, TreeseedHostingGraphInput, TreeseedHostingPlan, TreeseedHostingPlacementSummary, TreeseedHostingUnit, TreeseedServicePlacement } from './contracts.js';
 export declare function compileTreeseedHostingGraph(input: TreeseedHostingGraphInput): TreeseedHostingGraph;
 export declare function planTreeseedHostingGraph(input: TreeseedHostingGraphInput & {
-    dryRun?: boolean;
+    planOnly?: boolean;
 }): Promise<TreeseedHostingPlan>;
 /**
  * @deprecated Use reconcileTreeseedTarget with hosting selectors instead.
  */
 export declare function applyTreeseedHostingGraph(input: TreeseedHostingGraphInput & {
-    dryRun?: boolean;
+    planOnly?: boolean;
 }): Promise<TreeseedHostingApplyResult>;
 export declare function serializeHostingUnit(unit: TreeseedHostingUnit): {
     id: string;
@@ -111,7 +111,7 @@ export declare function serializeHostingPlan(plan: TreeseedHostingPlan): {
     liveVerification: import("../reconcile/platform.js").TreeseedCanonicalLiveVerification;
     ok: boolean;
     environment: TreeseedHostingEnvironment;
-    dryRun: boolean;
+    planOnly: boolean;
 };
 export declare function serializeHostingApplyResult(result: TreeseedHostingApplyResult): {
     selectedApps: string[];
@@ -190,6 +190,6 @@ export declare function serializeHostingApplyResult(result: TreeseedHostingApply
     liveVerification: import("../reconcile/platform.js").TreeseedCanonicalLiveVerification;
     ok: boolean;
     environment: TreeseedHostingEnvironment;
-    dryRun: boolean;
+    planOnly: boolean;
 };
 export declare function hostingEnvironmentLabel(environment: TreeseedHostingEnvironment): string;

package/dist/hosting/graph.js

@@ -162,8 +162,8 @@ function railwaySourcePolicy(input, serviceKey, service, imageRef) {
   const configuredSource = service.railway?.source && typeof service.railway.source === "object" && !Array.isArray(service.railway.source) ? service.railway.source : {};
   const configuredMode = typeof service.railway?.sourceMode === "string" ? service.railway.sourceMode : null;
   const repository = typeof service.railway?.sourceRepo === "string" ? service.railway.sourceRepo : typeof configuredSource.repository === "string" ? configuredSource.repository : typeof configuredSource.repo === "string" ? configuredSource.repo : readPackageRepository(resolveRailwayServiceSourceRoot(input, serviceKey, service)) ?? readPackageRepository(input.tenantRoot);
-  const sourceEligible = ["api", "operationsRunner", "capacityProviderManager", "capacityProviderRunner"].includes(serviceKey);
-  const mode = input.environment === "prod" ? "image" : configuredMode === "git" || configuredMode === "image" ? configuredMode : imageRef ? "image" : input.environment === "staging" && sourceEligible && repository ? "git" : "git";
+  const apiPackageSourceEligible = ["api", "operationsRunner"].includes(serviceKey);
+  const mode = input.environment === "prod" ? "image" : input.environment === "staging" && apiPackageSourceEligible ? "git" : configuredMode === "git" || configuredMode === "image" ? configuredMode : imageRef ? "image" : "git";
   if (mode !== "git") {
     return {
       sourceMode: "image",
@@ -721,14 +721,14 @@ async function planTreeseedHostingGraph(input) {
   const graph = compileTreeseedHostingGraph(input);
   const units = [];
   for (const unit of graph.units) {
-    const observed = await unit.host.refresh({ environment: graph.environment, unit, graph, dryRun: input.dryRun !== false });
-    const plan = await unit.host.diff({ environment: graph.environment, unit, graph, observed, dryRun: input.dryRun !== false });
-    const verification = await unit.host.verify({ environment: graph.environment, unit, graph, observed, dryRun: input.dryRun !== false });
+    const observed = await unit.host.refresh({ environment: graph.environment, unit, graph, planOnly: input.planOnly !== false });
+    const plan = await unit.host.diff({ environment: graph.environment, unit, graph, observed, planOnly: input.planOnly !== false });
+    const verification = await unit.host.verify({ environment: graph.environment, unit, graph, observed, planOnly: input.planOnly !== false });
     units.push({ unit, observed, plan, verification });
   }
   return {
     environment: graph.environment,
-    dryRun: input.dryRun !== false,
+    planOnly: input.planOnly !== false,
     units,
     placements: graph.placements,
     warnings: graph.warnings
@@ -769,10 +769,10 @@ async function applyTreeseedHostingGraph(input) {
   const graph = compileTreeseedHostingGraph(input);
   const selectedSystems = railwayReconcileSystemsForUnits(graph.units);
   const infrastructureUnits = graph.units.filter(isInfrastructureHostedUnit);
-  if (plan.dryRun) {
+  if (plan.planOnly) {
     return {
       environment: plan.environment,
-      dryRun: true,
+      planOnly: true,
       selectedApps: [...new Set(graph.units.map((unit) => unit.application?.id).filter((value) => Boolean(value)))],
       selectedSystems,
       skippedSystems: ["web", "data", "github"].filter((system) => !selectedSystems.includes(system)).map((system) => ({ system, reason: selectedSystems.length > 0 ? "Not selected by hosting app filter." : "No Railway reconciliation selected." })),
@@ -794,7 +794,7 @@ async function applyTreeseedHostingGraph(input) {
     target: createPersistentDeployTarget(graph.environment),
     systems: selectedSystems.length > 0 ? selectedSystems : void 0,
     env: railwayEnvForHostingApply(input, graph),
-    dryRun: plan.dryRun
+    planOnly: plan.planOnly
   });
   const resultByUnit = /* @__PURE__ */ new Map();
   for (const entry of reconcile.results) {
@@ -808,11 +808,11 @@ async function applyTreeseedHostingGraph(input) {
       unit,
       plan: entry.plan,
       result: {
-        status: reconcileResult?.verification?.ready || plan.dryRun ? "ready" : "blocked",
+        status: reconcileResult?.verification?.ready || plan.planOnly ? "ready" : "blocked",
         locators: reconcileResult?.resourceLocators ?? {},
         state: reconcileResult?.state ?? {
           unitId: unit.id,
-          action: plan.dryRun ? "plan" : "unmatched"
+          action: plan.planOnly ? "plan" : "unmatched"
         },
         warnings: reconcileResult?.warnings ?? []
       },
@@ -831,9 +831,9 @@ async function applyTreeseedHostingGraph(input) {
         warnings: reconcileResult.verification.warnings
       } : {
         unitId: unit.id,
-        status: plan.dryRun ? "ready" : "blocked",
-        verified: plan.dryRun,
-        checks: plan.dryRun ? [] : [{
+        status: plan.planOnly ? "ready" : "blocked",
+        verified: plan.planOnly,
+        checks: plan.planOnly ? [] : [{
           key: "reconcile-result",
           label: "Hosting unit matched a reconcile result",
           ok: false,
@@ -845,7 +845,7 @@ async function applyTreeseedHostingGraph(input) {
   });
   return {
     environment: plan.environment,
-    dryRun: plan.dryRun,
+    planOnly: plan.planOnly,
     selectedApps: [...new Set(graph.units.map((unit) => unit.application?.id).filter((value) => Boolean(value)))],
     selectedSystems,
     skippedSystems: ["web", "data", "github"].filter((system) => !selectedSystems.includes(system)).map((system) => ({ system, reason: selectedSystems.length > 0 ? "Not selected by hosting app filter." : "No Railway reconciliation selected." })),
@@ -1032,7 +1032,7 @@ function serializeHostingPlan(plan) {
   const canonical = canonicalHostingReportFromPlan(plan);
   return {
     environment: plan.environment,
-    dryRun: plan.dryRun,
+    planOnly: plan.planOnly,
     ...canonical,
     selectedApps: [...new Set(plan.units.map((entry) => entry.unit.application?.id).filter((value) => Boolean(value)))],
     selectedSystems,
@@ -1063,7 +1063,7 @@ function serializeHostingApplyResult(result) {
   const canonical = canonicalHostingReportFromApplyResult(result);
   return {
     environment: result.environment,
-    dryRun: result.dryRun,
+    planOnly: result.planOnly,
     ...canonical,
     selectedApps: result.selectedApps ?? [],
     selectedSystems: result.selectedSystems ?? [],

package/dist/operations/agent-tools.d.ts

@@ -1,5 +1,5 @@
 export declare const AGENT_OPERATION_NAMES: readonly ["switch", "dev", "verify", "save", "update", "stage", "close", "release"];
-export declare const AGENT_OPERATION_MODES: readonly ["dry_run", "read_only", "mutating"];
+export declare const AGENT_OPERATION_MODES: readonly ["plan", "read_only", "mutating"];
 export type AgentOperationName = (typeof AGENT_OPERATION_NAMES)[number];
 export type AgentOperationMode = (typeof AGENT_OPERATION_MODES)[number];
 export type AgentOperationStatus = 'completed' | 'waiting' | 'failed' | 'skipped' | 'retry_created';

package/dist/operations/agent-tools.js

@@ -8,7 +8,7 @@ const AGENT_OPERATION_NAMES = [
   "close",
   "release"
 ];
-const AGENT_OPERATION_MODES = ["dry_run", "read_only", "mutating"];
+const AGENT_OPERATION_MODES = ["plan", "read_only", "mutating"];
 function normalizePath(value) {
   return value.replace(/\\/gu, "/").replace(/^\.?\//u, "").replace(/\/+/gu, "/");
 }

package/dist/operations/providers/default.js

@@ -718,7 +718,7 @@ class RepositoryHostCreateRepositoriesOperation extends BaseOperation {
     }
     return operationResult(this.metadata, await createKnowledgeHubRepositories({
       plan,
-      dryRun: input.dryRun === true,
+      planOnly: input.planOnly === true,
       description: typeof input.description === "string" ? input.description : null,
       homepageUrl: typeof input.homepageUrl === "string" ? input.homepageUrl : null
     }));
@@ -741,7 +741,7 @@ class ContentPublishOperation extends BaseOperation {
     const tenantRoot = typeof input.tenantRoot === "string" ? input.tenantRoot : context.cwd;
     const contentRepositoryRoot = typeof input.contentRepositoryRoot === "string" ? input.contentRepositoryRoot : typeof input.contentRoot === "string" ? input.contentRoot : null;
     const scope = input.scope === "staging" || input.scope === "prod" || input.scope === "local" ? input.scope : "prod";
-    if (input.dryRun === true) {
+    if (input.planOnly === true) {
       return operationResult(this.metadata, {
         status: "planned",
         tenantRoot,

package/dist/operations/services/config-runtime.d.ts

@@ -358,10 +358,10 @@ export declare function checkTreeseedProviderConnections({ tenantRoot, scope, en
     issues: any[];
 }>;
 export declare function formatTreeseedProviderConnectionReport(report: any): string;
-export declare function syncTreeseedGitHubEnvironment({ tenantRoot, scope, dryRun, repository: repositoryInput, valuesOverlay, entryIds, managedHostMode, execution, concurrency, onProgress, }: {
+export declare function syncTreeseedGitHubEnvironment({ tenantRoot, scope, planOnly, repository: repositoryInput, valuesOverlay, entryIds, managedHostMode, execution, concurrency, onProgress, }: {
     tenantRoot: string;
     scope?: TreeseedConfigScope;
-    dryRun?: boolean;
+    planOnly?: boolean;
     repository?: string | null;
     valuesOverlay?: Record<string, string | undefined>;
     entryIds?: string[];
@@ -402,10 +402,10 @@ export declare function syncTreeseedGitHubEnvironment({ tenantRoot, scope, dryRu
     };
     entryIds: string[] | undefined;
 }>;
-export declare function syncTreeseedCloudflareEnvironment({ tenantRoot, scope, dryRun, valuesOverlay, entryIds, onProgress, }: {
+export declare function syncTreeseedCloudflareEnvironment({ tenantRoot, scope, planOnly, valuesOverlay, entryIds, onProgress, }: {
     tenantRoot: string;
     scope?: TreeseedConfigScope;
-    dryRun?: boolean;
+    planOnly?: boolean;
     valuesOverlay?: Record<string, string | undefined>;
     entryIds?: string[];
     onProgress?: (message: string, stream?: 'stdout' | 'stderr') => void;
@@ -420,10 +420,10 @@ export declare function syncTreeseedCloudflareEnvironment({ tenantRoot, scope, d
     secrets: string[];
     varsManagedByWranglerConfig: string[];
 };
-export declare function syncTreeseedRailwayEnvironment({ tenantRoot, scope, dryRun, valuesOverlay, entryIds, onProgress, }: {
+export declare function syncTreeseedRailwayEnvironment({ tenantRoot, scope, planOnly, valuesOverlay, entryIds, onProgress, }: {
     tenantRoot: string;
     scope?: TreeseedConfigScope;
-    dryRun?: boolean;
+    planOnly?: boolean;
     valuesOverlay?: Record<string, string | undefined>;
     entryIds?: string[];
     onProgress?: (message: string, stream?: 'stdout' | 'stderr') => void;
@@ -441,12 +441,12 @@ export declare function syncTreeseedRailwayEnvironment({ tenantRoot, scope, dryR
         environmentName: string;
         secrets: any;
         variables: any;
-        dryRun: boolean;
+        planOnly: boolean;
     }[];
 }>;
-export declare function initializeTreeseedPersistentEnvironment({ tenantRoot, scope, dryRun }?: {
+export declare function initializeTreeseedPersistentEnvironment({ tenantRoot, scope, planOnly }?: {
     scope?: string | undefined;
-    dryRun?: boolean | undefined;
+    planOnly?: boolean | undefined;
 }): Promise<{
     scope: string;
     target: {

package/dist/operations/services/config-runtime.js

@@ -1836,8 +1836,8 @@ function assertTreeseedCommandEnvironment({ tenantRoot, scope, purpose }) {
   error.details = report.validation;
   throw error;
 }
-function runGh(args, { cwd, dryRun = false, input, env } = {}) {
-  if (dryRun) {
+function runGh(args, { cwd, planOnly = false, input, env } = {}) {
+  if (planOnly) {
     return { status: 0, stdout: "", stderr: "" };
   }
   const gh = resolveTreeseedToolBinary("gh", { env });
@@ -2374,7 +2374,7 @@ function createGitHubConfigSyncUnits({
 async function syncTreeseedGitHubEnvironment({
   tenantRoot,
   scope = "prod",
-  dryRun = false,
+  planOnly = false,
   repository: repositoryInput,
   valuesOverlay = {},
   entryIds,
@@ -2433,7 +2433,7 @@ async function syncTreeseedGitHubEnvironment({
   }
   let completed = 0;
   const total = items.length;
-  if (!dryRun) {
+  if (!planOnly) {
     const units = createGitHubConfigSyncUnits({ scope, repository, environment, items });
     if (units.length === 0) {
       progress(`[${scope}][github][sync] Complete: 0 secrets, 0 variables, 0 total.`);
@@ -2515,7 +2515,7 @@ async function syncTreeseedGitHubEnvironment({
 function syncTreeseedCloudflareEnvironment({
   tenantRoot,
   scope = "prod",
-  dryRun = false,
+  planOnly = false,
   valuesOverlay = {},
   entryIds,
   onProgress
@@ -2538,7 +2538,7 @@ function syncTreeseedCloudflareEnvironment({
   const cloudflareSecrets = Object.fromEntries(registry.entries.filter((entry) => entry.scopes.includes(scope) && entry.targets.includes("cloudflare-secret") && (!entryFilter || entryFilter.has(entry.id))).map((entry) => [entry.id, values[entry.id]]).filter(([, value]) => typeof value === "string" && value.length > 0));
   progress(`[${scope}][cloudflare][sync] Syncing Cloudflare secrets...`);
   const syncedSecrets = syncCloudflareSecrets(tenantRoot, {
-    dryRun,
+    planOnly,
     target,
     extraSecrets: cloudflareSecrets,
     entryIds
@@ -2564,7 +2564,7 @@ function railwayEnvironmentEntryIdsForService(registry, values, scope, target, s
 async function syncTreeseedRailwayEnvironment({
   tenantRoot,
   scope = "prod",
-  dryRun = false,
+  planOnly = false,
   valuesOverlay = {},
   entryIds,
   onProgress
@@ -2608,13 +2608,13 @@ async function syncTreeseedRailwayEnvironment({
       environmentName,
       secrets: railwayEnvironmentEntryIdsForService(registry, serviceValues, scope, "railway-secret", service.key, entryFilter),
       variables: railwayEnvironmentEntryIdsForService(registry, serviceValues, scope, "railway-var", service.key, entryFilter),
-      dryRun
+      planOnly
     };
   }).filter(Boolean);
   for (const service of services) {
     const serviceValues = serviceValuesByName.get(service.serviceName || service.serviceId || service.instanceKey || service.service) ?? values;
     progress(`[${scope}][railway][${service.service}] Syncing ${service.secrets.length} secrets and ${service.variables.length} variables...`);
-    if (!dryRun) {
+    if (!planOnly) {
       const railwayEnv = { ...process.env, ...values };
       const project = (await ensureRailwayProject({
         projectId: "",
@@ -2653,7 +2653,7 @@ async function syncTreeseedRailwayEnvironment({
     services
   };
 }
-async function initializeTreeseedPersistentEnvironment({ tenantRoot, scope = "prod", dryRun = false } = {}) {
+async function initializeTreeseedPersistentEnvironment({ tenantRoot, scope = "prod", planOnly = false } = {}) {
   const normalizedScope = scope === "prod" ? "prod" : scope;
   const target = createPersistentDeployTarget(normalizedScope);
   const summary = await reconcileTreeseedTarget({

package/dist/operations/services/deploy.d.ts

@@ -218,8 +218,8 @@ export declare function buildTreeseedManagedCloudflareCacheRules(deployConfig: a
     };
     enabled: boolean;
 }[];
-export declare function reconcileCloudflareWebCacheRules(tenantRoot: any, deployConfig: any, state: any, target: any, { dryRun, env: providedEnv }?: {
-    dryRun?: boolean | undefined;
+export declare function reconcileCloudflareWebCacheRules(tenantRoot: any, deployConfig: any, state: any, target: any, { planOnly, env: providedEnv }?: {
+    planOnly?: boolean | undefined;
 }): {
     managed: boolean;
     skipped: boolean;
@@ -232,14 +232,14 @@ export declare function reconcileCloudflareWebCacheRules(tenantRoot: any, deploy
         managed: boolean;
         skipped: boolean;
         reason: string;
-        dryRun?: undefined;
+        planOnly?: undefined;
         zoneId?: undefined;
         host?: undefined;
         rules?: undefined;
         rulesetId?: undefined;
     } | {
         managed: boolean;
-        dryRun: boolean;
+        planOnly: boolean;
         zoneId: any;
         host: any;
         rules: {
@@ -277,7 +277,7 @@ export declare function reconcileCloudflareWebCacheRules(tenantRoot: any, deploy
         rulesetId: any;
         skipped?: undefined;
         reason?: undefined;
-        dryRun?: undefined;
+        planOnly?: undefined;
         rules?: undefined;
     })[];
     skipped?: undefined;
@@ -341,8 +341,8 @@ export declare function validateDestroyPrerequisites(tenantRoot: any, { requireR
 }): import("../../platform/contracts.js").TreeseedDeployConfig;
 export declare function shouldDeleteRailwayProjectAfterEnvironmentDestroy(project: any, scope: any, deleteData: any, deletedEnvironmentId?: null): boolean;
 export declare function setDestroyDockerRunnerForTests(runner: any): void;
-export declare function dockerLocalRuntimeResourceOperations({ dryRun }?: {
-    dryRun?: boolean | undefined;
+export declare function dockerLocalRuntimeResourceOperations({ planOnly }?: {
+    planOnly?: boolean | undefined;
 }): any[];
 export declare function cloudflareDestroyVerification(tenantRoot: any, deployConfig: any, state: any, env: any): {
     provider: string;
@@ -627,7 +627,7 @@ export declare function verifyProvisionedCloudflareResources(tenantRoot: any, op
 };
 export declare function runRemoteD1Migrations(tenantRoot: any, options?: {}): {
     databaseName: any;
-    dryRun: boolean;
+    planOnly: boolean;
 };
 export declare function markDeploymentInitialized(tenantRoot: any, options?: {}): any;
 export declare function markManagedServicesInitialized(tenantRoot: any, options?: {}): any;