@treeseed/sdk 0.12.26 → 0.12.27

package/dist/reconcile/builtin-adapters.js

@@ -56,6 +56,7 @@ import {
   deleteRailwayService,
   deleteRailwayVolume,
   deployRailwayServiceInstance,
+  inspectRailwayServiceDeploymentHealth,
   listRailwayEnvironmentServices,
   getRailwayServiceInstance,
   getRailwayProject,
@@ -298,7 +299,7 @@ function buildPackageWorkflowAdapter() {
     },
     apply(input) {
       const packageId = typeof input.unit.spec.packageId === "string" ? input.unit.spec.packageId : typeof input.unit.metadata.packageId === "string" ? input.unit.metadata.packageId : null;
-      if (packageId && input.context.dryRun !== true && input.diff.action !== "noop") {
+      if (packageId && input.context.planOnly !== true && input.diff.action !== "noop") {
         const sync = syncTreeseedPackageWorkflows({
           root: input.context.tenantRoot,
           packageId,
@@ -836,7 +837,7 @@ function buildLocalDockerComposeAdapter() {
       const composeFiles = observedOrResolvedComposeFiles(input);
       const cwd = String(input.observed.live.cwd ?? input.context.tenantRoot);
       const projectName = String(input.unit.spec.projectName ?? "treeseed-capacity-provider");
-      if (input.context.dryRun !== true && composeFiles.length > 0 && composeFiles.every((composeFile) => existsSync(composeFile))) {
+      if (input.context.planOnly !== true && composeFiles.length > 0 && composeFiles.every((composeFile) => existsSync(composeFile))) {
         const result = runDockerCompose({
           composeFiles,
           projectName,
@@ -1270,7 +1271,7 @@ function buildLocalProcessAdapter() {
     },
     async destroy(input) {
       const surfaces = Array.isArray(input.unit.spec.surfaces) ? input.unit.spec.surfaces.filter((entry) => typeof entry === "string") : [String(input.unit.spec.processId ?? input.unit.logicalName)];
-      if (input.context.dryRun !== true) {
+      if (input.context.planOnly !== true) {
         await runManagedDevAction({
           tenantRoot: input.context.tenantRoot,
           action: "stop",
@@ -1797,7 +1798,7 @@ function buildReleaseGateAdapter() {
           parentContext: input.context,
           selector,
           target: { kind: "persistent", scope: environment },
-          dryRun: input.context.dryRun === true
+          planOnly: input.context.planOnly === true
         });
         return genericResult(input, { ...input.observed.live, nested, fingerprint: input.unit.spec.fingerprint });
       }
@@ -1906,7 +1907,7 @@ function buildWorkflowMetaAdapter() {
           parentContext: input.context,
           selector,
           target: input.context.target,
-          dryRun: input.context.dryRun === true
+          planOnly: input.context.planOnly === true
         });
         return genericResult(input, { ...input.observed.live, nested, fingerprint });
       }
@@ -2000,7 +2001,7 @@ function buildCloudflareEnv(input) {
   };
 }
 function hasLiveResourceId(value) {
-  return typeof value === "string" && value.length > 0 && !value.startsWith("dryrun-") && !value.startsWith("local-") && !value.endsWith("-id") && !value.endsWith("-preview-id");
+  return typeof value === "string" && value.length > 0 && !value.startsWith("plan-") && !value.startsWith("local-") && !value.endsWith("-id") && !value.endsWith("-preview-id");
 }
 function buildRailwayEnv(input, scope) {
   const values = resolveReconcileEnvironmentValues(input, scope);
@@ -2421,6 +2422,12 @@ async function observeRailwayCustomDomainLive(input, domain) {
   });
   return normalized?.domain ? normalized : customDomain;
 }
+function railwayCustomDomainHasDnsRequirements(live) {
+  if (!live) {
+    return false;
+  }
+  return Array.isArray(live.dnsRecords) && live.dnsRecords.length > 0 || typeof live.serviceDomain === "string" && live.serviceDomain.trim().length > 0 || typeof live.verificationDnsHost === "string" && live.verificationDnsHost.trim().length > 0 && typeof live.verificationToken === "string" && live.verificationToken.trim().length > 0;
+}
 function collectCloudflareEnvironmentSync(input) {
   const target = toDeployTarget(input.context.target);
   const scope = scopeFromTarget(target);
@@ -2481,7 +2488,7 @@ function verificationCheck(key, description, source, options) {
   };
 }
 function summarizeVerification(unitId, checks, warnings = []) {
-  const missing = checks.flatMap((check) => !check.exists ? [`${check.key}: ${check.description}`] : []);
+  const missing = checks.flatMap((check) => !check.exists ? [`${check.key}: ${check.issues.join("; ") || check.description}`] : []);
   const drifted = checks.flatMap(
     (check) => check.exists && (!check.configured || !check.ready || !check.verified || check.issues.length > 0) ? [`${check.key}: ${check.issues.join("; ") || "verification failed"}`] : []
   );
@@ -2518,7 +2525,7 @@ function unsupportedVerification(unitId, message) {
     warnings: []
   };
 }
-function syncPagesEnvironmentVariablesForTarget(input, { dryRun = false } = {}) {
+function syncPagesEnvironmentVariablesForTarget(input, { planOnly = false } = {}) {
   const target = toDeployTarget(input.context.target);
   if (target.kind !== "persistent") {
     return { vars: [], secrets: [] };
@@ -2540,7 +2547,7 @@ function syncPagesEnvironmentVariablesForTarget(input, { dryRun = false } = {})
     ...plainVars,
     ...secretVars
   };
-  if (dryRun || Object.keys(envVars).length === 0) {
+  if (planOnly || Object.keys(envVars).length === 0) {
     return {
       vars: Object.keys(plainVars),
       secrets: Object.keys(secretVars)
@@ -2572,17 +2579,17 @@ function syncPagesEnvironmentVariablesForTarget(input, { dryRun = false } = {})
     secrets: Object.keys(secretVars)
   };
 }
-function reconcileCloudflareTarget(input, { dryRun = false } = {}) {
+function reconcileCloudflareTarget(input, { planOnly = false } = {}) {
   const target = toDeployTarget(input.context.target);
   const deployConfig = input.context.deployConfig;
   const state = loadDeployState(input.context.tenantRoot, deployConfig, { target });
   const env = buildCloudflareEnv(input);
-  const kvNamespaces = dryRun ? [] : listKvNamespaces(input.context.tenantRoot, env);
-  const d1Databases = dryRun ? [] : listD1Databases(input.context.tenantRoot, env);
-  const queues = dryRun ? [] : listQueues(input.context.tenantRoot, env);
-  const buckets = dryRun ? [] : listR2Buckets(input.context.tenantRoot, env);
-  const pagesProjects = dryRun ? [] : listPagesProjects(input.context.tenantRoot, env);
-  const turnstileWidgets = dryRun ? [] : listTurnstileWidgets(input.context.tenantRoot, env);
+  const kvNamespaces = planOnly ? [] : listKvNamespaces(input.context.tenantRoot, env);
+  const d1Databases = planOnly ? [] : listD1Databases(input.context.tenantRoot, env);
+  const queues = planOnly ? [] : listQueues(input.context.tenantRoot, env);
+  const buckets = planOnly ? [] : listR2Buckets(input.context.tenantRoot, env);
+  const pagesProjects = planOnly ? [] : listPagesProjects(input.context.tenantRoot, env);
+  const turnstileWidgets = planOnly ? [] : listTurnstileWidgets(input.context.tenantRoot, env);
   const runStep = (label, fn) => {
     try {
       return fn();
@@ -2606,9 +2613,9 @@ function reconcileCloudflareTarget(input, { dryRun = false } = {}) {
       state.kvNamespaces[binding].previewId = existing.id;
       return;
     }
-    if (dryRun) {
-      state.kvNamespaces[binding].id = `dryrun-${current.name}`;
-      state.kvNamespaces[binding].previewId = `dryrun-${current.name}`;
+    if (planOnly) {
+      state.kvNamespaces[binding].id = `plan-${current.name}`;
+      state.kvNamespaces[binding].previewId = `plan-${current.name}`;
       return;
     }
     runWrangler(["kv", "namespace", "create", current.name], {
@@ -2638,9 +2645,9 @@ function reconcileCloudflareTarget(input, { dryRun = false } = {}) {
       current.previewDatabaseId = existing.previewDatabaseUuid ?? existing.uuid;
       return;
     }
-    if (dryRun) {
-      current.databaseId = `dryrun-${current.databaseName}`;
-      current.previewDatabaseId = `dryrun-${current.databaseName}`;
+    if (planOnly) {
+      current.databaseId = `plan-${current.databaseName}`;
+      current.previewDatabaseId = `plan-${current.databaseName}`;
       return;
     }
     try {
@@ -2676,7 +2683,7 @@ function reconcileCloudflareTarget(input, { dryRun = false } = {}) {
     }
     let refreshedBuckets = buckets;
     const existing = refreshedBuckets.find((entry) => entry?.name === bucketName);
-    if (existing || dryRun) {
+    if (existing || planOnly) {
       return;
     }
     try {
@@ -2699,7 +2706,7 @@ function reconcileCloudflareTarget(input, { dryRun = false } = {}) {
     }
     const existing = pagesProjects.find((entry) => entry?.name === current.projectName);
     if (existing) {
-      if (!dryRun && (existing.production_branch ?? "main") !== (current.productionBranch ?? "main")) {
+      if (!planOnly && (existing.production_branch ?? "main") !== (current.productionBranch ?? "main")) {
         cloudflareApiRequest(
           `/accounts/${encodeURIComponent(env.CLOUDFLARE_ACCOUNT_ID)}/pages/projects/${encodeURIComponent(current.projectName)}`,
           {
@@ -2714,7 +2721,7 @@ function reconcileCloudflareTarget(input, { dryRun = false } = {}) {
       current.url = existing.subdomain ? `https://${existing.subdomain}` : current.url ?? `https://${current.projectName}.pages.dev`;
       return;
     }
-    if (dryRun) {
+    if (planOnly) {
       current.url = `https://${current.projectName}.pages.dev`;
       return;
     }
@@ -2755,9 +2762,9 @@ function reconcileCloudflareTarget(input, { dryRun = false } = {}) {
     current.mode = "managed";
     current.managed = true;
     const existing = findTurnstileWidget(turnstileWidgets, current, current.name);
-    if (dryRun) {
-      current.sitekey = current.sitekey ?? `dryrun-${current.name}-sitekey`;
-      current.secret = current.secret ?? `dryrun-${current.name}-secret`;
+    if (planOnly) {
+      current.sitekey = current.sitekey ?? `plan-${current.name}-sitekey`;
+      current.secret = current.secret ?? `plan-${current.name}-secret`;
       current.lastSyncedAt = nowIso();
       return;
     }
@@ -2790,7 +2797,7 @@ function reconcileCloudflareTarget(input, { dryRun = false } = {}) {
   runStep("r2", ensureR2Bucket);
   runStep("pages", ensurePagesProject);
   runStep("turnstile-widget", ensureTurnstileWidget);
-  runStep("web-cache", () => reconcileCloudflareWebCacheRules(input.context.tenantRoot, deployConfig, state, target, { dryRun, env }));
+  runStep("web-cache", () => reconcileCloudflareWebCacheRules(input.context.tenantRoot, deployConfig, state, target, { planOnly, env }));
   state.readiness.configured = true;
   state.readiness.provisioned = hasProvisionedCloudflareResources(state);
   state.readiness.deployable = state.readiness.provisioned === true;
@@ -2807,7 +2814,7 @@ function reconcileCloudflareTarget(input, { dryRun = false } = {}) {
   writeDeployState(input.context.tenantRoot, state, { target });
   return { state, summary: buildProvisioningSummary(deployConfig, state, target) };
 }
-function syncCloudflareSecretsForTarget(input, { dryRun = false } = {}) {
+function syncCloudflareSecretsForTarget(input, { planOnly = false } = {}) {
   const target = toDeployTarget(input.context.target);
   const deployConfig = input.context.deployConfig;
   const state = loadDeployState(input.context.tenantRoot, deployConfig, { target });
@@ -3818,11 +3825,11 @@ async function reconcileStaleOperationsRunnerResourcesForProject(input, {
     });
   }
 }
-async function syncRailwayEnvironmentForScope(input, { dryRun = false, serviceKeys } = {}) {
+async function syncRailwayEnvironmentForScope(input, { planOnly = false, serviceKeys } = {}) {
   const scope = input.context.target.kind === "persistent" ? input.context.target.scope : "staging";
   const sync = collectRailwayEnvironmentSync(input);
   const selectedServiceKeys = Array.isArray(serviceKeys) && serviceKeys.length > 0 ? [...new Set(serviceKeys.map((value) => String(value).trim()).filter(Boolean))] : void 0;
-  traceRailwayReconcile(input.context.env, "sync:start", `scope=${scope} dryRun=${dryRun ? "yes" : "no"}`);
+  traceRailwayReconcile(input.context.env, "sync:start", `scope=${scope} planOnly=${planOnly ? "yes" : "no"}`);
   const projectGroups = configuredRailwayProjectSyncGroups(input, scope, selectedServiceKeys);
   if (projectGroups.length === 0) {
     return {
@@ -3830,7 +3837,7 @@ async function syncRailwayEnvironmentForScope(input, { dryRun = false, serviceKe
       services: [],
       secrets: Object.keys(sync.secrets),
       variables: Object.keys(sync.variables),
-      dryRun,
+      planOnly,
       workspace: ""
     };
   }
@@ -3839,7 +3846,7 @@ async function syncRailwayEnvironmentForScope(input, { dryRun = false, serviceKe
   for (const projectServices of projectGroups) {
     const serviceKeySet = [...new Set(projectServices.map((service) => service.key))];
     const topology = await resolveRailwayTopologyForScope(input, scope, {
-      ensure: !dryRun,
+      ensure: !planOnly,
       ensureServices: false,
       serviceKeys: serviceKeySet,
       includeInstances: false,
@@ -3854,7 +3861,7 @@ async function syncRailwayEnvironmentForScope(input, { dryRun = false, serviceKe
     for (const service of projectServices) {
       railwayIacServiceInput(input, sync, service, scope);
     }
-    if (dryRun) {
+    if (planOnly) {
       syncedServices.push(...projectServices);
       continue;
     }
@@ -3983,7 +3990,7 @@ async function syncRailwayEnvironmentForScope(input, { dryRun = false, serviceKe
     services: syncedServices,
     secrets: Object.keys(sync.secrets),
     variables: Object.keys(sync.variables),
-    dryRun,
+    planOnly,
     workspace
   };
 }
@@ -4750,7 +4757,8 @@ async function observeCustomDomainUnit(input) {
     }
     case "custom-domain:api": {
       const domain = String(input.unit.spec.domain ?? "").trim();
-      const live = getCustomDomainState(input, "railway", domain) ?? await observeRailwayCustomDomainLive(input, domain) ?? input.persistedState?.lastObservedState ?? input.persistedState?.lastReconciledState ?? null;
+      const cached = getCustomDomainState(input, "railway", domain);
+      const live = (cached && railwayCustomDomainHasDnsRequirements(cached) ? cached : null) ?? await observeRailwayCustomDomainLive(input, domain) ?? cached ?? input.persistedState?.lastObservedState ?? input.persistedState?.lastReconciledState ?? null;
       if (live?.domain) {
         storeCustomDomainState(input, "railway", domain, live);
       }
@@ -4811,7 +4819,8 @@ async function verifyCustomDomainUnit(input) {
     }
     case "custom-domain:api": {
       const domain = String(input.unit.spec.domain ?? "").trim();
-      const live = getCustomDomainState(input, "railway", domain) ?? await observeRailwayCustomDomainLive(input, domain) ?? getPersistedCustomDomainState(input, "railway", domain) ?? input.persistedState?.lastObservedState ?? input.persistedState?.lastReconciledState ?? null;
+      const cached = getCustomDomainState(input, "railway", domain);
+      const live = (cached && railwayCustomDomainHasDnsRequirements(cached) ? cached : null) ?? await observeRailwayCustomDomainLive(input, domain) ?? cached ?? getPersistedCustomDomainState(input, "railway", domain) ?? input.persistedState?.lastObservedState ?? input.persistedState?.lastReconciledState ?? null;
       const dnsRecords = Array.isArray(live?.dnsRecords) ? live.dnsRecords : [];
       const certificateStatus = typeof live?.certificateStatus === "string" ? live.certificateStatus.trim().toUpperCase() : null;
       const verified = live?.verified === true;
@@ -5081,13 +5090,50 @@ async function verifyRailwayUnit(input) {
         }));
       }
       const desiredRootDirectory = service.imageRef || service.sourceMode === "image" ? null : railwayServiceRootDirectory(input.context.tenantRoot, service);
+      const normalizeRailwayRootDirectory = (value) => {
+        const trimmed = String(value ?? "").trim();
+        return trimmed || ".";
+      };
       if (desiredRootDirectory) {
+        const observedRootDirectory = normalizeRailwayRootDirectory(entry.instance?.rootDirectory);
+        const desiredNormalizedRootDirectory = normalizeRailwayRootDirectory(desiredRootDirectory);
         checks.push(verificationCheck("railway.instance.root-directory", "Railway root directory matches desired config", "api", {
           exists: Boolean(entry.instance?.id),
-          configured: entry.instance?.rootDirectory === desiredRootDirectory,
+          configured: observedRootDirectory === desiredNormalizedRootDirectory,
           expected: desiredRootDirectory,
           observed: entry.instance?.rootDirectory ?? null,
-          issues: entry.instance?.rootDirectory === desiredRootDirectory ? [] : ["Railway root directory does not match the desired value."]
+          issues: observedRootDirectory === desiredNormalizedRootDirectory ? [] : ["Railway root directory does not match the desired value."]
+        }));
+      }
+      if (service.sourceMode === "git" && entry.service?.id && entry.environment?.id) {
+        const deployment = await inspectRailwayServiceDeploymentHealth({
+          serviceId: entry.service.id,
+          environmentId: entry.environment.id,
+          env: topology.env
+        }).catch((error) => ({
+          ok: false,
+          repo: null,
+          branch: null,
+          rootDirectory: null,
+          message: error instanceof Error ? error.message : String(error)
+        }));
+        const repoMatches = service.sourceRepo ? deployment.repo === service.sourceRepo : true;
+        const branchMatches = service.sourceBranch ? deployment.branch === service.sourceBranch : true;
+        const rootMatches = desiredRootDirectory ? normalizeRailwayRootDirectory(deployment.rootDirectory) === normalizeRailwayRootDirectory(desiredRootDirectory) : true;
+        const deploymentIssues = [
+          repoMatches ? null : `Expected Railway Git deployment repo ${service.sourceRepo}, observed ${deployment.repo ?? "(unset)"}.`,
+          branchMatches ? null : `Expected Railway Git deployment branch ${service.sourceBranch}, observed ${deployment.branch ?? "(unset)"}.`,
+          rootMatches ? null : `Expected Railway deployment root ${desiredRootDirectory}, observed ${deployment.rootDirectory ?? "(unset)"}.`,
+          deployment.repo || deployment.branch ? null : "Railway latest deployment does not expose a Git repository/branch; staging may still be using a Docker image source."
+        ].filter((issue) => Boolean(issue));
+        checks.push(verificationCheck("railway.service.source-mode", "Railway staging service deploys from Git source", "api", {
+          exists: Boolean(entry.service?.id),
+          configured: deploymentIssues.length === 0,
+          ready: deploymentIssues.length === 0,
+          verified: deploymentIssues.length === 0,
+          expected: { sourceMode: "git", repo: service.sourceRepo ?? null, branch: service.sourceBranch ?? null, rootDirectory: desiredRootDirectory ?? null },
+          observed: { repo: deployment.repo, branch: deployment.branch, rootDirectory: deployment.rootDirectory, message: deployment.message ?? null },
+          issues: deploymentIssues
         }));
       }
       if (service.key === "api") {

package/dist/reconcile/contracts.d.ts

@@ -128,7 +128,7 @@ export interface TreeseedReconcileRunContext {
     target: TreeseedReconcileTarget;
     deployConfig: TreeseedDeployConfig;
     launchEnv: NodeJS.ProcessEnv;
-    dryRun?: boolean;
+    planOnly?: boolean;
     write?: (line: string) => void;
     session: Map<string, unknown>;
 }

package/dist/reconcile/engine.d.ts

@@ -30,7 +30,7 @@ export declare function planTreeseedReconciliation({ tenantRoot, target, env, sy
     state: TreeseedReconcileStateRecord;
     deployConfig: import("../platform/contracts.js").TreeseedDeployConfig;
 }>;
-export declare function reconcileTreeseedTarget({ tenantRoot, target, env, systems, selector, units, write, dryRun, session, }: {
+export declare function reconcileTreeseedTarget({ tenantRoot, target, env, systems, selector, units, write, planOnly, session, }: {
     tenantRoot: string;
     target: TreeseedReconcileTarget;
     env?: NodeJS.ProcessEnv;
@@ -38,7 +38,7 @@ export declare function reconcileTreeseedTarget({ tenantRoot, target, env, syste
     selector?: TreeseedReconcileSelector;
     units?: TreeseedDesiredUnit[];
     write?: (line: string) => void;
-    dryRun?: boolean;
+    planOnly?: boolean;
     session?: Map<string, unknown>;
 }): Promise<{
     target: TreeseedReconcileTarget;
@@ -83,11 +83,11 @@ export declare function collectTreeseedReconcileStatus({ tenantRoot, target, env
         verification: TreeseedUnitVerificationResult | null;
     }[];
 }>;
-export declare function reconcileTreeseedNestedTarget({ parentContext, selector, target, dryRun, }: {
+export declare function reconcileTreeseedNestedTarget({ parentContext, selector, target, planOnly, }: {
     parentContext: TreeseedReconcileRunContext;
     selector: TreeseedReconcileSelector;
     target: TreeseedReconcileTarget;
-    dryRun: boolean;
+    planOnly: boolean;
 }): Promise<{
     target: TreeseedReconcileTarget;
     units: TreeseedDesiredUnit[];

package/dist/reconcile/engine.js

@@ -26,14 +26,14 @@ function formatVerificationFailure(verification) {
   ].filter(Boolean);
   return details.length > 0 ? `Verification failed (${details.join(" | ")})` : "Verification failed.";
 }
-function createRunContext(tenantRoot, target, launchEnv, write, dryRun = false, session) {
+function createRunContext(tenantRoot, target, launchEnv, write, planOnly = false, session) {
   const { deployConfig } = deriveTreeseedDesiredUnits({ tenantRoot, target, env: launchEnv });
   return {
     tenantRoot,
     target,
     deployConfig,
     launchEnv,
-    dryRun,
+    planOnly,
     write,
     session: session ?? /* @__PURE__ */ new Map()
   };
@@ -278,12 +278,12 @@ async function reconcileTreeseedTarget({
   selector,
   units,
   write,
-  dryRun = false,
+  planOnly = false,
   session
 }) {
   const planned = await planTreeseedReconciliation({ tenantRoot, target, env, systems, selector, units, write });
   const registry = createTreeseedReconcileRegistry(planned.deployConfig);
-  const context = createRunContext(tenantRoot, target, env, write, dryRun, session);
+  const context = createRunContext(tenantRoot, target, env, write, planOnly, session);
   const results = [];
   const verificationMap = /* @__PURE__ */ new Map();
   const timingEntries = [];
@@ -337,7 +337,7 @@ async function reconcileTreeseedTarget({
     let result;
     try {
       const stageStartMs = performance.now();
-      if (dryRun) {
+      if (planOnly) {
         result = {
           unit: plan.unit,
           observed: plan.observed,
@@ -360,7 +360,7 @@ async function reconcileTreeseedTarget({
       unitTiming.children?.push({
         name: `${unitTiming.name}:apply`,
         durationMs: elapsedMs(stageStartMs),
-        status: dryRun ? "skipped" : "success"
+        status: planOnly ? "skipped" : "success"
       });
     } catch (error) {
       unitTiming.children?.push({
@@ -373,7 +373,7 @@ async function reconcileTreeseedTarget({
       wrapAdapterFailure("apply", plan.unit.provider, plan.unit.unitType, plan.unit.unitId, error);
     }
     let refreshedObserved = result.observed;
-    if (!dryRun) {
+    if (!planOnly) {
       try {
         const stageStartMs = performance.now();
         refreshedObserved = await Promise.resolve(adapter.refresh({
@@ -447,17 +447,17 @@ 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) {
-      if (!dryRun) {
+      if (!planOnly) {
         await persistVerifiedResult(persisted, verifiedResult);
       }
       throw new Error(`Treeseed reconcile verification failed for ${plan.unit.provider}:${plan.unit.unitType} (${plan.unit.unitId}): ${formatVerificationFailure(verification)}`);
     }
-    if (!dryRun) {
+    if (!planOnly) {
       await persistVerifiedResult(persisted, verifiedResult);
     }
     results.push(verifiedResult);
   });
-  if (!dryRun) {
+  if (!planOnly) {
     writeTreeseedReconcileState(tenantRoot, planned.state, env);
   }
   return {
@@ -579,7 +579,7 @@ async function reconcileTreeseedNestedTarget({
   parentContext,
   selector,
   target,
-  dryRun
+  planOnly
 }) {
   const previousVerificationResults = parentContext.session.get("treeseed:verification-results");
   const previousTimings = parentContext.session.get("treeseed:timings");
@@ -590,7 +590,7 @@ async function reconcileTreeseedNestedTarget({
       env: parentContext.launchEnv,
       selector,
       write: parentContext.write,
-      dryRun,
+      planOnly,
       session: parentContext.session
     });
   } finally {

package/dist/reconcile/providers/release-private.d.ts

@@ -61,7 +61,7 @@ export declare function runHostedReconcileGate(input: {
     parentContext: TreeseedReconcileRunContext;
     selector: TreeseedReconcileSelector;
     target: TreeseedReconcileTarget;
-    dryRun: boolean;
+    planOnly: boolean;
 }): Promise<{
     target: TreeseedReconcileTarget;
     units: import("../contracts.js").TreeseedDesiredUnit[];

package/dist/scripts/tenant-deploy.js

@@ -21,7 +21,7 @@ function writeDeployReport(payload) {
 }
 function parseArgs(argv) {
     const parsed = {
-        dryRun: false,
+        planOnly: false,
         only: null,
         name: null,
         environment: null,
@@ -32,8 +32,8 @@ function parseArgs(argv) {
         const current = rest.shift();
         if (!current)
             continue;
-        if (current === '--dry-run') {
-            parsed.dryRun = true;
+        if (current === '--plan') {
+            parsed.planOnly = true;
             continue;
         }
         if (current === '--only') {
@@ -166,8 +166,8 @@ async function main() {
     }
     if (scope === 'local') {
         runTenantDeployPreflight({ cwd: tenantRoot, scope: 'local' });
-        await runTenantWebBuild({ tenantRoot, scope: 'local', dryRun: options.dryRun, env: process.env });
-        writeDeployReport({ ok: true, kind: 'success', scope, dryRun: options.dryRun, target: deployTargetLabel(target) });
+        await runTenantWebBuild({ tenantRoot, scope: 'local', planOnly: options.planOnly, env: process.env });
+        writeDeployReport({ ok: true, kind: 'success', scope, planOnly: options.planOnly, target: deployTargetLabel(target) });
         console.log('Treeseed local deploy completed as a build-only publish target.');
         return;
     }
@@ -177,7 +177,7 @@ async function main() {
             tenantRoot,
             scope,
             target,
-            dryRun: options.dryRun,
+            planOnly: options.planOnly,
             env: process.env,
         });
     }
@@ -192,21 +192,21 @@ async function main() {
     }
     if (shouldRun('migrate')) {
         const result = await runTenantDataMigration(context);
-        console.log(`${options.dryRun ? 'Planned' : 'Applied'} remote migrations for ${result.databaseName}.`);
+        console.log(`${options.planOnly ? 'Planned' : 'Applied'} remote migrations for ${result.databaseName}.`);
     }
     if (shouldRun('build')) {
         await runTenantWebBuild(context);
     }
     if (shouldRun('publish')) {
         await runTenantWebPublish(context);
-        if (!options.dryRun) {
+        if (!options.planOnly) {
             finalizeDeploymentState(tenantRoot, { target });
         }
     }
     writeDeployReport({
         ok: true,
         kind: 'success',
-        dryRun: options.dryRun,
+        planOnly: options.planOnly,
         only: options.only,
         target: deployTargetLabel(target),
     });

package/dist/scripts/tenant-destroy.js

@@ -7,7 +7,7 @@ import { deriveCloudflareWorkerName } from '../platform/deploy-config.js';
 const tenantRoot = process.cwd();
 function parseArgs(argv) {
     const parsed = {
-        dryRun: false,
+        planOnly: false,
         force: false,
         skipConfirmation: false,
         confirm: null,
@@ -20,8 +20,8 @@ function parseArgs(argv) {
         const current = rest.shift();
         if (!current)
             continue;
-        if (current === '--dry-run') {
-            parsed.dryRun = true;
+        if (current === '--plan') {
+            parsed.planOnly = true;
             continue;
         }
         if (current === '--force') {
@@ -86,7 +86,7 @@ const scope = options.environment ?? 'prod';
 const target = createPersistentDeployTarget(scope);
 applyTreeseedEnvironmentToProcess({ tenantRoot, scope, override: true });
 assertTreeseedCommandEnvironment({ tenantRoot, scope, purpose: 'destroy' });
-const deployConfig = validateDestroyPrerequisites(tenantRoot, { requireRemote: !options.dryRun });
+const deployConfig = validateDestroyPrerequisites(tenantRoot, { requireRemote: !options.planOnly });
 const state = loadDeployState(tenantRoot, deployConfig, { target });
 const expectedConfirmation = getExpectedConfirmation(deployConfig);
 if (!options.skipConfirmation) {
@@ -98,14 +98,14 @@ if (!options.skipConfirmation) {
     }
 }
 const result = await destroyTreeseedEnvironmentResources(tenantRoot, {
-    dryRun: options.dryRun,
+    planOnly: options.planOnly,
     force: options.force,
     deleteData: options.deleteData,
     target,
 });
 printDestroySummary(result);
-if (options.dryRun) {
-    console.log('Dry run: no remote resources were deleted.');
+if (options.planOnly) {
+    console.log('Plan: no remote resources were deleted.');
     process.exit(0);
 }
 cleanupDestroyedState(tenantRoot, { target, removeBuildArtifacts: options.removeBuildArtifacts });

package/dist/scripts/tenant-workflow-action.js

@@ -10,7 +10,7 @@ function parseArgs(argv) {
         environment: null,
         projectId: null,
         previewId: null,
-        dryRun: false,
+        planOnly: false,
     };
     const rest = [...argv];
     while (rest.length) {
@@ -49,8 +49,8 @@ function parseArgs(argv) {
             parsed.previewId = current.split('=', 2)[1] ?? null;
             continue;
         }
-        if (current === '--dry-run') {
-            parsed.dryRun = true;
+        if (current === '--plan') {
+            parsed.planOnly = true;
             continue;
         }
         throw new Error(`Unknown workflow action argument: ${current}`);
@@ -78,7 +78,7 @@ async function main() {
         scope,
         projectId: options.projectId ?? process.env.TREESEED_PROJECT_ID ?? null,
         previewId: options.previewId,
-        dryRun: options.dryRun,
+        planOnly: options.planOnly,
         write: (line) => writeStatus(line),
     });
     if (result !== undefined) {

package/dist/scripts/test-scaffold.js

@@ -233,8 +233,8 @@ function runScaffoldChecks(siteRoot) {
         });
     }
     if (scaffoldChecks.has('deploy')) {
-        withTiming('scaffold deploy dry-run', () => {
-            runStep('npm', ['run', 'deploy', '--', '--dry-run'], { cwd: siteRoot });
+        withTiming('scaffold deploy plan', () => {
+            runStep('npm', ['run', 'deploy', '--', '--plan'], { cwd: siteRoot });
         });
     }
 }

package/dist/scripts/workspace-command-e2e.js

@@ -491,15 +491,15 @@ async function runLocalSuite() {
                 env: cacheEnv(),
             });
         });
-        await withStep('scaffold tenant deploy dry-run', async () => {
-            return runCommand('scaffold-deploy-dry-run', process.execPath, [packageScriptPath('treeseed'), 'deploy', '--dry-run'], {
+        await withStep('scaffold tenant deploy plan', async () => {
+            return runCommand('scaffold-deploy-plan', process.execPath, [packageScriptPath('treeseed'), 'deploy', '--plan'], {
                 cwd: siteRoot,
                 env: cacheEnv(),
             });
         });
-        await withStep('scaffold tenant destroy dry-run', async () => {
+        await withStep('scaffold tenant destroy plan', async () => {
             const deployConfig = readTenantConfig(siteRoot);
-            return runCommand('scaffold-destroy-dry-run', process.execPath, [packageScriptPath('treeseed'), 'destroy', '--dry-run', '--skip-confirmation', '--confirm', String(deployConfig.slug)], {
+            return runCommand('scaffold-destroy-plan', process.execPath, [packageScriptPath('treeseed'), 'destroy', '--plan', '--skip-confirmation', '--confirm', String(deployConfig.slug)], {
                 cwd: siteRoot,
                 env: cacheEnv(),
             });