@kindgi/cli 0.1.8 → 0.1.9-rc.0

package/dist/commands/deploy.js

@@ -28,21 +28,30 @@ import { stat } from 'node:fs/promises';
 import { isAbsolute, join, resolve } from 'node:path';
 import { LOCAL_ENV_NAME, packValues, readPackEnv } from '@kindgi/secrets-dotenv';
 import { deployApiAddress, hostedApiAddress } from '../api-address.js';
-import { HOSTED_BUILD } from '../build/hosted.js';
 import { isEnvelopeSigned } from '../deploy/envelope-loader.js';
+import { packServiceProblemText, packServiceRetiredText } from '../deploy/pack-service-text.js';
 import { buildPostBody, deriveIdempotencyKey, deriveSyncSecretsIdempotencyKey, } from '../deploy/post.js';
+import { promotionPath } from '../deploy/promotion-path.js';
 import { renderResponse } from '../deploy/response.js';
+import { envProjectRefs } from '../env-projects.js';
+import { packEnvProblemLines, packEnvSecretSetCommand, packEnvSetCommand, } from '../env/pack-env-hint.js';
 import { describePackEnvPlan, plainSecretReason, planPackEnv, } from '../env/pack-env-plan.js';
 import { renderJson } from '../output.js';
 import { loadPackConfig } from '../pack-config.js';
+import { PROJECT_ID_RE } from '../project-ref.js';
 import { isWait, sendWaitingOutRateLimits } from '../rate-limit-wait.js';
+import { SLUG } from '../slug.js';
+import { environmentsOf, resolveValueTarget } from '../value-target.js';
 import { runBuild } from './build.js';
 /** Default relative path to look for a pre-built envelope. */
 export const DEFAULT_ENVELOPE_RELATIVE_PATH = '.kindgi/build/deploy-envelope.json';
 export const deployCommand = {
     kind: 'leaf',
     name: 'deploy',
-    description: 'Deploy a signed pack image to Kindgi. Reads deploy-envelope.json (or runs `kindgi build` inline) + POSTs to /v1/deployments.',
+    description: 'Deploy a signed pack image to Kindgi. Reads deploy-envelope.json (or runs `kindgi build` inline) + POSTs to /v1/deployments. ' +
+        "`--hosted` (or the env block's `build: 'hosted'`) deploys to Kindgi hosted: an inline build runs on the hosted build service (as `kindgi build --hosted`), and after the deploy it waits, up to 5 minutes, for the deployment's pack service to be ready. " +
+        "A deploy into the Default project with a pack tool whose id is an MCP endpoint's tool's is refused (`tool-kind-mismatch`), and nothing is deployed.",
+    hostedRun: { defaultEnv: 'staging' },
     usage: 'kindgi deploy [--env <name>] [--from-envelope <path>] [--endpoint <url>] [--token <bearer>] ' +
         '[--tenant <id>] [--project <id|slug>] [--hosted] [--idempotency-key <str>] [--dry-run] [--sync-secrets] [--allow-missing-env] ' +
         '[--target <t>] [--build-endpoint <url>] [--out <dir>] [--artifact-version <v>] [--published-at <iso>] ' +
@@ -69,10 +78,6 @@ export const deployCommand = {
             type: 'string',
             description: "The project to deploy into, one per client: its id, or its slug. A slug two orgs share is refused: pass the id. Default: a tenant-wide deploy, into the tenant's Default project.",
         },
-        hosted: {
-            type: 'boolean',
-            description: "Deploy to Kindgi hosted: an inline build runs on the hosted build service (as `kindgi build --hosted`), and after the deploy it waits, up to 5 minutes, for the deployment's pack service to be ready. Same as the env block's `build: 'hosted'`.",
-        },
         'idempotency-key': {
             type: 'string',
             description: 'The `Idempotency-Key` header. Default: a hash of the request body, so the same image deployed again returns the same deployment.',
@@ -85,7 +90,7 @@ export const deployCommand = {
         // verticals rotate secrets on a separate cadence.
         'sync-secrets': {
             type: 'boolean',
-            description: "After the deploy lands, also send the values in `.env.<env>` to the deployment's secrets. Off by default.",
+            description: "After the deploy lands, also send the values in `.env.<env>` to the deployment's secrets. Off by default. A hosted deploy needs --env with it.",
         },
         // Deploy although a name the pack's env.required declares has no
         // value for --env (the pack service won't be ready until it has).
@@ -104,7 +109,7 @@ export const deployCommand = {
         },
         out: {
             type: 'string',
-            description: 'Where the envelope is looked for, and an inline build writes. Default: `.kindgi/build` under the pack root.',
+            description: 'Where the envelope is looked for, and an inline build writes (default: `.kindgi/build`). An inline build applies the same --out rules as `kindgi build`: not the pack root or a directory containing it, and under it for a TypeScript pack.',
         },
         'artifact-version': {
             type: 'string',
@@ -173,13 +178,49 @@ export async function runDeploy(ctx) {
     const envRefusal = checkPackEnv(args, line);
     if (envRefusal !== undefined)
         return envRefusal;
+    // On a runtime that keeps its values under one env, a pack environment
+    // with a `project` is that project, and its secret sync goes there, under
+    // the env the runtime serves. Any other env's sync is refused here,
+    // before a build or an upload, as the runtime would refuse the sync after
+    // the deployment.
+    let syncEnvName = args.envName;
+    let environmentProject;
+    const named = args.environments[args.envName] !== undefined;
+    if ((args.syncSecrets || named) && runners.servedEnv !== undefined) {
+        const target = resolveValueTarget({
+            flag: args.envName,
+            served: await runners.servedEnv({
+                endpoint: args.endpoint,
+                token: args.token,
+                fetchImpl: ctx.fetch,
+                ...(ctx.stopSignal !== undefined && { signal: ctx.stopSignal }),
+            }),
+            write: args.syncSecrets,
+            what: `the secrets in .env.${args.envName}`,
+            mayOmit: false,
+            environments: args.environments,
+        });
+        if (target.kind === 'refused')
+            return failure(target.stderr);
+        if (target.kind === 'ok' && target.environment !== undefined) {
+            environmentProject = target.environment.projectRef;
+            syncEnvName = target.envName;
+            line(`  Project:     ${environmentProject}  (environments.${args.envName}.project)`);
+            if (args.syncSecrets)
+                line(`  Secrets:     under ${syncEnvName}, the env the runtime serves`);
+            line('');
+        }
+    }
     // ---- 1. The project to deploy into (--project) ---------------------
     //
     // Resolved first: a project that isn't there fails before a build, and
     // a hosted build carries the project's id as its label.
-    const project = await resolveProject(args, runners, ctx);
+    const project = await resolveDeployProject(args, environmentProject, runners, ctx);
     if (project.kind === 'error')
         return failure(project.message);
+    const hostedEnvRefusal = refuseHostedConfigEnv(args, project.id);
+    if (hostedEnvRefusal !== undefined)
+        return hostedEnvRefusal;
     // ---- 2. Ensure envelope on disk -------------------------------------
     const envelopeReady = await ensureEnvelopeExists(ctx, args, runners, line, project.id);
     if (envelopeReady.kind === 'error')
@@ -286,6 +327,7 @@ export async function runDeploy(ctx) {
         ...(ctx.stopSignal !== undefined && { signal: ctx.stopSignal }),
     }), deployRefusal);
     // ---- 10. Render response ---------------------------------------------
+    const promotionPath = await promotionPathOf(args, runners, ctx, result);
     const rendered = renderResponse(result, {
         envName: args.envName,
         endpoint: args.endpoint,
@@ -296,6 +338,7 @@ export async function runDeploy(ctx) {
         signerKeyId: envelope.signerKeyId ?? '(unsigned)',
         envelopePath: args.envelopePath,
         idempotencyKey,
+        promotionPath,
     });
     for (const l of rendered.banner)
         line(l);
@@ -318,7 +361,7 @@ export async function runDeploy(ctx) {
     const syncSummary = { performed: false };
     const deployedRecord = result.kind === 'created' || result.kind === 'replayed' ? result.record : null;
     if (args.syncSecrets && deployedRecord !== null) {
-        const syncOutcome = await runSecretsSync(ctx, args, runners, deployedRecord.deploymentId, line);
+        const syncOutcome = await runSecretsSync(ctx, args, syncEnvName, runners, deployedRecord.deploymentId, line);
         Object.assign(syncSummary, syncOutcome);
     }
     // ---- 12. Hosted: wait for the deployment's pack service --------------
@@ -327,7 +370,7 @@ export async function runDeploy(ctx) {
     // deployment is in place whatever the wait finds.
     let packService;
     if (args.hosted && deployedRecord !== null && deployedRecord.endpoint !== undefined) {
-        const waited = await waitForPackService(ctx, args, runners, deployedRecord, line);
+        const waited = await waitForPackService(ctx, args, runners, deployedRecord, line, project.id);
         if (waited.kind === 'error') {
             return { kind: 'error', stderr: `${banner.join('\n')}\n${waited.message}`, exitCode: 1 };
         }
@@ -370,7 +413,9 @@ function deployRefusal(result) {
  * opted in via `--sync-secrets`. Warns loudly when secret-shaped keys
  * are present (they should live in `kindgi secrets set` instead).
  */
-async function runSecretsSync(ctx, args, runners, deploymentId, line) {
+async function runSecretsSync(ctx, args, 
+/** The env the values go under: `--env`, or the one a runtime that keeps its values under one serves. */
+envName, runners, deploymentId, line) {
     const file = await detectSecretsFile(args, '');
     if (file === null || file.entries.length === 0) {
         line('  --sync-secrets set, but no `.env.<envName>` entries to sync. Skipping.');
@@ -389,7 +434,7 @@ async function runSecretsSync(ctx, args, runners, deploymentId, line) {
         line('');
     }
     const syncBody = {
-        envName: args.envName,
+        envName,
         secrets: file.entries.map((e) => ({ name: e.name, value: e.value })),
     };
     const idempotencyKey = deriveSyncSecretsIdempotencyKey(deploymentId, syncBody);
@@ -437,6 +482,10 @@ async function runSecretsSync(ctx, args, runners, deploymentId, line) {
  * value (unless `--allow-missing-env`) or a secret is given in the clear.
  */
 function checkPackEnv(args, line) {
+    // A hosted pack service gets the values set in the workspace, not these:
+    // `refuseHostedConfigEnv`, once the project is known.
+    if (args.hosted)
+        return undefined;
     const plan = args.packEnv;
     if (plan.entries.length === 0 && plan.problems.length === 0 && plan.warnings.length === 0) {
         return undefined;
@@ -456,6 +505,27 @@ function checkPackEnv(args, line) {
     }
     return undefined;
 }
+/**
+ * A hosted deploy: Kindgi Cloud gives the pack service the env values set
+ * in the workspace (`kindgi env set`, a secret with `kindgi secrets set`),
+ * at the deployment's project, then its org, then the tenant.
+ * `environments.<env>.env` in kindgi.config isn't read there, so a config
+ * that gives any is refused before anything is built or sent, naming each
+ * name and how to set it.
+ */
+function refuseHostedConfigEnv(args, projectId) {
+    const plan = args.packEnv;
+    if (!args.hosted || (plan.given.length === 0 && plan.problems.length === 0))
+        return undefined;
+    const block = `environments.${args.envName}.env`;
+    const names = plan.given.length === 0 ? '' : ` (${plan.given.join(', ')})`;
+    const target = { envName: args.envName, ...(projectId !== undefined && { projectId }) };
+    const command = packEnvSetCommand({ ...target, hasProjectMapping: false });
+    const secrets = plan.entries.some((e) => e.source?.kind === 'secret')
+        ? ` (a secret with \`${packEnvSecretSetCommand(target)}\`)`
+        : '';
+    return failure(`kindgi deploy: on Kindgi Cloud the pack service gets the env values set in your workspace, not ${block} in kindgi.config${names}. Set each with \`${command}\`${secrets}, then remove ${block} from kindgi.config and deploy again.\n`);
+}
 // ---------------------------------------------------------------------
 // Envelope existence — either read from disk or inline-build
 // ---------------------------------------------------------------------
@@ -607,25 +677,15 @@ const PACK_SERVICE_WAIT_MS = 5 * 60 * 1000;
 const PACK_SERVICE_POLL_MS = 2_000;
 /** Reads in a row that may fail before it stops waiting. */
 const PACK_SERVICE_READ_TRIES = 3;
-/** Why a deployment has no pack service yet, by its `problem.code`. */
-const PACK_SERVICE_PROBLEMS = {
-    'tenant-not-provisioned': 'your workspace has nowhere to run pack services yet',
-    'capacity-unavailable': 'there is no room for another pack service just now',
-    'service-start-failed': "the pack's image was deployed but didn't start",
-    'image-not-allowed': "the image is outside your workspace's own repository",
-    'endpoint-url-invalid': "the platform couldn't connect the pack service",
-    'endpoint-host-not-allowed': "the platform couldn't connect the pack service",
-    'endpoint-name-mismatch': "the platform couldn't connect the pack service",
-    'endpoint-unreachable': "the pack service didn't answer",
-    'endpoint-info-mismatch': 'the pack service answered as another pack or version',
-};
 /**
  * Waits for the deployment's own pack service to be `ready`, reading the
- * deployment again every 2 s and saying each new state once. Fails when
- * it's `cleared`, after 5 minutes, after a few failed reads in a row, or
- * on Ctrl+C. The deployment is in place whatever it finds.
+ * deployment again every 2 s and saying each new state once. A `cleared`
+ * one that's `waiting` (a suspension that took it down was lifted) is
+ * waited for like a pending one. Fails when it's `cleared` otherwise (saying
+ * why, when the server says), after 5 minutes, after a few failed reads in
+ * a row, or on Ctrl+C. The deployment is in place whatever it finds.
  */
-async function waitForPackService(ctx, args, runners, record, line) {
+async function waitForPackService(ctx, args, runners, record, line, projectId) {
     const read = runners.getDeployment;
     if (read === undefined) {
         return {
@@ -639,7 +699,17 @@ async function waitForPackService(ctx, args, runners, record, line) {
     const started = now();
     let endpoint = record.endpoint;
     let said = '';
+    let saidEnv = '';
     let failedReads = 0;
+    // What stands in the way of its env, said once, and again when it changes.
+    const sayPackEnv = async () => {
+        const lines = await packEnvLines(ctx, args, runners, id, projectId);
+        const text = lines.join('\n');
+        if (text !== '' && text !== saidEnv)
+            for (const l of lines)
+                line(`      ${l}`);
+        saidEnv = text;
+    };
     line('  Waiting for the pack service');
     for (;;) {
         const settled = settledPackService(endpoint, id);
@@ -648,9 +718,14 @@ async function waitForPackService(ctx, args, runners, record, line) {
                 line('    ✓ ready\n');
             return settled;
         }
-        const state = pendingState(endpoint);
-        if (state !== said)
+        const state = waitingState(endpoint);
+        if (state !== said) {
             line(`    … ${state}`);
+            // At once, before the platform records it as the problem; and again then.
+            if (said === '' || endpoint.problem?.code.startsWith('pack-env-') === true) {
+                await sayPackEnv();
+            }
+        }
         said = state;
         if (now() - started >= PACK_SERVICE_WAIT_MS) {
             return stoppedWaiting(`The pack service isn't ready after 5 minutes: ${state}`, id);
@@ -671,6 +746,29 @@ async function waitForPackService(ctx, args, runners, record, line) {
         }
     }
 }
+/**
+ * Where the deployment's pack declares names that stand in the way, said
+ * as what to do: nothing when none does, when the server doesn't give pack
+ * services their env (or is older), or when it can't be read.
+ */
+async function packEnvLines(ctx, args, runners, deploymentId, projectId) {
+    if (runners.getPackEnv === undefined)
+        return [];
+    const got = await runners.getPackEnv({
+        endpoint: args.endpoint,
+        token: args.token,
+        deploymentId,
+        fetchImpl: ctx.fetch,
+        ...(ctx.stopSignal !== undefined && { signal: ctx.stopSignal }),
+    });
+    if (got.kind !== 'ok')
+        return [];
+    return packEnvProblemLines(got.packEnv.data, {
+        envName: got.packEnv.envName,
+        ...(projectId !== undefined && { projectId }),
+        hasProjectMapping: false,
+    });
+}
 /** The deployment's pack service now, read again. */
 async function readPackService(read, ctx, args, deploymentId) {
     const got = await read({
@@ -689,24 +787,39 @@ function stoppedWaiting(why, deploymentId) {
         message: `${why}. deploymentId ${deploymentId}. Run the same \`kindgi deploy --hosted\` again to keep waiting: it sends the same deployment, and the server answers with this one.\n`,
     };
 }
-/** A pack service that's done with: `ready`, or `cleared` (a failure); else undefined. */
+/**
+ * A pack service that's done with: `ready`, or `cleared` and not `waiting`
+ * (a failure, with the server's reason when it gives one: an older server
+ * gives none); else undefined.
+ */
 function settledPackService(endpoint, id) {
     if (endpoint.status === 'ready')
         return { kind: 'ok', endpoint };
-    if (endpoint.status === 'cleared') {
+    if (endpoint.status !== 'cleared' || endpoint.waiting === true)
+        return undefined;
+    if (endpoint.retired === undefined) {
         return {
             kind: 'error',
-            message: `The deployment's pack service was taken down before it was ready (cleared). deploymentId ${id}.\n`,
+            message: `The deployment's pack service was taken down (cleared). deploymentId ${id}.\n`,
         };
     }
-    return undefined;
+    const why = packServiceRetiredText(endpoint.retired);
+    return {
+        kind: 'error',
+        message: `The deployment's pack service was taken down (cleared, ${endpoint.retired}): ${why}. deploymentId ${id}.\n`,
+    };
 }
-/** A pending pack service, as the wait says it: `pending`, and why when there's a problem. */
-function pendingState(endpoint) {
+/**
+ * A pack service being waited for, as the wait says it: `pending`, or
+ * `cleared, waiting for its pack service again`, and why when there's a
+ * problem.
+ */
+function waitingState(endpoint) {
+    const state = endpoint.status === 'cleared' ? 'cleared, waiting for its pack service again' : 'pending';
     if (endpoint.problem === undefined)
-        return 'pending';
-    const why = PACK_SERVICE_PROBLEMS[endpoint.problem.code] ?? 'not ready yet';
-    return `pending (${endpoint.problem.code}): ${why}`;
+        return state;
+    const why = packServiceProblemText(endpoint.problem.code);
+    return `${state} (${endpoint.problem.code}): ${why}`;
 }
 function sleepUnlessStopped(ms, signal) {
     return new Promise((resolve) => {
@@ -719,18 +832,33 @@ function sleepUnlessStopped(ms, signal) {
         signal?.addEventListener('abort', done, { once: true });
     });
 }
-// ---------------------------------------------------------------------
-// The project a deploy goes into
-// ---------------------------------------------------------------------
-const PROJECT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * The project to deploy into: `--project`, else the pack environment's
+ * `project` when the runtime keeps its values under one env (`fromEnvironment`).
+ * A `--project` that isn't that environment's project is refused.
+ */
+async function resolveDeployProject(args, fromEnvironment, runners, ctx) {
+    const flag = await resolveProject(args.projectRef, '--project', args, runners, ctx);
+    if (flag.kind === 'error' || fromEnvironment === undefined)
+        return flag;
+    const where = `environments.${args.envName}.project`;
+    const environment = await resolveProject(fromEnvironment, where, args, runners, ctx);
+    if (environment.kind === 'error' || args.projectRef === undefined)
+        return environment;
+    if (flag.id === environment.id)
+        return environment;
+    return {
+        kind: 'error',
+        message: `--project ${args.projectRef} isn't the ${args.envName} environment's project, ${fromEnvironment} (${where}). Leave --project out, or deploy with the --env whose project it is.\n`,
+    };
+}
 /**
  * `--project`: an id goes as it is (the server answers 404 for one of no
  * project of the tenant); a slug is looked up, and refused when it names
  * no project, or several (a slug is unique within an org, so two orgs may
  * share one). Absent: tenant-wide.
  */
-async function resolveProject(args, runners, ctx) {
-    const ref = args.projectRef;
+async function resolveProject(ref, where, args, runners, ctx) {
     if (ref === undefined)
         return { kind: 'ok' };
     if (PROJECT_ID_RE.test(ref))
@@ -738,7 +866,7 @@ async function resolveProject(args, runners, ctx) {
     if (runners.findProjects === undefined) {
         return {
             kind: 'error',
-            message: `--project ${ref}: this build can't look a slug up. Pass the project's id.\n`,
+            message: `${where} ${ref}: this build can't look a slug up. Pass the project's id.\n`,
         };
     }
     const found = await runners.findProjects({
@@ -751,21 +879,21 @@ async function resolveProject(args, runners, ctx) {
     if (found.kind === 'error') {
         return {
             kind: 'error',
-            message: `--project ${ref}: couldn't list the tenant's projects: ${found.message}\n`,
+            message: `${where} ${ref}: couldn't list the tenant's projects: ${found.message}\n`,
         };
     }
     const [only, ...more] = found.projects;
     if (only === undefined) {
         return {
             kind: 'error',
-            message: `--project ${ref}: no project of this tenant has that slug. \`kindgi projects list\` shows them.\n`,
+            message: `${where} ${ref}: no project of this tenant has that slug. \`kindgi projects list\` shows them; \`kindgi projects create --name=<name> --slug=${SLUG.test(ref) ? ref : '<slug>'}\` makes one.\n`,
         };
     }
     if (more.length > 0) {
         const ids = found.projects.map((p) => `${p.id} (${p.name}${p.orgId === undefined ? '' : `, org ${p.orgId}`})`);
         return {
             kind: 'error',
-            message: `--project ${ref}: ${found.projects.length} projects of this tenant have that slug, in different orgs: ${ids.join(', ')}. Pass the id.\n`,
+            message: `${where} ${ref}: ${found.projects.length} projects of this tenant have that slug, in different orgs: ${ids.join(', ')}. Pass the id.\n`,
         };
     }
     return { kind: 'ok', id: only.id };
@@ -782,7 +910,8 @@ async function resolveDeployArgs(ctx) {
     const cfg = config.config;
     // --env — default staging (matches build's default).
     const envFlag = ctx.options.env;
-    const envName = typeof envFlag === 'string' && envFlag !== '' ? envFlag : 'staging';
+    const envGiven = typeof envFlag === 'string' && envFlag !== '';
+    const envName = envGiven ? envFlag : 'staging';
     const envBlock = cfg.environments?.[envName] !== undefined
         ? cfg.environments[envName]
         : undefined;
@@ -790,14 +919,25 @@ async function resolveDeployArgs(ctx) {
     const outFlag = ctx.options.out;
     const outDirRaw = typeof outFlag === 'string' && outFlag !== '' ? outFlag : '.kindgi/build';
     const outDir = isAbsolute(outDirRaw) ? outDirRaw : resolve(packDir, outDirRaw);
-    const hosted = ctx.options.hosted === true || envBlock?.build === HOSTED_BUILD;
-    if (ctx.options.hosted === true && ctx.options['build-endpoint'] !== undefined) {
+    // --hosted, or the env block's `build: 'hosted'` (main.ts, `hostedRun`).
+    const hosted = ctx.hosted;
+    if (ctx.globals.hosted && ctx.options['build-endpoint'] !== undefined) {
         return {
             kind: 'error',
             stderr: '--hosted builds on the hosted build service, and --build-endpoint names another build server: leave one out.\n',
             exitCode: 1,
         };
     }
+    // A hosted runtime reads a deployment's secrets in the env it serves.
+    // Without --env the sync would send `.env.staging` under `staging`,
+    // which it may never read: the env is named, not defaulted.
+    if (hosted && ctx.options['sync-secrets'] === true && !envGiven) {
+        return {
+            kind: 'error',
+            stderr: "--sync-secrets on a hosted deploy needs --env. A hosted runtime reads a deployment's secrets in the env it serves; without --env, the values in .env.staging would go up under staging. Pass --env=<the env it serves>.\n",
+            exitCode: 1,
+        };
+    }
     // The API (api-address.ts): --endpoint > the env block's `endpoint` >
     // the CLI's own address (`--url`, KINDGI_API_URL or the stored one).
     // A stored key goes only to the address stored with it; a hosted
@@ -833,6 +973,9 @@ async function resolveDeployArgs(ctx) {
             exitCode: 1,
         };
     }
+    // No --endpoint or env `endpoint`: the key goes to the CLI's own address.
+    if (named.every((n) => n.url === undefined || n.url === ''))
+        ctx.noteOwnAddressKey();
     // --tenant — used only as a consistency check against the envelope.
     const tenantFlag = ctx.options.tenant;
     const explicitTenantId = typeof tenantFlag === 'string' && tenantFlag !== '' ? tenantFlag : undefined;
@@ -877,11 +1020,50 @@ async function resolveDeployArgs(ctx) {
             dryRun,
             syncSecrets,
             envBlock,
+            environments: environmentsOf(cfg),
             packEnv: packEnv.plan,
             allowMissingEnv: ctx.options['allow-missing-env'] === true,
         },
     };
 }
+/**
+ * A deploy refused into a later environment of its order
+ * (`409 environment-takes-promotions`): each environment from the order's
+ * first to that one, named from the pack config, for the hint. `undefined`
+ * for any other answer, and when the refusal doesn't name the first (the
+ * caller can't read it) or the reads fail: the hint then says the rule
+ * without names.
+ */
+async function promotionPathOf(args, runners, ctx, result) {
+    if (result.kind !== 'wire-error' || result.error.code !== 'environment-takes-promotions') {
+        return undefined;
+    }
+    const { position, firstProjectId } = result.error;
+    if (position === undefined || firstProjectId === undefined)
+        return undefined;
+    if (runners.listProjects === undefined || runners.listEnvironmentOrders === undefined) {
+        return undefined;
+    }
+    const opts = {
+        endpoint: args.endpoint,
+        token: args.token,
+        fetchImpl: ctx.fetch,
+        ...(ctx.stopSignal !== undefined && { signal: ctx.stopSignal }),
+    };
+    const [projects, orders] = await Promise.all([
+        runners.listProjects(opts),
+        runners.listEnvironmentOrders(opts),
+    ]);
+    if (projects.kind === 'error' || orders.kind === 'error')
+        return undefined;
+    return promotionPath({
+        firstProjectId,
+        position,
+        orders: orders.orders,
+        projects: projects.projects,
+        environments: envProjectRefs(args.environments),
+    });
+}
 async function loadDeployConfig(ctx, packDir) {
     const outcome = await loadPackConfig(ctx, packDir);
     if (outcome.kind === 'ok')