@brass-build/cli 0.1.0 → 0.2.0

package/src/args.ts

@@ -7,13 +7,16 @@ export interface ParsedArgs {
   // A flag present with no value (`--json`) stores `true`; a valued flag
   // (`--doc abc` / `--doc=abc`) stores the string.
   flags: Record<string, string | true>;
+  // Boolean flags written with a value (`--json=false`). A boolean flag is on
+  // by being present, so any value behind one contradicts the flag itself, and
+  // the reading a caller expects is the opposite of the one it would get.
+  valuedBooleans: string[];
 }
 
-// Flags that never take a value, so `brass publish --yes ./dist` parses
-// `./dist` as a positional rather than the value of `--yes`.
+// Flags that never take a value, so `brass agents pull --stdout ./dir` parses
+// `./dir` as a positional rather than the value of `--stdout`.
 const BOOLEAN_FLAGS = new Set([
   'json',
-  'yes',
   'help',
   'version',
   'stdout',
@@ -52,18 +55,102 @@ export function unknownFlags(parsed: ParsedArgs): string[] {
   return Object.keys(parsed.flags).filter((name) => !KNOWN_FLAGS.has(name));
 }
 
+// The flags every command reads, whichever it is: where to talk to and what
+// to print.
+const COMMON_FLAGS = [
+  'api-url',
+  'auth-url',
+  'dashboard-url',
+  'help',
+  'json',
+  'version',
+] as const;
+
+// What each command reads beyond those, and how many positionals it takes
+// (the command word included, so `publish [dir]` is 2). A flag one command
+// reads is not thereby a flag of the next: `--wait` is the sign-in poll's
+// deadline and `publish` has its own, so `brass publish --wait 600` waits
+// exactly as long as it would have without the flag. Refusing it names the
+// mistake, where accepting it leaves the caller believing they set something.
+const COMMAND_ARGS: Record<string, { flags: readonly string[]; positionals: number }> = {
+  login: { flags: ['check', 'new', 'start', 'wait'], positionals: 1 },
+  logout: { flags: [], positionals: 1 },
+  status: { flags: ['app', 'manifest', 'token'], positionals: 2 },
+  publish: {
+    flags: [
+      'app',
+      'client-token',
+      'gate',
+      'manifest',
+      'name',
+      'org',
+      'slug',
+      'token',
+      'visibility',
+    ],
+    positionals: 2,
+  },
+  schema: { flags: ['doc', 'out', 'token'], positionals: 2 },
+  agents: { flags: ['org', 'out', 'stdout', 'token'], positionals: 2 },
+  whoami: { flags: ['token'], positionals: 1 },
+};
+
+// The flags `command` does not read, out of the ones this CLI knows. A name
+// the CLI knows nowhere is `unknownFlags`' answer and stays there, so a
+// misspelling is reported as one rather than as a flag of another command.
+// A command this CLI does not have answers for itself.
+export function flagsNotReadBy(parsed: ParsedArgs, command: string): string[] {
+  const spec = COMMAND_ARGS[command];
+  if (spec === undefined) return [];
+  const reads = new Set<string>([...COMMON_FLAGS, ...spec.flags]);
+  return Object.keys(parsed.flags).filter(
+    (name) => KNOWN_FLAGS.has(name) && !reads.has(name),
+  );
+}
+
+// The positionals past the ones `command` reads. An ignored one is the same
+// silence a flag no command reads leaves: `brass publish out dist` publishes
+// `out`, and the caller who meant `dist` is told nothing.
+export function extraPositionals(parsed: ParsedArgs, command: string): string[] {
+  const spec = COMMAND_ARGS[command];
+  if (spec === undefined) return [];
+  return parsed.positionals.slice(spec.positionals);
+}
+
+// The flags of `command` that carry a value, so a bare one is the caller
+// naming something the run then resolves a default for. `--wait` is absent
+// here because a bare `--wait` is its own answer (the default deadline).
+export function valueFlagsOf(command: string): string[] {
+  const spec = COMMAND_ARGS[command];
+  if (spec === undefined) return [];
+  return [...COMMON_FLAGS, ...spec.flags].filter(
+    (name) => !BOOLEAN_FLAGS.has(name) && name !== 'wait',
+  );
+}
+
 // Which of `names` were given without a value (`--api-url --json`, or
 // `--api-url` last on the line). The parser stores those as `true` and
 // `stringFlag` reads that as absent, so an origin flag in this state resolves
 // the production default while the command line names another stack. That is
 // the same silent retarget `unknownFlags` catches for a misspelled name.
+//
+// An EMPTY value counts, and it is the shape a caller actually reaches: a
+// script writing `--slug "$SLUG"` against an unset variable passes the flag
+// with nothing behind it. That value is not absent the way a bare flag is, so
+// it resolves no default and travels to the server as an empty string, where
+// the mistake is reported (if at all) in the server's vocabulary rather than
+// as the missing value it is.
 export function valuelessFlags(parsed: ParsedArgs, names: readonly string[]): string[] {
-  return names.filter((name) => parsed.flags[name] === true);
+  return names.filter((name) => {
+    const value = parsed.flags[name];
+    return value === true || value === '';
+  });
 }
 
 export function parseArgs(argv: readonly string[]): ParsedArgs {
   const positionals: string[] = [];
   const flags: Record<string, string | true> = {};
+  const valuedBooleans: string[] = [];
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === undefined) continue;
@@ -71,7 +158,16 @@ export function parseArgs(argv: readonly string[]): ParsedArgs {
       const body = arg.slice(2);
       const eq = body.indexOf('=');
       if (eq !== -1) {
-        flags[body.slice(0, eq)] = body.slice(eq + 1);
+        const name = body.slice(0, eq);
+        if (BOOLEAN_FLAGS.has(name)) {
+          // Recorded rather than read: `--json=false` reads as ON, which is
+          // the reverse of what the caller wrote, and `--stdout=false` would
+          // send a file's contents to stdout and write nothing.
+          valuedBooleans.push(name);
+          flags[name] = true;
+          continue;
+        }
+        flags[name] = body.slice(eq + 1);
         continue;
       }
       if (BOOLEAN_FLAGS.has(body)) {
@@ -89,7 +185,7 @@ export function parseArgs(argv: readonly string[]): ParsedArgs {
       positionals.push(arg);
     }
   }
-  return { positionals, flags };
+  return { positionals, flags, valuedBooleans };
 }
 
 // Read a flag expected to carry a string value; a bare boolean flag (no

package/src/cli.ts

@@ -6,7 +6,10 @@ import {
   parseArgs,
   stringFlag,
   boolFlag,
+  extraPositionals,
+  flagsNotReadBy,
   unknownFlags,
+  valueFlagsOf,
   valuelessFlags,
   type ParsedArgs,
 } from './args.js';
@@ -18,10 +21,15 @@ import {
   type Origins,
   type Profile,
 } from './config.js';
-import { readCredentialsFile, readPendingLogin, writeStoredCredential } from './store.js';
+import {
+  readCredentialsFile,
+  readPendingLogin,
+  writePendingLogin,
+  writeStoredCredential,
+} from './store.js';
 import { BrassApi, BrassApiError, type AppVisibility } from './api.js';
 import { serviceTokenAuth, type AuthProvider } from './auth.js';
-import { loginDevice, sessionAuth } from './session.js';
+import { loginDevice, postDeviceCancel, postSignOut, sessionAuth } from './session.js';
 import { loginStart, loginCheck } from './login.js';
 import { createLogger, type Logger } from './log.js';
 import {
@@ -31,6 +39,7 @@ import {
   whoami,
   status,
   type CommandContext,
+  type CredentialKind,
 } from './commands.js';
 import { readProjectState, resolveAppId, readManifest } from './project.js';
 
@@ -47,7 +56,7 @@ Usage:
   brass login --check        Check a started sign-in once; stores the session when approved.
                              --wait [seconds] polls until approved (default 120s), renewing
                              an expired code in place and printing the new one.
-  brass logout               Forget the stored sign-in for this environment.
+  brass logout               End the stored sign-in for this environment, here and on the server.
   brass status [dir]         Report the credential + app state and the one command to run next.
   brass publish [dir]        Build output in [dir] (default: dist) is deployed to the app's hosting.
   brass schema pull --doc <docId> [--out brass-app.json]
@@ -82,8 +91,15 @@ Publish flags:
 export async function run(argv: readonly string[]): Promise<number> {
   const parsed = parseArgs(argv);
   const command = parsed.positionals[0];
-
-  if (boolFlag(parsed, 'version') && command === undefined) {
+  // Which credential the invocation resolved, once it has. A 401 is reported
+  // in that credential's own vocabulary, so it stays undefined until
+  // `buildContext` settles it and a failure before then carries no guess.
+  let credentialKind: CredentialKind | undefined;
+
+  // Answered whichever command follows, like `--help` beside it: both are
+  // declared flags of every command (`COMMON_FLAGS`), so a caller who asks
+  // which version is installed gets the answer rather than a publish.
+  if (boolFlag(parsed, 'version')) {
     process.stdout.write(`${VERSION}\n`);
     return 0;
   }
@@ -103,6 +119,41 @@ export async function run(argv: readonly string[]): Promise<number> {
     return 1;
   }
 
+  // Then what THIS command reads, which is the same check one scope in: a
+  // flag or a positional the command ignores leaves the run differing from
+  // what the command line asked for, with nothing said. Judged from argv
+  // alone, so it answers a caller who has not signed in.
+  const misplaced = flagsNotReadBy(parsed, command);
+  if (misplaced.length > 0) {
+    const names = misplaced.map((n) => `--${n}`).join(', ');
+    process.stderr.write(
+      `error: ${names} ${misplaced.length === 1 ? 'is not a flag' : 'are not flags'} of \`brass ${command}\`\n\n${USAGE}`,
+    );
+    return 1;
+  }
+  const extra = extraPositionals(parsed, command);
+  if (extra.length > 0) {
+    const args = extra.map((p) => JSON.stringify(p)).join(', ');
+    process.stderr.write(
+      `error: unexpected ${extra.length === 1 ? 'argument' : 'arguments'} ${args} for \`brass ${command}\`\n\n${USAGE}`,
+    );
+    return 1;
+  }
+  if (parsed.valuedBooleans.length > 0) {
+    const names = parsed.valuedBooleans.map((n) => `--${n}`).join(', ');
+    process.stderr.write(
+      `error: ${names} ${parsed.valuedBooleans.length === 1 ? 'takes' : 'take'} no value\n`,
+    );
+    return 1;
+  }
+  const bare = valuelessFlags(parsed, valueFlagsOf(command));
+  if (bare.length > 0) {
+    process.stderr.write(
+      `error: Missing value for ${bare.map((n) => `--${n}`).join(', ')}\n`,
+    );
+    return 1;
+  }
+
   const json = boolFlag(parsed, 'json');
   const log = createLogger(json);
 
@@ -115,32 +166,63 @@ export async function run(argv: readonly string[]): Promise<number> {
     // (and the next step to obtain one) is a first-class outcome, not an error.
     if (command === 'status') return await runStatus(parsed, log);
 
-    const ctx = await buildContext(parsed);
-    switch (command) {
-      case 'publish':
-        log.result(await runPublish(ctx, parsed));
-        return 0;
-      case 'schema':
-        log.result(await runSchema(ctx, parsed));
-        return 0;
-      case 'agents':
-        log.result(await runAgents(ctx, parsed));
-        return 0;
-      case 'whoami':
-        log.result(await whoami(ctx));
-        return 0;
-      default:
-        process.stderr.write(`Unknown command "${command}".\n\n${USAGE}`);
-        return 1;
+    // What the caller asked for is decided from argv alone, so it is decided
+    // BEFORE a credential is resolved. A misspelt command, a missing
+    // subcommand and an invalid flag value are all answerable without one, and
+    // resolving the credential first answers every one of them with "No
+    // credential. Run `brass login`": the caller re-authenticates over a typo,
+    // and only a caller who already has a credential is ever shown the message
+    // naming the real mistake.
+    if (!isCredentialedCommand(command)) {
+      process.stderr.write(`Unknown command "${command}".\n\n${USAGE}`);
+      return 1;
     }
+    const plan = planCommand(command, parsed);
+
+    const ctx = await buildContext(parsed);
+    credentialKind = ctx.credentialKind;
+    log.result(await plan(ctx));
+    return 0;
   } catch (err) {
-    process.stderr.write(`${formatError(err)}\n`);
+    process.stderr.write(`${formatError(err, credentialKind)}\n`);
     return 1;
   }
 }
 
 type Context = CommandContext;
 
+// The commands that need a resolved credential; `login` / `logout` / `status`
+// are answered above without one.
+const CREDENTIALED_COMMANDS = ['publish', 'schema', 'agents', 'whoami'] as const;
+type CredentialedCommand = (typeof CREDENTIALED_COMMANDS)[number];
+
+function isCredentialedCommand(value: string): value is CredentialedCommand {
+  return (CREDENTIALED_COMMANDS as readonly string[]).includes(value);
+}
+
+// The work a command will do once it has a credential.
+type CommandPlan = (ctx: Context) => Promise<unknown>;
+
+// Resolve argv to that work, validating everything argv alone decides and
+// throwing on a shape the caller got wrong. Splitting the plan from the run is
+// what lets the shape be judged before a credential is resolved.
+function planCommand(command: CredentialedCommand, parsed: ParsedArgs): CommandPlan {
+  switch (command) {
+    case 'publish':
+      return planPublish(parsed);
+    case 'schema':
+      return planSchema(parsed);
+    case 'agents':
+      return planAgents(parsed);
+    case 'whoami':
+      return (ctx): Promise<unknown> => whoami(ctx);
+    default: {
+      const exhaustive: never = command;
+      throw new Error(`Unhandled command "${String(exhaustive)}"`);
+    }
+  }
+}
+
 interface Base {
   origins: Origins;
   profile: Profile;
@@ -226,6 +308,7 @@ async function runLogin(parsed: ParsedArgs, log: Logger): Promise<number> {
       profile,
       log,
       ...(boolFlag(parsed, 'new') ? { force: true } : {}),
+      ...(waitSeconds !== undefined ? { resultFollows: true } : {}),
     });
     // `--start --wait` is the whole sign-in in one command: relay the code it
     // prints, then it holds for the approval up to the deadline.
@@ -245,10 +328,38 @@ async function runLogin(parsed: ParsedArgs, log: Logger): Promise<number> {
 }
 
 async function runLogout(parsed: ParsedArgs, log: Logger): Promise<number> {
-  const { profile } = resolveBase(parsed);
+  const { origins, profile } = resolveBase(parsed);
+
+  // Revoke on the server first, while the pointer is still readable. A
+  // service token belongs to an organization and is revoked in the dashboard,
+  // so only a stored session has anything to end here.
+  const file = await readCredentialsFile();
+  const stored = file?.credentials[profile]?.session?.sid;
+  const signedOut = stored === undefined ? true : await postSignOut(origins.authBaseUrl, stored);
+
+  // A started sign-in is redeemable by whoever holds the device code, and a
+  // human may still approve it after this command returns, so cancelling it on
+  // the server is what a sign-out owes. Dropping the local record alone would
+  // leave the grant live and this machine unable to name it.
+  const pending = await readPendingLogin(profile);
+  const cancelled =
+    pending === null ? true : await postDeviceCancel(origins.authBaseUrl, pending.deviceCode);
+
   await writeStoredCredential(profile, null);
-  log.success('Signed out.');
-  log.result({ signed_out: true });
+  await writePendingLogin(profile, null);
+  const revoked = signedOut && cancelled;
+
+  // The local credential is gone either way, so say so, and name the part
+  // that did not happen rather than reporting a clean sign-out over a
+  // credential that still works.
+  if (revoked) {
+    log.success('Signed out.');
+  } else {
+    log.success(
+      'Signed out on this machine. Brass could not be reached to revoke the sign-in, so run `brass logout` again when it is.',
+    );
+  }
+  log.result({ signed_out: true, revoked });
   return 0;
 }
 
@@ -317,7 +428,7 @@ async function runStatus(parsed: ParsedArgs, log: Logger): Promise<number> {
   return 0;
 }
 
-async function runPublish(ctx: Context, parsed: ParsedArgs): Promise<unknown> {
+function planPublish(parsed: ParsedArgs): CommandPlan {
   const dir = parsed.positionals[1] ?? 'dist';
   const flagApp = stringFlag(parsed, 'app');
   const envApp = process.env['BRASS_APP_ID'];
@@ -325,26 +436,29 @@ async function runPublish(ctx: Context, parsed: ParsedArgs): Promise<unknown> {
   const org = stringFlag(parsed, 'org');
   const slug = stringFlag(parsed, 'slug');
   const clientToken = stringFlag(parsed, 'client-token');
+  const manifestPath = stringFlag(parsed, 'manifest') ?? 'brass-app.json';
   const visibility = parseVisibilityFlag(stringFlag(parsed, 'visibility'));
   const requireAccess = parseGateFlag(stringFlag(parsed, 'gate'));
-  const state = await readProjectState(ctx.cwd);
-  const appId = resolveAppId({
-    ...(flagApp !== undefined ? { flagApp } : {}),
-    ...(envApp !== undefined ? { envApp } : {}),
-    state,
-    profile: ctx.profile,
-  });
-  return publish(ctx, {
-    dir,
-    manifestPath: stringFlag(parsed, 'manifest') ?? 'brass-app.json',
-    ...(appId !== null ? { appId } : {}),
-    ...(name !== undefined ? { name } : {}),
-    ...(org !== undefined ? { organizationId: org } : {}),
-    ...(clientToken !== undefined ? { clientToken } : {}),
-    ...(slug !== undefined ? { slug } : {}),
-    ...(visibility !== undefined ? { visibility } : {}),
-    ...(requireAccess !== undefined ? { requireAccess } : {}),
-  });
+  return async (ctx): Promise<unknown> => {
+    const state = await readProjectState(ctx.cwd);
+    const appId = resolveAppId({
+      ...(flagApp !== undefined ? { flagApp } : {}),
+      ...(envApp !== undefined ? { envApp } : {}),
+      state,
+      profile: ctx.profile,
+    });
+    return publish(ctx, {
+      dir,
+      manifestPath,
+      ...(appId !== null ? { appId } : {}),
+      ...(name !== undefined ? { name } : {}),
+      ...(org !== undefined ? { organizationId: org } : {}),
+      ...(clientToken !== undefined ? { clientToken } : {}),
+      ...(slug !== undefined ? { slug } : {}),
+      ...(visibility !== undefined ? { visibility } : {}),
+      ...(requireAccess !== undefined ? { requireAccess } : {}),
+    });
+  };
 }
 
 // How long `--wait` holds for the approval: bare `--wait` takes the default,
@@ -386,33 +500,48 @@ function parseGateFlag(value: string | undefined): boolean | undefined {
   return value === 'on';
 }
 
-async function runSchema(ctx: Context, parsed: ParsedArgs): Promise<unknown> {
-  const sub = parsed.positionals[1];
-  if (sub === 'pull') {
-    const docId = stringFlag(parsed, 'doc');
-    if (docId === undefined) throw new Error('brass schema pull requires --doc <docId>');
-    return schemaPull(ctx, { docId, outPath: stringFlag(parsed, 'out') ?? 'brass-app.json' });
+function planSchema(parsed: ParsedArgs): CommandPlan {
+  if (parsed.positionals[1] !== 'pull') {
+    throw new Error('Usage: brass schema pull --doc <docId> [--out brass-app.json]');
   }
-  throw new Error('Usage: brass schema pull --doc <docId> [--out brass-app.json]');
+  const docId = stringFlag(parsed, 'doc');
+  if (docId === undefined) throw new Error('brass schema pull requires --doc <docId>');
+  const outPath = stringFlag(parsed, 'out') ?? 'brass-app.json';
+  return (ctx): Promise<unknown> => schemaPull(ctx, { docId, outPath });
 }
 
-async function runAgents(ctx: Context, parsed: ParsedArgs): Promise<unknown> {
+function planAgents(parsed: ParsedArgs): CommandPlan {
   if (parsed.positionals[1] !== 'pull') {
     throw new Error(
       'Usage: brass agents pull [--out AGENTS.md | --stdout] [--org <organizationId>]',
     );
   }
+  // Both flags claim stdout: `--stdout` puts the instructions there verbatim,
+  // `--json` the result object. Together they interleave two payloads on one
+  // stream, so a caller parsing either reads the other's bytes as part of it.
+  if (boolFlag(parsed, 'stdout') && boolFlag(parsed, 'json')) {
+    throw new Error(
+      'Pass one of --stdout or --json: both write to stdout, so together neither is parseable.',
+    );
+  }
   const org = stringFlag(parsed, 'org');
-  return agentsPull(ctx, {
+  const options = {
     outPath: stringFlag(parsed, 'out') ?? 'AGENTS.md',
     ...(boolFlag(parsed, 'stdout') ? { stdout: true } : {}),
     ...(org !== undefined ? { organizationId: org } : {}),
-  });
+  };
+  return (ctx): Promise<unknown> => agentsPull(ctx, options);
 }
 
-function formatError(err: unknown): string {
+// Render a failure for the terminal, naming the fix for a 401 in the
+// vocabulary of the credential that was actually rejected. A session's
+// refusal already arrives carrying `brass login` (the refresh authors it), so
+// appending a service-token hint there tells the caller to check an
+// environment variable they never set, next to the sentence naming the real
+// fix. `status` classifies the same 401 the same way.
+function formatError(err: unknown, credentialKind?: CredentialKind): string {
   if (err instanceof BrassApiError) {
-    if (err.status === 401) {
+    if (err.status === 401 && credentialKind !== 'session') {
       return `error: ${err.message} (the credential was rejected; check BRASS_SERVICE_TOKEN or --token)`;
     }
     return `error: ${err.message}`;

package/src/commands.ts

@@ -109,7 +109,7 @@ export async function publish(ctx: CommandContext, opts: PublishOptions): Promis
   if (opts.visibility !== undefined) {
     await ensureVisibility(ctx, appId, opts.visibility, resolved.detail?.visibility);
   }
-  const hosting = await ensureHosting(ctx, appId, opts.slug);
+  const hosting = await ensureHosting(ctx, appId, opts.slug, opts.requireAccess);
   if (opts.requireAccess !== undefined) {
     await ensureGate(ctx, appId, opts.requireAccess, hosting);
   }
@@ -126,7 +126,12 @@ export async function publish(ctx: CommandContext, opts: PublishOptions): Promis
   // of a couple of reads instead of an upload and a poll loop.
   const unchanged = await activeVersionMatches(ctx, appId, hash);
   if (unchanged !== null) {
-    const status = await ctx.api.get<HostingStatus>(`/apps/${encodeURIComponent(appId)}/hosting`);
+    const status = await awaitGateSettled(
+      ctx,
+      appId,
+      await ctx.api.get<HostingStatus>(`/apps/${encodeURIComponent(appId)}/hosting`),
+      opts.sleep ?? realSleep,
+    );
     ctx.log.success(`Already up to date${status.url ? `: ${status.url}` : ''}`);
     // Refreshed here too, so publishing twice says the same thing both times.
     // A publisher acting on a warning re-runs publish to check, and a signal
@@ -164,7 +169,12 @@ export async function publish(ctx: CommandContext, opts: PublishOptions): Promis
   // schema missing `family`) right here instead of silently later.
   const warnings = await refreshCapabilities(ctx, appId);
 
-  const status = await ctx.api.get<HostingStatus>(`/apps/${encodeURIComponent(appId)}/hosting`);
+  const status = await awaitGateSettled(
+    ctx,
+    appId,
+    await ctx.api.get<HostingStatus>(`/apps/${encodeURIComponent(appId)}/hosting`),
+    opts.sleep ?? realSleep,
+  );
   if (status.url) ctx.log.success(`Deployed: ${status.url}`);
   return { app_id: appId, version_id: version.version_id, url: status.url, warnings };
 }
@@ -223,14 +233,13 @@ async function ensureVisibility(
 }
 
 // Converge the hosted load gate to `want` (`true` = gated to the audience,
-// `false` = world-loadable). Always PATCH, even when the DDB flag already
-// reads `want`: the PATCH is what reaches the server-side reconcile that
-// repairs a wedged edge marker (a prior toggle whose flag write landed but
-// whose marker write lost every ETag race leaves the flag reading correct
-// while the marker disagrees). Skipping the PATCH on a matching flag would
-// leave such a gate wedged forever, since every later publish would skip it
-// too. `status` is the state `ensureHosting` just observed, used only to word
-// the log line. (`require_access` absent === off.)
+// `false` = world-loadable). Always PATCH, even when the reported state
+// already reads `want`: the PATCH is what asks the platform to re-settle a
+// gate whose reported and served states have drifted apart, which reading the
+// reported one alone cannot detect. Skipping it on a match would leave such an
+// app stuck, since every later publish would skip it too. `status` is the
+// state `ensureHosting` just observed, used only to word the log line.
+// (`require_access` absent === off.)
 async function ensureGate(
   ctx: CommandContext,
   appId: string,
@@ -250,15 +259,22 @@ async function ensureGate(
   }
 }
 
+// Enable hosting when the app is not hosted yet, at the load-gate state the
+// publish wants. Stating the gate here rather than leaving it to the PATCH
+// below settles it in one step: a new slot is gated by default, so a publish
+// that wants a world-loadable one would otherwise turn the gate on and
+// straight back off, doing twice the work to reach one state.
 async function ensureHosting(
   ctx: CommandContext,
   appId: string,
   slug?: string,
+  requireAccess?: boolean,
 ): Promise<HostingStatus> {
   const status = await ctx.api.get<HostingStatus>(`/apps/${encodeURIComponent(appId)}/hosting`);
   if (status.enabled) return status;
-  const body: { slug?: string } = {};
+  const body: { slug?: string; require_access?: boolean } = {};
   if (slug !== undefined) body.slug = slug;
+  if (requireAccess !== undefined) body.require_access = requireAccess;
   const enabled = await ctx.api.post<HostingStatus>(
     `/apps/${encodeURIComponent(appId)}/hosting`,
     body,
@@ -267,11 +283,42 @@ async function ensureHosting(
   return enabled;
 }
 
-// The currently-served version when it is `ready` and already carries
-// `hash`, else null. A null (no active version, a non-ready active version, or
-// a hash mismatch) means `publish` must upload. A first deploy has no active
-// version, so it always uploads; a version predating content hashing has no
-// recorded hash and so never matches, forcing one re-upload that self-heals.
+// A published bundle is not reachable until the platform has registered the
+// slot to serve it, and that registration can lag or fail on its own. Reading
+// the status is what asks the platform to settle it, so a slot that is not
+// ready yet is re-read a few times before publish gives up. Publishing
+// reports success only once the slot will actually serve, so an unreachable
+// one is a failed publish rather than a URL that answers 404.
+const GATE_SETTLE_ATTEMPTS = 3;
+const GATE_SETTLE_GAP_MS = 2000;
+
+async function awaitGateSettled(
+  ctx: CommandContext,
+  appId: string,
+  status: HostingStatus,
+  sleep: (ms: number) => Promise<void>,
+): Promise<HostingStatus> {
+  // An api that does not report the field tells us nothing to act on.
+  if (status.gate_settled !== false) return status;
+  for (let attempt = 1; attempt < GATE_SETTLE_ATTEMPTS; attempt++) {
+    await sleep(GATE_SETTLE_GAP_MS);
+    const latest = await ctx.api.get<HostingStatus>(`/apps/${encodeURIComponent(appId)}/hosting`);
+    if (latest.gate_settled !== false) return latest;
+  }
+  // Says what is true of the SLOT, because both publish paths end here: the
+  // one that uploaded a new bundle and the one that found the app already
+  // serving this exact bundle and skipped the upload. A message naming an
+  // upload sends the second caller looking for one that never happened.
+  throw new Error(
+    'The hosted slot never registered, so it will not serve. ' +
+      'Run publish again to retry.',
+  );
+}
+
+// The currently-served version when it is `ready` and already carries `hash`,
+// else null. A null (no active version, a non-ready active version, or a hash
+// mismatch) means `publish` must upload. A first deploy has no active version,
+// so it always uploads.
 async function activeVersionMatches(
   ctx: CommandContext,
   appId: string,
@@ -287,8 +334,8 @@ async function activeVersionMatches(
 
 // Poll until the version reaches a KNOWN terminal state (`ready` / `failed`),
 // then return it; time out otherwise. Deliberately loops while the status is
-// anything other than a known terminal — `pending` OR any status this pinned
-// CLI does not recognize — rather than returning on `!== 'pending'`. That way
+// anything other than a known terminal (`pending`, or any status this pinned
+// CLI does not recognize) rather than returning on `!== 'pending'`. That way
 // a future server status (a finer-grained non-terminal like `unpacking`, or a
 // new terminal-failure like `rejected`) is not mistaken for "done": an
 // unrecognized non-terminal keeps polling, and an unrecognized terminal