@gogitcms/editor 0.23.0

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@gogitcms/editor",
+  "version": "0.23.0",
+  "description": "Terminal UI for setting up and running the Go·Git CMS content editor",
+  "type": "module",
+  "bin": {
+    "gogitcms-editor": "bin/gogitcms-editor.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/go-git-cms/gogitcms.git",
+    "directory": "apps/editor"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin",
+    "src",
+    "app",
+    "npm-shrinkwrap.json"
+  ],
+  "scripts": {
+    "prepack": "node scripts/prepack.mjs",
+    "smoke": "node scripts/smoke.mjs",
+    "start": "node bin/gogitcms-editor.mjs"
+  },
+  "dependencies": {
+    "@apollo/client": "^3.11.8",
+    "@handlewithcare/react-prosemirror": "^3.2.7",
+    "@react-navigation/native": "^7.3.11",
+    "@vitejs/plugin-react": "^4.3.1",
+    "graphql": "^16.9.0",
+    "graphql-ws": "^6.1.0",
+    "markdown-it": "^14.3.0",
+    "posthog-js": "^1.200.0",
+    "prosemirror-commands": "^1.7.1",
+    "prosemirror-dropcursor": "^1.8.3",
+    "prosemirror-gapcursor": "^1.4.1",
+    "prosemirror-history": "^1.5.0",
+    "prosemirror-inputrules": "^1.5.1",
+    "prosemirror-keymap": "^1.2.3",
+    "prosemirror-markdown": "^1.13.5",
+    "prosemirror-model": "^1.25.11",
+    "prosemirror-schema-list": "^1.5.1",
+    "prosemirror-state": "^1.4.4",
+    "prosemirror-tables": "^1.8.5",
+    "prosemirror-transform": "^1.12.0",
+    "prosemirror-view": "1.42.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-native-web": "^0.21.2",
+    "react-reconciler": "0.33.0",
+    "terminal-kit": "^3.1.2",
+    "vite": "^5.4.2",
+    "y-prosemirror": "^1.2.12",
+    "y-protocols": "^1.0.6",
+    "y-websocket": "^2.1.0",
+    "yjs": "^13.6.20"
+  },
+  "devDependencies": {
+    "@gogitcms/frontend": "workspace:*"
+  },
+  "optionalDependencies": {
+    "@gogitcms/gitcms-local-darwin-arm64": "0.23.0",
+    "@gogitcms/gitcms-local-darwin-x64": "0.23.0",
+    "@gogitcms/gitcms-local-linux-arm64": "0.23.0",
+    "@gogitcms/gitcms-local-linux-x64": "0.23.0",
+    "@gogitcms/gitcms-local-win32-x64": "0.23.0"
+  }
+}

package/src/commands/build.mjs

@@ -0,0 +1,100 @@
+// `gogitcms-editor build` — export the editor as a static SPA for self-hosting.
+//
+// The output is deliberately three files: index.html plus one JS and one CSS
+// bundle. That is what a self-hoster can drop on any static host without
+// thinking about chunk graphs or preload headers.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import * as config from "../lib/config.mjs";
+import * as credentials from "../lib/credentials.mjs";
+import { resolveAppRoot, viteConfigFile } from "../lib/appRoot.mjs";
+import { PLUGIN_PEER_DEPS, cmsPluginsVite, projectAliases, resolvePlugins } from "../lib/plugins.mjs";
+
+export async function build(screen, opts) {
+  const cfg = await config.load();
+  screen.header("BUILD");
+  if (!cfg) {
+    screen.fail("No cms.config.js found — run  gogitcms-editor init  first.");
+    return 1;
+  }
+
+  // Plugins listed in cms.config are bundled into the SPA (resolved from the
+  // project directory), the same as the dev server does.
+  let resolvedPlugins;
+  try {
+    resolvedPlugins = resolvePlugins(cfg);
+  } catch (e) {
+    screen.fail(e.message);
+    return 1;
+  }
+
+  const apiUrl = credentials.normalizeApiUrl(opts.apiUrl || cfg.API_URL);
+  const outDir = path.resolve(opts.out || "dist");
+  const appRoot = resolveAppRoot();
+  // BASE_PATH in the config is the deployment's mount path; --base overrides it
+  // for a one-off build. It sets both the asset URLs and, via BASE_URL, the
+  // paths the SPA's router writes.
+  const base = config.basePathFor(cfg, opts.base);
+
+  screen.setDone(0, Boolean(await credentials.load(apiUrl)));
+  screen.setDone(1);
+  screen.setStatus({ mode: "RUN", hint: "building" });
+  await screen.stream([{ text: "transforming content…", cls: "dim" }]);
+
+  const started = Date.now();
+  const { build: viteBuild } = await import("vite");
+  try {
+    await viteBuild({
+      root: appRoot,
+      configFile: viteConfigFile(appRoot),
+      base,
+      // The bundle is built for one deployment, so its API target is baked in
+      // rather than left to a runtime global.
+      define: config.defineFor({ ...cfg, API_URL: apiUrl }),
+      resolve: { dedupe: PLUGIN_PEER_DEPS, alias: projectAliases() },
+      plugins: [cmsPluginsVite(resolvedPlugins)],
+      logLevel: "silent",
+      build: {
+        outDir,
+        emptyOutDir: true,
+        // One JS file and one CSS file, with stable names: no hashed chunk soup
+        // for a self-hoster to wire up.
+        cssCodeSplit: false,
+        rollupOptions: {
+          output: {
+            inlineDynamicImports: true,
+            entryFileNames: "app.js",
+            assetFileNames: "app.[ext]",
+          },
+        },
+      },
+    });
+  } catch (e) {
+    screen.fail(`Build failed — ${e.message}`);
+    return 1;
+  }
+
+  const files = await fs.readdir(outDir);
+  let bytes = 0;
+  for (const f of files) bytes += (await fs.stat(path.join(outDir, f))).size;
+
+  screen.setDone(2);
+  screen.setStatus({ mode: "DONE", hint: "ready to deploy" });
+  await screen.stream([
+    ...files.sort().map((f) => ({ text: `  ${f}`, cls: "out" })),
+    { text: `✓ ${files.length} files · ${(bytes / 1024 / 1024).toFixed(1)} MB`, cls: "ok" },
+    { text: `✓ built in ${((Date.now() - started) / 1000).toFixed(2)}s → ${path.relative(process.cwd(), outDir) || outDir}`, cls: "ok" },
+    { text: `  serve at ${base}`, cls: "dim" },
+    "",
+    // Deep links are client-side routes with no file behind them, so a host that
+    // 404s unknown paths breaks every reload and bookmark.
+    { text: `Serve index.html for unknown paths under ${base} so deep links reload.`, cls: "dim" },
+    // The hosted SPA signs in with PKCE, and the server only returns an
+    // authorization code to a registered editor origin. Saying so here saves a
+    // confusing "invalid redirect_uri" on the first real deploy.
+    { text: "Register this site's URL as an editor in the dashboard, or sign-in", cls: "dim" },
+    { text: "will be refused at its new origin.", cls: "dim" },
+  ]);
+  return 0;
+}

package/src/commands/dev.mjs

@@ -0,0 +1,186 @@
+// `gogitcms-editor dev` — run the editor locally against your CMS (step 03).
+//
+// The SPA normally signs in with PKCE, which requires its origin to be a
+// registered editor deployment; a throwaway localhost port never is. The CLI
+// already holds a session from `login`, so it brokers one instead: the dev
+// server exposes /__gitcms/token, and the SPA takes its access token from there.
+// See tokenBroker below for why that endpoint is safe to expose.
+
+import path from "node:path";
+import * as api from "../lib/api.mjs";
+import * as config from "../lib/config.mjs";
+import * as credentials from "../lib/credentials.mjs";
+import { resolveAppRoot, viteConfigFile } from "../lib/appRoot.mjs";
+import { openUrl } from "../lib/open.mjs";
+import { TOKEN_PATH, localTokenBroker, tokenBroker } from "../lib/tokenBroker.mjs";
+import * as localServer from "../lib/localServer.mjs";
+import { PLUGIN_PEER_DEPS, cmsPluginsVite, pluginDirs, projectAliases, resolvePlugins } from "../lib/plugins.mjs";
+
+export async function dev(screen, opts) {
+  const cfg = await config.load();
+  // Local mode is the one path that does not require a config: the working copy's
+  // go-git-cms.yml already says what the content is, and cms.config.mjs exists to
+  // point the SPA at a hosted API there isn't one of.
+  const local = Boolean(opts.local) || cfg?.MODE === "local";
+  if (!cfg && !local) {
+    screen.header("SETUP");
+    screen.fail("No cms.config.js found — run  gogitcms-editor init  first.");
+    return 1;
+  }
+
+  // Started in local mode; held so the teardown below can stop it.
+  let localHandle = null;
+  let apiUrl;
+  let creds = null;
+  let brokerPlugin;
+  let runtimeConfig;
+
+  if (local) {
+    screen.setDone(0, true);
+    screen.setDone(1);
+    screen.header("DEV");
+    await screen.stream([{ text: "▲ starting the local content server…", cls: "dim" }]);
+    try {
+      localHandle = await localServer.start({
+        root: path.resolve(opts.root || process.cwd()),
+        port: opts.localPort,
+        // The server's own warnings (an unusable config, an unwatchable tree) are
+        // the user's to see; they arrive on stderr as it runs.
+        onLog: (line) => screen.line(line, "dim"),
+      });
+    } catch (e) {
+      screen.fail(e.message);
+      return 1;
+    }
+    const hs = localHandle.handshake;
+    apiUrl = hs.apiUrl;
+    // These override cms.config.mjs: local ids are derived from the working copy
+    // at startup, so a stored id from a hosted setup would address nothing.
+    runtimeConfig = {
+      ...cfg,
+      API_URL: hs.apiUrl,
+      WORKSPACE_ID: hs.workspaceId,
+      REPOSITORY_ID: hs.repositoryId,
+      TOKEN_ENDPOINT: TOKEN_PATH,
+      // Tells the SPA to hide the surfaces local mode cannot serve (see
+      // config.ts). Build-time only, so a page cannot talk itself into it.
+      MODE: "local",
+    };
+    brokerPlugin = localTokenBroker(hs.token);
+  } else {
+    apiUrl = credentials.normalizeApiUrl(opts.apiUrl || cfg.API_URL);
+    creds = await credentials.load(apiUrl);
+
+    screen.setDone(0, Boolean(creds));
+    screen.setDone(1);
+    screen.header("DEV");
+
+    if (!creds) {
+      screen.fail(`Not signed in to ${apiUrl} — run  gogitcms-editor login  first.`);
+      return 1;
+    }
+
+    // Fail before starting a server the SPA could never authenticate against.
+    try {
+      await api.accessToken(apiUrl);
+    } catch (e) {
+      screen.fail(e.message);
+      return 1;
+    }
+    runtimeConfig = { ...cfg, API_URL: apiUrl, TOKEN_ENDPOINT: TOKEN_PATH };
+    brokerPlugin = tokenBroker(apiUrl);
+  }
+
+  const appRoot = resolveAppRoot();
+  const port = Number(opts.port || 5173);
+  const host = opts.host || "localhost";
+  // Serve from the same mount the deployment uses, so a subpath install is
+  // exercised in development rather than discovered after it ships.
+  const base = config.basePathFor(cfg, opts.base);
+
+  screen.setStatus({
+    mode: "RUN",
+    auth: local ? "local files" : creds.email || "signed in",
+    authed: true,
+    hint: "ctrl-c to stop",
+  });
+  await screen.stream([
+    { text: "▲ starting dev server…", cls: "dim" },
+  ]);
+
+  // Resolve any plugins listed in cms.config from the project directory, so the
+  // editor bundles them into the SPA the same way `cms-frontend` does.
+  let resolvedPlugins;
+  try {
+    resolvedPlugins = resolvePlugins(cfg);
+  } catch (e) {
+    screen.fail(e.message);
+    return 1;
+  }
+
+  const started = Date.now();
+  const { createServer } = await import("vite");
+  let server;
+  try {
+    server = await createServer({
+      root: appRoot,
+      base,
+      configFile: viteConfigFile(appRoot),
+      // The SPA reads these at module scope; injecting them here is what points
+      // the local editor at the real API rather than its own origin.
+      define: config.defineFor(runtimeConfig),
+      // dedupe keeps one React / design-system across the app and its plugins;
+      // the alias is how a plugin globs the project's own components directory.
+      resolve: { dedupe: PLUGIN_PEER_DEPS, alias: projectAliases() },
+      server: {
+        port,
+        strictPort: true,
+        host,
+        // Plugins live in the project's node_modules, outside the editor app
+        // root; allow the dev server to read them (and the project itself).
+        fs: { allow: [appRoot, process.cwd(), ...pluginDirs(resolvedPlugins)] },
+      },
+      plugins: [brokerPlugin, cmsPluginsVite(resolvedPlugins)],
+    });
+    await server.listen();
+  } catch (e) {
+    screen.fail(`Could not start the dev server — ${e.message}`);
+    if (localHandle) await localHandle.stop();
+    return 1;
+  }
+
+  // The app lives under `base`, so that — not the bare origin — is the URL to
+  // open; Vite only serves the SPA beneath it.
+  const url = `http://${host === "0.0.0.0" ? "localhost" : host}:${port}${base}`;
+  screen.line(`  ➜  Local     ${url}`, "out");
+  screen.line(`  ➜  API       ${apiUrl}${local ? "  (local files)" : ""}`, "out");
+  if (local) screen.line(`  ➜  Content   ${localHandle.handshake.root}`, "out");
+  screen.line(`  ➜  Editor    ${path.basename(appRoot)}`, "dim");
+  screen.ok(`ready in ${Date.now() - started} ms`);
+  screen.line("");
+  if (local) {
+    // Say plainly what local mode cannot do, rather than letting the user find
+    // out by clicking something that is missing.
+    screen.line("Editing files directly. Branch switching, merges and collaboration are off.", "dim");
+  } else {
+    screen.line("Server running · run  gogitcms-editor build  when ready to ship.", "dim");
+  }
+
+  if (opts.open) openUrl(url);
+
+  // Hold the process open until interrupted, then shut the server down cleanly
+  // so the port is free for the next run.
+  // onInterrupt overrides the CLI's default Ctrl-C teardown (see bin) so the
+  // server gets closed rather than the process shot: returning from here lets
+  // main() finish normally and restore the terminal on its way out.
+  await new Promise((resolve) => {
+    screen.onInterrupt = async () => {
+      screen.line("");
+      screen.line("Stopping dev server…", "dim");
+      await server.close().catch(() => {});
+      if (localHandle) await localHandle.stop().catch(() => {});
+      resolve();
+    };
+  });
+  return 0;
+}

package/src/commands/init.mjs

@@ -0,0 +1,144 @@
+// `gogitcms-editor init` — write the project's cms.config.js (step 02 of the design).
+//
+// The workspace and repository are picked from what the signed-in user actually
+// has access to, so the config can't name something the editor will later fail
+// to load. Flags cover the non-interactive path (CI, or a terminal-less shell).
+
+import path from "node:path";
+import * as api from "../lib/api.mjs";
+import * as config from "../lib/config.mjs";
+import * as credentials from "../lib/credentials.mjs";
+import { REPOSITORIES, WORKSPACES } from "../lib/graphql.mjs";
+import { confirm, select } from "../tui/prompts.mjs";
+import { isInteractive } from "../tui/screen.mjs";
+import { DEFAULT_API_URL } from "../lib/defaults.mjs";
+
+export async function init(screen, opts) {
+  // An existing config's API_URL is the best default: re-running init in a
+  // configured project shouldn't silently retarget it at localhost.
+  const existing = await config.load();
+  const apiUrl = credentials.normalizeApiUrl(opts.apiUrl || existing?.API_URL || DEFAULT_API_URL);
+
+  screen.header("SETUP");
+  const creds = await credentials.load(apiUrl);
+  if (!creds) {
+    screen.fail(`Not signed in to ${apiUrl} — run  gogitcms-editor login  first.`);
+    return 1;
+  }
+  screen.setDone(0);
+  screen.setStatus({ auth: creds.email || "signed in", authed: true, hint: "next: gogitcms-editor dev" });
+
+  const current = config.find();
+  if (current && !opts.yes) {
+    const overwrite = await confirm(
+      screen,
+      `${path.basename(current)} already exists. Overwrite it?`,
+      false,
+    );
+    if (!overwrite) {
+      screen.line("Left the existing config alone.", "dim");
+      return 0;
+    }
+  }
+
+  await screen.stream([{ text: "Loading your workspaces…", cls: "dim" }]);
+
+  let workspaces;
+  try {
+    ({ workspaces } = await api.graphql(apiUrl, WORKSPACES));
+  } catch (e) {
+    screen.fail(e.message);
+    return 1;
+  }
+  if (!workspaces?.length) {
+    screen.fail("You have no workspaces yet. Create one in the dashboard first.");
+    return 1;
+  }
+
+  const workspace = await pick(screen, {
+    what: "workspace",
+    flag: "--workspace",
+    items: workspaces,
+    label: (w) => `${w.name}  (${w.slug})`,
+    match: (w, v) => w.id === v || w.slug === v || w.name === v,
+    requested: opts.workspace,
+  });
+  if (!workspace) return 1;
+
+  const { repositories } = await api.graphql(apiUrl, REPOSITORIES, { workspaceId: workspace.id });
+  if (!repositories?.length) {
+    screen.fail(`No repositories connected to ${workspace.name}. Connect one in the dashboard first.`);
+    return 1;
+  }
+
+  const repository = await pick(screen, {
+    what: "repository",
+    flag: "--repository",
+    items: repositories,
+    label: (r) => `${r.owner}/${r.name}`,
+    match: (r, v) => r.id === v || `${r.owner}/${r.name}` === v || r.name === v,
+    requested: opts.repository,
+  });
+  if (!repository) return 1;
+
+  const written = {
+    API_URL: apiUrl,
+    WORKSPACE_ID: workspace.id,
+    REPOSITORY_ID: repository.id,
+    // Carried over when re-running init, so a subpath deployment isn't silently
+    // reset to the root.
+    BASE_PATH: opts.base || existing?.BASE_PATH || "/",
+  };
+  const file = await config.write(written);
+
+  // Echo the file back the way the design renders it: a header line, then the
+  // body, so the user sees exactly what landed in their project.
+  screen.line("");
+  screen.line(path.basename(file), "filehdr");
+  for (const l of config.render(written).trimEnd().split("\n")) {
+    screen.line(`  ${l}`, "fileline");
+  }
+
+  screen.setDone(1);
+  await screen.stream([
+    "",
+    { text: `✓ Wrote ${path.basename(file)}`, cls: "ok" },
+    { text: `  ${workspace.name} · ${repository.owner}/${repository.name}`, cls: "dim" },
+    "",
+    { text: "Next — run  gogitcms-editor dev  to start the local editor.", cls: "dim" },
+  ]);
+  return 0;
+}
+
+// pick resolves one choice: from a flag when given, from a menu when the
+// terminal allows it, and automatically when there is only one candidate.
+async function pick(screen, { what, flag, items, label, match, requested }) {
+  if (requested) {
+    const found = items.find((i) => match(i, requested));
+    if (!found) {
+      screen.fail(`No ${what} matching ${JSON.stringify(requested)}. Available: ${items.map(label).join(", ")}`);
+      return null;
+    }
+    screen.line(`${what}: ${label(found)}`, "dim");
+    return found;
+  }
+  if (items.length === 1) {
+    screen.line(`${what}: ${label(items[0])}`, "dim");
+    return items[0];
+  }
+  if (!isInteractive()) {
+    screen.fail(`Several ${what}s available — pass ${flag}. Options: ${items.map(label).join(", ")}`);
+    return null;
+  }
+  const chosen = await select(
+    screen,
+    `Select a ${what}`,
+    items.map((i) => ({ label: label(i), value: i })),
+  );
+  if (!chosen) {
+    screen.line("Cancelled.", "dim");
+    return null;
+  }
+  screen.line(`${what}: ${label(chosen)}`, "dim");
+  return chosen;
+}

package/src/commands/login.mjs

@@ -0,0 +1,116 @@
+// `gogitcms-editor login` — the device grant (step 01 of the design).
+//
+// The CLI asks the server for a code pair, shows the short one and the page to
+// enter it on, then polls until a signed-in browser approves. Nothing is typed
+// into the terminal: the password never touches this process.
+
+import * as api from "../lib/api.mjs";
+import * as credentials from "../lib/credentials.mjs";
+import { openUrl } from "../lib/open.mjs";
+import { confirm } from "../tui/prompts.mjs";
+import { DEFAULT_API_URL } from "../lib/defaults.mjs";
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export async function login(screen, opts) {
+  const apiUrl = credentials.normalizeApiUrl(opts.apiUrl || DEFAULT_API_URL);
+  screen.header("SETUP");
+  screen.setStatus({ mode: "AUTH", hint: "waiting for approval" });
+
+  await screen.stream([{ text: `Requesting device authorization from ${apiUrl}…`, cls: "dim" }, ""]);
+
+  let pair;
+  try {
+    pair = await api.requestDeviceCode(apiUrl);
+  } catch (e) {
+    screen.fail(`Could not reach ${apiUrl} — ${e.message}`);
+    return 1;
+  }
+
+  screen.line("FIRST — copy your one-time code", "label");
+  screen.line(pair.userCode, "code");
+  screen.line("");
+  screen.line("THEN — open the link and enter it", "label");
+  screen.line(`→ ${pair.verificationUri}`, "out");
+  screen.line("");
+
+  if (await confirm(screen, "Open that page in your browser now?")) {
+    // verificationUriComplete carries the code, so the page can resolve it
+    // without the user retyping what they just read.
+    openUrl(pair.verificationUriComplete || pair.verificationUri);
+  }
+
+  const stop = screen.startSpinner("Waiting for approval…");
+  const result = await pollForToken(apiUrl, pair);
+  stop();
+
+  if (!result.ok) {
+    screen.fail(result.message);
+    screen.setStatus({ mode: "READY", hint: "next: gogitcms-editor login" });
+    return 1;
+  }
+
+  // Identify the session so the status line can show who is signed in. A failure
+  // here is cosmetic — the tokens are already valid.
+  let email = "";
+  try {
+    email = (await api.me(apiUrl, result.tokens.accessToken)).email;
+  } catch {
+    email = "signed in";
+  }
+
+  await credentials.save(apiUrl, {
+    accessToken: result.tokens.accessToken,
+    refreshToken: result.tokens.refreshToken,
+    expiresAt: credentials.expiresAtFrom(result.tokens.accessToken),
+    email,
+  });
+
+  screen.setDone(0);
+  screen.setStatus({ mode: "READY", auth: email, authed: true, hint: "next: gogitcms-editor init" });
+  await screen.stream([
+    { text: "✓ Authorized in browser", cls: "ok" },
+    { text: `✓ Signed in as ${email}`, cls: "ok" },
+    { text: `  credentials → ${credentials.credentialsPath}`, cls: "dim" },
+    "",
+    { text: "Next — run  gogitcms-editor init  to create your config.", cls: "dim" },
+  ]);
+  return 0;
+}
+
+// pollForToken asks for the session on the server's cadence until it is
+// approved, rejected, or the code expires.
+async function pollForToken(apiUrl, pair) {
+  const deadline = Date.now() + (pair.expiresIn || 900) * 1000;
+  let interval = (pair.interval || 5) * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(interval);
+    try {
+      const tokens = await api.pollDeviceToken(apiUrl, pair.deviceCode);
+      return { ok: true, tokens };
+    } catch (e) {
+      switch (e.slug) {
+        case "authorization_pending":
+          continue;
+        case "slow_down":
+          // The server is asking for more room; back off rather than keep the
+          // same cadence and risk being cut off.
+          interval += 5000;
+          continue;
+        case "access_denied":
+          return { ok: false, message: "Request rejected in the browser. Nothing was signed in." };
+        case "expired_token":
+          return { ok: false, message: "That code expired. Run  gogitcms-editor login  again." };
+        case "invalid_grant":
+          return { ok: false, message: "That code is no longer valid. Run  gogitcms-editor login  again." };
+        default:
+          // A transient network blip shouldn't abandon a flow the user has
+          // already approved in their browser — keep polling until the deadline.
+          if (!e.status) continue;
+          return { ok: false, message: e.message };
+      }
+    }
+  }
+  return { ok: false, message: "Timed out waiting for approval. Run  gogitcms-editor login  again." };
+}

package/src/commands/status.mjs

@@ -0,0 +1,68 @@
+// `gogitcms-editor status` — where the three setup steps stand, and `logout`.
+
+import path from "node:path";
+import * as config from "../lib/config.mjs";
+import * as credentials from "../lib/credentials.mjs";
+import { STEPS } from "../tui/theme.mjs";
+import { DEFAULT_API_URL } from "../lib/defaults.mjs";
+
+// resolveSession finds which server this project belongs to and whether we hold
+// a session for it: the config's API_URL when there is one, otherwise the single
+// stored session, otherwise the default.
+export async function resolveSession(opts = {}) {
+  const cfg = await config.load();
+  const apiUrl = credentials.normalizeApiUrl(opts.apiUrl || cfg?.API_URL || "");
+  if (apiUrl) return { apiUrl, cfg, creds: await credentials.load(apiUrl) };
+
+  const any = await credentials.loadAny();
+  if (any) return { apiUrl: any[0], cfg, creds: any[1] };
+  return { apiUrl: credentials.normalizeApiUrl(DEFAULT_API_URL), cfg, creds: null };
+}
+
+export async function status(screen, opts) {
+  const { apiUrl, cfg, creds } = await resolveSession(opts);
+  const configFile = config.find();
+  const done = [Boolean(creds), Boolean(cfg), false];
+  done.forEach((d, i) => screen.setDone(i, d));
+
+  screen.setStatus({
+    mode: done[0] && done[1] ? "READY" : "READY",
+    auth: creds?.email || "not logged in",
+    authed: Boolean(creds),
+    hint: nextHint(done),
+  });
+  screen.header("STATUS");
+
+  screen.line("setup progress", "label");
+  STEPS.forEach((s, i) => {
+    screen.line(`  [${done[i] ? "x" : " "}] ${s.label}  ·  ${s.cmd}`, done[i] ? "ok" : "out");
+  });
+  screen.line("");
+  screen.line(`  server     ${apiUrl}`, "dim");
+  screen.line(`  account    ${creds?.email || "—"}`, "dim");
+  screen.line(`  config     ${configFile ? path.relative(process.cwd(), configFile) : "—"}`, "dim");
+  if (cfg?.REPOSITORY_ID) screen.line(`  repository ${cfg.REPOSITORY_ID}`, "dim");
+  screen.line("");
+  return 0;
+}
+
+export function nextHint(done) {
+  const next = done.findIndex((d) => !d);
+  return next === -1 ? "gogitcms-editor build → deploy" : `next: ${STEPS[next].cmd}`;
+}
+
+export async function logout(screen, opts) {
+  const { apiUrl, creds } = await resolveSession(opts);
+  screen.header("SETUP");
+  if (!creds) {
+    screen.line(`No stored session for ${apiUrl}.`, "dim");
+    return 0;
+  }
+  await credentials.clear(apiUrl);
+  screen.setStatus({ auth: "not logged in", authed: false, hint: "next: gogitcms-editor login" });
+  screen.ok(`Signed out of ${apiUrl}`);
+  // Only this machine's copy is dropped; the session itself is revoked from the
+  // dashboard, so say so rather than implying a global sign-out.
+  screen.line("  The session can also be revoked in the dashboard under Account → Security.", "dim");
+  return 0;
+}