@sandboxsonny/ace-kit 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @sandboxsonny/ace-kit
 
+## 0.3.0
+
+### Minor Changes
+
+- a9d7700: `ace-kit login`, `ace-kit logout` and `ace-kit whoami`: sign in to CMS Ace from the command line.
+  
+  `ace-kit login` uses the OAuth device flow: the terminal shows a short code and opens the admin app, where you type the code and approve it. No password goes into the terminal. The login is kept in the macOS Keychain, or in a file only you can read on other systems, and is what the dev-server sync for sections will use. It can do much less than a browser login and ends after 30 days unused. Needs a CMS Ace API with command-line sign-in (its migration 00020). Set `ACE_TOKEN` to use a token instead (for a build server).
+  
+  `ace-kit generate` is unchanged.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -51,6 +51,7 @@ const about = await getEntry("pages", "about");
 | [React](docs/react.md)                     | Components for any React framework           |
 | [Live preview](docs/live-preview.md)       | What a site must do for the editor's preview |
 | [Typed content](docs/typed-content.md)     | `ace-kit generate`                           |
+| [The command line](docs/command-line.md)   | `ace-kit login`, `logout`, `whoami`          |
 | [Rich text](docs/rich-text.md)             | The document format and how it is drawn      |
 | [API reference](docs/api-reference.md)     | Every export                                 |
 | [Releasing](docs/releasing.md)             | Versions, the changelog and publishing       |

package/dist/cli.js

@@ -1,8 +1,233 @@
 #!/usr/bin/env node
 
-// src/generate/cli.ts
-import { mkdir, writeFile } from "fs/promises";
-import { dirname, resolve } from "path";
+// src/cli/environment.ts
+import { spawn } from "child_process";
+import { hostname } from "os";
+
+// src/auth/file-store.ts
+import { mkdir, readFile, rename, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+// src/auth/login-store.ts
+function normaliseApiUrl(address) {
+  let parsed;
+  try {
+    parsed = new URL(address.trim());
+  } catch {
+    throw new Error(`"${address}" is not a web address. Write the API address like http://localhost:8080.`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`The API address must start with http:// or https:// (it was "${address}").`);
+  }
+  if (parsed.username || parsed.password) {
+    throw new Error("The API address must not contain a username or password.");
+  }
+  return `${parsed.origin}${parsed.pathname.replace(/\/+$/, "")}`;
+}
+function hasExpired(login, now) {
+  const endsAt = Date.parse(login.expiresAt);
+  return Number.isNaN(endsAt) || endsAt <= now;
+}
+function parseStoredLogin(value) {
+  if (typeof value !== "object" || value === null) return null;
+  const { token, expiresAt, email } = value;
+  if (typeof token !== "string" || token === "" || typeof expiresAt !== "string" || typeof email !== "string")
+    return null;
+  return { token, expiresAt, email };
+}
+
+// src/auth/file-store.ts
+function defaultLoginFile(variables, platform) {
+  if (platform === "win32" && variables.APPDATA) return join(variables.APPDATA, "ace-kit", "credentials.json");
+  const configFolder = variables.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(configFolder, "ace-kit", "credentials.json");
+}
+function createFileStore(path) {
+  async function readAll() {
+    let text;
+    try {
+      text = await readFile(path, "utf8");
+    } catch {
+      return {};
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return {};
+    }
+    const found = {};
+    if (typeof parsed === "object" && parsed !== null) {
+      for (const [address, value] of Object.entries(parsed)) {
+        const login = parseStoredLogin(value);
+        if (login) found[address] = login;
+      }
+    }
+    return found;
+  }
+  async function writeAll(logins) {
+    await mkdir(dirname(path), { recursive: true, mode: 448 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(logins, null, 2)}
+`, { mode: 384 });
+    await rename(temporary, path);
+  }
+  return {
+    description: path,
+    async read(apiUrl) {
+      return (await readAll())[normaliseApiUrl(apiUrl)] ?? null;
+    },
+    async write(apiUrl, login) {
+      const logins = await readAll();
+      logins[normaliseApiUrl(apiUrl)] = login;
+      await writeAll(logins);
+    },
+    async remove(apiUrl) {
+      const logins = await readAll();
+      delete logins[normaliseApiUrl(apiUrl)];
+      await writeAll(logins);
+    }
+  };
+}
+
+// src/auth/keychain-store.ts
+var keychainService = "ace-kit";
+function createKeychainStore(run) {
+  async function read(apiUrl) {
+    const found = await run("security", [
+      "find-generic-password",
+      "-s",
+      keychainService,
+      "-a",
+      normaliseApiUrl(apiUrl),
+      "-w"
+    ]);
+    if (found.exitCode !== 0) return null;
+    try {
+      return parseStoredLogin(JSON.parse(Buffer.from(found.stdout.trim(), "base64").toString("utf8")));
+    } catch {
+      return null;
+    }
+  }
+  return {
+    description: "the macOS Keychain",
+    read,
+    async write(apiUrl, login) {
+      const account = normaliseApiUrl(apiUrl);
+      if (/["\\\s]/.test(account)) throw new Error("That API address can't be kept in the Keychain.");
+      const secret = Buffer.from(JSON.stringify(login), "utf8").toString("base64");
+      await run(
+        "security",
+        ["-i"],
+        `add-generic-password -s "${keychainService}" -a "${account}" -l "Ace Kit login" -w "${secret}" -U
+`
+      );
+      const kept = await read(apiUrl);
+      if (kept?.token !== login.token) throw new Error("The login could not be saved in the macOS Keychain.");
+    },
+    async remove(apiUrl) {
+      await run("security", ["delete-generic-password", "-s", keychainService, "-a", normaliseApiUrl(apiUrl)]);
+    }
+  };
+}
+
+// src/auth/choose-store.ts
+async function chooseLoginStore(options) {
+  const file = createFileStore(defaultLoginFile(options.variables, options.platform));
+  if (options.platform !== "darwin" || options.variables.ACE_KIT_CREDENTIALS === "file") return file;
+  try {
+    await options.run("security", ["help"]);
+    return createKeychainStore(options.run);
+  } catch {
+    return file;
+  }
+}
+
+// src/auth/last-api-url.ts
+import { mkdir as mkdir2, readFile as readFile2, rename as rename2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, join as join2 } from "path";
+function defaultLastApiUrlFile(variables, platform) {
+  return join2(dirname2(defaultLoginFile(variables, platform)), "last-api-url");
+}
+function createLastApiUrl(path) {
+  return {
+    async read() {
+      try {
+        return normaliseApiUrl((await readFile2(path, "utf8")).trim());
+      } catch {
+        return null;
+      }
+    },
+    async write(apiUrl) {
+      await mkdir2(dirname2(path), { recursive: true, mode: 448 });
+      const temporary = `${path}.${process.pid}.tmp`;
+      await writeFile2(temporary, `${normaliseApiUrl(apiUrl)}
+`, { mode: 384 });
+      await rename2(temporary, path);
+    }
+  };
+}
+
+// src/cli/version.ts
+var aceKitVersion = true ? "0.3.0" : "development";
+
+// src/cli/environment.ts
+var runCommand = (command, commandArguments, input) => new Promise((resolve2, reject) => {
+  const child = spawn(command, commandArguments, { stdio: ["pipe", "pipe", "ignore"] });
+  let stdout = "";
+  child.stdout.on("data", (chunk) => {
+    stdout += chunk.toString("utf8");
+  });
+  child.on("error", reject);
+  child.on("close", (exitCode) => resolve2({ exitCode: exitCode ?? 1, stdout }));
+  child.stdin.on("error", () => {
+  });
+  child.stdin.end(input ?? "");
+});
+function browserCommand(platform, address) {
+  if (platform === "darwin") return { command: "open", commandArguments: [address] };
+  if (platform === "win32") return { command: "rundll32", commandArguments: ["url.dll,FileProtocolHandler", address] };
+  return { command: "xdg-open", commandArguments: [address] };
+}
+async function openBrowser(platform, address) {
+  const { command, commandArguments } = browserCommand(platform, address);
+  await new Promise((resolve2) => {
+    const child = spawn(command, commandArguments, { stdio: "ignore", detached: true });
+    child.on("error", () => resolve2());
+    child.on("spawn", () => {
+      child.unref();
+      resolve2();
+    });
+  });
+}
+async function createRealEnvironment() {
+  try {
+    process.loadEnvFile(".env");
+  } catch {
+  }
+  const variables = { ...process.env };
+  const platform = process.platform;
+  return {
+    variables,
+    platform,
+    hostname: hostname(),
+    version: aceKitVersion,
+    out: (text) => process.stdout.write(`${text}
+`),
+    error: (text) => console.error(text),
+    fetchImplementation: (input, init) => fetch(input, init),
+    sleep: (milliseconds) => new Promise((resolve2) => setTimeout(resolve2, milliseconds)),
+    now: Date.now,
+    openBrowser: (address) => openBrowser(platform, address),
+    store: await chooseLoginStore({ platform, variables, run: runCommand }),
+    lastApiUrl: createLastApiUrl(defaultLastApiUrlFile(variables, platform))
+  };
+}
+
+// src/cli/generate-command.ts
+import { mkdir as mkdir3, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname3, resolve } from "path";
 import { parseArgs } from "util";
 
 // src/client/errors.ts
@@ -160,8 +385,8 @@ export {};
 // src/helpers/package-name.ts
 var packageName = "@sandboxsonny/ace-kit";
 
-// src/generate/cli.ts
-var usage = `ace-kit generate: write TypeScript types for your CMS Ace content types.
+// src/cli/generate-command.ts
+var generateUsage = `ace-kit generate: write TypeScript types for your CMS Ace content types.
 
 Usage:
   ace-kit generate [--api-url <address>] [--domain <domain>] [--out <file>]
@@ -172,13 +397,10 @@ Options:
   --out       Where to write the types (default: src/ace-kit.generated.d.ts).
   --help      Show this message.
 `;
-async function main() {
-  try {
-    process.loadEnvFile(".env");
-  } catch {
-  }
-  const { positionals, values } = parseArgs({
-    allowPositionals: true,
+async function generateCommand(commandArguments, environment) {
+  const { values } = parseArgs({
+    // eslint-disable-next-line id-denylist -- "args" is the name node's parseArgs gives this option.
+    args: commandArguments,
     options: {
       "api-url": { type: "string" },
       domain: { type: "string" },
@@ -186,27 +408,365 @@ async function main() {
       help: { type: "boolean" }
     }
   });
-  if (values.help || positionals[0] !== "generate") {
-    console.log(usage);
-    return values.help ? 0 : 1;
+  if (values.help) {
+    environment.out(generateUsage);
+    return 0;
   }
-  const apiUrl = values["api-url"] ?? process.env.ACE_API_URL;
-  const siteDomain = values.domain ?? process.env.ACE_SITE_DOMAIN;
+  const apiUrl = values["api-url"] ?? environment.variables.ACE_API_URL;
+  const siteDomain = values.domain ?? environment.variables.ACE_SITE_DOMAIN;
   if (!apiUrl || !siteDomain) {
-    console.error(
+    environment.error(
       "Give the API address and the site's domain: --api-url and --domain, or ACE_API_URL and ACE_SITE_DOMAIN."
     );
     return 1;
   }
-  const client = createAceClient({ apiUrl, siteDomain, cacheSeconds: 0 });
+  const client = createAceClient({
+    apiUrl,
+    siteDomain,
+    cacheSeconds: 0,
+    fetchImplementation: environment.fetchImplementation
+  });
   const contentTypes = await client.getContentTypes();
   const file = resolve(values.out ?? "src/ace-kit.generated.d.ts");
-  await mkdir(dirname(file), { recursive: true });
-  await writeFile(file, generateTypes(contentTypes, packageName, siteDomain));
-  console.log(`Wrote types for ${contentTypes.length} content type${contentTypes.length === 1 ? "" : "s"} to ${file}.`);
+  await mkdir3(dirname3(file), { recursive: true });
+  await writeFile3(file, generateTypes(contentTypes, packageName, siteDomain));
+  environment.out(
+    `Wrote types for ${contentTypes.length} content type${contentTypes.length === 1 ? "" : "s"} to ${file}.`
+  );
+  return 0;
+}
+
+// src/cli/login-commands.ts
+import { parseArgs as parseArgs2 } from "util";
+
+// src/auth/device-login.ts
+var DeviceLoginError = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "DeviceLoginError";
+    this.reason = reason;
+  }
+};
+var requestTimeoutMilliseconds2 = 15e3;
+var maximumFailures = 5;
+async function post(dependencies, apiUrl, path, body) {
+  return dependencies.fetchImplementation(`${apiUrl}${path}`, {
+    method: "POST",
+    headers: { Accept: "application/json", "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(requestTimeoutMilliseconds2)
+  });
+}
+async function readMessage(response) {
+  try {
+    const body = await response.json();
+    if (typeof body.error === "string") return body.error;
+  } catch {
+  }
+  return `The CMS answered with an error (${response.status}).`;
+}
+async function startDeviceLogin(dependencies) {
+  let response;
+  try {
+    response = await post(dependencies, dependencies.apiUrl, "/auth/device", { client_name: dependencies.clientName });
+  } catch {
+    throw new DeviceLoginError("unavailable", `Could not reach the CMS at ${dependencies.apiUrl}.`);
+  }
+  if (response.status === 503) throw new DeviceLoginError("unsupported", await readMessage(response));
+  if (response.status === 429)
+    throw new DeviceLoginError("unavailable", "Too many attempts. Wait a minute and try again.");
+  if (response.status === 404) {
+    throw new DeviceLoginError(
+      "unsupported",
+      `${dependencies.apiUrl} does not offer command-line sign-in. Is it a CMS Ace API, and is it up to date?`
+    );
+  }
+  if (!response.ok) throw new DeviceLoginError("unavailable", await readMessage(response));
+  const body = await response.json().catch(() => null);
+  const { device_code, user_code, verification_uri, expires_in, interval } = body ?? {};
+  if (typeof device_code !== "string" || typeof user_code !== "string" || typeof verification_uri !== "string" || typeof expires_in !== "number" || typeof interval !== "number") {
+    throw new DeviceLoginError(
+      "unavailable",
+      "The CMS sent a reply this version of ace-kit can't read. Update ace-kit."
+    );
+  }
+  return {
+    deviceCode: device_code,
+    userCode: user_code,
+    verificationUri: verification_uri,
+    expiresInSeconds: expires_in,
+    intervalSeconds: Math.max(1, interval)
+  };
+}
+async function waitForApproval(dependencies) {
+  const { apiUrl, request, sleep, now } = dependencies;
+  const deadline = now() + request.expiresInSeconds * 1e3;
+  let intervalSeconds = request.intervalSeconds;
+  let failures = 0;
+  for (; ; ) {
+    await sleep(intervalSeconds * 1e3);
+    if (now() > deadline)
+      throw new DeviceLoginError("expired", "The code ran out before it was approved. Run ace-kit login again.");
+    let response;
+    try {
+      response = await post(dependencies, apiUrl, "/auth/device/token", { device_code: request.deviceCode });
+    } catch {
+      failures += 1;
+      if (failures >= maximumFailures)
+        throw new DeviceLoginError("unavailable", `Lost contact with the CMS at ${apiUrl}.`);
+      continue;
+    }
+    if (response.status === 404) {
+      throw new DeviceLoginError("expired", "The CMS no longer knows this login. Run ace-kit login again.");
+    }
+    if (response.status === 429) {
+      intervalSeconds += 5;
+      continue;
+    }
+    if (!response.ok) {
+      failures += 1;
+      if (failures >= maximumFailures) throw new DeviceLoginError("unavailable", await readMessage(response));
+      continue;
+    }
+    failures = 0;
+    const body = await response.json().catch(() => null);
+    switch (body?.status) {
+      case "pending":
+        continue;
+      case "slow_down":
+        intervalSeconds += 5;
+        continue;
+      case "denied":
+        throw new DeviceLoginError("denied", "The login was turned down in the admin app.");
+      case "expired":
+        throw new DeviceLoginError("expired", "The code ran out before it was approved. Run ace-kit login again.");
+      case "approved": {
+        const user = body.user;
+        if (typeof body.token !== "string" || typeof body.expires_at !== "string" || typeof user?.email !== "string") {
+          throw new DeviceLoginError("unavailable", "The CMS approved the login but sent a reply that can't be read.");
+        }
+        return { token: body.token, expiresAt: body.expires_at, email: user.email };
+      }
+      default:
+        throw new DeviceLoginError(
+          "unavailable",
+          "The CMS sent a reply this version of ace-kit can't read. Update ace-kit."
+        );
+    }
+  }
+}
+
+// src/auth/resolve-login.ts
+async function resolveLogin(options) {
+  const fromEnvironment = options.variables.ACE_TOKEN?.trim();
+  if (fromEnvironment) return { token: fromEnvironment, source: "the ACE_TOKEN setting" };
+  const stored = await options.store.read(options.apiUrl);
+  if (!stored || hasExpired(stored, options.now())) return null;
+  return { token: stored.token, email: stored.email, source: options.store.description };
+}
+
+// src/cli/login-commands.ts
+var loginUsage = `ace-kit login: sign in to CMS Ace from the command line.
+
+Usage:
+  ace-kit login  [--api-url <address>]    Sign in. Opens the admin app, where you type the code shown here.
+  ace-kit logout [--api-url <address>]    Sign out, and forget the login kept on this machine.
+  ace-kit whoami [--api-url <address>]    Say who you are signed in as.
+
+Options:
+  --api-url   Where the CMS Ace API lives (or set ACE_API_URL, in the environment or a .env file).
+  --help      Show this message.
+
+The login is kept in the macOS Keychain, or in a file only you can read on other systems. On a build server,
+where nobody can approve a login in a browser, set ACE_TOKEN instead.
+`;
+var requestTimeoutMilliseconds3 = 15e3;
+async function readApiUrl(commandArguments, environment) {
+  const { values } = parseArgs2({
+    // eslint-disable-next-line id-denylist -- "args" is the name node's parseArgs gives this option.
+    args: commandArguments,
+    options: { "api-url": { type: "string" }, help: { type: "boolean" } }
+  });
+  if (values.help) return { help: true };
+  const address = values["api-url"] ?? environment.variables.ACE_API_URL ?? await environment.lastApiUrl.read();
+  if (!address) {
+    environment.error(
+      "Give the API address: --api-url, or ACE_API_URL in the environment or a .env file. (Once you have signed in, that address is remembered.)"
+    );
+    return null;
+  }
+  try {
+    return { apiUrl: normaliseApiUrl(address) };
+  } catch (error) {
+    environment.error(error instanceof Error ? error.message : String(error));
+    return null;
+  }
+}
+function webAddress(address) {
+  try {
+    const parsed = new URL(address);
+    return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed.href : null;
+  } catch {
+    return null;
+  }
+}
+var isLocal = (apiUrl) => ["localhost", "127.0.0.1", "[::1]"].includes(new URL(apiUrl).hostname);
+async function loginCommand(commandArguments, environment) {
+  const read = await readApiUrl(commandArguments, environment);
+  if (!read) return 1;
+  if ("help" in read) {
+    environment.out(loginUsage);
+    return 0;
+  }
+  const { apiUrl } = read;
+  if (apiUrl.startsWith("http://") && !isLocal(apiUrl)) {
+    environment.error(
+      `Warning: ${apiUrl} is not encrypted (http://), so the login could be read on the way. Use https:// if you can.`
+    );
+  }
+  try {
+    const request = await startDeviceLogin({
+      fetchImplementation: environment.fetchImplementation,
+      apiUrl,
+      clientName: `ace-kit ${environment.version} on ${environment.hostname}`
+    });
+    const page = webAddress(request.verificationUri);
+    if (!page)
+      throw new DeviceLoginError(
+        "unsupported",
+        "The CMS sent an approval address that isn't a web address, so it was not opened."
+      );
+    environment.out(`Signing in to ${apiUrl}
+`);
+    environment.out(`  1. Go to   ${page}`);
+    environment.out(`  2. Type    ${request.userCode}
+`);
+    environment.out("Check the code on that page matches. Waiting for you to approve it (Ctrl-C to cancel)...");
+    await environment.openBrowser(page).catch(() => void 0);
+    const login = await waitForApproval({
+      fetchImplementation: environment.fetchImplementation,
+      apiUrl,
+      request,
+      sleep: environment.sleep,
+      now: environment.now
+    });
+    await environment.store.write(apiUrl, login);
+    await environment.lastApiUrl.write(apiUrl).catch(() => void 0);
+    environment.out(`
+Signed in as ${login.email}. The login is kept in ${environment.store.description}.`);
+    return 0;
+  } catch (error) {
+    environment.error(`
+${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+}
+async function logoutCommand(commandArguments, environment) {
+  const read = await readApiUrl(commandArguments, environment);
+  if (!read) return 1;
+  if ("help" in read) {
+    environment.out(loginUsage);
+    return 0;
+  }
+  const { apiUrl } = read;
+  const stored = await environment.store.read(apiUrl);
+  if (!stored) {
+    environment.out(`Not signed in to ${apiUrl}.`);
+    return 0;
+  }
+  const ended = await environment.fetchImplementation(`${apiUrl}/auth/logout`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${stored.token}` },
+    signal: AbortSignal.timeout(requestTimeoutMilliseconds3)
+  }).then(
+    (response) => response.ok || response.status === 401,
+    () => false
+  );
+  await environment.store.remove(apiUrl);
+  environment.out(
+    ended ? `Signed out of ${apiUrl}.` : `Forgot the login for ${apiUrl} on this machine, but could not reach the CMS to end it there. It ends by itself after 30 days unused; a super admin can also end it from the Sessions screen.`
+  );
   return 0;
 }
-main().then(
+async function whoamiCommand(commandArguments, environment) {
+  const read = await readApiUrl(commandArguments, environment);
+  if (!read) return 1;
+  if ("help" in read) {
+    environment.out(loginUsage);
+    return 0;
+  }
+  const { apiUrl } = read;
+  const login = await resolveLogin({
+    apiUrl,
+    variables: environment.variables,
+    store: environment.store,
+    now: environment.now
+  });
+  if (!login) {
+    environment.out(`Not signed in to ${apiUrl}. Run: ace-kit login`);
+    return 1;
+  }
+  try {
+    const response = await environment.fetchImplementation(`${apiUrl}/auth/me`, {
+      headers: { Accept: "application/json", Authorization: `Bearer ${login.token}` },
+      signal: AbortSignal.timeout(requestTimeoutMilliseconds3)
+    });
+    if (response.status === 401) {
+      environment.out(`The login from ${login.source} has ended. Run: ace-kit login`);
+      return 1;
+    }
+    if (!response.ok) {
+      environment.error(`The CMS answered with an error (${response.status}).`);
+      return 1;
+    }
+    const me = await response.json();
+    environment.out(`Signed in to ${apiUrl} as ${String(me.email)}, using the login in ${login.source}.`);
+    return 0;
+  } catch {
+    environment.error(`Could not reach the CMS at ${apiUrl}.`);
+    return 1;
+  }
+}
+
+// src/cli/main.ts
+var usage = `ace-kit: tools for sites built on CMS Ace.
+
+Commands:
+  ace-kit generate   Write TypeScript types for your content types.
+  ace-kit login      Sign in from the command line (opens the admin app).
+  ace-kit logout     Sign out.
+  ace-kit whoami     Say who you are signed in as.
+
+Run a command with --help for more.
+`;
+async function runCli(commandArguments, environment) {
+  const [command, ...rest] = commandArguments;
+  switch (command) {
+    case "generate":
+      return generateCommand(rest, environment);
+    case "login":
+      return loginCommand(rest, environment);
+    case "logout":
+      return logoutCommand(rest, environment);
+    case "whoami":
+      return whoamiCommand(rest, environment);
+    case "--help":
+    case "-h":
+    case "help":
+    case void 0:
+      environment.out(usage);
+      return command === void 0 ? 1 : 0;
+    default:
+      environment.error(`Unknown command "${command}".
+
+${usage}`);
+      return 1;
+  }
+}
+
+// src/cli/bin.ts
+createRealEnvironment().then((environment) => runCli(process.argv.slice(2), environment)).then(
   (code) => process.exit(code),
   (error) => {
     console.error(error instanceof Error ? error.message : error);

package/docs/command-line.md

@@ -0,0 +1,51 @@
+# The command line
+
+`ace-kit` is also a command. It signs you in to CMS Ace from your terminal, and writes types for your content.
+
+```sh
+npx ace-kit login      # sign in
+npx ace-kit whoami     # who am I signed in as?
+npx ace-kit logout     # sign out
+npx ace-kit generate   # write TypeScript types (see Typed content)
+```
+
+Every command takes `--api-url`, or reads `ACE_API_URL` from the environment or a `.env` file in the folder you run it in. Failing both, it uses the address you last signed in to (kept in a small file beside your logins), so after `ace-kit login --api-url …` you can simply run `ace-kit whoami` from anywhere.
+
+## Signing in
+
+```sh
+npx ace-kit login --api-url http://localhost:8080
+```
+
+```
+Signing in to http://localhost:8080
+
+  1. Go to   http://localhost:5173/device
+  2. Type    BCDF-GHJK
+
+Check the code on that page matches. Waiting for you to approve it (Ctrl-C to cancel)...
+```
+
+Your browser opens the CMS admin app's approval page. **Type the code from your terminal** into it (it is deliberately not in the link), check that the tool and the address it shows are yours, and choose **Approve**. The terminal then says who you are signed in as. This is the OAuth device flow, the same shape as `gh auth login`: no password is ever typed into the terminal, and nothing secret is written in a file inside your project.
+
+Only approve a login you started just now, from your own terminal. If the code on the page doesn't match the one in your terminal, or you didn't ask for a login, choose **Turn it down**.
+
+## Where the login is kept
+
+- **On a Mac:** the macOS Keychain, as an item named `ace-kit` whose account is the API address. You can see it in Keychain Access. Ace Kit uses the `security` program that comes with macOS, so nothing native is installed, and the login is handed to it on standard input, never as an argument other users of the machine could read.
+- **Anywhere else:** a file only you can read, `~/.config/ace-kit/credentials.json` (mode `0600`, in a folder of mode `0700`; `%APPDATA%\ace-kit` on Windows). Set `XDG_CONFIG_HOME` to move it.
+- Set `ACE_KIT_CREDENTIALS=file` to use the file even on a Mac.
+
+One login is kept per API address, so you can be signed in to a local CMS and a hosted one at once.
+
+## What a command-line login can do
+
+Much less than you can in the browser. It can see which sites you can reach, read their content types, and read and sync their section types (the last only on a site where you are an owner, or a super admin). It cannot manage members, passwords or other logins, read or change entries and images, or approve another command-line login. It lasts 90 days at most and ends after 30 days unused. A super admin sees it on the Sessions screen, named after your machine, and can end it from there.
+
+## Build servers
+
+A build server has nobody to approve a login in a browser. Set `ACE_TOKEN` to a token instead and Ace Kit uses it in place of a stored login. (Tokens for this are not made yet; for now sign in on the machine that needs it.)
+
+## Signing out
+
+`npx ace-kit logout` ends the login at the CMS and forgets it on this machine. If the CMS can't be reached it still forgets it here, and says so.

package/docs/getting-started.md

@@ -22,7 +22,7 @@ npm install @sandboxsonny/ace-kit
 | `@sandboxsonny/ace-kit/react-router`                     | React Router 7, browser-safe: `AceRichText` (router links), `AceImage`, `AceNotice`, `createMeta`, `useAceMenu`, `useAcePreview`                                  |
 | `@sandboxsonny/ace-kit/react-router/server`              | React Router 7, server only: `createPageLoader`, `createRootLoader`, `handleRequest` (the server entry), `getEntry`, `getEntries`, `getMenuLinks`, `getAceClient` |
 | `@sandboxsonny/ace-kit/vite`                             | A Vite plugin: reads `ACE_` settings from `.env` in development and keeps one copy of React                                                                       |
-| `ace-kit` (command)                                      | `ace-kit generate`, which writes TypeScript types for your content                                                                                                |
+| `ace-kit` (command)                                      | `ace-kit generate` (TypeScript types for your content), `login`, `logout`, `whoami` (see [the command line](./command-line.md))                                   |
 
 ## The client
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxsonny/ace-kit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Everything a website needs to use CMS Ace: a typed client, addressing, images, menus, rich text, live preview, and Astro and React adapters.",
   "keywords": [
     "cms",