@brass-build/cli 0.1.0

package/src/config.ts

@@ -0,0 +1,132 @@
+// Target + credential resolution for the CLI. Pure functions over an
+// explicit inputs bag (flags, env vars, an optional on-disk credentials
+// file) so the resolution order is unit-testable without touching the real
+// filesystem or `process`.
+
+export interface Origins {
+  apiBaseUrl: string;
+  authBaseUrl: string;
+  dashboardBaseUrl: string;
+}
+
+// Production is the default, and the only origin set the package carries: a
+// developer publishing needs no configuration to target the real platform,
+// and every other stack is named by its URLs, so no deployment's hostname
+// scheme is derivable from what ships. Matches the SDK's own defaults.
+const PROD_ORIGINS: Origins = {
+  apiBaseUrl: 'https://api.brass.build',
+  authBaseUrl: 'https://auth.brass.build',
+  dashboardBaseUrl: 'https://app.brass.build',
+};
+
+export interface OriginOverrides {
+  apiBaseUrl?: string;
+  authBaseUrl?: string;
+  dashboardBaseUrl?: string;
+}
+
+// Resolve the three origins, each override winning over the production
+// default for its own field. A trailing slash is trimmed, so an origin
+// written either way reaches the same credential slot.
+export function resolveOrigins(overrides: OriginOverrides): Origins {
+  return {
+    apiBaseUrl: trimTrailingSlash(overrides.apiBaseUrl ?? PROD_ORIGINS.apiBaseUrl),
+    authBaseUrl: trimTrailingSlash(overrides.authBaseUrl ?? PROD_ORIGINS.authBaseUrl),
+    dashboardBaseUrl: trimTrailingSlash(
+      overrides.dashboardBaseUrl ?? PROD_ORIGINS.dashboardBaseUrl,
+    ),
+  };
+}
+
+function trimTrailingSlash(url: string): string {
+  return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+
+// The credential-file / project-state key: `prod`, or `origin:<host>` for a
+// stack named by URL, so one machine holds a session per target at once
+// without collision.
+export type Profile = string;
+
+// The on-disk credentials file shape, keyed by profile. `brass login` writes
+// a `session` (the opaque platform-session pointer); a `token` slot lets a
+// service token be stored too, though CI usually supplies that via
+// `BRASS_SERVICE_TOKEN`.
+export interface StoredCredential {
+  token?: string;
+  session?: { sid: string };
+}
+export interface CredentialsFile {
+  version: 1;
+  credentials: Record<Profile, StoredCredential>;
+}
+
+export interface CredentialInputs {
+  // `--token` on the command line.
+  flagToken?: string;
+  // `BRASS_SERVICE_TOKEN` in the environment (the CI path: a pipeline
+  // secret, no interactive login).
+  envToken?: string;
+  // The credential file parsed off disk, when present.
+  file?: CredentialsFile;
+  profile: Profile;
+}
+
+// A service token is a static bearer; a session is a stored login the CLI
+// refreshes into short-lived access tokens.
+export type ResolvedCredential =
+  | { kind: 'service'; token: string; source: 'flag' | 'env' | 'file' }
+  | { kind: 'session'; sid: string; source: 'file' };
+
+// Resolve which credential to use, most-explicit first: an inline `--token`,
+// then `BRASS_SERVICE_TOKEN`, then the stored login session, then a stored
+// service token. Null when none is available (the caller turns that into the
+// "run brass login or set BRASS_SERVICE_TOKEN" guidance).
+export function resolveCredential(inputs: CredentialInputs): ResolvedCredential | null {
+  if (isNonEmpty(inputs.flagToken)) {
+    return { kind: 'service', token: inputs.flagToken.trim(), source: 'flag' };
+  }
+  if (isNonEmpty(inputs.envToken)) {
+    return { kind: 'service', token: inputs.envToken.trim(), source: 'env' };
+  }
+  const stored = inputs.file?.credentials[inputs.profile];
+  if (stored?.session && isNonEmpty(stored.session.sid)) {
+    return { kind: 'session', sid: stored.session.sid.trim(), source: 'file' };
+  }
+  if (isNonEmpty(stored?.token)) {
+    return { kind: 'service', token: stored.token.trim(), source: 'file' };
+  }
+  return null;
+}
+
+function isNonEmpty(v: string | undefined): v is string {
+  return typeof v === 'string' && v.trim() !== '';
+}
+
+// The profile (credential-file + project-state key) a resolved origin set
+// belongs to. Derived from WHERE the invocation points, so a stack named by
+// `--api-url` / `--auth-url` is confined to its own slot: keyed on the flags
+// instead, every per-URL invocation would land on `prod`, where `brass login`
+// overwrites the production session.
+export function profileForOrigins(origins: Origins): Profile {
+  if (sameOrigins(origins, PROD_ORIGINS)) return 'prod';
+  // The data API names the deployment an app id and a session belong to.
+  return `origin:${hostOf(origins.apiBaseUrl)}`;
+}
+
+function sameOrigins(a: Origins, b: Origins): boolean {
+  return (
+    a.apiBaseUrl === b.apiBaseUrl &&
+    a.authBaseUrl === b.authBaseUrl &&
+    a.dashboardBaseUrl === b.dashboardBaseUrl
+  );
+}
+
+// The host (with port) of a base URL, so the key reads as the stack it names.
+// An unparseable value keys on itself, which still gives it its own slot.
+function hostOf(baseUrl: string): string {
+  try {
+    return new URL(baseUrl).host;
+  } catch {
+    return baseUrl;
+  }
+}

package/src/log.ts

@@ -0,0 +1,41 @@
+// A tiny logger the commands write through, so tests can capture output and
+// a `--json` mode can suppress the human lines. Human status goes to stderr;
+// stdout is reserved for machine-readable results (`--json`) so a pipeline
+// can consume `brass ... --json | jq` without status noise on the same stream.
+
+export interface Logger {
+  info(message: string): void;
+  warn(message: string): void;
+  success(message: string): void;
+  result(payload: unknown): void;
+  // Raw payload write to stdout, verbatim (no added newline, no `--json`
+  // gating). For a command whose primary output IS content a caller reads or
+  // pipes (e.g. `agents pull --stdout`); status stays on stderr so stdout
+  // carries only that content.
+  write(text: string): void;
+}
+
+export function createLogger(json: boolean): Logger {
+  return {
+    info(message) {
+      if (!json) process.stderr.write(`${message}\n`);
+    },
+    // Warnings survive `--json`, unlike status lines. `--json` reserves
+    // STDOUT for the result, which a warning on stderr never touches, and the
+    // caller most likely to act on one is a script or a coding agent running
+    // in that mode. Suppressing it there loses the signal on the only path
+    // that reads output mechanically.
+    warn(message) {
+      process.stderr.write(`warning: ${message}\n`);
+    },
+    success(message) {
+      if (!json) process.stderr.write(`${message}\n`);
+    },
+    result(payload) {
+      if (json) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    },
+    write(text) {
+      process.stdout.write(text);
+    },
+  };
+}

package/src/login.ts

@@ -0,0 +1,211 @@
+// The two-phase `brass login --start` / `brass login --check` flow, the
+// agent-shaped variant of the blocking device grant. `--start` mints the
+// grant, prints the approval URL + code, persists the grant, and exits, so a
+// harness that cannot hold a long-running command can relay the URL to the
+// human. `--check` reloads the grant and polls it, once by default or until a
+// bounded `--wait` deadline. Both share `pollDeviceTokenOnce`'s classification
+// with the blocking flow.
+//
+// The flow is built around one fact: the human approving is not watching the
+// terminal, so the wait is open-ended while the grant is not. Every phase
+// therefore keeps a live grant alive on its own rather than handing the
+// caller a recovery step: `--start` resumes a grant that is still good instead
+// of superseding the code already relayed, and a lapsed grant is replaced in
+// 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 {
+  readPendingLogin,
+  writePendingLogin,
+  writeStoredCredential,
+  type PendingLogin,
+} from './store.js';
+import type { Logger } from './log.js';
+import type { Profile } from './config.js';
+
+const realSleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+// A grant with less than this left is renewed rather than handed out, so a
+// caller never relays a code that dies while the human is still reading it.
+const MIN_USABLE_REMAINING_MS = 60_000;
+
+export interface LoginStartOptions {
+  authBaseUrl: string;
+  profile: Profile;
+  log: Logger;
+  // Mint a fresh grant even when a usable one is pending (`--new`), for a
+  // human who lost the relayed code.
+  force?: boolean;
+  env?: NodeJS.ProcessEnv;
+  now?: () => number;
+}
+
+// Mint a device grant, persist it as the profile's pending sign-in, print
+// the approval URL + user code, and exit without waiting. The browser is not
+// opened: the human approving is often on a different machine, so the URL is
+// printed for relaying.
+export async function loginStart(options: LoginStartOptions): Promise<number> {
+  const now = options.now ?? ((): number => Date.now());
+  const env = options.env ?? process.env;
+  // Resume a grant with usable time left. A second `--start` otherwise mints a
+  // 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 resumed =
+    existing !== null && existing.expiresAt - now() > MIN_USABLE_REMAINING_MS ? existing : null;
+  const pending = resumed ?? (await mintPendingLogin(options.authBaseUrl, now(), options.profile, env));
+  promptFor(options.log, pending, {
+    lead: resumed === null ? null : 'A sign-in is already waiting for approval.',
+  });
+  options.log.result({
+    state: 'started',
+    resumed: resumed !== null,
+    verification_url: targetUrl(pending),
+    user_code: pending.userCode,
+    expires_at: pending.expiresAt,
+    expires_in_seconds: remainingSeconds(pending, now()),
+  });
+  return 0;
+}
+
+export interface LoginCheckOptions {
+  profile: Profile;
+  log: Logger;
+  // Poll until approval for up to this many seconds instead of once
+  // (`--wait`). A grant that lapses inside the window is renewed in place and
+  // the new code printed, so the wait outlives any single grant.
+  waitSeconds?: number;
+  env?: NodeJS.ProcessEnv;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+// Poll the profile's pending grant. Approved stores the session exactly as the
+// blocking flow does and clears the grant; denied clears it and exits nonzero.
+// Expiry renews the grant in place and prints the new code. Without `--wait`
+// this makes exactly one poll and reports what it saw; with it, it keeps
+// polling until approval or the deadline, and a deadline reached with the
+// grant still pending is a `pending` result, not a failure: the grant is
+// alive and the next check resumes it.
+export async function loginCheck(options: LoginCheckOptions): Promise<number> {
+  const env = options.env ?? process.env;
+  const now = options.now ?? ((): number => Date.now());
+  const sleep = options.sleep ?? realSleep;
+  const waitMs = Math.max(0, (options.waitSeconds ?? 0) * 1000);
+  const deadline = now() + waitMs;
+
+  let pending = await readPendingLogin(options.profile, env);
+  if (pending === null) {
+    options.log.info('No sign-in in progress. Run `brass login --start` first.');
+    options.log.result({ state: 'none' });
+    return 1;
+  }
+  let intervalSeconds = pending.intervalSeconds;
+  // Set once the loop renews a lapsed grant, so the reported state tells the
+  // caller a NEW code needs relaying rather than the one it already sent.
+  let renewed = false;
+  // Whether the grant's code has already been printed since the last poll, so
+  // a renewal that is immediately followed by the closing report prints the
+  // code once rather than twice.
+  let justPrompted = false;
+
+  for (;;) {
+    if (now() >= pending.expiresAt) {
+      pending = await mintPendingLogin(pending.authBaseUrl, now(), options.profile, env);
+      intervalSeconds = pending.intervalSeconds;
+      renewed = true;
+      promptFor(options.log, pending, {
+        lead: 'The previous code expired, so this sign-in has a new one.',
+      });
+      justPrompted = true;
+    }
+
+    const outcome = await pollDeviceTokenOnce(pending.authBaseUrl, pending.deviceCode, now());
+    if (outcome.state === 'approved') {
+      if (!outcome.tokens.sessionToken) {
+        throw new Error('Device sign-in did not return a session token.');
+      }
+      await writeStoredCredential(
+        options.profile,
+        { session: { sid: outcome.tokens.sessionToken } },
+        env,
+      );
+      await writePendingLogin(options.profile, null, env);
+      const email = decodeEmail(outcome.tokens.idToken);
+      options.log.success(email !== undefined ? `Signed in as ${email}.` : 'Signed in.');
+      options.log.result({ state: 'approved', ...(email !== undefined ? { email } : {}) });
+      return 0;
+    }
+    if (outcome.state === 'denied') {
+      await writePendingLogin(options.profile, null, env);
+      options.log.info('Sign-in was denied. Run `brass login --start` to begin a new one.');
+      options.log.result({ state: 'denied' });
+      return 1;
+    }
+    // RFC 8628 §3.5: polling too fast. Back off for the rest of this wait.
+    if (outcome.state === 'slow_down') intervalSeconds += 5;
+
+    const nextPollAt = now() + intervalSeconds * 1000;
+    if (nextPollAt > deadline) break;
+    await sleep(intervalSeconds * 1000);
+    justPrompted = false;
+  }
+
+  // Still pending: reprint the URL + code so the caller can relay them again.
+  if (!justPrompted) {
+    promptFor(options.log, pending, { lead: renewed ? null : 'Not approved yet.' });
+  }
+  options.log.result({
+    state: renewed ? 'renewed' : 'pending',
+    verification_url: targetUrl(pending),
+    user_code: pending.userCode,
+    expires_at: pending.expiresAt,
+    expires_in_seconds: remainingSeconds(pending, now()),
+  });
+  return 0;
+}
+
+async function mintPendingLogin(
+  authBaseUrl: string,
+  now: number,
+  profile: Profile,
+  env: NodeJS.ProcessEnv,
+): Promise<PendingLogin> {
+  const auth = await deviceAuthorize(authBaseUrl, now);
+  const pending: PendingLogin = {
+    authBaseUrl,
+    deviceCode: auth.deviceCode,
+    userCode: auth.userCode,
+    verificationUri: auth.verificationUri,
+    ...(auth.verificationUriComplete !== undefined
+      ? { verificationUriComplete: auth.verificationUriComplete }
+      : {}),
+    intervalSeconds: auth.intervalSeconds,
+    expiresAt: auth.expiresAt,
+  };
+  await writePendingLogin(profile, pending, env);
+  return pending;
+}
+
+function targetUrl(pending: PendingLogin): string {
+  return pending.verificationUriComplete ?? pending.verificationUri;
+}
+
+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.',
+  );
+}

package/src/project.ts

@@ -0,0 +1,176 @@
+import { readFile, writeFile, readdir, stat, mkdir } from 'node:fs/promises';
+import { join, relative, sep, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { zipSync } from 'fflate';
+import type { BrassSchemaManifest } from './api.js';
+
+// Local state the CLI persists so a re-`publish` targets the same app
+// instead of creating a duplicate. Committed to the app's repo (like
+// Vercel's `.vercel/project.json`), or supplied out-of-band via `--app` /
+// `BRASS_APP_ID` for a stateless pipeline. Keyed by profile (`prod` / `dev` /
+// `origin:<host>`) so one checkout can hold an app id per target.
+export interface ProjectState {
+  version: 1;
+  apps: Record<string, { app_id: string }>;
+}
+
+const PROJECT_DIR = '.brass';
+const PROJECT_FILE = 'project.json';
+
+export function projectStatePath(cwd: string): string {
+  return join(cwd, PROJECT_DIR, PROJECT_FILE);
+}
+
+export async function readProjectState(cwd: string): Promise<ProjectState | null> {
+  try {
+    const raw = await readFile(projectStatePath(cwd), 'utf8');
+    const parsed = JSON.parse(raw) as ProjectState;
+    if (parsed.version !== 1 || typeof parsed.apps !== 'object' || parsed.apps === null) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeProjectAppId(
+  cwd: string,
+  profile: string,
+  appId: string,
+): Promise<void> {
+  const existing = (await readProjectState(cwd)) ?? { version: 1 as const, apps: {} };
+  const next: ProjectState = {
+    version: 1,
+    apps: { ...existing.apps, [profile]: { app_id: appId } },
+  };
+  await mkdir(join(cwd, PROJECT_DIR), { recursive: true });
+  await writeFile(projectStatePath(cwd), `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+}
+
+// Resolve which app to publish to, most-explicit first: an inline `--app`,
+// then `BRASS_APP_ID`, then the per-profile project state on disk. Null means
+// "no app known yet" and the caller creates one.
+export function resolveAppId(inputs: {
+  flagApp?: string;
+  envApp?: string;
+  state: ProjectState | null;
+  profile: string;
+}): string | null {
+  if (nonEmpty(inputs.flagApp)) return inputs.flagApp.trim();
+  if (nonEmpty(inputs.envApp)) return inputs.envApp.trim();
+  const stored = inputs.state?.apps[inputs.profile]?.app_id;
+  return nonEmpty(stored) ? stored.trim() : null;
+}
+
+function nonEmpty(v: string | undefined): v is string {
+  return typeof v === 'string' && v.trim() !== '';
+}
+
+// The served capability manifest an app authors (`brass-app.json` /
+// `/.well-known/brass-app.json`). The CLI reads `name` for a first create
+// (and `client_token` as its stable idempotency key), and writes `schema` on
+// a `schema pull`; every other field is passed through untouched.
+export interface AppManifest {
+  name?: string;
+  // A stable, caller-chosen key that makes a first `publish` from CI
+  // idempotent: with it, repeated create-from-scratch runs (ephemeral CI has
+  // no persisted `.brass/project.json`) resolve the same app instead of
+  // minting a duplicate. Committed in the repo, so it is the same across
+  // runs. Opaque and non-secret (org-scoped; creating with it still needs the
+  // caller's org authority).
+  client_token?: string;
+  schema?: BrassSchemaManifest;
+  [key: string]: unknown;
+}
+
+export async function readManifest(path: string): Promise<AppManifest | null> {
+  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;
+  }
+}
+
+export async function writeManifest(path: string, manifest: AppManifest): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+}
+
+// Write raw UTF-8 text to a file, creating parent directories as needed.
+// Content is written verbatim (no added trailing newline) so a pulled
+// document round-trips byte-for-byte with what the server stored.
+export async function writeTextFile(path: string, content: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content, 'utf8');
+}
+
+// Set the manifest's `schema` to a pulled schema manifest, preserving every
+// other field and their order. Pure so the "copy verbatim" guarantee is
+// testable: the declaration goes in unchanged, no re-derivation. Returns a
+// new object.
+export function mergeSchemaIntoManifest(
+  manifest: AppManifest,
+  schema: BrassSchemaManifest,
+): AppManifest {
+  return { ...manifest, schema };
+}
+
+// Recursively collect a directory's files into fflate's zip input map, keyed
+// by forward-slash relative path (zip entries never use the OS separator).
+// Symlinks are followed via `stat`; empty directories are omitted (a static
+// bundle has none that matter).
+export async function collectZipEntries(root: string): Promise<Record<string, Uint8Array>> {
+  const entries: Record<string, Uint8Array> = {};
+  async function walk(dir: string): Promise<void> {
+    const names = await readdir(dir);
+    for (const name of names) {
+      const abs = join(dir, name);
+      const info = await stat(abs);
+      if (info.isDirectory()) {
+        await walk(abs);
+      } else if (info.isFile()) {
+        const rel = relative(root, abs).split(sep).join('/');
+        entries[rel] = new Uint8Array(await readFile(abs));
+      }
+    }
+  }
+  await walk(root);
+  return entries;
+}
+
+export function zipEntries(entries: Record<string, Uint8Array>): Uint8Array {
+  if (Object.keys(entries).length === 0) {
+    throw new Error('No files found to publish');
+  }
+  return zipSync(entries);
+}
+
+export async function zipDirectory(root: string): Promise<Uint8Array> {
+  return zipEntries(await collectZipEntries(root));
+}
+
+// A deterministic hash of a bundle's contents: sha256 over the sorted
+// `path\0sha256(bytes)` line of every file. It is derived from the SAME file
+// map `zipDirectory` uploads (`collectZipEntries`), so equal hashes mean the
+// served bytes would be identical, and it hashes file contents rather than the
+// zip bytes (a zip carries mtimes and so is not reproducible for identical
+// input). `publish` records this on the version it uploads and skips the
+// upload + unpack-wait when the app's active version already carries it.
+export function contentHash(entries: Record<string, Uint8Array>): string {
+  const lines = Object.keys(entries)
+    .sort()
+    .map((path) => `${path}\0${createHash('sha256').update(entries[path]!).digest('hex')}`);
+  return createHash('sha256').update(lines.join('\n')).digest('hex');
+}
+
+export async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}