@gogitcms/editor 0.23.0

package/src/lib/plugins.mjs

@@ -0,0 +1,164 @@
+// Resolving the plugins listed in a project's cms.config.js `plugins` and
+// feeding them to Vite as the `virtual:cms-plugins` module the SPA boots from
+// (apps/frontend/src/main.tsx). This is the gogitcms-editor counterpart of the same
+// logic in apps/frontend/bin/cms-frontend.mjs — duplicated rather than shared
+// because gogitcms-editor publishes a self-contained tarball that vendors its
+// dependencies and cannot import from apps/frontend at a consumer's runtime.
+//
+//   plugins: [
+//     "@acme/cms-analytics",                 // npm package in the project
+//     ["@acme/cms-colors", { palette: 1 }],  // with options → setup(cms, options)
+//     "./local-plugins/experiments",         // relative path during development
+//   ]
+//
+// Each entry resolves from the project directory (where cms.config.js and the
+// node_modules holding its plugins live), and is emitted as a dynamic import so
+// the plugin loads lazily at runtime.
+
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+
+// The shared modules a plugin imports by the same @gogitcms/* names the app
+// uses. dedupe collapses each to the app's own copy so one React / one
+// design-system (one theme context) is shared across the app and its plugins.
+// In a published gogitcms-editor the staged Vite config also aliases these onto the
+// vendored copies, which resolves them even when the project has not installed
+// them (they are optional peers).
+export const PLUGIN_PEER_DEPS = [
+  "react",
+  "react-dom",
+  "react-native-web",
+  "@gogitcms/design-system",
+  "@gogitcms/plugin-sdk",
+  "@gogitcms/markdown-editor",
+];
+
+// LEGACY_SCOPE_ALIASES redirects the pre-rename @go-git-cms/* names onto the
+// @gogitcms/* ones the host actually provides.
+//
+// The workspace moved scope when the packages moved to npmjs, but plugins
+// published before that — @go-git-cms/plugin-mdx is the one in this repo —
+// import the old names. Without this they resolve to whatever copy of the old
+// package the project happens to have installed, which is a SECOND
+// design-system and therefore a second theme React context: the plugin's
+// controls render unthemed beside the host's. dedupe cannot fix that, because
+// dedupe collapses copies of one name rather than bridging two names.
+//
+// Aliases, not dedupe entries, for that reason. Harmless when a plugin never
+// names them. Remove once the ecosystem has republished under @gogitcms.
+const LEGACY_SCOPE = "@go-git-cms";
+export const LEGACY_SCOPE_ALIASES = Object.fromEntries(
+  PLUGIN_PEER_DEPS.filter((name) => name.startsWith("@gogitcms/")).map((name) => [
+    `${LEGACY_SCOPE}/${name.slice("@gogitcms/".length)}`,
+    name,
+  ]),
+);
+
+// The directory a project exposes to its plugins, and the specifier they reach
+// it by. A plugin that renders the project's own components has to name them in
+// a literal `import.meta.glob` — that is the only form Vite can see — but the
+// directory it should glob belongs to the project, and no relative path from an
+// installed package reaches it (under pnpm the package is a symlink into the
+// content-addressed store). Vite resolves `resolve.alias` inside a glob
+// pattern, so the alias is what closes that gap: the plugin's pattern stays
+// literal and the host decides where it points.
+//
+// Always aliased, whether or not the directory exists — an alias pointing at
+// nothing simply matches nothing, and creating the directory should not require
+// restarting the dev server to be noticed.
+export const PROJECT_COMPONENTS_SPECIFIER = "@cms-components";
+export const PROJECT_COMPONENTS_DIR = "cms-components";
+
+// projectAliases returns the resolve.alias entries for a project directory.
+export function projectAliases(cwd = process.cwd()) {
+  return {
+    ...LEGACY_SCOPE_ALIASES,
+    [PROJECT_COMPONENTS_SPECIFIER]: path.resolve(cwd, PROJECT_COMPONENTS_DIR),
+  };
+}
+
+// nearestPackageName walks up from a resolved entry file to name a plugin
+// linked by path, so its id matches what it would be if installed from a
+// registry.
+function nearestPackageName(entryFile) {
+  for (let dir = path.dirname(entryFile); ; dir = path.dirname(dir)) {
+    const pkg = path.join(dir, "package.json");
+    if (fs.existsSync(pkg)) {
+      try {
+        const name = JSON.parse(fs.readFileSync(pkg, "utf8")).name;
+        if (name) return name;
+      } catch {
+        /* unparseable package.json — keep walking */
+      }
+    }
+    if (dir === path.dirname(dir)) return null;
+  }
+}
+
+// resolvePlugins normalizes a config's `plugins` to { id, options, entry },
+// with `entry` the absolute path to each plugin's main file, resolved from the
+// project directory.
+export function resolvePlugins(cfg, cwd = process.cwd()) {
+  const specs = Array.isArray(cfg?.plugins) ? cfg.plugins : [];
+  // Resolve as the project would: from a real file inside it. package.json is
+  // always present; cms.config.* may be .mjs/.ts, so package.json is the stable
+  // anchor for createRequire.
+  const req = createRequire(path.join(cwd, "package.json"));
+  const seen = new Set();
+  return specs.map((spec) => {
+    let name, options;
+    if (typeof spec === "string") name = spec;
+    else if (Array.isArray(spec)) [name, options] = spec;
+    else if (spec && typeof spec === "object") ({ name, options } = spec);
+    if (!name || typeof name !== "string") {
+      throw new Error(`cms.config plugins: invalid entry ${JSON.stringify(spec)}`);
+    }
+    const isPath = name.startsWith(".") || path.isAbsolute(name);
+    let entry;
+    try {
+      entry = req.resolve(isPath ? path.resolve(cwd, name) : name);
+    } catch {
+      throw new Error(
+        `cms.config plugins: cannot resolve "${name}" from ${cwd} — is it installed?`,
+      );
+    }
+    const id = (isPath ? nearestPackageName(entry) : null) ?? name;
+    if (seen.has(id)) throw new Error(`cms.config plugins: duplicate plugin "${id}"`);
+    seen.add(id);
+    return { id, options, entry };
+  });
+}
+
+// cmsPluginsVite provides the `virtual:cms-plugins` module the SPA imports.
+// Always installed by dev/build (even with an empty list, so the import
+// resolves), it replaces the empty stub the staged config used to ship.
+export function cmsPluginsVite(resolved) {
+  const VIRTUAL = "virtual:cms-plugins";
+  const RESOLVED = "\0" + VIRTUAL;
+  return {
+    name: "cms-plugins",
+    // enforce:"pre" so this resolves the virtual id before any other plugin.
+    enforce: "pre",
+    resolveId(id) {
+      return id === VIRTUAL ? RESOLVED : undefined;
+    },
+    load(id) {
+      if (id !== RESOLVED) return undefined;
+      const entries = resolved.map(
+        (p) =>
+          `  { id: ${JSON.stringify(p.id)}, options: ${
+            p.options === undefined ? "undefined" : JSON.stringify(p.options)
+          }, load: () => import(${JSON.stringify(p.entry)}) },`,
+      );
+      return `export const plugins = [\n${entries.join("\n")}\n];\n`;
+    },
+  };
+}
+
+// pluginDirs returns the absolute directories the plugin entries live in, so
+// the dev server's fs.allow can include them (they sit in the project's
+// node_modules, outside the editor's app root).
+export function pluginDirs(resolved) {
+  return [...new Set(resolved.map((p) => path.dirname(p.entry)))];
+}

package/src/lib/tokenBroker.mjs

@@ -0,0 +1,85 @@
+// The dev server's token endpoint.
+//
+// `gogitcms-editor dev` serves the editor from a throwaway localhost origin, which
+// the server's PKCE redirect allowlist will never contain (it admits the
+// same-origin /app path and editor deployments registered on a workspace — see
+// validRedirectURI in packages/rest/v1.0.0/auth_handlers.go). Rather than ask
+// people to register every dev port, the CLI lends the SPA the session it
+// already has.
+//
+// That makes this endpoint a bearer-token dispenser, so it is fenced in:
+//   * the dev server binds to the requested host (localhost by default), and
+//   * requests must come from a loopback Host and carry no cross-site Origin,
+// which keeps a page on some other origin in the same browser from fetching a
+// token out of it.
+
+import * as api from "./api.mjs";
+
+export const TOKEN_PATH = "/__gitcms/token";
+
+function isLoopbackHost(host = "") {
+  const name = host.replace(/:\d+$/, "").replace(/^\[|\]$/g, "");
+  return name === "localhost" || name === "127.0.0.1" || name === "::1";
+}
+
+// originAllowed rejects a cross-site fetch. Same-origin requests from the SPA
+// either omit Origin or send the dev server's own, so anything else — a page on
+// another site trying to read a token out of the dev server — is refused.
+function originAllowed(req) {
+  const origin = req.headers.origin;
+  if (!origin) return true;
+  try {
+    return isLoopbackHost(new URL(origin).host) && new URL(origin).host === req.headers.host;
+  } catch {
+    return false;
+  }
+}
+
+// localTokenBroker serves the local server's session token instead of a hosted
+// access token. Same endpoint, same loopback fencing — the SPA's boot path
+// (Root() in App.tsx) prefers a brokered token over the PKCE bounce, so local
+// mode lands on "authed" without touching an issuer that does not exist.
+export function localTokenBroker(token) {
+  return {
+    name: "gitcms-local-token-broker",
+    configureServer(server) {
+      server.middlewares.use(TOKEN_PATH, (req, res) => {
+        if (!isLoopbackHost(req.headers.host) || !originAllowed(req)) {
+          res.statusCode = 403;
+          res.end(JSON.stringify({ error: "forbidden" }));
+          return;
+        }
+        res.setHeader("Content-Type", "application/json");
+        res.setHeader("Cache-Control", "no-store");
+        res.end(JSON.stringify({ accessToken: token }));
+      });
+    },
+  };
+}
+
+// tokenBroker is a Vite plugin serving a fresh access token for apiUrl.
+export function tokenBroker(apiUrl) {
+  return {
+    name: "gitcms-token-broker",
+    configureServer(server) {
+      server.middlewares.use(TOKEN_PATH, async (req, res) => {
+        if (!isLoopbackHost(req.headers.host) || !originAllowed(req)) {
+          res.statusCode = 403;
+          res.end(JSON.stringify({ error: "forbidden" }));
+          return;
+        }
+        try {
+          const accessToken = await api.accessToken(apiUrl);
+          res.setHeader("Content-Type", "application/json");
+          // A short-lived credential must not linger in any cache.
+          res.setHeader("Cache-Control", "no-store");
+          res.end(JSON.stringify({ accessToken }));
+        } catch (e) {
+          res.statusCode = e instanceof api.NotLoggedInError ? 401 : 502;
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ error: e.message }));
+        }
+      });
+    },
+  };
+}

package/src/tui/prompts.mjs

@@ -0,0 +1,92 @@
+// Interactive pickers. Each one tears the sticky block down first — terminal-kit
+// draws its menus at the cursor and manages the lines itself, so leaving our
+// status line pinned underneath would corrupt both — and hands stdin back
+// afterwards via withInput (see releaseInput for why that is mandatory).
+//
+// None of these work without a TTY. Callers must resolve the value from a flag
+// in that case; `requireInteractive` turns the mistake into a clear error rather
+// than a hang on stdin.
+
+import { getTerm, isInteractive, releaseInput } from "./screen.mjs";
+import { THEME } from "./theme.mjs";
+
+export class NotInteractiveError extends Error {
+  constructor(what, flag) {
+    super(`${what} must be chosen interactively — pass ${flag} when running without a terminal.`);
+    this.name = "NotInteractiveError";
+  }
+}
+
+export function requireInteractive(what, flag) {
+  if (!isInteractive()) throw new NotInteractiveError(what, flag);
+}
+
+// withInput runs one terminal-kit widget and guarantees stdin is handed back,
+// whatever happens. While input is grabbed the terminal is in raw mode, so
+// Ctrl-C is delivered as a key event instead of a signal — the listener below
+// restores that behaviour by hand, or the user could not abort a prompt at all.
+// 130 is the conventional status for "terminated by Ctrl-C".
+async function withInput(screen, fn) {
+  const term = getTerm();
+  const onKey = (name) => {
+    if (name !== "CTRL_C") return;
+    screen.finish();
+    term("\n");
+    process.exit(130);
+  };
+  term.on("key", onKey);
+  try {
+    return await fn(term);
+  } finally {
+    term.off("key", onKey);
+    releaseInput();
+  }
+}
+
+// select renders a single-column menu and resolves the chosen item. `items` are
+// { label, value } pairs; Escape cancels, which resolves to null.
+export async function select(screen, title, items) {
+  requireInteractive(title, "the matching flag");
+  screen.clearSticky();
+  const term = getTerm();
+  term.colorRgbHex(THEME.dim, title);
+  term("\n");
+  const result = await withInput(screen, (t) =>
+    t.singleColumnMenu(
+      items.map((i) => i.label),
+      { cancelable: true, selectedStyle: t.bgBrightWhite.black, leftPadding: "  ", selectedLeftPadding: "› " },
+    ).promise,
+  );
+  term("\n");
+  screen.drawSticky();
+  if (result.canceled || result.selectedIndex == null) return null;
+  return items[result.selectedIndex].value;
+}
+
+// ask reads a line of input with an optional default.
+export async function ask(screen, label, { defaultValue = "" } = {}) {
+  requireInteractive(label, "the matching flag");
+  screen.clearSticky();
+  const term = getTerm();
+  term.colorRgbHex(THEME.dim, `${label} `);
+  const value = await withInput(screen, (t) =>
+    t.inputField({ default: defaultValue, cancelable: true }).promise,
+  );
+  term("\n");
+  screen.drawSticky();
+  return value == null ? null : value.trim();
+}
+
+// confirm asks a yes/no question, defaulting to yes.
+export async function confirm(screen, question, defaultYes = true) {
+  if (!isInteractive()) return defaultYes;
+  screen.clearSticky();
+  const term = getTerm();
+  term.colorRgbHex(THEME.dim, `${question} ${defaultYes ? "[Y/n]" : "[y/N]"} `);
+  const answer = await withInput(screen, (t) =>
+    t.yesOrNo({ yes: ["y", "Y", "ENTER"], no: ["n", "N"] }).promise,
+  );
+  term("\n");
+  screen.drawSticky();
+  return answer;
+}

package/src/tui/screen.mjs

@@ -0,0 +1,282 @@
+// The screen: header, streamed output lines, and the sticky bottom block
+// (optional spinner line + status line) from the terminal onboarding design.
+//
+// Output is written as ordinary lines so scrollback still works; the sticky
+// block lives on the last one or two lines and is erased and redrawn around each
+// write. Everything degrades to plain `console.log` when stdout is not a TTY, so
+// piping the CLI into a file or a CI log yields clean text.
+
+import tk from "terminal-kit";
+import { classStyle, STEPS, THEME } from "./theme.mjs";
+
+// terminal-kit resolves the terminal on first access to `tk.terminal`, and on
+// macOS its detection does path.parse() on TERM/COLORTERM/TERM_PROGRAM without
+// checking that any of them is set — which throws under a bare pty (`script`,
+// some CI runners, cron). Acquire it lazily, so a non-TTY run never touches it
+// at all, and name a terminal when the environment names none.
+let _term = null;
+
+export function getTerm() {
+  if (!_term) {
+    if (!process.env.TERM && !process.env.COLORTERM && !process.env.TERM_PROGRAM) {
+      process.env.TERM = "xterm-256color";
+    }
+    _term = tk.terminal;
+  }
+  return _term;
+}
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+// Line cadence from the design, so output reads as it arrives rather than
+// dumping at once. Suppressed off a TTY and under GITCMS_NO_ANIMATION (tests).
+const DELAY = { default: 155, ok: 280, blank: 55 };
+
+export function isInteractive() {
+  return Boolean(process.stdout.isTTY) && !process.env.CI && !process.env.GITCMS_NO_TTY;
+}
+
+function animated() {
+  return isInteractive() && !process.env.GITCMS_NO_ANIMATION;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export class Screen {
+  constructor() {
+    // How many lines the sticky block currently occupies (0 = not drawn).
+    this.sticky = 0;
+    this.spinnerText = "";
+    this.spinnerFrame = 0;
+    this.spinnerTimer = null;
+    this.status = {
+      mode: "READY",
+      auth: "not logged in",
+      authed: false,
+      cwd: shortCwd(),
+      hint: "",
+    };
+    this.done = [false, false, false];
+    this.interactive = isInteractive();
+    // Set by a long-running command (dev) that needs to shut something down on
+    // Ctrl-C instead of being killed where it stands. See bin/gogitcms-editor.mjs.
+    this.onInterrupt = null;
+  }
+
+  // ---- output -------------------------------------------------------------
+
+  // line writes one output line in the style of its class (see theme.mjs).
+  line(text = "", cls = "out") {
+    if (!this.interactive) {
+      console.log(text);
+      return;
+    }
+    this.clearSticky();
+    const style = classStyle(cls);
+    const body = style.spaced ? [...String(text)].join(" ") : String(text);
+    if (style.bold) getTerm().bold();
+    getTerm().colorRgbHex(style.color, body);
+    getTerm().styleReset();
+    getTerm()("\n");
+    this.drawSticky();
+  }
+
+  // stream writes lines with the design's pacing. Each entry is a string or
+  // { text, cls }.
+  async stream(lines) {
+    for (const entry of lines) {
+      const { text = "", cls = "out" } = typeof entry === "string" ? { text: entry } : entry;
+      this.line(text, cls);
+      if (!animated()) continue;
+      await sleep(text.trim() === "" ? DELAY.blank : DELAY[cls] || DELAY.default);
+    }
+  }
+
+  ok(text) {
+    this.line(text.startsWith("✓") ? text : `✓ ${text}`, "ok");
+  }
+
+  fail(text) {
+    this.line(text.startsWith("✗") ? text : `✗ ${text}`, "err");
+  }
+
+  // header prints the branded block and the step ticker: the top chrome of the
+  // design, drawn once per command rather than pinned.
+  header(subtitle = "SETUP") {
+    if (!this.interactive) {
+      console.log(`gogitcms-editor — ${subtitle.toLowerCase()}`);
+      return;
+    }
+    this.clearSticky();
+    getTerm().colorRgbHex(THEME.faint, "GO·GIT CMS ");
+    getTerm().colorRgbHex(THEME.border, "/ ");
+    getTerm().colorRgbHex(THEME.dim, subtitle);
+    const doneCount = this.done.filter(Boolean).length;
+    const progress = `${doneCount} / ${STEPS.length} complete`;
+    const pad = Math.max(1, getTerm().width - 13 - subtitle.length - progress.length);
+    getTerm()(" ".repeat(pad));
+    getTerm().colorRgbHex(THEME.faint, progress);
+    getTerm()("\n");
+    this.steps();
+    getTerm()("\n");
+    this.drawSticky();
+  }
+
+  // steps renders the 01/02/03 ticker, marking completed steps with a check and
+  // the current one as active.
+  steps() {
+    const current = this.done.findIndex((d) => !d);
+    STEPS.forEach((s, i) => {
+      const isDone = this.done[i];
+      const active = i === current;
+      const mark = isDone ? "✓" : s.n;
+      const color = isDone || active ? THEME.fg : THEME.dim;
+      if (isDone || active) getTerm().bold();
+      getTerm().colorRgbHex(color, `${mark} ${s.label}`);
+      getTerm().styleReset();
+      if (i < STEPS.length - 1) getTerm().colorRgbHex(THEME.border, "  ·  ");
+    });
+    getTerm()("\n");
+  }
+
+  // ---- status -------------------------------------------------------------
+
+  setStatus(patch) {
+    Object.assign(this.status, patch);
+    if (this.interactive) {
+      this.clearSticky();
+      this.drawSticky();
+    }
+  }
+
+  setDone(index, value = true) {
+    this.done[index] = value;
+  }
+
+  // ---- spinner ------------------------------------------------------------
+
+  // startSpinner pins an animated line above the status line. Returns a stop
+  // function that clears it; callers usually follow with ok()/fail().
+  startSpinner(text) {
+    this.spinnerText = text;
+    if (!this.interactive) {
+      console.log(text);
+      return () => {};
+    }
+    this.clearSticky();
+    this.drawSticky();
+    if (animated()) {
+      this.spinnerTimer = setInterval(() => {
+        this.spinnerFrame = (this.spinnerFrame + 1) % SPINNER_FRAMES.length;
+        this.clearSticky();
+        this.drawSticky();
+      }, 90);
+      // A pinned spinner must never hold the process open on its own.
+      this.spinnerTimer.unref?.();
+    }
+    return () => this.stopSpinner();
+  }
+
+  stopSpinner() {
+    if (this.spinnerTimer) {
+      clearInterval(this.spinnerTimer);
+      this.spinnerTimer = null;
+    }
+    if (!this.spinnerText) return;
+    this.spinnerText = "";
+    if (this.interactive) {
+      this.clearSticky();
+      this.drawSticky();
+    }
+  }
+
+  // ---- sticky block -------------------------------------------------------
+
+  // drawSticky renders the spinner line (when active) and the status line at the
+  // bottom, leaving the cursor parked at the start of the status line so the
+  // next clearSticky knows exactly what to erase.
+  drawSticky() {
+    if (!this.interactive) return;
+    let lines = 0;
+    if (this.spinnerText) {
+      getTerm().colorRgbHex(THEME.dim, `${SPINNER_FRAMES[this.spinnerFrame]} ${this.spinnerText}`);
+      getTerm()("\n");
+      lines++;
+    }
+    this.statusLine();
+    lines++;
+    this.sticky = lines;
+  }
+
+  // clearSticky erases the sticky block and returns the cursor to its first
+  // line, which is where the next output line belongs.
+  clearSticky() {
+    if (!this.interactive || this.sticky === 0) return;
+    for (let i = 0; i < this.sticky; i++) {
+      getTerm().column(1);
+      getTerm().eraseLine();
+      if (i < this.sticky - 1) getTerm().up(1);
+    }
+    this.sticky = 0;
+  }
+
+  // statusLine draws the mode pill, auth state, working directory and next-step
+  // hint — the bottom bar of the design. No trailing newline: it is the last
+  // thing on screen.
+  statusLine() {
+    const s = this.status;
+    const pillBg =
+      s.mode === "DONE" ? THEME.ok : s.mode === "READY" ? THEME.pill : THEME.fg;
+    const pillFg = s.mode === "READY" ? THEME.fg : THEME.bg;
+    getTerm().bgColorRgbHex(pillBg);
+    getTerm().colorRgbHex(pillFg, ` ${s.mode} `);
+    getTerm().styleReset();
+    getTerm().colorRgbHex(s.authed ? THEME.ok : THEME.faint, " ● ");
+    getTerm().colorRgbHex(THEME.dim, s.auth);
+    getTerm().colorRgbHex(THEME.faint, `  ${s.cwd}`);
+    if (s.hint) {
+      const left = `  ${s.mode}  ● ${s.auth}  ${s.cwd}`.length;
+      const pad = Math.max(1, getTerm().width - left - s.hint.length - 1);
+      getTerm()(" ".repeat(pad));
+      getTerm().colorRgbHex(THEME.faint, s.hint);
+    }
+    getTerm().styleReset();
+  }
+
+  // done tears the sticky block down so the shell prompt returns to a clean
+  // line. Every command must call this before exiting.
+  finish() {
+    this.stopSpinner();
+    if (!this.interactive) return;
+    this.clearSticky();
+    getTerm().styleReset();
+    releaseInput();
+  }
+}
+
+// releaseInput hands stdin back to the shell. terminal-kit's widgets (menus,
+// input fields, yes/no) grab input and never let go, which leaves the terminal
+// in raw mode: the process then hangs after its last line — a grabbed stdin is
+// an active handle, so the event loop never drains — and Ctrl-C arrives as a key
+// event rather than SIGINT, so it cannot kill anything either. Every path that
+// grabs input must end here.
+export function releaseInput() {
+  if (!_term) return;
+  try {
+    _term.grabInput(false);
+    _term.hideCursor(false);
+  } catch {
+    // Restoring a terminal that was never grabbed is a no-op, not an error.
+  }
+  // grabInput(false) removes terminal-kit's listener but leaves stdin resumed;
+  // pausing it releases the last handle keeping the process alive.
+  if (process.stdin.isTTY) process.stdin.pause();
+}
+
+// shortCwd renders the working directory the way a shell prompt does.
+function shortCwd() {
+  const cwd = process.cwd();
+  const home = process.env.HOME || "";
+  return home && cwd.startsWith(home) ? `~${cwd.slice(home.length)}` : cwd;
+}
+

package/src/tui/theme.mjs

@@ -0,0 +1,40 @@
+// The palette and line taxonomy from the terminal onboarding design. Colours are
+// applied with terminal-kit's truecolor helpers; on a terminal without truecolor
+// terminal-kit degrades them to the nearest palette entry on its own.
+
+export const THEME = {
+  fg: "#ededed",
+  dim: "#808080",
+  faint: "#5c5c5c",
+  ok: "#5fce8a",
+  err: "#f08b82",
+  border: "#242424",
+  bg: "#0a0a0a",
+  pill: "#3d3d3d",
+};
+
+// Line classes, mirroring resolveLine() in the design. Each maps to a colour and
+// whether it is emphasised; `code` is the big one-time code, `fileline` is a
+// rendered config file body.
+const CLASSES = {
+  out: { color: THEME.fg },
+  dim: { color: THEME.dim },
+  ok: { color: THEME.ok },
+  err: { color: THEME.err },
+  label: { color: THEME.dim, bold: true, caps: true },
+  code: { color: THEME.fg, bold: true, spaced: true },
+  filehdr: { color: THEME.dim, bold: true },
+  fileline: { color: THEME.fg },
+  in: { color: THEME.fg, bold: true },
+};
+
+export function classStyle(cls) {
+  return CLASSES[cls] || CLASSES.out;
+}
+
+// The three onboarding steps, in the order the design walks them.
+export const STEPS = [
+  { n: "01", label: "auth", cmd: "gogitcms-editor login" },
+  { n: "02", label: "config", cmd: "gogitcms-editor init" },
+  { n: "03", label: "run", cmd: "gogitcms-editor dev" },
+];