@treeseed/sdk 0.8.3 → 0.8.4

package/dist/operations/services/project-platform.js

@@ -44,6 +44,8 @@ import { CloudflareQueuePullClient, CloudflareQueuePushClient } from "../../remo
 import { runPrefixedCommand, runTreeseedBootstrapDag, sleep, writeTreeseedBootstrapLine } from "./bootstrap-runner.js";
 import { runTenantDeployPreflight } from "./save-deploy-preflight.js";
 const PROJECT_PLATFORM_BOOTSTRAP_SYSTEMS = ["data", "web", "api", "agents"];
+const WEB_PLATFORM_BOOTSTRAP_SYSTEMS = ["data", "web"];
+const PROCESSING_PLATFORM_BOOTSTRAP_SYSTEMS = ["api", "agents"];
 function stableHash(value) {
   return createHash("sha256").update(value).digest("hex");
 }
@@ -448,24 +450,39 @@ function stableArtifactAliasKey(teamId, artifact) {
   const fileName = typeof artifact.metadata?.fileName === "string" && artifact.metadata.fileName ? artifact.metadata.fileName : `${artifact.itemId}${extname(artifact.content.objectKey) || ".bin"}`;
   return `teams/${teamId}/published/artifacts/${artifact.kind}/${artifact.itemId}/${fileName}`;
 }
-async function probeHttp(url) {
-  try {
-    const response = await fetch(url, {
-      headers: { accept: "application/json,text/html;q=0.9,*/*;q=0.8" }
-    });
-    return {
-      ok: response.ok,
-      status: response.status,
-      url
-    };
-  } catch (error) {
-    return {
-      ok: false,
-      status: null,
-      url,
-      error: error instanceof Error ? error.message : String(error)
-    };
+async function probeHttp(url, { attempts = 1, delayMs = 2e3 } = {}) {
+  let result = {
+    ok: false,
+    status: null,
+    url
+  };
+  const maxAttempts = Math.max(1, Math.floor(attempts));
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const response = await fetch(url, {
+        headers: { accept: "application/json,text/html;q=0.9,*/*;q=0.8" }
+      });
+      result = {
+        ok: response.ok,
+        status: response.status,
+        url,
+        attempts: attempt
+      };
+    } catch (error) {
+      result = {
+        ok: false,
+        status: null,
+        url,
+        error: error instanceof Error ? error.message : String(error),
+        attempts: attempt
+      };
+    }
+    if (result.ok || attempt >= maxAttempts) {
+      return result;
+    }
+    await sleep(delayMs);
   }
+  return result;
 }
 function queueClientConfig(siteConfig, state) {
   const accountId = String(process.env.CLOUDFLARE_ACCOUNT_ID ?? siteConfig.cloudflare.accountId ?? "").trim();
@@ -1219,29 +1236,29 @@ async function monitorProjectPlatform(options) {
   const state = loadDeployState(options.tenantRoot, siteConfig, { target });
   const webProbeUrl = resolveImmediatePagesProbeUrl(siteConfig, state, target);
   const apiBaseUrl = resolveImmediateApiProbeUrl(siteConfig, state, target);
+  const railwayResources = options.scope === "local" || !apiSelected && !agentsSelected ? { ok: true, skipped: true, reason: options.scope === "local" ? "local_scope" : "railway_not_selected" } : await verifyRailwayManagedResources(options.tenantRoot, options.scope, {
+    env,
+    settleDeployments: true,
+    onProgress: options.write
+  });
   const skippedApiCheck = apiSelected ? { ok: false, skipped: true, reason: "api_url_unconfigured" } : { ok: true, skipped: true, reason: "api_not_selected" };
   const skippedAgentCheck = agentsSelected ? { ok: false, skipped: true, reason: "api_url_unconfigured" } : { ok: true, skipped: true, reason: "agents_not_selected" };
   const checks = {
-    pages: await probeHttp(webProbeUrl),
-    apiHealth: apiSelected && apiBaseUrl ? await probeHttp(`${String(apiBaseUrl).replace(/\/+$/u, "")}/healthz`) : skippedApiCheck,
-    apiReady: apiSelected && apiBaseUrl ? await probeHttp(`${String(apiBaseUrl).replace(/\/+$/u, "")}/readyz`) : skippedApiCheck,
-    d1Health: apiSelected && apiBaseUrl ? await probeHttp(`${String(apiBaseUrl).replace(/\/+$/u, "")}/healthz/deep`) : skippedApiCheck,
-    agentHealth: agentsSelected && apiBaseUrl ? await probeHttp(`${String(apiBaseUrl).replace(/\/+$/u, "")}/internal/core/agent/healthz`) : skippedAgentCheck,
+    pages: await probeHttp(webProbeUrl, { attempts: 3, delayMs: 5e3 }),
+    apiHealth: apiSelected && apiBaseUrl ? await probeHttp(`${String(apiBaseUrl).replace(/\/+$/u, "")}/healthz`, { attempts: 8, delayMs: 1e4 }) : skippedApiCheck,
+    apiReady: apiSelected && apiBaseUrl ? await probeHttp(`${String(apiBaseUrl).replace(/\/+$/u, "")}/readyz`, { attempts: 8, delayMs: 1e4 }) : skippedApiCheck,
+    d1Health: apiSelected && apiBaseUrl ? await probeHttp(`${String(apiBaseUrl).replace(/\/+$/u, "")}/healthz/deep`, { attempts: 8, delayMs: 1e4 }) : skippedApiCheck,
+    agentHealth: agentsSelected && apiBaseUrl ? await probeHttp(`${String(apiBaseUrl).replace(/\/+$/u, "")}/internal/core/agent/healthz`, { attempts: 8, delayMs: 1e4 }) : skippedAgentCheck,
     r2: options.dryRun ? { ok: true, skipped: true, reason: "dry_run" } : probeR2(options.tenantRoot, siteConfig, state, target),
     queue: options.dryRun ? Promise.resolve({ ok: true, skipped: true, reason: "dry_run" }) : probeQueue(siteConfig, state),
     scaleProbe: probeScaleConfiguration(siteConfig, state),
-    railwayResources: options.scope === "local" || !apiSelected && !agentsSelected ? Promise.resolve({ ok: true, skipped: true, reason: options.scope === "local" ? "local_scope" : "railway_not_selected" }) : verifyRailwayManagedResources(options.tenantRoot, options.scope, {
-      env,
-      settleDeployments: true,
-      onProgress: options.write
-    }),
+    railwayResources,
     readiness: state.readiness
   };
   const resolvedChecks = {
     ...checks,
     r2: await checks.r2,
-    queue: await checks.queue,
-    railwayResources: await checks.railwayResources
+    queue: await checks.queue
   };
   const ok = [
     resolvedChecks.pages,
@@ -1299,14 +1316,26 @@ async function syncControlPlaneState(options) {
   });
 }
 async function runProjectPlatformAction(action, options) {
+  const previousWorkflowAction = process.env.TREESEED_WORKFLOW_ACTION;
+  const previousWorkflowPlane = process.env.TREESEED_WORKFLOW_PLANE;
+  process.env.TREESEED_WORKFLOW_ACTION = action;
+  process.env.TREESEED_WORKFLOW_PLANE = previousWorkflowPlane ?? (action === "deploy_processing" ? "processing" : "web");
   applyTreeseedEnvironmentToProcess({ tenantRoot: options.tenantRoot, scope: options.scope, override: true });
   const reporter = resolveReporter(options.tenantRoot, options.reporter);
   try {
     switch (action) {
-      case "provision":
-        return await provisionProjectPlatform({ ...options, reporter });
-      case "deploy_code":
-        return await deployProjectPlatform({ ...options, reporter });
+      case "deploy_web":
+        return await deployProjectPlatform({
+          ...options,
+          reporter,
+          bootstrapSystems: options.bootstrapSystems ?? WEB_PLATFORM_BOOTSTRAP_SYSTEMS
+        });
+      case "deploy_processing":
+        return await deployProjectPlatform({
+          ...options,
+          reporter,
+          bootstrapSystems: options.bootstrapSystems ?? PROCESSING_PLATFORM_BOOTSTRAP_SYSTEMS
+        });
       case "publish_content":
         return await publishProjectContent({ ...options, reporter });
       case "monitor":
@@ -1317,7 +1346,7 @@ async function runProjectPlatformAction(action, options) {
   } catch (error) {
     await reportDeployment(reporter, {
       environment: options.scope,
-      deploymentKind: action === "provision" ? "provision" : action === "publish_content" ? "content" : action === "deploy_code" ? "code" : "mixed",
+      deploymentKind: action === "publish_content" ? "content" : action === "deploy_web" || action === "deploy_processing" ? "code" : "mixed",
       status: "failed",
       sourceRef: currentRef(options.tenantRoot),
       commitSha: currentCommit(options.tenantRoot),
@@ -1328,6 +1357,17 @@ async function runProjectPlatformAction(action, options) {
       finishedAt: (/* @__PURE__ */ new Date()).toISOString()
     }).catch(() => void 0);
     throw error;
+  } finally {
+    if (previousWorkflowAction === void 0) {
+      delete process.env.TREESEED_WORKFLOW_ACTION;
+    } else {
+      process.env.TREESEED_WORKFLOW_ACTION = previousWorkflowAction;
+    }
+    if (previousWorkflowPlane === void 0) {
+      delete process.env.TREESEED_WORKFLOW_PLANE;
+    } else {
+      process.env.TREESEED_WORKFLOW_PLANE = previousWorkflowPlane;
+    }
   }
 }
 export {

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

@@ -8,6 +8,9 @@ export declare function resolveRailwayAuthToken(env?: NodeJS.ProcessEnv): string
 export declare function buildRailwayCommandEnv(env?: NodeJS.ProcessEnv): {
     [key: string]: string | undefined;
 };
+export declare function buildRailwayDeployCommandEnv(env?: NodeJS.ProcessEnv): {
+    [key: string]: string | undefined;
+};
 export declare function isRailwayTransientFailure(result: any): boolean;
 export declare function runRailway(args: any, { cwd, capture, allowFailure, input, env }?: {
     capture?: boolean | undefined;
@@ -329,11 +332,31 @@ export declare function verifyRailwayManagedResources(tenantRoot: any, scope: an
     ok: boolean;
     checks: any[];
 }>;
-export declare function planRailwayServiceDeploy(service: any, { env }?: {
+export declare function shouldRunRailwayPredeployBuild(env?: NodeJS.ProcessEnv): boolean;
+export declare function planRailwayServiceDeploy(service: any, { env, projectTokenMode }?: {
+    env?: NodeJS.ProcessEnv | undefined;
+    projectTokenMode?: boolean | undefined;
+}): {
+    command: string;
+    args: string[];
+    cwd: any;
+};
+export declare function buildRailwayLinkCommandEnv(env?: NodeJS.ProcessEnv, service?: {}): any;
+export declare function writeRailwayCliProjectConfig(service: any, { env, cwd }?: {
+    env?: NodeJS.ProcessEnv | undefined;
+    cwd?: any;
+}): {
+    configPath: string;
+    projectPath: string;
+    projectId: string;
+    environmentId: string;
+    serviceId: string;
+} | null;
+export declare function planRailwayServiceLink(service: any, { env }?: {
     env?: NodeJS.ProcessEnv | undefined;
 }): {
     command: string;
-    args: any[];
+    args: string[];
     cwd: any;
 };
 export declare function deployRailwayService(tenantRoot: any, service: any, { dryRun, write, prefix, env, }?: {

package/dist/operations/services/railway-deploy.js

@@ -1,5 +1,5 @@
-import { existsSync } from "node:fs";
-import { relative, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { loadCliDeployConfig } from "./runtime-tools.js";
 import { createPersistentDeployTarget, resolveTreeseedResourceIdentity } from "./deploy.js";
@@ -221,10 +221,19 @@ function resolveRailwayAuthToken(env = process.env) {
 function buildRailwayCommandEnv(env = process.env) {
   const merged = { ...env };
   const token = resolveRailwayAuthToken(merged);
+  const projectToken = configuredEnvValue(merged, "RAILWAY_TOKEN");
   if (token) {
     merged.RAILWAY_API_TOKEN = token;
   } else {
-    delete merged.RAILWAY_API_TOKEN;
+    merged.RAILWAY_API_TOKEN = void 0;
+  }
+  merged.RAILWAY_TOKEN = projectToken || void 0;
+  return merged;
+}
+function buildRailwayDeployCommandEnv(env = process.env) {
+  const merged = buildRailwayCommandEnv(env);
+  if (shouldAttachRailwayDeployLogs(merged)) {
+    merged.CI = "true";
   }
   return merged;
 }
@@ -306,7 +315,11 @@ function isRailwayAlreadyExistsMessage(result) {
   return /already exists|already taken|duplicate|has already been taken/iu.test(railwayMessage(result));
 }
 function isRailwayTransientFailure(result) {
-  return /timed out|failed to fetch|temporarily unavailable|econnreset|etimedout|failed to stream build logs|failed to retrieve build log/iu.test(railwayMessage(result));
+  const message = railwayMessage(result);
+  if (!message.trim() && result?.status === 1) {
+    return true;
+  }
+  return /timed out|failed to fetch|temporarily unavailable|econnreset|etimedout|failed to stream build logs|failed to retrieve build log/iu.test(message);
 }
 function sleepSync(milliseconds) {
   if (!Number.isFinite(milliseconds) || milliseconds <= 0) {
@@ -1165,28 +1178,249 @@ async function verifyRailwayManagedResources(tenantRoot, scope, {
   };
 }
 function shouldAttachRailwayDeployLogs(env = process.env) {
-  return configuredEnvValue(env, "TREESEED_RAILWAY_DEPLOY_ATTACH_LOGS") === "1";
-}
-function planRailwayServiceDeploy(service, { env = process.env } = {}) {
-  const args = [
-    "up",
-    "--service",
-    service.serviceName ?? service.serviceId,
-    shouldAttachRailwayDeployLogs(env) ? "--ci" : "--detach"
-  ];
+  const configured = configuredEnvValue(env, "TREESEED_RAILWAY_DEPLOY_ATTACH_LOGS");
+  if (configured === "1" || configured === "true") {
+    return true;
+  }
+  if (configured === "0" || configured === "false") {
+    return false;
+  }
+  return false;
+}
+function shouldUseVerboseRailwayDeploy(env = process.env) {
+  const configured = configuredEnvValue(env, "TREESEED_RAILWAY_DEPLOY_VERBOSE");
+  if (configured === "1" || configured === "true") {
+    return true;
+  }
+  if (configured === "0" || configured === "false") {
+    return false;
+  }
+  return shouldAttachRailwayDeployLogs(env);
+}
+function shouldIncludeRailwayIgnoredFiles(env = process.env) {
+  const configured = configuredEnvValue(env, "TREESEED_RAILWAY_DEPLOY_INCLUDE_IGNORED");
+  return configured === "1" || configured === "true";
+}
+function shouldRunRailwayPredeployBuild(env = process.env) {
+  const configured = configuredEnvValue(env, "TREESEED_RAILWAY_PREDEPLOY_BUILD");
+  if (configured === "1" || configured === "true") {
+    return true;
+  }
+  if (configured === "0" || configured === "false") {
+    return false;
+  }
+  return configuredEnvValue(env, "CI") !== "true";
+}
+function planRailwayServiceDeploy(service, { env = process.env, projectTokenMode = false } = {}) {
+  const serviceSelector = service.serviceName ?? service.serviceId;
+  const args = ["up"];
+  if (serviceSelector) {
+    args.push("--service", serviceSelector);
+  }
+  if (shouldIncludeRailwayIgnoredFiles(env)) {
+    args.push("--no-gitignore");
+  }
+  args.push(shouldAttachRailwayDeployLogs(env) ? "--ci" : "--detach");
+  if (shouldUseVerboseRailwayDeploy(env)) {
+    args.push("--verbose");
+  }
+  if (!projectTokenMode && service.projectId) {
+    args.push("--project", service.projectId);
+  }
+  const environmentName = normalizeRailwayEnvironmentName(service.railwayEnvironment);
+  if (!projectTokenMode && environmentName) {
+    args.push("--environment", environmentName);
+  }
+  return {
+    command: "railway",
+    args,
+    cwd: service.rootDir
+  };
+}
+function planRailwayProjectEnvironmentLink(service) {
+  const args = ["link"];
+  if (service.projectId) {
+    args.push("--project", service.projectId);
+  }
+  const environmentName = normalizeRailwayEnvironmentName(service.railwayEnvironment);
+  if (environmentName) {
+    args.push("--environment", environmentName);
+  }
+  args.push("--json");
+  return {
+    command: "railway",
+    args,
+    cwd: service.rootDir
+  };
+}
+function buildRailwayCliContextEnv(env, service) {
+  return {
+    ...env,
+    RAILWAY_PROJECT_ID: configuredEnvValue(service, "projectId") || configuredEnvValue(env, "RAILWAY_PROJECT_ID") || void 0,
+    RAILWAY_ENVIRONMENT_ID: configuredEnvValue(service, "environmentId") || configuredEnvValue(env, "RAILWAY_ENVIRONMENT_ID") || void 0,
+    RAILWAY_SERVICE_ID: configuredEnvValue(service, "serviceId") || configuredEnvValue(env, "RAILWAY_SERVICE_ID") || void 0
+  };
+}
+function buildRailwayLinkCommandEnv(env = process.env, service = {}) {
+  return buildRailwayCliContextEnv({
+    ...buildRailwayDeployCommandEnv({ ...env, RAILWAY_TOKEN: void 0 }),
+    RAILWAY_TOKEN: void 0
+  }, service);
+}
+function railwayCliConfigPath(env = process.env) {
+  const railwayHome = configuredEnvValue(env, "RAILWAY_HOME");
+  if (railwayHome) {
+    return resolve(railwayHome, "config.json");
+  }
+  const home = configuredEnvValue(env, "HOME");
+  if (!home) {
+    return "";
+  }
+  return resolve(home, ".railway", "config.json");
+}
+function readRailwayCliConfig(configPath) {
+  if (!configPath || !existsSync(configPath)) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function writeRailwayCliProjectConfig(service, { env = process.env, cwd = service.rootDir } = {}) {
+  const projectId = configuredEnvValue(service, "projectId");
+  const environmentId = configuredEnvValue(service, "environmentId");
+  const serviceId = configuredEnvValue(service, "serviceId");
+  const projectPath = cwd ? resolve(cwd) : "";
+  const configPath = railwayCliConfigPath(env);
+  if (!configPath || !projectPath || !projectId || !environmentId || !serviceId) {
+    return null;
+  }
+  const existing = readRailwayCliConfig(configPath);
+  const projects = existing.projects && typeof existing.projects === "object" ? existing.projects : {};
+  const next = {
+    ...existing,
+    projects: {
+      ...projects,
+      [projectPath]: {
+        projectPath,
+        name: configuredEnvValue(service, "projectName") || configuredEnvValue(service, "serviceName") || projectId,
+        project: projectId,
+        environment: environmentId,
+        environmentName: normalizeRailwayEnvironmentName(service.railwayEnvironment) || configuredEnvValue(service, "environmentName") || environmentId,
+        service: serviceId
+      }
+    },
+    user: existing.user && typeof existing.user === "object" ? existing.user : {
+      token: null,
+      accessToken: null,
+      refreshToken: null,
+      tokenExpiresAt: null
+    },
+    linkedFunctions: existing.linkedFunctions ?? null
+  };
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, `${JSON.stringify(next, null, 2)}
+`, "utf8");
+  return {
+    configPath,
+    projectPath,
+    projectId,
+    environmentId,
+    serviceId
+  };
+}
+function planRailwayServiceLink(service, { env = process.env } = {}) {
+  const args = ["link"];
   if (service.projectId) {
     args.push("--project", service.projectId);
   }
+  const workspace = resolveRailwayWorkspace(env);
+  if (workspace) {
+    args.push("--workspace", workspace);
+  }
   const environmentName = normalizeRailwayEnvironmentName(service.railwayEnvironment);
   if (environmentName) {
     args.push("--environment", environmentName);
   }
+  const serviceSelector = service.serviceName ?? service.serviceId;
+  if (serviceSelector) {
+    args.push("--service", serviceSelector);
+  }
+  args.push("--json");
   return {
     command: "railway",
     args,
     cwd: service.rootDir
   };
 }
+function railwayProjectTokenName(service) {
+  const environment = normalizeRailwayEnvironmentName(service.railwayEnvironment) || "environment";
+  const serviceName = String(service.serviceName ?? service.serviceId ?? service.key ?? "service").toLowerCase().replace(/[^a-z0-9-]+/gu, "-").replace(/^-+|-+$/gu, "").slice(0, 48) || "service";
+  return `treeseed-ci-${environment}-${serviceName}`;
+}
+async function createRailwayCliProjectToken(service, { env = process.env } = {}) {
+  const projectId = configuredEnvValue(service, "projectId");
+  const environmentId = configuredEnvValue(service, "environmentId");
+  if (!projectId || !environmentId) {
+    return "";
+  }
+  const name = railwayProjectTokenName(service);
+  try {
+    const existingPayload = await railwayGraphqlRequest({
+      query: `
+query TreeseedProjectTokens($projectId: String!) {
+	projectTokens(projectId: $projectId, first: 100) {
+		edges {
+			node {
+				id
+				name
+				projectId
+				environmentId
+			}
+		}
+	}
+}
+`.trim(),
+      variables: { projectId },
+      env
+    });
+    const existingTokens = railwayEdgeNodes(existingPayload.data?.projectTokens);
+    for (const token2 of existingTokens) {
+      if (token2?.name === name && token2?.projectId === projectId && token2?.environmentId === environmentId && token2?.id) {
+        await railwayGraphqlRequest({
+          query: `
+mutation TreeseedProjectTokenDelete($id: String!) {
+	projectTokenDelete(id: $id)
+}
+`.trim(),
+          variables: { id: token2.id },
+          env
+        });
+      }
+    }
+  } catch {
+  }
+  const payload = await railwayGraphqlRequest({
+    query: `
+mutation TreeseedProjectTokenCreate($input: ProjectTokenCreateInput!) {
+	projectTokenCreate(input: $input)
+}
+`.trim(),
+    variables: {
+      input: {
+        projectId,
+        environmentId,
+        name
+      }
+    },
+    env
+  });
+  const token = payload.data?.projectTokenCreate;
+  return typeof token === "string" && token.trim() ? token.trim() : "";
+}
 async function resolveRailwayDeployProjectContext(service, { env = process.env } = {}) {
   if (service.projectId) {
     return service;
@@ -1302,6 +1536,12 @@ async function syncRailwayServiceRuntimeConfigurationAfterDeploy(tenantRoot, ser
     });
   }
   return {
+    projectId: project.id,
+    projectName: project.name ?? service.projectName ?? null,
+    environmentId: environment.id,
+    environmentName: environment.name ?? environmentName,
+    serviceId: railwayService.id,
+    serviceName: railwayService.name ?? service.serviceName ?? null,
     instance: runtimeConfiguration?.instance ?? null,
     updated: Boolean(runtimeConfiguration?.updated || volumeConfiguration?.updated || volumeConfiguration?.created),
     volume: volumeConfiguration ? {
@@ -1408,8 +1648,12 @@ async function deployRailwayService(tenantRoot, service, {
     };
   }
   const deployService = await resolveRailwayDeployProjectContext(service, { env });
-  const plan = planRailwayServiceDeploy(deployService, { env });
   const commandEnv = buildRailwayCommandEnv({ ...process.env, ...env });
+  let railwayDeployEnv = buildRailwayDeployCommandEnv(commandEnv);
+  const railway = resolveTreeseedToolCommand("railway", { env: commandEnv });
+  if (!railway) {
+    throw new Error("Railway CLI is unavailable.");
+  }
   const taskPrefix = prefix ?? {
     scope: normalizeScope(deployService.scope ?? deployService.railwayEnvironment ?? "railway"),
     system: deployService.key === "api" ? "api" : "agents",
@@ -1419,7 +1663,33 @@ async function deployRailwayService(tenantRoot, service, {
   const runtimeConfiguration = await syncRailwayServiceRuntimeConfigurationAfterDeploy(tenantRoot, deployService, {
     env: commandEnv
   });
-  if (deployService.buildCommand) {
+  const cliDeployService = {
+    ...deployService,
+    projectId: runtimeConfiguration?.projectId ?? deployService.projectId,
+    projectName: runtimeConfiguration?.projectName ?? deployService.projectName,
+    environmentId: runtimeConfiguration?.environmentId ?? deployService.environmentId,
+    serviceId: runtimeConfiguration?.serviceId ?? deployService.serviceId,
+    serviceName: runtimeConfiguration?.serviceName ?? deployService.serviceName,
+    railwayEnvironment: runtimeConfiguration?.environmentName ?? runtimeConfiguration?.environmentId ?? deployService.railwayEnvironment
+  };
+  railwayDeployEnv = buildRailwayCliContextEnv(railwayDeployEnv, cliDeployService);
+  const hasCommandApiToken = Boolean(configuredEnvValue(commandEnv, "RAILWAY_API_TOKEN"));
+  let usesProjectToken = Boolean(configuredEnvValue(railwayDeployEnv, "RAILWAY_TOKEN"));
+  if (usesProjectToken) {
+    railwayDeployEnv = { ...railwayDeployEnv, RAILWAY_API_TOKEN: void 0 };
+  }
+  if (!usesProjectToken && !hasCommandApiToken) {
+    const projectToken = await createRailwayCliProjectToken(cliDeployService, { env: commandEnv });
+    if (projectToken) {
+      railwayDeployEnv = buildRailwayCliContextEnv({ ...railwayDeployEnv, RAILWAY_API_TOKEN: void 0, RAILWAY_TOKEN: projectToken }, cliDeployService);
+      usesProjectToken = true;
+    } else if (configuredEnvValue(commandEnv, "CI") === "true") {
+      throw new Error(`Railway CI deploy requires a project token for ${cliDeployService.serviceName ?? cliDeployService.key}. Automatic project token creation did not return a token.`);
+    }
+  }
+  const linkPlan = planRailwayServiceLink(cliDeployService, { env: commandEnv });
+  const plan = planRailwayServiceDeploy(cliDeployService, { env, projectTokenMode: usesProjectToken });
+  if (deployService.buildCommand && shouldRunRailwayPredeployBuild(commandEnv)) {
     const buildResult = await runPrefixedCommand("bash", ["-lc", deployService.buildCommand], {
       cwd: deployService.rootDir,
       env: commandEnv,
@@ -1430,11 +1700,28 @@ async function deployRailwayService(tenantRoot, service, {
       throw new Error(`Railway ${deployService.key} build command failed.`);
     }
   }
+  const hasRailwayApiToken = Boolean(configuredEnvValue(commandEnv, "RAILWAY_API_TOKEN"));
+  const cliConfig = configuredEnvValue(commandEnv, "CI") === "true" ? writeRailwayCliProjectConfig(cliDeployService, { env: railwayDeployEnv, cwd: plan.cwd }) : null;
+  const effectiveLinkPlan = hasRailwayApiToken ? linkPlan : usesProjectToken ? planRailwayProjectEnvironmentLink(cliDeployService) : linkPlan;
+  const railwayLinkEnv = hasRailwayApiToken ? buildRailwayLinkCommandEnv(commandEnv, cliDeployService) : railwayDeployEnv;
+  if (cliConfig) {
+    write ? write(`[${taskPrefix.scope}][${taskPrefix.system}][${taskPrefix.task}][link] Wrote Railway CLI project context for ${cliConfig.projectPath}.`, "stdout") : null;
+  } else {
+    const linkResult = await runPrefixedCommand(railway.command, [...railway.argsPrefix, ...effectiveLinkPlan.args], {
+      cwd: effectiveLinkPlan.cwd,
+      env: railwayLinkEnv,
+      write,
+      prefix: { ...taskPrefix, stage: "link" }
+    });
+    if (linkResult.status !== 0) {
+      throw new Error(linkResult.stderr?.trim() || linkResult.stdout?.trim() || `railway ${effectiveLinkPlan.args.join(" ")} failed with exit code ${linkResult.status ?? "unknown"} in ${effectiveLinkPlan.cwd}`);
+    }
+  }
   let lastFailure = null;
   for (let attempt = 1; attempt <= 5; attempt += 1) {
-    const result = await runPrefixedCommand(plan.command, plan.args, {
-      cwd: service.rootDir,
-      env: commandEnv,
+    const result = await runPrefixedCommand(railway.command, [...railway.argsPrefix, ...plan.args], {
+      cwd: plan.cwd,
+      env: railwayDeployEnv,
       write,
       prefix: taskPrefix
     });
@@ -1444,7 +1731,7 @@ async function deployRailwayService(tenantRoot, service, {
     }
     lastFailure = result;
     if (!isRailwayTransientFailure(result) || attempt === 5) {
-      throw new Error(result.stderr?.trim() || result.stdout?.trim() || `railway ${plan.args.join(" ")} failed`);
+      throw new Error(result.stderr?.trim() || result.stdout?.trim() || `railway ${plan.args.join(" ")} failed with exit code ${result.status ?? "unknown"} in ${plan.cwd}`);
     }
     const backoffMs = 5e3 * attempt;
     const warning = `Railway deploy for ${deployService.serviceName ?? deployService.serviceId ?? deployService.key} hit a transient failure; retrying in ${Math.round(backoffMs / 1e3)}s...`;
@@ -1471,6 +1758,8 @@ async function deployRailwayService(tenantRoot, service, {
 }
 export {
   buildRailwayCommandEnv,
+  buildRailwayDeployCommandEnv,
+  buildRailwayLinkCommandEnv,
   collectRailwayDeploymentStatusChecks,
   configuredRailwayScheduledJobs,
   configuredRailwayServices,
@@ -1485,14 +1774,17 @@ export {
   isRailwayTransientFailure,
   isUsableRailwayToken,
   planRailwayServiceDeploy,
+  planRailwayServiceLink,
   railwayServiceRuntimeStartCommand,
   resolveRailwayAuthToken,
   resolveRailwayDeploymentProfile,
   runRailway,
   setRailwaySecretVariable,
+  shouldRunRailwayPredeployBuild,
   validateRailwayDeployPrerequisites,
   validateRailwayServiceConfiguration,
   verifyRailwayManagedResources,
   verifyRailwayScheduledJobs,
-  waitForRailwayManagedDeploymentsSettled
+  waitForRailwayManagedDeploymentsSettled,
+  writeRailwayCliProjectConfig
 };

package/dist/operations/services/repository-save-orchestrator.d.ts

@@ -85,6 +85,7 @@ export type RepositorySaveResult = {
     rootRepo: RepositorySaveReport;
     waves: string[][];
     plannedVersions: Record<string, string>;
+    workflowGates?: Array<Record<string, unknown>>;
 };
 export type RepositorySavePlanRepo = {
     id: string;
@@ -150,6 +151,13 @@ export type RepositorySaveOptions = {
     includeRoot?: boolean;
     stablePackageRelease?: boolean;
     onProgress?: (message: string, stream?: 'stdout' | 'stderr') => void;
+    onWaveSaved?: (wave: {
+        index: number;
+        nodes: RepositorySaveNode[];
+        reports: RepositorySaveReport[];
+        allReports: RepositorySaveReport[];
+        rootRepo: RepositorySaveReport | null;
+    }) => Promise<Array<Record<string, unknown>> | void> | Array<Record<string, unknown>> | void;
 };
 export declare function runStreamingCommand(node: Pick<RepositorySaveNode, 'name' | 'path'>, options: Pick<RepositorySaveOptions, 'onProgress'>, phase: string, command: string, args: string[], commandOptions?: {
     cwd?: string;