@brass-build/cli 0.2.0 → 0.4.0

package/src/login.ts

@@ -14,13 +14,14 @@
 // place with a fresh one whose code is printed. A caller that has to relay a
 // second code because the first expired is the cost being avoided.
 
-import { deviceAuthorize, pollDeviceTokenOnce, decodeEmail } from './session.js';
+import { deviceAuthorize, pollDeviceTokenOnce, postDeviceCancel, decodeEmail } from './session.js';
 import {
   readPendingLogin,
   writePendingLogin,
   writeStoredCredential,
   type PendingLogin,
 } from './store.js';
+import { renderApprovalPrompt } from './approval-prompt.js';
 import type { Logger } from './log.js';
 import type { Profile } from './config.js';
 
@@ -37,6 +38,9 @@ export interface LoginStartOptions {
   // Mint a fresh grant even when a usable one is pending (`--new`), for a
   // human who lost the relayed code.
   force?: boolean;
+  // The app to approve alongside the CLI (`--app`), so one human action
+  // covers the sign-in and the app the machine will hand a browser.
+  targetAppId?: string;
   // Set when a wait follows in the same command (`--start --wait`), whose own
   // terminal result is the one the caller reads. `--json` is one document per
   // run, so the started state prints to the human stream only.
@@ -56,10 +60,24 @@ export async function loginStart(options: LoginStartOptions): Promise<number> {
   // second code and forgets the first, so an approval the human is part-way
   // through completes a grant the CLI can no longer redeem and they are asked
   // to sign in again.
-  const existing = options.force === true ? null : await readPendingLogin(options.profile, env);
+  const existing = await readPendingLogin(options.profile, env);
   const resumed =
-    existing !== null && existing.expiresAt - now() > MIN_USABLE_REMAINING_MS ? existing : null;
-  const pending = resumed ?? (await mintPendingLogin(options.authBaseUrl, now(), options.profile, env));
+    options.force !== true &&
+    existing !== null &&
+    existing.expiresAt - now() > MIN_USABLE_REMAINING_MS
+      ? existing
+      : null;
+  // A superseded grant that is still live stays approvable on the server for
+  // the rest of its TTL while this machine forgets the only copy of its
+  // device code, so cancel it before the record is overwritten. Best-effort:
+  // an undelivered cancel leaves a grant nobody can redeem from here, and the
+  // new grant is the one this command is for.
+  if (resumed === null && existing !== null && existing.expiresAt > now()) {
+    await postDeviceCancel(existing.authBaseUrl, existing.deviceCode);
+  }
+  const pending =
+    resumed ??
+    (await mintPendingLogin(options.authBaseUrl, now(), options.profile, env, options.targetAppId));
   promptFor(options.log, pending, {
     lead: resumed === null ? null : 'A sign-in is already waiting for approval.',
   });
@@ -119,7 +137,13 @@ export async function loginCheck(options: LoginCheckOptions): Promise<number> {
 
   for (;;) {
     if (now() >= pending.expiresAt) {
-      pending = await mintPendingLogin(pending.authBaseUrl, now(), options.profile, env);
+      pending = await mintPendingLogin(
+        pending.authBaseUrl,
+        now(),
+        options.profile,
+        env,
+        pending.targetAppId,
+      );
       intervalSeconds = pending.intervalSeconds;
       renewed = true;
       promptFor(options.log, pending, {
@@ -135,7 +159,7 @@ export async function loginCheck(options: LoginCheckOptions): Promise<number> {
       }
       await writeStoredCredential(
         options.profile,
-        { session: { sid: outcome.tokens.sessionToken } },
+        { session: { sid: outcome.tokens.sessionToken, authBaseUrl: pending.authBaseUrl } },
         env,
       );
       await writePendingLogin(options.profile, null, env);
@@ -178,11 +202,13 @@ async function mintPendingLogin(
   now: number,
   profile: Profile,
   env: NodeJS.ProcessEnv,
+  targetAppId?: string,
 ): Promise<PendingLogin> {
-  const auth = await deviceAuthorize(authBaseUrl, now);
+  const auth = await deviceAuthorize(authBaseUrl, now, targetAppId);
   const pending: PendingLogin = {
     authBaseUrl,
     deviceCode: auth.deviceCode,
+    ...(targetAppId !== undefined ? { targetAppId } : {}),
     userCode: auth.userCode,
     verificationUri: auth.verificationUri,
     ...(auth.verificationUriComplete !== undefined
@@ -203,15 +229,14 @@ function remainingSeconds(pending: PendingLogin, now: number): number {
   return Math.max(0, Math.round((pending.expiresAt - now) / 1000));
 }
 
-// The one rendering of "here is what to relay, and here is what to run next",
-// so a resumed, renewed, and freshly minted grant all read the same to whoever
-// is relaying it.
 function promptFor(log: Logger, pending: PendingLogin, opts: { lead: string | null }): void {
   log.info(
-    (opts.lead !== null ? `${opts.lead}\n` : '') +
-      'To approve this sign-in, go to:\n' +
-      `  ${targetUrl(pending)}\n` +
-      `and confirm the code:  ${pending.userCode}\n` +
-      '\nThen run `brass login --check --wait` to finish signing in.',
+    renderApprovalPrompt({
+      url: targetUrl(pending),
+      code: pending.userCode,
+      lead: opts.lead,
+      nextCommand: 'brass login --check --wait',
+      relaying: true,
+    }),
   );
 }

package/src/project.ts

@@ -1,5 +1,5 @@
 import { readFile, writeFile, readdir, stat, mkdir, realpath } from 'node:fs/promises';
-import { join, relative, sep, dirname } from 'node:path';
+import { join, relative, resolve, sep, dirname } from 'node:path';
 import { createHash } from 'node:crypto';
 import { zipSync } from 'fflate';
 import type { BrassSchemaManifest } from './api.js';
@@ -84,15 +84,90 @@ export interface AppManifest {
   [key: string]: unknown;
 }
 
+// The manifest filename, and the bundle-relative directory the capability
+// docs put it in.
+export const MANIFEST_FILENAME = 'brass-app.json';
+const WELL_KNOWN_DIR = '.well-known';
+
+// Where `publish` and `status` look for the served manifest, most
+// authoritative first. The copy inside the bundle is the one the platform
+// reads back after a deploy, so it outranks the repo root, which is the flat
+// layout an app that keeps its manifest beside `package.json` uses.
+export function publishManifestCandidates(dir: string): string[] {
+  return [join(dir, WELL_KNOWN_DIR, MANIFEST_FILENAME), MANIFEST_FILENAME];
+}
+
+// Where `schema pull` looks for a manifest to merge a pulled schema into.
+// Source locations only: a bundler rewrites its output directory on the next
+// build, so a schema written there is gone before the app is published. Each
+// candidate is used only when it already holds a file, so a layout this list
+// does not name falls back to the root default rather than being guessed at.
+export function sourceManifestCandidates(): string[] {
+  return [
+    MANIFEST_FILENAME,
+    join(WELL_KNOWN_DIR, MANIFEST_FILENAME),
+    join('public', WELL_KNOWN_DIR, MANIFEST_FILENAME),
+    join('static', WELL_KNOWN_DIR, MANIFEST_FILENAME),
+  ];
+}
+
+// Absent means no file at this path, which is what lets a caller walk a
+// candidate list. Every other failure throws: a manifest that exists and
+// cannot be parsed is a mistake to report, and answering it with `null` drops
+// the `name` and `client_token` it was written to carry, which reads as a
+// missing manifest and creates a duplicate app on the next stateless run.
 export async function readManifest(path: string): Promise<AppManifest | null> {
+  let raw: string;
   try {
-    const raw = await readFile(path, 'utf8');
-    const parsed = JSON.parse(raw) as unknown;
-    if (typeof parsed !== 'object' || parsed === null) return null;
-    return parsed as AppManifest;
-  } catch {
-    return null;
+    raw = await readFile(path, 'utf8');
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT' || code === 'ENOTDIR') return null;
+    throw new Error(`Could not read the manifest at ${path}: ${(err as Error).message}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch (err) {
+    throw new Error(`The manifest at ${path} is not valid JSON: ${(err as Error).message}`);
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`The manifest at ${path} must hold a JSON object.`);
+  }
+  return parsed as AppManifest;
+}
+
+// The first candidate that holds a manifest, paired with the path it came
+// from so a caller can name it. A candidate with no file is skipped; one that
+// is present and unreadable throws out of `readManifest`, so a malformed
+// manifest is reported rather than passed over for the next candidate down.
+export async function loadFirstManifest(
+  cwd: string,
+  candidates: readonly string[],
+): Promise<{ path: string; manifest: AppManifest } | null> {
+  for (const candidate of candidates) {
+    const manifest = await readManifest(resolve(cwd, candidate));
+    if (manifest !== null) return { path: candidate, manifest };
+  }
+  return null;
+}
+
+// The first candidate that holds a file, without parsing it. `schema pull`
+// picks its destination this way so it merges into a malformed manifest's
+// path and fails there, instead of stepping over it and writing a second
+// manifest the bundle never serves.
+export async function firstExistingManifestPath(
+  cwd: string,
+  candidates: readonly string[],
+): Promise<string | null> {
+  for (const candidate of candidates) {
+    try {
+      if ((await stat(resolve(cwd, candidate))).isFile()) return candidate;
+    } catch {
+      // Not there, or not reachable through this path. Try the next.
+    }
   }
+  return null;
 }
 
 export async function writeManifest(path: string, manifest: AppManifest): Promise<void> {

package/src/sdk-pairing.ts

@@ -0,0 +1,53 @@
+// Which `@brass-build/client` this CLI is allowed to use.
+//
+// The dependency is pinned to one exact version, and what the CLI imports is
+// the `internal` subpath, the entry that promises nothing from one release to
+// the next. So the only copy it can run against is the one it names, and a
+// correct install always provides it.
+//
+// What does not is a CLI running somewhere its own dependency is not
+// reachable, and every way in is quiet. `npx brass` from a directory with no
+// `node_modules` fetches the CLI alone from the registry. `npm i -g` nests a
+// registry copy under the CLI. Installing the CLI tarball by itself resolves
+// the SDK from npm, which succeeds precisely because an unreleased build in a
+// working tree still carries the last released version number.
+//
+// The check is on the VERSION, not on any one export, and that is the point:
+// a check per export is re-earned every time the CLI reaches for a new one,
+// and it reports whatever that call happened to need rather than the pairing
+// that is actually wrong. One version comparison covers every surface the CLI
+// imports today and every one it adds later.
+
+export interface LoadedSdk {
+  version: string;
+  // Which file answered. The version cannot identify a copy on its own: a
+  // machine can hold several that all report the same one, which is exactly
+  // the case here, so the path is what ends the search.
+  path: string;
+}
+
+// The mismatch, as a sentence, or `null` when the pairing is sound.
+//
+// `loaded` is null when the SDK could not be resolved from the CLI's own
+// location. That is not a mismatch: it is the shape an in-repo run takes,
+// where the module specifier is mapped to the SDK's source and there is no
+// installed package to read a version from. Being unable to check is not
+// evidence of a fault, so it passes.
+export function sdkMismatchMessage(args: {
+  pinned: string | undefined;
+  loaded: LoadedSdk | null;
+}): string | null {
+  const { pinned, loaded } = args;
+  if (pinned === undefined || loaded === null) return null;
+  if (loaded.version === pinned) return null;
+  return (
+    `This CLI is built against @brass-build/client ${pinned}, and the copy it ` +
+    `loads is ${loaded.version} (${loaded.path}). It reads the SDK's internal ` +
+    `entry, which changes between releases, so the two have to match. Install ` +
+    `the CLI into the directory you run it from ("npm i @brass-build/cli") and ` +
+    `run it as ./node_modules/.bin/brass with absolute paths: a global install ` +
+    `keeps its own copy of the SDK, and npx resolves node_modules from the ` +
+    `current directory, so it fetches one from the registry when run anywhere ` +
+    `else.`
+  );
+}

package/src/session.ts

@@ -11,6 +11,7 @@
 
 import { spawn } from 'node:child_process';
 import { BrassApiError, networkError } from './api.js';
+import { renderApprovalPrompt } from './approval-prompt.js';
 import type { AuthProvider } from './auth.js';
 
 // Every auth call carries a few hundred bytes, so a host still silent after
@@ -127,9 +128,9 @@ export async function postRefresh(
 // rest of the session's life, so forgetting it locally leaves a working
 // credential behind wherever a copy of the file went.
 //
-// Reports whether the server confirmed it. Every outcome still clears the
-// local credential (the caller asked to be signed out on this machine), so
-// this is what tells the caller whether a credential elsewhere is still live.
+// Reports whether the server confirmed it. The stored pointer is the caller's
+// only handle on the session, so what the caller does with the record follows
+// from this: an undelivered revoke keeps it for the retry.
 export async function postSignOut(
   authBaseUrl: string,
   sid: string,
@@ -151,10 +152,81 @@ export async function postSignOut(
   }
 }
 
+export type BrowserSessionOutcome =
+  | { state: 'ready'; url: string; expiresIn: number }
+  // The app is not approved for the platform session behind this machine's
+  // sign-in. The URL is a page the human opens to grant it; the mint is a
+  // re-run of the same command afterwards.
+  | { state: 'needs_approval'; approvalUrl: string; expiresIn: number };
+
+interface BrowserSessionWire {
+  url?: string;
+  expires_in?: number;
+  error?: string;
+  error_description?: string;
+  approval_url?: string;
+}
+
+// Ask the auth API for a URL that signs a browser in as the human this
+// machine is signed in as. The stored device pointer is the credential, and
+// the answer is `return_to` with a one-time code on it, so what reaches the
+// browser expires in minutes and is spent once.
+//
+// The URL is a credential for as long as it lives. It belongs in the browser
+// the caller is about to drive, not in a log, a PR body, or a commit.
+export async function postDeviceAppSession(
+  authBaseUrl: string,
+  sid: string,
+  args: { appId: string; returnTo: string },
+  origin: string = REFRESH_ORIGIN,
+): Promise<BrowserSessionOutcome> {
+  const url = `${authBaseUrl}/device/app-session`;
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded', origin },
+      body: new URLSearchParams({ sid, app_id: args.appId, return_to: args.returnTo }),
+      signal: AbortSignal.timeout(AUTH_TIMEOUT_MS),
+    });
+  } catch (cause) {
+    throw networkError(`reaching ${authBaseUrl}`, cause);
+  }
+  const json = (await response.json().catch(() => ({}))) as BrowserSessionWire;
+  if (response.ok) {
+    if (!json.url) {
+      throw new BrassApiError(response.status, 'Brass returned no browser-session URL.');
+    }
+    return {
+      state: 'ready',
+      url: json.url,
+      expiresIn: tokenTtlSeconds(json.expires_in),
+    };
+  }
+  if (json.error === 'app_not_approved' && json.approval_url) {
+    return {
+      state: 'needs_approval',
+      approvalUrl: json.approval_url,
+      expiresIn: tokenTtlSeconds(json.expires_in),
+    };
+  }
+  // The server's own wording where it has one: every refusal here names a
+  // specific thing the caller can fix (an unknown app, a return_to off the
+  // allowlist, a sign-in that has ended), and rewording them locally would
+  // lose which.
+  throw new BrassApiError(
+    response.status,
+    json.error_description ??
+      (response.status === 401
+        ? "Your Brass sign-in is no longer valid (401). Run 'brass login' to sign in again."
+        : `Could not mint a browser session (${response.status}).`),
+  );
+}
+
 // Abandon a sign-in this machine started and never redeemed, so the code it
-// relayed to a human stops being redeemable. Best effort, like `postSignOut`:
-// the caller clears the local record either way, and reports what it could not
-// reach.
+// relayed to a human stops being redeemable. Reports whether the server took
+// it, like `postSignOut`: the record naming the grant is the caller's only
+// handle on it, so what the caller does with the record follows from this.
 export async function postDeviceCancel(
   authBaseUrl: string,
   deviceCode: string,
@@ -216,11 +288,17 @@ interface DeviceAuthorizeWire {
   expires_in: number;
 }
 
+// `targetAppId` is the app the machine will hand a browser once it is signed
+// in (`brass login --app`). The grant still mints for the CLI alone; naming a
+// target only widens what the human's one approval covers, so a later
+// `brass browser-session` needs no second trip to a browser.
 export async function deviceAuthorize(
   authBaseUrl: string,
   now: number = Date.now(),
+  targetAppId?: string,
 ): Promise<DeviceAuthorization> {
   const body = new URLSearchParams({ app_id: CLI_APP_ID });
+  if (targetAppId !== undefined) body.set('target_app_id', targetAppId);
   let response: Response;
   try {
     response = await fetch(`${authBaseUrl}/device/authorize`, {
@@ -232,8 +310,18 @@ export async function deviceAuthorize(
   } catch (cause) {
     throw new Error(`Network error reaching ${authBaseUrl}: ${String(cause)}`);
   }
-  if (!response.ok) throw new Error(`Device sign-in could not start (${response.status})`);
-  const json = (await response.json()) as DeviceAuthorizeWire;
+  // The server's own reason where it sent one. Every 400 here names a
+  // specific thing the caller got wrong (an app id that is not an app, an app
+  // that does not support device sign-in), and a status on its own sends them
+  // looking at the network instead.
+  const json = (await response.json().catch(() => ({}))) as DeviceAuthorizeWire & {
+    error_description?: string;
+  };
+  if (!response.ok) {
+    throw new Error(
+      json.error_description ?? `Device sign-in could not start (${response.status})`,
+    );
+  }
   return {
     deviceCode: json.device_code,
     userCode: json.user_code,
@@ -334,6 +422,8 @@ export async function pollDeviceToken(
 
 export interface DeviceLoginOptions {
   authBaseUrl: string;
+  // An app to approve alongside the CLI (`brass login --app`).
+  targetAppId?: string;
   // Shows the verification URL + user code to the human; defaults to stderr.
   onPrompt?: (auth: DeviceAuthorization) => void;
   // Opens the approval page (user code prefilled) in a browser; defaults to
@@ -344,7 +434,7 @@ export interface DeviceLoginOptions {
 }
 
 export async function loginDevice(options: DeviceLoginOptions): Promise<LoginResult> {
-  const auth = await deviceAuthorize(options.authBaseUrl);
+  const auth = await deviceAuthorize(options.authBaseUrl, Date.now(), options.targetAppId);
   (options.onPrompt ?? defaultDevicePrompt)(auth);
   (options.openBrowser ?? openBrowser)(auth.verificationUriComplete ?? auth.verificationUri);
   const tokens = await pollDeviceToken(
@@ -357,12 +447,14 @@ export async function loginDevice(options: DeviceLoginOptions): Promise<LoginRes
 }
 
 function defaultDevicePrompt(auth: DeviceAuthorization): void {
-  const target = auth.verificationUriComplete ?? auth.verificationUri;
   process.stderr.write(
-    '\nOpening your browser to approve this sign-in.\n' +
-      `If it doesn't open, go to:\n  ${target}\n` +
-      `and confirm the code:  ${auth.userCode}\n` +
-      '\nWaiting for approval...\n',
+    `\n${renderApprovalPrompt({
+      url: auth.verificationUriComplete ?? auth.verificationUri,
+      code: auth.userCode,
+      // This command polls to approval on its own, so there is nothing further
+      // to run; what the reader needs is that the wait has started.
+      closing: 'Waiting for approval...',
+    })}\n`,
   );
 }
 

package/src/store.ts

@@ -47,6 +47,9 @@ export async function writeStoredCredential(
 export interface PendingLogin {
   authBaseUrl: string;
   deviceCode: string;
+  // The app named by `brass login --app`, carried so a grant this CLI renews
+  // in place asks for the same approval the relayed one did.
+  targetAppId?: string;
   userCode: string;
   verificationUri: string;
   verificationUriComplete?: string;
@@ -112,6 +115,80 @@ export async function writePendingLogin(
   } satisfies PendingLoginsFile);
 }
 
+// An app approval `brass browser-session` asked for and no one has granted
+// yet. Recorded for the same reason a pending sign-in is: the caller relayed a
+// URL to a human and now has to wait, and `brass status` is where it asks what
+// is outstanding. Without it, status reports the app as ready and names a next
+// step that is not the blocked one.
+//
+// One per profile, carrying the app it is for, so status reports it only
+// against the app it resolved. A second app asked about while a first is
+// pending overwrites it; the link it replaces stays valid on the server, and
+// re-running the command for that app reports it again.
+export interface PendingApproval {
+  appId: string;
+  approvalUrl: string;
+  authBaseUrl: string;
+  expiresAt: number;
+}
+
+interface PendingApprovalsFile {
+  version: 1;
+  pending: Record<Profile, PendingApproval>;
+}
+
+export function pendingApprovalFilePath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(dirname(credentialsFilePath(env)), 'pending-approval.json');
+}
+
+async function readPendingApprovalsFile(
+  env: NodeJS.ProcessEnv,
+): Promise<PendingApprovalsFile | null> {
+  try {
+    const raw = await readFile(pendingApprovalFilePath(env), 'utf8');
+    const parsed = JSON.parse(raw) as PendingApprovalsFile;
+    if (parsed.version !== 1 || typeof parsed.pending !== 'object') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export async function readPendingApproval(
+  profile: Profile,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<PendingApproval | null> {
+  const entry = (await readPendingApprovalsFile(env))?.pending[profile];
+  if (
+    entry === undefined ||
+    typeof entry.appId !== 'string' ||
+    typeof entry.approvalUrl !== 'string' ||
+    typeof entry.expiresAt !== 'number'
+  ) {
+    return null;
+  }
+  return entry;
+}
+
+// The approval URL names a question rather than carrying a credential (the
+// page still gates on the reader's own cookie), but the file is written
+// owner-only like its siblings: what it discloses is which machine is asking
+// about which app.
+export async function writePendingApproval(
+  profile: Profile,
+  pending: PendingApproval | null,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  const existing = (await readPendingApprovalsFile(env)) ?? { version: 1 as const, pending: {} };
+  const entries = { ...existing.pending };
+  if (pending === null) delete entries[profile];
+  else entries[profile] = pending;
+  await writeOwnerOnlyJson(pendingApprovalFilePath(env), {
+    version: 1,
+    pending: entries,
+  } satisfies PendingApprovalsFile);
+}
+
 async function writeOwnerOnlyJson(path: string, payload: unknown): Promise<void> {
   await mkdir(dirname(path), { recursive: true });
   await writeFile(path, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });

package/src/version.ts

@@ -3,6 +3,6 @@
 // free here, unlike the SDK's query-param channel). Lets the platform
 // measure the CLI version distribution, in particular pinned CI copies.
 // A unit test pins this to package.json's version.
-export const VERSION = '0.2.0';
+export const VERSION = '0.4.0';
 
 export const CLI_CLIENT_ID = `cli/${VERSION}`;