@gogitcms/editor 0.23.0

package/src/lib/api.mjs

@@ -0,0 +1,122 @@
+// REST + GraphQL client for the CLI.
+//
+// The CLI is a native client: it holds a refresh token itself (see
+// credentials.mjs) rather than relying on the HttpOnly cookie the browser gets,
+// so every token-issuing call passes `native: true` and reads the pair from the
+// response body.
+
+import * as credentials from "./credentials.mjs";
+
+export class ApiError extends Error {
+  constructor(status, slug, message) {
+    super(message || slug || `request failed with ${status}`);
+    this.name = "ApiError";
+    this.status = status;
+    // slug is the machine-readable reason (e.g. "authorization_pending") the
+    // device flow branches on.
+    this.slug = slug;
+  }
+}
+
+async function parseError(res) {
+  try {
+    const body = await res.json();
+    return body.error || body.message || "";
+  } catch {
+    return "";
+  }
+}
+
+async function post(apiUrl, path, body, token) {
+  const res = await fetch(`${credentials.normalizeApiUrl(apiUrl)}/api/v1${path}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    },
+    body: JSON.stringify(body ?? {}),
+  });
+  if (!res.ok) throw new ApiError(res.status, await parseError(res));
+  if (res.status === 204) return null;
+  return res.json();
+}
+
+// requestDeviceCode starts the device grant and returns the code pair plus where
+// to send the user.
+export function requestDeviceCode(apiUrl, clientName = "gogitcms-editor") {
+  return post(apiUrl, "/auth/device/code", { clientName });
+}
+
+// pollDeviceToken asks once for the session behind a device code. A pending or
+// rejected authorization arrives as an ApiError whose slug says which.
+export function pollDeviceToken(apiUrl, deviceCode) {
+  return post(apiUrl, "/auth/device/token", { deviceCode });
+}
+
+// refresh rotates the stored refresh token, returning a fresh pair.
+export function refresh(apiUrl, refreshToken) {
+  return post(apiUrl, "/auth/refresh", { refreshToken, native: true });
+}
+
+export async function me(apiUrl, token) {
+  const res = await fetch(`${credentials.normalizeApiUrl(apiUrl)}/api/v1/me`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (!res.ok) throw new ApiError(res.status, await parseError(res));
+  return res.json();
+}
+
+// accessToken returns a currently-valid access token for an API origin,
+// refreshing and re-persisting the pair when the stored one has aged out. Throws
+// NotLoggedInError when there is nothing to refresh from, so callers can point
+// the user at `gogitcms-editor login`.
+export class NotLoggedInError extends Error {
+  constructor(apiUrl) {
+    super(`Not signed in to ${apiUrl}. Run  gogitcms-editor login  first.`);
+    this.name = "NotLoggedInError";
+  }
+}
+
+export async function accessToken(apiUrl) {
+  const creds = await credentials.load(apiUrl);
+  if (!creds?.refreshToken) throw new NotLoggedInError(apiUrl);
+  if (credentials.isFresh(creds)) return creds.accessToken;
+
+  let pair;
+  try {
+    pair = await refresh(apiUrl, creds.refreshToken);
+  } catch (e) {
+    // A rejected refresh token is a dead session, not a transient failure —
+    // drop it so the next command asks for a fresh sign-in instead of retrying.
+    if (e instanceof ApiError && (e.status === 401 || e.status === 403)) {
+      await credentials.clear(apiUrl);
+      throw new NotLoggedInError(apiUrl);
+    }
+    throw e;
+  }
+  const next = {
+    ...creds,
+    accessToken: pair.accessToken,
+    // Refresh tokens rotate: keep the new one or the next refresh fails.
+    refreshToken: pair.refreshToken || creds.refreshToken,
+    expiresAt: credentials.expiresAtFrom(pair.accessToken),
+  };
+  await credentials.save(apiUrl, next);
+  return next.accessToken;
+}
+
+// graphql runs one operation against the server's /graphql endpoint with a fresh
+// access token. GraphQL reports errors in a 200 body, so those are surfaced here
+// rather than left for the caller to notice.
+export async function graphql(apiUrl, query, variables = {}) {
+  const token = await accessToken(apiUrl);
+  const res = await fetch(`${credentials.normalizeApiUrl(apiUrl)}/graphql`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+    body: JSON.stringify({ query, variables }),
+  });
+  if (!res.ok) throw new ApiError(res.status, await parseError(res));
+  const body = await res.json();
+  if (body.errors?.length) throw new Error(body.errors[0].message);
+  return body.data;
+}

package/src/lib/appRoot.mjs

@@ -0,0 +1,51 @@
+// Locating the SPA sources that `dev` and `build` run Vite over.
+//
+// Two layouts have to work:
+//   workspace — inside the monorepo the editor is the linked @gogitcms/frontend
+//     package, whose sources are the ones being edited.
+//   published — `scripts/prepack.mjs` stages a self-contained copy of the editor
+//     (plus the workspace @gogitcms/* packages it imports) into ./app, so the npm
+//     tarball carries everything and resolves nothing outside itself.
+//
+// The workspace copy wins when it resolves. @gogitcms/frontend is a devDependency, so
+// it is never installed for a consumer of the published package — only a
+// checkout can satisfy it, and there the live sources are always what the
+// developer means. Preferring ./app instead made a leftover staging directory
+// (one `make ide-build` is enough to create it) silently shadow the real
+// sources, so edits to the editor appeared to do nothing.
+
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(here, "..", "..");
+
+const require = createRequire(import.meta.url);
+
+export function resolveAppRoot() {
+  try {
+    // @gogitcms/frontend declares no "exports", so its package.json is resolvable and
+    // gives us the package directory without depending on an entry point.
+    return path.dirname(require.resolve("@gogitcms/frontend/package.json"));
+  } catch {
+    // Not a checkout: fall through to the copy staged into the tarball.
+  }
+  const staged = path.join(packageRoot, "app");
+  if (fs.existsSync(path.join(staged, "index.html"))) return staged;
+  throw new Error(
+    "Could not locate the editor sources. This build of gogitcms-editor is incomplete — reinstall the package.",
+  );
+}
+
+// viteConfigFile returns the Vite config that belongs to the resolved app root.
+// The staged copy ships its own (with aliases rewritten to the vendored
+// packages); the workspace copy uses the editor's own vite.config.ts.
+export function viteConfigFile(appRoot) {
+  for (const name of ["vite.config.mjs", "vite.config.ts"]) {
+    const file = path.join(appRoot, name);
+    if (fs.existsSync(file)) return file;
+  }
+  return undefined;
+}

package/src/lib/baked.json

@@ -0,0 +1,3 @@
+{
+  "apiUrl": "https://app.gogitcms.com"
+}

package/src/lib/config.mjs

@@ -0,0 +1,108 @@
+// The project's cms.config.{js,mjs,cjs,ts}, read from the working directory.
+//
+// The SPA reads the same shape at build time via Vite `define` — see
+// apps/frontend/src/config.ts, which resolves API_URL / WORKSPACE_ID /
+// REPOSITORY_ID out of __CMS_CONFIG_BUILD__. `init` writes this file; `dev` and
+// `build` read it back.
+
+import fs from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const NAMES = ["cms.config.js", "cms.config.mjs", "cms.config.cjs", "cms.config.ts"];
+
+// Written as .mjs, not .js: the file is an ES module, and in a project whose
+// package.json has no "type" field Node warns on every load about reparsing a
+// .js file as ESM. The .mjs extension is unambiguous, and `find` still accepts a
+// hand-written cms.config.js.
+export const CONFIG_FILENAME = "cms.config.mjs";
+
+// find returns the path of the project's config file, or null.
+export function find(cwd = process.cwd()) {
+  return NAMES.map((n) => path.resolve(cwd, n)).find((p) => fs.existsSync(p)) ?? null;
+}
+
+// load reads and evaluates the config file, returning its default export (or
+// null when there is no config yet).
+export async function load(cwd = process.cwd()) {
+  const file = find(cwd);
+  if (!file) return null;
+  if (file.endsWith(".ts")) {
+    // Transpile the TS config with esbuild (a Vite dependency) and import it.
+    const { transform } = await import("esbuild");
+    const src = await readFile(file, "utf8");
+    const { code } = await transform(src, { loader: "ts", format: "esm" });
+    const mod = await import("data:text/javascript," + encodeURIComponent(code));
+    return mod.default ?? mod.config ?? null;
+  }
+  const mod = await import(pathToFileURL(file).href);
+  return mod.default ?? mod.config ?? null;
+}
+
+// normalizeBasePath turns whatever a user writes — "cms", "/cms", "/cms/" — into
+// the form Vite's `base` expects: leading and trailing slash, or "/" for a site
+// served from the root. The SPA reads the same value back as
+// import.meta.env.BASE_URL to build its own URLs (see apps/frontend/src/
+// navigation.tsx), so this is the single place the mount path is decided.
+export function normalizeBasePath(raw) {
+  const trimmed = String(raw ?? "").trim();
+  if (!trimmed || trimmed === "/") return "/";
+  return `/${trimmed.replace(/^\/+|\/+$/g, "")}/`;
+}
+
+// render produces the file body `init` writes — a real ES module, formatted the
+// way it is shown in the terminal.
+export function render({ API_URL, WORKSPACE_ID, REPOSITORY_ID, BASE_PATH }) {
+  return [
+    "// Go·Git CMS editor configuration, written by `gogitcms-editor init`.",
+    "export default {",
+    `  API_URL: ${JSON.stringify(API_URL)},`,
+    `  WORKSPACE_ID: ${JSON.stringify(WORKSPACE_ID)},`,
+    `  REPOSITORY_ID: ${JSON.stringify(REPOSITORY_ID)},`,
+    "",
+    "  // Path this editor is served from. Use a subpath (e.g. \"/cms/\") when it",
+    "  // is mounted under one — assets and in-app URLs are both built from it.",
+    `  BASE_PATH: ${JSON.stringify(normalizeBasePath(BASE_PATH))},`,
+    "};",
+    "",
+  ].join("\n");
+}
+
+export async function write(config, cwd = process.cwd()) {
+  const file = path.resolve(cwd, CONFIG_FILENAME);
+  await writeFile(file, render(config), "utf8");
+  return file;
+}
+
+// The keys the SPA actually reads at runtime (apps/frontend/src/config.ts).
+// This list is an allow-list, so a key missing from it is dropped in silence —
+// PROJECT was, which meant a config pinning the editor to one project of a
+// multi-project repository built an editor that was not pinned to anything.
+// BASE_PATH is deliberately absent: it configures the bundler, and the SPA reads
+// the result as import.meta.env.BASE_URL rather than from this object.
+const RUNTIME_KEYS = [
+  "API_URL",
+  "WORKSPACE_ID",
+  "REPOSITORY_ID",
+  "PROJECT",
+  "TOKEN_ENDPOINT",
+  "COLLAB_URL",
+  "MODE",
+];
+
+// defineFor packages the config for Vite's `define`, matching the
+// __CMS_CONFIG_BUILD__ constant the SPA declares. Returns {} when there is
+// nothing to inject, so a plain `vite` run still works.
+export function defineFor(config) {
+  const clean = Object.fromEntries(
+    RUNTIME_KEYS.map((k) => [k, config?.[k]]).filter(([, v]) => v != null && v !== ""),
+  );
+  return Object.keys(clean).length ? { __CMS_CONFIG_BUILD__: JSON.stringify(clean) } : {};
+}
+
+// basePathFor resolves the mount path for a command: an explicit --base flag
+// wins over the config file, which wins over the root.
+export function basePathFor(config, flag) {
+  return normalizeBasePath(flag || config?.BASE_PATH || "/");
+}

package/src/lib/credentials.mjs

@@ -0,0 +1,91 @@
+// Credential storage for the CLI.
+//
+// Tokens live in ~/.gitcms/credentials, keyed by API origin so one machine can
+// hold sessions for several servers (a local stack and a hosted one). The file
+// holds a refresh token — a long-lived bearer credential — so the directory is
+// created 0700 and the file written 0600, and it is never logged or echoed.
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const DIR = path.join(os.homedir(), ".gitcms");
+const FILE = path.join(DIR, "credentials");
+
+export const credentialsPath = FILE;
+
+// Access tokens are short-lived; refresh a little early so a long-running
+// command never presents one that expires mid-flight.
+const EXPIRY_SKEW_MS = 30_000;
+
+// normalizeApiUrl strips a trailing slash so the same server is one key however
+// the user typed it.
+export function normalizeApiUrl(apiUrl) {
+  return String(apiUrl || "").replace(/\/+$/, "");
+}
+
+async function readAll() {
+  try {
+    return JSON.parse(await fs.readFile(FILE, "utf8"));
+  } catch (e) {
+    if (e.code === "ENOENT") return {};
+    // A corrupt file shouldn't wedge the CLI — `login` will overwrite it.
+    if (e instanceof SyntaxError) return {};
+    throw e;
+  }
+}
+
+async function writeAll(all) {
+  await fs.mkdir(DIR, { recursive: true, mode: 0o700 });
+  await fs.writeFile(FILE, JSON.stringify(all, null, 2) + "\n", { mode: 0o600 });
+  // mkdir/writeFile only apply the mode when creating, so an existing file keeps
+  // whatever it had — re-assert both.
+  await fs.chmod(DIR, 0o700).catch(() => {});
+  await fs.chmod(FILE, 0o600);
+}
+
+// load returns the stored credentials for an API origin, or null.
+export async function load(apiUrl) {
+  const all = await readAll();
+  return all[normalizeApiUrl(apiUrl)] ?? null;
+}
+
+// loadAny returns [apiUrl, credentials] for the single stored session, used when
+// no API URL is known yet (e.g. `status` before `init`). Null when there are
+// none, or when there are several and the caller must disambiguate.
+export async function loadAny() {
+  const all = await readAll();
+  const keys = Object.keys(all);
+  if (keys.length !== 1) return null;
+  return [keys[0], all[keys[0]]];
+}
+
+export async function save(apiUrl, creds) {
+  const all = await readAll();
+  all[normalizeApiUrl(apiUrl)] = creds;
+  await writeAll(all);
+}
+
+export async function clear(apiUrl) {
+  const all = await readAll();
+  delete all[normalizeApiUrl(apiUrl)];
+  await writeAll(all);
+}
+
+// expiresAtFrom converts an access-token lifetime into an absolute timestamp.
+export function expiresAtFrom(accessToken) {
+  // The access token is a JWT; read its exp rather than guessing a TTL the
+  // server owns. An unparseable token just means "refresh on first failure".
+  try {
+    const [, payload] = accessToken.split(".");
+    const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    if (typeof claims.exp === "number") return claims.exp * 1000;
+  } catch {
+    // fall through
+  }
+  return 0;
+}
+
+export function isFresh(creds) {
+  return Boolean(creds?.accessToken) && creds.expiresAt > Date.now() + EXPIRY_SKEW_MS;
+}

package/src/lib/defaults.mjs

@@ -0,0 +1,26 @@
+// Where the CLI points when nothing says otherwise.
+//
+// GITCMS_API_URL lets a self-hoster set their server once (in a shell profile or
+// a project .envrc) instead of passing --api-url to every command; it always
+// wins. Otherwise the published CLI points at the value baked in at publish time
+// (see scripts/prepack.mjs — the hosted server when built on GitHub Actions),
+// falling back to the local stack so a fresh monorepo checkout works with no
+// configuration.
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+function bakedApiUrl() {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const { apiUrl } = JSON.parse(readFileSync(path.join(here, "baked.json"), "utf8"));
+    return apiUrl || "";
+  } catch {
+    // No baked.json in a local checkout — fall through to localhost.
+    return "";
+  }
+}
+
+export const DEFAULT_API_URL =
+  process.env.GITCMS_API_URL || bakedApiUrl() || "http://localhost:8080";

package/src/lib/graphql.mjs

@@ -0,0 +1,28 @@
+// The handful of GraphQL documents `init` needs, as plain strings — the CLI
+// talks to /graphql with fetch and has no Apollo runtime. They mirror WORKSPACES
+// and REPOSITORIES in apps/frontend/src/queries.ts; keep them in step if the
+// schema's selection set changes.
+
+export const WORKSPACES = /* GraphQL */ `
+  query Workspaces {
+    workspaces {
+      id
+      name
+      slug
+    }
+  }
+`;
+
+export const REPOSITORIES = /* GraphQL */ `
+  query Repositories($workspaceId: ID) {
+    repositories(workspaceId: $workspaceId) {
+      id
+      owner
+      name
+      branches {
+        id
+        name
+      }
+    }
+  }
+`;

package/src/lib/localServer.mjs

@@ -0,0 +1,206 @@
+// The local content server (gitcms-local), spawned by `gogitcms-editor dev --local`.
+//
+// In local mode there is no hosted API and no account: a Go binary indexes the
+// working copy and serves the same GraphQL schema over loopback. This module
+// finds that binary, starts it, and reads back the handshake the SPA needs.
+//
+// The binary is an optional dependency, so a remote-only install never downloads
+// platform binaries it will not run — which also means "not installed" is a
+// normal state to explain rather than a crash.
+
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+
+const require = createRequire(import.meta.url);
+
+// The scopes a binary package can be published under, most likely first.
+//
+// @gogitcms is the npm org and the name this CLI carries in the tree. The
+// GitHub Packages copy is renamed to @go-git-cms at publish time, because that
+// registry requires the package scope to equal the repo owner and the GitHub
+// org is spelled differently from the npm org (scripts/npm-scope.mjs). A CLI
+// installed from GitHub Packages therefore has @go-git-cms binaries in its
+// node_modules, so resolution has to try both — this file ships inside both
+// tarballs and cannot know which one it is running from.
+const SCOPES = ["@gogitcms", "@go-git-cms"];
+
+// ownScope reads the scope off this CLI's own name, so resolution and the
+// "not installed" hint both lead with the registry the user actually installed
+// from rather than with a guess. Falls back to the npmjs scope if the manifest
+// is unreadable, which is not a reason to fail — the other candidate is tried
+// either way.
+function ownScope() {
+  try {
+    const { name } = require("../../package.json");
+    const scope = typeof name === "string" ? name.split("/")[0] : null;
+    if (SCOPES.includes(scope)) return scope;
+  } catch {
+    // Fall through.
+  }
+  return SCOPES[0];
+}
+
+// PLATFORM_SUFFIXES maps Node's platform/arch onto the published binary
+// packages. They are optional dependencies of this CLI, so npm installs exactly
+// the one matching the machine (os/cpu) and skips the rest — the binaries are
+// ~21 MB each, and a remote-only user should not pay for five of them.
+// Mirrors the matrix in scripts/build-local-binaries.mjs.
+const PLATFORM_SUFFIXES = {
+  "darwin-arm64": "gitcms-local-darwin-arm64",
+  "darwin-x64": "gitcms-local-darwin-x64",
+  "linux-x64": "gitcms-local-linux-x64",
+  "linux-arm64": "gitcms-local-linux-arm64",
+  "win32-x64": "gitcms-local-win32-x64",
+};
+
+// platformPackages returns the candidate package names for this machine, this
+// CLI's own scope first, or an empty list on a platform we publish no binary
+// for.
+function platformPackages(key) {
+  const suffix = PLATFORM_SUFFIXES[key];
+  if (!suffix) return [];
+  const mine = ownScope();
+  const ordered = [mine, ...SCOPES.filter((s) => s !== mine)];
+  return ordered.map((scope) => `${scope}/${suffix}`);
+}
+
+export class LocalServerError extends Error {}
+
+// resolveBinary finds the gitcms-local executable.
+//
+// Order matters: an explicit override wins so a developer can point at a build
+// from source, then the platform package, then a PATH lookup for someone who
+// installed the Go binary directly.
+export function resolveBinary() {
+  if (process.env.GITCMS_LOCAL_BIN) {
+    const override = process.env.GITCMS_LOCAL_BIN;
+    if (!fs.existsSync(override)) {
+      throw new LocalServerError(`GITCMS_LOCAL_BIN points at ${override}, which does not exist.`);
+    }
+    return override;
+  }
+
+  const key = `${process.platform}-${process.arch}`;
+  const candidates = platformPackages(key);
+  const exe = process.platform === "win32" ? "gitcms-local.exe" : "gitcms-local";
+  for (const pkg of candidates) {
+    try {
+      // Resolve the package's own manifest, then the binary beside it — resolving
+      // the binary path directly would depend on it being an export.
+      const manifest = require.resolve(`${pkg}/package.json`);
+      const candidate = path.join(path.dirname(manifest), "bin", exe);
+      if (fs.existsSync(candidate)) return candidate;
+    } catch {
+      // Not installed under this scope — try the next, then PATH, then error.
+    }
+  }
+
+  const onPath = lookupOnPath();
+  if (onPath) return onPath;
+
+  // candidates[0] is this CLI's own scope (see platformPackages), so the
+  // install hint matches the registry the user actually got this copy from.
+  const preferred = candidates[0];
+  throw new LocalServerError(
+    preferred
+      ? `Local mode needs the ${preferred} binary, which ships as an optional\n` +
+        `  dependency of this CLI. If you installed with --no-optional or\n` +
+        `  --ignore-optional, reinstall without it:\n\n` +
+        `      npm install ${preferred}\n\n` +
+        `  Or build from source (apps/local) and set GITCMS_LOCAL_BIN.`
+      : `Local mode has no prebuilt binary for ${key}.\n` +
+        `  Build one from apps/local and point GITCMS_LOCAL_BIN at it.`,
+  );
+}
+
+function lookupOnPath() {
+  const exe = process.platform === "win32" ? "gitcms-local.exe" : "gitcms-local";
+  for (const dir of (process.env.PATH || "").split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, exe);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+// start spawns the server and resolves with its handshake once it is listening.
+//
+// The binary prints one line of JSON to stdout with --json and logs to stderr,
+// so the handshake is read from the first stdout line rather than by polling a
+// health endpoint — it is available the instant the port is bound, and it
+// carries the session token the SPA needs anyway.
+export async function start({ root, port, onLog }) {
+  const bin = resolveBinary();
+  const args = ["serve", "--root", root, "--json"];
+  if (port) args.push("--port", String(port));
+
+  const child = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+
+  let stdout = "";
+  let stderr = "";
+  const handshake = await new Promise((resolve, reject) => {
+    // A binary that starts but never prints (a hung filesystem, a huge cold
+    // index) must not hang the CLI forever with no explanation.
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(new LocalServerError(`The local server did not start within 60s.${stderr ? `\n${stderr.trim()}` : ""}`));
+    }, 60_000);
+
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+      const newline = stdout.indexOf("\n");
+      if (newline === -1) return;
+      clearTimeout(timer);
+      try {
+        resolve(JSON.parse(stdout.slice(0, newline)));
+      } catch (e) {
+        reject(new LocalServerError(`Could not read the local server's handshake: ${e.message}`));
+      }
+    });
+
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+      if (onLog) onLog(chunk.trimEnd());
+    });
+
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      reject(new LocalServerError(`Could not start ${bin}: ${e.message}`));
+    });
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      reject(new LocalServerError(`The local server exited (${code}).${stderr ? `\n${stderr.trim()}` : ""}`));
+    });
+  });
+
+  // The startup listeners above reject on exit; past the handshake an exit is
+  // just the process ending, so they are replaced.
+  child.removeAllListeners("exit");
+  child.removeAllListeners("error");
+
+  return {
+    handshake,
+    stop: () =>
+      new Promise((resolve) => {
+        if (child.exitCode !== null) return resolve();
+        child.once("exit", () => resolve());
+        child.kill();
+      }),
+  };
+}
+
+// capabilities fetches the server's capability flags, which tell the SPA which
+// surfaces to hide. Fetched rather than assumed so the flags live in one place —
+// the server — and a future capability needs no CLI change.
+export async function capabilities(handshake) {
+  const res = await fetch(handshake.contextUrl, {
+    headers: { Accept: "application/json" },
+  });
+  if (!res.ok) throw new LocalServerError(`The local server rejected the context request (${res.status}).`);
+  const body = await res.json();
+  return body.capabilities ?? {};
+}

package/src/lib/open.mjs

@@ -0,0 +1,23 @@
+// Opening a URL in the user's browser, without a dependency.
+//
+// Best-effort by design: the CLI always prints the URL too, so a headless box or
+// a locked-down desktop just means the user copies it by hand.
+
+import { spawn } from "node:child_process";
+
+export function openUrl(url) {
+  const [cmd, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : ["xdg-open", [url]];
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}