@inquir/compute-cli 0.4.0 → 0.4.1

package/dist/commands/apps.js

@@ -2,17 +2,20 @@ import path from 'node:path';
 import { alertsSubcommand, logHistorySubcommand, metricsSubcommand, OBSERVATION_HELP, OBSERVATION_VALUE_FLAGS } from './apps-observability.js';
 import { RESOURCES_HELP, RESOURCES_VALUE_FLAGS, resourcesSubcommand } from './apps-resources.js';
 import { DESCRIBE_HELP, describeSubcommand } from './apps-describe.js';
+import { INSTANCES_HELP, instancesSubcommand, resolveReplicaAllocationId } from './apps-instances.js';
 import { followPromoteRollout } from './apps-promote.js';
 import { hasFlag, readFlagValue, readJsonFlag, readLimitFlag, readMultiFlag, readPositionalArgs, } from '../utils/args.js';
-import { listAppBackups, getAppBackup, createAppBackup, deleteAppBackup, restoreAppBackup, getAppConnectionUrl, connectApps, addApplicationDomain, archiveApplication, cancelBuild, createApplication, getBuild, listApplicationDomains, listBuilds, queueBuild, removeApplicationDomain, createRelease, redeployApplication, execInApplication, getAppLimits, getApplication, getProject, getRelease, listApplications, promoteRelease, isPromoteAccepted, requireAuth, resolveApplication, rollbackApplication, stopRelease, streamBuildLogs, streamReleaseLogs, updateApplication, wakeApplication, pauseApplication, verifyApplicationDomain, } from '../utils/api.js';
-import { ApiError, DEFAULT_BUILD_TIMEOUT_POLICY, createZipBase64, isSettledReleaseStatus, isTerminalBuildStatus } from '../sdk.js';
-import { formatBytes, formatElapsed, humanizeApiError, permanentAddress, presentRelease, } from '../utils/apps-presentation.js';
+import { listAppBackups, getAppBackup, createAppBackup, deleteAppBackup, restoreAppBackup, getAppConnectionUrl, connectApps, createApiClient, addApplicationDomain, archiveApplication, cancelBuild, createApplication, getBuild, listApplicationDomains, listBuilds, queueBuild, removeApplicationDomain, createRelease, redeployApplication, execInApplication, getAppLimits, getAppLocation, getApplication, getProject, getProductionReplacement, getRelease, listApplications, promoteRelease, isPromoteAccepted, requireAuth, resolveApplication, rollbackApplication, stopRelease, streamBuildLogs, streamReleaseLogs, updateApplication, wakeApplication, pauseApplication, verifyApplicationDomain, } from '../utils/api.js';
+import { ApiError, DEFAULT_BUILD_TIMEOUT_POLICY, getAppLogHistory, isSettledReleaseStatus, isTerminalBuildStatus } from '../sdk.js';
+import { formatBytes, formatElapsed, humanizeApiError, permanentAddress, presentRelease, replacementPhaseMeaning, } from '../utils/apps-presentation.js';
 import { buildApiOptions, runtime } from '../utils/context.js';
 import { confirm } from '../utils/prompt.js';
 import { resolveCreateProject } from '../utils/project-context.js';
 import { CliError, ExitCode, toCliError, usageError } from '../utils/errors.js';
 import { redact, registerSecret } from '../utils/redact.js';
-import { dim, formatTable, printCommandHelp, printError, printInfo, printLine, printSuccess } from '../utils/output.js';
+import { dim, formatTable, printCommandHelp, printError, printInfo, printLine, printSuccess, printWarning } from '../utils/output.js';
+import { containerPathArgument, MSYS_PATH_HINT } from '../utils/msys-path.js';
+import { packSourceForUpload } from '../utils/source-pack.js';
 /** Value flags across every subcommand — readPositionalArgs must know them all. */
 const VALUE_FLAGS = [
     ...OBSERVATION_VALUE_FLAGS,
@@ -52,6 +55,8 @@ const VALUE_FLAGS = [
     '--stabilization',
     '--scale-down-stabilization',
     '--replicas',
+    '--node-selector',
+    '--location',
 ];
 export async function appsCommand(args) {
     const [subcommand, ...rest] = readPositionalArgs(args, { valueFlags: VALUE_FLAGS });
@@ -96,6 +101,8 @@ export async function appsCommand(args) {
             return resourcesSubcommand(args, rest, apiOptions);
         case 'describe':
             return describeSubcommand(args, rest, apiOptions);
+        case 'instances':
+            return instancesSubcommand(args, rest, apiOptions);
         case 'promote':
             return promoteSubcommand(args, rest, apiOptions);
         case 'rollback':
@@ -144,7 +151,8 @@ function printAppsHelp() {
         'builds <app>                List image builds',
         'status <app>                Endpoints and recent releases',
         'describe <app>              Why it is (not) running: conditions, placement, events',
-        'logs <app|release|build>    Stream container (or build) logs',
+        'instances <app>             Replicas (like pods): name, state, runner, CPU/RAM now',
+        'logs <app|release|build>    Recent container (or build) logs, then follow (--no-follow exits)',
         'log-history <app>          Persisted runtime or HTTP logs with time/replica filters',
         'metrics <app>              CPU/RAM, network, disk I/O or HTTP history (--json)',
         'alerts <app> [action]      Configure resource/deployment alerts and read incidents',
@@ -152,8 +160,8 @@ function printAppsHelp() {
         'promote <release>           Send production traffic to a release',
         'rollback <app>              Return production to the previous release',
         'stop <release>              Stop a release that is not serving production',
-        'exec <release> -- <cmd>     Run a command inside the container',
-        'update <app>                Change env vars, ports, resources, egress',
+        'exec <app> [--replica <r>] -- <cmd>  Run a command in production (one replica: name or index)',
+        'update <app>                Change env vars, ports, resources, egress, node selector',
         'scale <app> [mode]          Set always/http/manual scaling (--replicas for always)',
         'wake <app>                  Start a sleeping application',
         'pause <app>                 Stop an http/manual app (HTTP wakes only http mode)',
@@ -164,7 +172,7 @@ function printAppsHelp() {
         '--project <project>         create: this project by id, slug or unique name (overrides projects use)',
         '--image <ref>               Container image, e.g. nginx:alpine (omit to build from source)',
         '--promote                   deploy: take production by itself once healthy (needs apps:promote)',
-        '--template <name>           postgres | redis: volume, stable TCP endpoint, generated password, first release',
+        '--template <name>           postgres | redis: volume, private TCP endpoint, generated password, first release',
         '--dir <path>                Source directory to build (default: current directory)',
         '--dockerfile <path>         Dockerfile relative to the context (default: Dockerfile)',
         '--context <path>            Build context inside the source tree (default: .)',
@@ -174,6 +182,10 @@ function printAppsHelp() {
         '--tcp <name:port[:public]>  Extra TCP port; endpoint port is platform-managed (repeatable)',
         '--volume <name:/path[:ro]> Persistent volume mount (repeatable)',
         '--volume-runner <id>        Pin volumes (and the container) to a worker runner',
+        '--node-selector KEY=VALUE   update: run only on servers with this node label (repeatable),',
+        '                            e.g. inquir.io/region=eu; --clear-node-selector removes it',
+        '--location <id|auto>        update (experimental): run in this location, e.g. nl or ru; auto',
+        '                            runs wherever there is capacity. Applies from the next deploy',
         '--set KEY=VALUE             Environment variable (repeatable)',
         '--memory <mb>               Memory ceiling (default 512)',
         '--cpu <vcpus>               CPU ceiling (default 0.5)',
@@ -235,6 +247,77 @@ export function parseTcpPortFlag(value) {
     }
     return spec;
 }
+/**
+ * `--location <id|auto>`: the service's location, verbatim; the server says
+ * which ids it offers. Undefined when the flag is absent.
+ */
+export function parseLocationFlag(value) {
+    if (value === undefined)
+        return undefined;
+    const location = value.trim().toLowerCase();
+    if (!/^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/.test(location)) {
+        throw usageError(`Invalid --location value '${value}'`, 'inquir apps update <app> --location nl   (or --location auto)');
+    }
+    return location;
+}
+/**
+ * The status line of a service's location: its setting by name, what
+ * production runs with while a change waits for the next deploy, and where
+ * the replicas run. Undefined while the platform offers no location choice.
+ */
+export function describeServiceLocation(status) {
+    if (!status.enabled)
+        return undefined;
+    const name = (id) => (id === 'auto' ? 'Auto' : status.locations.find((entry) => entry.id === id)?.name ?? id);
+    const parts = [status.setting === 'auto' ? 'Auto (wherever there is capacity)' : name(status.setting)];
+    if (status.pending && status.applied !== null) {
+        parts.push(`applies on the next deploy (production runs ${status.applied === 'auto' ? 'without a location' : `in ${name(status.applied)}`})`);
+    }
+    const running = [...new Set(status.replicas.map((replica) => (replica.location ? name(replica.location) : 'a server without a location')))];
+    if (running.length > 0)
+        parts.push(`running in ${running.join(', ')}`);
+    return parts.join(' — ');
+}
+/**
+ * `--node-selector KEY=VALUE` (repeatable): the node labels a server must
+ * carry, verbatim (`inquir.io/region=eu`, `tier=fast`). The server validates
+ * keys and values and says which keys it exposes.
+ */
+export function parseNodeSelectorFlags(values) {
+    const selector = {};
+    for (const entry of values) {
+        const index = entry.indexOf('=');
+        const key = index > 0 ? entry.slice(0, index).trim() : '';
+        if (!key) {
+            throw usageError(`Invalid --node-selector value '${entry}'`, 'inquir apps update <app> --node-selector inquir.io/region=eu');
+        }
+        if (Object.hasOwn(selector, key)) {
+            throw usageError(`--node-selector repeats the key '${key}'`, 'inquir apps update <app> --node-selector inquir.io/region=eu');
+        }
+        selector[key] = entry.slice(index + 1).trim();
+    }
+    return selector;
+}
+/**
+ * The runtime defaults with `--node-selector` / `--clear-node-selector`
+ * applied over `base` (the flags' runtime, else the stored one); undefined
+ * when neither flag is given.
+ */
+export function applyNodeSelectorFlags(args, base) {
+    const values = readMultiFlag(args, '--node-selector');
+    const clear = hasFlag(args, '--clear-node-selector');
+    if (values.length === 0 && !clear)
+        return undefined;
+    if (values.length > 0 && clear) {
+        throw usageError('Use either --node-selector or --clear-node-selector', 'inquir apps update <app> --clear-node-selector');
+    }
+    if (!base) {
+        throw usageError('This application has no runtime defaults to place; set its port first', 'inquir apps update <app> --port 3000 --node-selector inquir.io/region=eu');
+    }
+    const rest = { ...base };
+    delete rest.nodeSelector;
+    return clear ? rest : { ...rest, nodeSelector: parseNodeSelectorFlags(values) };
+}
 export function parseSetFlags(values) {
     const env = {};
     for (const entry of values) {
@@ -340,7 +423,7 @@ export function parseVolumeFlag(value) {
     let mountPath = separator > 0 ? value.slice(separator + 1) : '';
     let readOnly = false;
     if (/^[A-Za-z]:[\\/]/.test(mountPath)) {
-        throw usageError(`Invalid --volume mount path '${mountPath}'`, 'Volume targets are absolute paths inside the Linux container, for example data:/var/lib/data');
+        throw usageError(`Invalid --volume mount path '${mountPath}'`, `Volume targets are absolute paths inside the Linux container, for example data:/var/lib/data. ${MSYS_PATH_HINT}`);
     }
     const modifierAt = mountPath.lastIndexOf(':');
     if (modifierAt >= 0) {
@@ -419,7 +502,12 @@ export function buildRuntimeFromFlags(args, baseRuntime) {
     const memory = readFlagValue(args, '--memory');
     const cpu = readFlagValue(args, '--cpu');
     const drainGraceRaw = readFlagValue(args, '--drain-grace');
-    const healthPath = readFlagValue(args, '--health-path');
+    const healthPathRaw = readFlagValue(args, '--health-path');
+    const healthPathArgument = healthPathRaw !== undefined ? containerPathArgument(healthPathRaw, '--health-path') : undefined;
+    if (healthPathArgument?.recoveredFrom) {
+        printWarning(`--health-path: read '${healthPathArgument.recoveredFrom}' as ${healthPathArgument.value} (Git Bash path conversion). ${MSYS_PATH_HINT}`);
+    }
+    const healthPath = healthPathArgument?.value;
     const healthCommand = readFlagValue(args, '--health-command');
     const ports = tcpValues.map(parseTcpPortFlag);
     const volumes = volumeValues.map(parseVolumeFlag);
@@ -589,15 +677,117 @@ async function landingProjectLines(app, requestedProject, apiOptions) {
 }
 const TEMPLATE_NAMES = ['postgres', 'redis'];
 /** `apps <sub> --help` answered per subcommand; the global page is the fallback. */
-const SUBCOMMAND_HELP = {
+export const SUBCOMMAND_HELP = {
     ...OBSERVATION_HELP,
     ...RESOURCES_HELP,
     ...DESCRIBE_HELP,
+    ...INSTANCES_HELP,
     logs: [
-        'Usage: inquir apps logs <app|release|build> [--tail <n>]',
-        '  Streams container or build logs. Ctrl-C stops following.',
+        'Usage: inquir apps logs <app|release|build> [--tail <n>] [--no-follow] [--replica <name|index|allocation>]',
+        '  Prints the last --tail lines (default 200, at most 2000), then follows new',
+        '  ones until Ctrl-C.',
+        '  --no-follow Print the last --tail lines and exit (for scripts and agents).',
+        '  --replica   Only one replica\'s lines (see apps instances <app>).',
         '  --history selects persisted history instead; see apps log-history --help.',
     ],
+    exec: [
+        'Usage: inquir apps exec <app> [--replica <name|index|allocation>] [--timeout <ms>] -- <command>',
+        '  Runs one audited command in the production container. <app> is the',
+        '  application name or id; the id of its production release works too.',
+        '  --replica   One serving replica (see apps instances <app>); default: the projected one.',
+    ],
+    list: [
+        'Usage: inquir apps list [--json]',
+        '',
+        '  The workspace\'s applications with their production status.',
+    ],
+    deploy: [
+        'Usage: inquir apps deploy <app> [--image <ref> | --build <buildId> | --dir <path>] [--promote] [--no-wait]',
+        '',
+        '  Without --image or --build, packs the source directory (default: the',
+        '  current one), builds its Dockerfile and releases the image as a preview.',
+        '  The upload honours .dockerignore and .inquirignore and never contains',
+        '  .env files, private keys or literal registry tokens.',
+        '  --image <ref>        Release a container image instead of building',
+        '  --build <buildId>    Release an existing successful build',
+        '  --dir <path>         Source directory (default: current directory)',
+        '  --dockerfile, --context, --target, --build-arg KEY=VALUE  Build options',
+        '  --promote            Take production by itself once healthy (needs apps:promote)',
+        '  --no-wait            Return as soon as the release is queued',
+        '  Runtime flags (--port, --tcp, --volume, --set, --memory, --cpu, ...) as in apps --help.',
+    ],
+    status: [
+        'Usage: inquir apps status <app> [--json]',
+        '',
+        '  Production, endpoints (public URL, private address, TCP ports), volumes',
+        '  and recent releases.',
+    ],
+    rollback: [
+        'Usage: inquir apps rollback <app> [--json]',
+        '',
+        '  Returns production to the previous release: instantly while its container',
+        '  still runs, otherwise after it restarts and passes its health check.',
+    ],
+    stop: [
+        'Usage: inquir apps stop <release>',
+        '',
+        '  Stops a release that is not serving production; its container and preview',
+        '  URL go away.',
+    ],
+    build: [
+        'Usage: inquir apps build <app> [--dir <path>] [--dockerfile <path>] [--context <path>] [--target <stage>] [--build-arg KEY=VALUE]',
+        '',
+        '  Builds an image from source without releasing it (release it later with',
+        '  apps deploy <app> --build <buildId>). Uploads like apps deploy.',
+    ],
+    builds: [
+        'Usage: inquir apps builds <app> [--cancel <buildId>] [--json]',
+        '',
+        '  Lists the application\'s image builds; --cancel stops a queued or running one.',
+    ],
+    update: [
+        'Usage: inquir apps update <app> [--set KEY=VALUE] [--port <n>] [--memory <mb>] [--cpu <vcpus>] [--ingress private|public] [flags]',
+        '',
+        '  Applied now: --ingress (the generated public domain is created or removed',
+        '  at once) and --description.',
+        '  Applied by the next release (inquir apps redeploy <app>): --set, --port,',
+        '  --tcp, --volume, --memory, --cpu, --drain-grace, --health-path,',
+        '  --health-command, --egress, --location, --node-selector / --clear-node-selector.',
+    ],
+    scale: [
+        'Usage: inquir apps scale <app> <always|http|manual> [--replicas <n>] [--idle-timeout <d>] [--activation-timeout <d>] [--stabilization <d>]',
+        '',
+        '  always   Keep --replicas replicas running (1..8)',
+        '  http     Sleep after --idle-timeout without requests (minimum 5m); a request wakes it',
+        '  manual   Run until paused; only wake starts it again',
+        '  Durations: 90s, 15m, 1h30m. Takes effect now.',
+        '',
+        'Examples:',
+        '  inquir apps scale web always --replicas 2',
+        '  inquir apps scale web http --idle-timeout 15m',
+    ],
+    wake: [
+        'Usage: inquir apps wake <app> [--json]',
+        '',
+        '  Starts a sleeping (http) or paused (manual) application.',
+    ],
+    pause: [
+        'Usage: inquir apps pause <app> [--json]',
+        '',
+        '  Stops an http or manual application; an http one wakes on the next request.',
+    ],
+    domain: [
+        'Usage: inquir apps domain <app> [hostname] [--verify | --remove] [--json]',
+        '',
+        '  Without a hostname, lists the bound domains. With one, binds it and prints',
+        '  the DNS records to create; --verify checks them, --remove unbinds it.',
+    ],
+    delete: [
+        'Usage: inquir apps delete <app>',
+        '',
+        '  Archives the application and stops every release. Refused while another',
+        '  application depends on it (apps connect).',
+    ],
     promote: [
         'Usage: inquir apps promote <release> [--no-wait] [--json]',
         '',
@@ -625,9 +815,10 @@ const SUBCOMMAND_HELP = {
         '  --project <project>  Add to this project (id, slug or unique name). Otherwise',
         '                      uses projects use; without a selection, creates a project',
         '                      named after the app (group it later: inquir projects move).',
-        '  --template <name>   postgres | redis: volume, pinned public TCP port,',
-        '                      generated password, and the first release — one command',
-        '                      from nothing to a running database.',
+        '  --template <name>   postgres | redis: a volume, a private TCP port',
+        '                      (<slug>.apps.internal, reachable from your other',
+        '                      services), a generated password and the first release —',
+        '                      one command from nothing to a running database.',
         '  --volume-runner <id>  Pin volumes + container to a worker runner (id or',
         '                      unique prefix); the data lives on that machine. With',
         '                      --template the worker runs the operator\'s digest-pinned',
@@ -677,8 +868,55 @@ const SUBCOMMAND_HELP = {
     ],
 };
 const BACKUPS_USAGE = 'inquir apps backups <app> [list|create|restore <backupId>|delete <backupId>]';
+/**
+ * "2/3 ~10-08 14:00": the row's place among its volume's backups of the same
+ * kind, and roughly when it goes; "next cleanup" once past the limit.
+ */
+export function formatBackupKeeps(backup) {
+    const retention = backup.retention;
+    if (!retention)
+        return '';
+    const place = `${retention.position}/${retention.limit}`;
+    if (!retention.kept)
+        return `${place} next cleanup`;
+    if (!retention.expiresAt)
+        return place;
+    return `${place} ~${retention.expiresAt.slice(5, 16).replace('T', ' ')}`;
+}
+/** One line on what the workspace's backup policy keeps. */
+export function formatBackupPolicy(policy) {
+    const owner = policy.source === 'override' ? 'This workspace' : `Plan ${policy.planCode}`;
+    const every = policy.frequencyHours === 24 ? 'daily' : `every ${policy.frequencyHours}h`;
+    const automatic = policy.automatic
+        ? `the last ${policy.retainCount} automatic backup(s) (${every})`
+        : 'no automatic backups';
+    let line = `${owner} keeps ${automatic} and ${policy.maxManualBackups} manual backup(s) per volume`;
+    if (policy.grace)
+        line += `; after a plan change, up to ${policy.grace.retainCount} are kept until ${policy.grace.until.slice(0, 10)}`;
+    if (!policy.automaticAvailable && policy.automaticUnavailableReason === 'volume_on_worker') {
+        line += '; this app\'s volumes live on a worker, where the platform cannot back them up yet';
+    }
+    return line;
+}
+/**
+ * An empty backup list. A volume on a worker runner cannot be snapshotted by
+ * the platform yet, and `create` is refused there too: say so instead of
+ * suggesting it.
+ */
+export function emptyBackupsLines(appName, policy) {
+    if (policy && !policy.automaticAvailable && policy.automaticUnavailableReason === 'volume_on_worker') {
+        return [
+            `No backups for ${appName}: its volume lives on a worker runner, where the platform cannot back up volumes yet`,
+            '  (automatic or on demand; `backups create` is refused there too). Runner-side backups are in progress.',
+            '  Until then, see "Backups before risky changes" in the Node.js + Postgres tutorial:',
+            '  https://inquir.org/docs/node-postgres',
+        ];
+    }
+    return [`No backups for ${appName} yet — create one: inquir apps backups ${appName} create`];
+}
 /** The one backup table: `create` prints it too, once the rows settle. */
 function renderBackupTable(items) {
+    const keeps = items.some((b) => b.retention);
     printLine(formatTable(items.map((b) => ({
         id: b.id.slice(0, 8),
         volume: b.volumeName,
@@ -686,7 +924,10 @@ function renderBackupTable(items) {
         trigger: b.trigger,
         size: formatBytes(b.sizeBytes ?? b.artifactSizeBytes),
         created: b.createdAt.replace('T', ' ').slice(0, 19),
-    })), ['id', 'volume', 'status', 'trigger', 'size', 'created']));
+        keeps: formatBackupKeeps(b),
+    })), keeps
+        ? ['id', 'volume', 'status', 'trigger', 'size', 'created', 'keeps']
+        : ['id', 'volume', 'status', 'trigger', 'size', 'created']));
 }
 /** Accept a short id, the way the release commands do. */
 async function resolveBackup(applicationId, needle, identifier, apiOptions) {
@@ -758,9 +999,12 @@ async function backupsSubcommand(args, positionals, apiOptions) {
         if (json)
             return printLine(JSON.stringify(page, null, 2));
         if (page.items.length === 0) {
-            printInfo(`No backups for ${app.name} yet — create one: inquir apps backups ${app.name} create`);
+            for (const line of emptyBackupsLines(app.name, page.policy))
+                printInfo(line);
             return;
         }
+        if (page.policy)
+            printInfo(dim(formatBackupPolicy(page.policy)));
         renderBackupTable(page.items);
         if (page.nextCursor) {
             printInfo(dim(`  older: inquir apps backups ${app.name} list --cursor ${page.nextCursor}`));
@@ -1154,7 +1398,11 @@ async function runSourceBuild(applicationId, appName, args, apiOptions) {
     const buildArgs = parseSetFlags(readMultiFlag(args, '--build-arg'));
     if (!json)
         printInfo(dim(`— packing ${dir} —`));
-    const sourceZipBase64 = await createZipBase64(dir);
+    const sourceZipBase64 = await packSourceForUpload(dir, {
+        json,
+        ...(readFlagValue(args, '--context') ? { context: readFlagValue(args, '--context') } : {}),
+        ...(readFlagValue(args, '--dockerfile') ? { dockerfile: readFlagValue(args, '--dockerfile') } : {}),
+    });
     const queued = await queueBuild(applicationId, {
         sourceZipBase64,
         source: 'cli',
@@ -1336,24 +1584,64 @@ export async function waitForBuild(buildId, apiOptions, options = {}) {
  * reason instead of sitting out its whole timeout.
  */
 const FAILED_STARTS_BEFORE_REPORTING = 3;
+/** Every how many release polls a running replacement's phase is re-read. */
+const REPLACEMENT_PROBE_EVERY = 5;
+/**
+ * The phase of the stop-first production replacement a PENDING release is
+ * the target of. Bounded: the operation is read on the first PENDING poll
+ * and then every REPLACEMENT_PROBE_EVERY polls, and never again once a read
+ * fails or names no replacement for this release (a preview, an older
+ * server), so an ordinary deploy costs one extra request.
+ */
+export function createReplacementProbe(read, every = REPLACEMENT_PROBE_EVERY) {
+    let polls = 0;
+    let done = false;
+    let phase = '';
+    return {
+        async phaseOf(release) {
+            if (done)
+                return '';
+            polls += 1;
+            if ((polls - 1) % every !== 0)
+                return phase;
+            const operation = await read(release.applicationId).catch(() => null);
+            if (!operation || operation.targetReleaseId !== release.id) {
+                done = true;
+                phase = '';
+                return '';
+            }
+            phase = operation.phase;
+            return phase;
+        },
+    };
+}
 /** Poll until the release settles; the platform decides when it is healthy. */
 async function waitForRelease(releaseId, apiOptions, timeoutMs = 10 * 60_000) {
     const deadline = Date.now() + timeoutMs;
     const startedAt = Date.now();
     let lastProgress = '';
     const json = readJsonFlag(process.argv);
+    let replacementClient;
+    const replacement = createReplacementProbe(async (applicationId) => {
+        replacementClient ??= await createApiClient(apiOptions);
+        return getProductionReplacement(applicationId, apiOptions, replacementClient);
+    });
     for (;;) {
         const release = await getRelease(releaseId, apiOptions);
         // A failed start on the pinned runner changes the reason, not the status.
         const reason = release.serving ? release.failureReason ?? '' : '';
-        if (`${release.status}\n${reason}` !== lastProgress) {
-            lastProgress = `${release.status}\n${reason}`;
+        // PENDING is also the whole of a stop-first replacement of production,
+        // which pulls nothing: its phase says what the wait is.
+        const phase = release.status === 'PENDING' ? await replacement.phaseOf(release) : '';
+        if (`${release.status}\n${reason}\n${phase}` !== lastProgress) {
+            lastProgress = `${release.status}\n${reason}\n${phase}`;
             // Say what is happening in words, with elapsed time — a two-minute health
             // gate in silence reads as a hang. Under --json only stdout must stay
             // parseable; progress goes to stderr.
             const shown = presentRelease(release);
+            const meaning = (phase && replacementPhaseMeaning(phase)) || shown.meaning;
             const lines = [
-                `— ${shown.label} (${formatElapsed(Date.now() - startedAt)})${shown.meaning ? `: ${shown.meaning}` : ''} —`,
+                `— ${shown.label} (${formatElapsed(Date.now() - startedAt)})${meaning ? `: ${meaning}` : ''} —`,
                 ...(reason ? [`  ${reason}`] : []),
             ];
             for (const line of lines) {
@@ -1437,9 +1725,16 @@ export function releaseEndpointLines(release, previewUrl, options = {}) {
  */
 export function privateEndpointLines(detail, active, options = {}) {
     if (!detail.privateDomain) {
-        return options.privateNetworking
-            ? ['(provisioning — private DNS and routing are being verified)']
-            : [];
+        if (!options.privateNetworking)
+            return [];
+        // The address routes to production, so without one there is nothing to
+        // verify yet, and with no serving replica it is down, not provisioning.
+        if (!active)
+            return ['(none yet — production gets one once a release is promoted)'];
+        if (active.serving && active.serving.ready === 0) {
+            return ['(unavailable — no production replica is serving; see inquir apps describe <app>)'];
+        }
+        return ['(provisioning — private DNS and routing are being verified)'];
     }
     const lines = [];
     if (detail.privateBaseUrl)
@@ -1517,6 +1812,18 @@ function formatDurationSeconds(seconds) {
     }
     return parts.join(' ');
 }
+/** One line for a startup probe; defaults as the server applies them (src/apps/startup-probe.ts). */
+export function describeStartupProbe(probe) {
+    const period = probe.periodSeconds ?? 10;
+    const threshold = probe.failureThreshold ?? 3;
+    const delay = probe.initialDelaySeconds ?? 0;
+    const mode = probe.type ?? (probe.command ? 'command' : undefined);
+    const target = mode === 'command'
+        ? `command ${JSON.stringify(probe.command ?? '')}`
+        : `${mode ?? 'probe'}${probe.port ? ` port ${probe.port}` : ''}${mode !== 'tcp' ? ` ${probe.path ?? '/'}` : ''}`;
+    return `${target}, every ${period}s, ${threshold} failure${threshold === 1 ? '' : 's'} allowed` +
+        `${delay ? ` after ${delay}s` : ''} (up to ${delay + period * threshold}s before the healthcheck)`;
+}
 export function describeScalingPolicy(policy) {
     const range = `${policy.minReplicas}–${policy.maxReplicas} replicas`;
     if (policy.activation === 'http') {
@@ -1552,6 +1859,15 @@ async function statusSubcommand(args, positionals, apiOptions) {
     const pinnedRunner = detail.volumeRunnerId;
     if (pinnedRunner)
         printLine(`  volume pin: runner ${pinnedRunner}`);
+    // Experimental service location: shown only where the platform offers it.
+    if (limits?.features?.serviceLocations) {
+        const location = await getAppLocation(app.id, apiOptions).catch(() => null);
+        const line = location ? describeServiceLocation(location) : undefined;
+        if (line)
+            printLine(`  location:   ${line}`);
+    }
+    if (detail.runtime?.startupProbe)
+        printLine(`  startup:    ${describeStartupProbe(detail.runtime.startupProbe)}`);
     const servingRelease = detail.releases.find((r) => r.id === detail.production?.activeReleaseId);
     if (servingRelease?.serving && servingRelease.serving.ready < servingRelease.serving.desired) {
         // Production points at it, but its replica does not answer on the runner yet.
@@ -1692,29 +2008,74 @@ async function logsSubcommand(args, positionals, apiOptions) {
     const build = await getBuild(identifier, apiOptions).catch(() => null);
     if (build) {
         printInfo(dim(`— build ${build.id.slice(0, 8)} (${build.status}) —`));
-        for await (const event of streamBuildLogs(build.id, apiOptions)) {
-            if (event.type === 'log' && event.line) {
-                if (json)
-                    process.stderr.write(`${redact(event.line)}\n`);
-                else
-                    printLine(event.line);
-            }
-            else if (event.type === 'complete') {
-                printInfo(dim(`— build ${event.status ?? 'finished'} —`));
-                break;
-            }
-            else if (event.type === 'error') {
-                printLine(dim(`— ${event.message ?? 'stream error'} —`));
-                break;
+        // A finished build replays its log and the stream ends by itself. A
+        // running one follows; with --no-follow, stop once the replay goes quiet.
+        const stop = new AbortController();
+        const quiet = hasFlag(args, '--no-follow') && !isTerminalBuildStatus(build.status)
+            ? createQuietStop(() => stop.abort())
+            : null;
+        try {
+            for await (const event of streamBuildLogs(build.id, apiOptions, stop.signal)) {
+                quiet?.heard();
+                if (event.type === 'log' && event.line) {
+                    if (json)
+                        process.stderr.write(`${redact(event.line)}\n`);
+                    else
+                        printLine(event.line);
+                }
+                else if (event.type === 'complete') {
+                    printInfo(dim(`— build ${event.status ?? 'finished'} —`));
+                    break;
+                }
+                else if (event.type === 'error') {
+                    printLine(dim(`— ${event.message ?? 'stream error'} —`));
+                    break;
+                }
             }
         }
+        catch (error) {
+            if (!stop.signal.aborted)
+                throw error;
+        }
+        finally {
+            quiet?.cancel();
+        }
+        if (stop.signal.aborted) {
+            printInfo(dim(`— build ${build.id.slice(0, 8)} is still running; follow it: inquir apps logs ${build.id} —`));
+        }
         return;
     }
     const releaseId = await resolveReleaseId(identifier, apiOptions);
     const tailRaw = readFlagValue(args, '--tail');
     const tail = tailRaw ? Number(tailRaw) : 200;
-    printInfo(dim(`— streaming logs for release ${releaseId.slice(0, 8)} (ctrl-c to stop) —`));
-    for await (const event of streamReleaseLogs(releaseId, { tail }, apiOptions)) {
+    if (!Number.isInteger(tail) || tail < 1 || tail > MAX_LOG_TAIL) {
+        throw usageError(`--tail must be an integer between 1 and ${MAX_LOG_TAIL}`, 'inquir apps logs <app> --tail 100');
+    }
+    const replica = readFlagValue(args, '--replica');
+    if (hasFlag(args, '--replica') && !replica?.trim())
+        throw usageError('Missing --replica value', 'inquir apps instances <app>');
+    let allocationId;
+    if (replica?.trim()) {
+        const release = await getRelease(releaseId, apiOptions);
+        // Only this release's replicas: an index or name of production would be another container.
+        allocationId = await resolveReplicaAllocationId(release.applicationId, replica, apiOptions, { releaseId: release.id });
+    }
+    if (hasFlag(args, '--no-follow')) {
+        const release = await getRelease(releaseId, apiOptions);
+        const client = await createApiClient(apiOptions);
+        const entries = await readRecentRuntimeLogs((query) => getAppLogHistory(client, release.applicationId, query), { releaseId, tail, ...(allocationId ? { allocationId } : {}) });
+        if (json) {
+            printLine(redact(JSON.stringify(entries, null, 2)));
+            return;
+        }
+        for (const entry of entries)
+            printLine(entry.message);
+        if (entries.length === 0)
+            printInfo(dim(`— no stored logs for release ${releaseId.slice(0, 8)} —`));
+        return;
+    }
+    printInfo(dim(`— streaming logs for release ${releaseId.slice(0, 8)}${allocationId ? `, replica ${allocationId.slice(0, 8)}` : ''} (ctrl-c to stop) —`));
+    for await (const event of streamReleaseLogs(releaseId, { tail, ...(allocationId ? { allocationId } : {}) }, apiOptions)) {
         if (event.type === 'log' && event.line) {
             // Under --json the log tail goes to stderr so stdout stays parseable.
             if (json)
@@ -1731,6 +2092,63 @@ async function logsSubcommand(args, positionals, apiOptions) {
         }
     }
 }
+/** The most lines `apps logs --tail` asks for (the API's own ceiling). */
+const MAX_LOG_TAIL = 2000;
+/**
+ * How far back `--no-follow` reads: inside the 7-day runtime retention with
+ * an hour to spare, so a client clock up to an hour off still names a window
+ * the API accepts. `to` is left to the server's clock.
+ */
+const RUNTIME_LOG_WINDOW_MS = 7 * 86_400_000 - 3_600_000;
+/** `logs --no-follow` on a running build: stop once its replay is this quiet... */
+const BUILD_LOG_QUIET_MS = 2_000;
+/** ...or when nothing at all arrived this long after the request (a slow connection). */
+const BUILD_LOG_FIRST_EVENT_MS = 15_000;
+/**
+ * Calls `stop` once a stream goes quiet: BUILD_LOG_FIRST_EVENT_MS before the
+ * first event (connecting may be slow), BUILD_LOG_QUIET_MS after the latest.
+ */
+export function createQuietStop(stop, timings = { firstEventMs: BUILD_LOG_FIRST_EVENT_MS, quietMs: BUILD_LOG_QUIET_MS }) {
+    let timer = setTimeout(stop, timings.firstEventMs);
+    return {
+        heard() {
+            clearTimeout(timer);
+            timer = setTimeout(stop, timings.quietMs);
+        },
+        cancel() {
+            clearTimeout(timer);
+        },
+    };
+}
+const LOG_HISTORY_PAGE = 200;
+/**
+ * `apps logs --no-follow`: the last `tail` stored lines of one release (one
+ * replica with `allocationId`), oldest first — what the live stream prints
+ * before it starts following, without the following.
+ */
+export async function readRecentRuntimeLogs(fetchPage, options) {
+    const now = options.now ?? Date.now();
+    // The first page fixes the window; later pages repeat it with the cursor.
+    let window = { from: new Date(now - RUNTIME_LOG_WINDOW_MS).toISOString() };
+    const newestFirst = [];
+    let cursor;
+    while (newestFirst.length < options.tail) {
+        const page = await fetchPage({
+            ...window,
+            releaseId: options.releaseId,
+            ...(options.allocationId ? { allocationId: options.allocationId } : {}),
+            limit: Math.min(LOG_HISTORY_PAGE, options.tail - newestFirst.length),
+            ...(cursor ? { cursor } : {}),
+        });
+        newestFirst.push(...page.entries);
+        if (!page.nextCursor || page.entries.length === 0)
+            break;
+        cursor = page.nextCursor;
+        if (page.from && page.to)
+            window = { from: page.from, to: page.to };
+    }
+    return newestFirst.slice(0, options.tail).reverse();
+}
 async function promoteSubcommand(args, positionals, apiOptions) {
     const [identifier] = positionals;
     if (!identifier)
@@ -1741,9 +2159,11 @@ async function promoteSubcommand(args, positionals, apiOptions) {
     // Say up front what promotion does to this release: a preview-profile
     // release with production-only variables is restarted with them before
     // traffic moves, and its preview URL retires.
+    let release = null;
+    let app = null;
     if (!json) {
-        const release = await getRelease(releaseId, apiOptions).catch(() => null);
-        const app = release ? await getApplication(release.applicationId, apiOptions).catch(() => null) : null;
+        release = await getRelease(releaseId, apiOptions).catch(() => null);
+        app = release ? await getApplication(release.applicationId, apiOptions).catch(() => null) : null;
         if (release && release.envProfile !== 'production' && (app?.productionOnlyEnvKeys?.length ?? 0) > 0) {
             printInfo(dim('  the container restarts with production-only variables before traffic moves'));
         }
@@ -1775,12 +2195,33 @@ async function promoteSubcommand(args, positionals, apiOptions) {
         printLine(`  ${url}`);
     }
     if ((result.productionUrls ?? []).length === 0 && !result.productionUrl) {
-        printInfo(dim('  no hostname — reach it at its TCP endpoints (inquir apps status <app>)'));
+        for (const line of promotedWithoutHostnameLines(release, app))
+            printInfo(dim(line));
     }
     if (result.previousReleaseId) {
         printInfo(dim(`  previous release ${result.previousReleaseId.slice(0, 8)} kept for rollback`));
     }
 }
+/**
+ * What to say after a promotion that produced no public URL. An HTTP service
+ * is private, not unreachable: same-workspace services reach it at its
+ * private address. Only a TCP-only service is reached at its TCP endpoints.
+ */
+export function promotedWithoutHostnameLines(release, app) {
+    const name = app?.name ?? '<app>';
+    // The server reads a port without a protocol as HTTP (src/apps/app-ports.ts).
+    const http = typeof release?.runtime?.port === 'number'
+        || (release?.runtime?.ports ?? []).some((port) => (port.protocol ?? 'http') === 'http');
+    if (http) {
+        return [
+            app?.privateBaseUrl
+                ? `  private — your other services reach it at ${app.privateBaseUrl}`
+                : `  private — your other services reach it at http://<slug>.apps.internal, listed by inquir apps status ${name} once routing is verified`,
+            `  public URL: inquir apps update ${name} --ingress public`,
+        ];
+    }
+    return [`  no hostname — reach it at its TCP endpoints (inquir apps status ${name})`];
+}
 async function rollbackSubcommand(args, positionals, apiOptions) {
     const [identifier] = positionals;
     if (!identifier)
@@ -1920,7 +2361,8 @@ async function updateSubcommand(args, positionals, apiOptions) {
     await requireAuth(apiOptions);
     const app = await resolveApplication(identifier, apiOptions);
     const envVars = parseSetFlags(readMultiFlag(args, '--set'));
-    const runtimeSpec = buildRuntimeFromFlags(args, app.runtime);
+    const flagsRuntime = buildRuntimeFromFlags(args, app.runtime);
+    const runtimeSpec = applyNodeSelectorFlags(args, flagsRuntime ?? app.runtime) ?? flagsRuntime;
     const description = readFlagValue(args, '--description');
     const networkPolicy = buildNetworkPolicyPatch({
         egress: readFlagValue(args, '--egress'),
@@ -1928,9 +2370,11 @@ async function updateSubcommand(args, positionals, apiOptions) {
         current: app.networkPolicy,
     });
     const volumeRunner = readFlagValue(args, '--volume-runner');
+    const location = parseLocationFlag(readFlagValue(args, '--location'));
     const patch = {
         ...(description !== undefined ? { description } : {}),
         ...(volumeRunner ? { volumeRunner } : {}),
+        ...(location !== undefined ? { location } : {}),
         ...(runtimeSpec ? { runtime: runtimeSpec } : {}),
         // Only the keys given here change; the server merges masked values, so
         // untouched secrets survive.
@@ -1946,7 +2390,43 @@ async function updateSubcommand(args, positionals, apiOptions) {
         return;
     }
     printSuccess(`Updated ${updated.name}`);
-    printInfo(dim('  changes apply to the next release: inquir apps deploy ' + updated.name));
+    // Advisory: e.g. a node selector no server matches right now.
+    for (const warning of updated.warnings ?? [])
+        printInfo(`  warning: ${warning}`);
+    const ingress = readFlagValue(args, '--ingress');
+    for (const line of updateTimingLines(updated.name, {
+        hasProduction: Boolean(updated.productionReleaseId ?? app.productionReleaseId),
+        ingress: ingress === 'public' || ingress === 'private' ? ingress : undefined,
+        nextRelease: Object.keys(envVars).length > 0 || runtimeSpec !== undefined
+            || readFlagValue(args, '--egress') !== undefined || volumeRunner !== undefined
+            || location !== undefined,
+    })) {
+        printInfo(dim(line));
+    }
+}
+/**
+ * When an `apps update` takes effect. Public Networking is applied by the
+ * server at once (the generated route is created or removed in the same
+ * request); env, runtime, egress, placement and location are what the next
+ * release is built from.
+ */
+export function updateTimingLines(appName, changed) {
+    const lines = [];
+    const hasProduction = changed.hasProduction !== false;
+    if (changed.ingress === 'public') {
+        lines.push(hasProduction
+            ? `  public networking: applied now — the generated domain serves production (inquir apps status ${appName})`
+            : '  public networking: on — the generated domain serves production once a release is promoted');
+    }
+    else if (changed.ingress === 'private') {
+        lines.push('  public networking: removed now — the generated domain no longer serves it; the private address stays');
+    }
+    if (changed.nextRelease) {
+        // redeploy re-releases production and refuses without one.
+        const next = hasProduction ? `inquir apps redeploy ${appName}` : `inquir apps deploy ${appName}`;
+        lines.push(`  ${changed.ingress ? 'the other changes apply' : 'changes apply'} to the next release: ${next}`);
+    }
+    return lines;
 }
 async function execSubcommand(args, positionals, apiOptions) {
     const [identifier, ...commandParts] = positionals;
@@ -1956,14 +2436,15 @@ async function execSubcommand(args, positionals, apiOptions) {
     if (!command)
         throw usageError('Missing command', 'inquir apps exec <app> -- ls -la');
     await requireAuth(apiOptions);
-    // `apps exec` is intentionally application-scoped. Accepting a stale or
-    // preview release id here and then calling the production-only app endpoint
-    // would silently change the operator's target to production.
-    const application = await resolveApplication(identifier, apiOptions);
+    const application = await resolveExecApplication(identifier, apiOptions, readJsonFlag(args));
     const timeoutRaw = readFlagValue(args, '--timeout');
+    const replica = readFlagValue(args.slice(0, args.includes('--') ? args.indexOf('--') : args.length), '--replica');
+    if (hasFlag(args.slice(0, args.includes('--') ? args.indexOf('--') : args.length), '--replica') && !replica?.trim()) {
+        throw usageError('Missing --replica value', 'inquir apps exec <app> --replica <name|index> -- <command>');
+    }
     let result;
     try {
-        result = await execInApplication(application.id, command, timeoutRaw ? Number(timeoutRaw) : undefined, apiOptions);
+        result = await execInApplication(application.id, command, timeoutRaw ? Number(timeoutRaw) : undefined, apiOptions, replica?.trim() ? { replica: replica.trim() } : {});
     }
     catch (err) {
         if (err instanceof Error)
@@ -1974,6 +2455,9 @@ async function execSubcommand(args, positionals, apiOptions) {
         printLine(JSON.stringify(result, null, 2));
     }
     else {
+        if (replica && result.replicaIndex !== undefined) {
+            printInfo(dim(`— replica ${result.replicaIndex}${result.allocationId ? ` (${result.allocationId.slice(0, 8)})` : ''} —`));
+        }
         if (result.stdout)
             process.stdout.write(result.stdout);
         if (result.stderr)
@@ -1984,6 +2468,43 @@ async function execSubcommand(args, positionals, apiOptions) {
     if (result.exitCode !== 0)
         process.exitCode = ExitCode.ERROR;
 }
+/**
+ * `apps exec` runs in production through the application-scoped endpoint. An
+ * application name or id is the target; a release id is accepted only when it
+ * is that application's production release. A stale or preview release id
+ * would otherwise silently change the operator's target to production, so it
+ * is refused with the command that does run.
+ */
+async function resolveExecApplication(identifier, apiOptions, json) {
+    let appError;
+    try {
+        return await resolveApplication(identifier, apiOptions);
+    }
+    catch (error) {
+        appError = error;
+    }
+    const release = await getRelease(identifier, apiOptions).catch(() => null);
+    if (!release)
+        throw appError;
+    const detail = await getApplication(release.applicationId, apiOptions);
+    const production = detail.production?.activeReleaseId;
+    if (production !== release.id) {
+        throw new CliError(`Release ${release.id.slice(0, 8)} is not ${detail.name}'s production release`, {
+            code: 'EXEC_NOT_PRODUCTION',
+            exitCode: ExitCode.USAGE,
+            explanation: 'apps exec runs a command in the production container only.',
+            fix: production
+                ? `Run it in production (release ${production.slice(0, 8)}): inquir apps exec ${detail.name} -- <command>`
+                : `${detail.name} has no production release yet; promote one first: inquir apps promote ${release.id.slice(0, 8)}`,
+        });
+    }
+    const note = `— ${detail.name}, production release ${release.id.slice(0, 8)} —`;
+    if (json)
+        process.stderr.write(`${note}\n`);
+    else
+        printInfo(dim(note));
+    return detail;
+}
 function printVerificationInstructions(domain) {
     const v = domain.verification;
     if (!v)