@cardstack/boxel-cli 0.2.0-unstable.327 → 0.2.0-unstable.446

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardstack/boxel-cli",
-  "version": "0.2.0-unstable.327",
+  "version": "0.2.0-unstable.446",
   "license": "MIT",
   "description": "CLI tools for Boxel workspace management",
   "main": "./dist/index.js",
@@ -54,8 +54,8 @@
     "vite": "^6.3.2",
     "vitest": "^2.1.9",
     "@cardstack/postgres": "0.0.0",
-    "@cardstack/local-types": "0.0.0",
-    "@cardstack/runtime-common": "1.0.0"
+    "@cardstack/runtime-common": "1.0.0",
+    "@cardstack/local-types": "0.0.0"
   },
   "publishConfig": {
     "access": "public",

package/src/commands/profile.ts

@@ -80,7 +80,7 @@ function validateUrl(input: string, label: string): string {
 
 // Matches scripts/env-slug.sh: lowercase, "/" -> "-", strip chars outside
 // [a-z0-9-], collapse runs of "-", trim leading/trailing "-".
-function computeEnvSlug(name: string): string {
+export function computeEnvSlug(name: string): string {
   return name
     .toLowerCase()
     .replace(/\//g, '-')
@@ -91,7 +91,7 @@ function computeEnvSlug(name: string): string {
 
 // Derive URLs from BOXEL_ENVIRONMENT using the same ".${slug}.localhost"
 // pattern that mise-tasks/lib/env-vars.sh produces for env-mode local dev.
-function resolveBoxelEnvironment(): EnvironmentDefaults | null {
+export function resolveBoxelEnvironment(): EnvironmentDefaults | null {
   const raw = process.env.BOXEL_ENVIRONMENT;
   if (!raw || !raw.trim()) return null;
   const slug = computeEnvSlug(raw);
@@ -458,14 +458,28 @@ async function addProfileNonInteractive(
     process.exit(1);
   }
 
-  if (manager.getProfile(matrixId)) {
-    console.log(
-      `${FG_YELLOW}Profile ${matrixId} already exists. Updating password.${RESET}`,
+  const isUpdate = Boolean(manager.getProfile(matrixId));
+
+  // addProfile performs a real matrixLogin and persists the resulting
+  // access token (the password never lands on disk). It also handles the
+  // create-vs-reauth split uniformly: re-running it on an existing profile
+  // refreshes the stored token while preserving cached realm tokens.
+  try {
+    await manager.addProfile(
+      matrixId,
+      password,
+      displayName,
+      matrixUrl,
+      realmServerUrl,
     );
-    await manager.updatePassword(matrixId, password);
-    if (displayName) {
-      manager.updateDisplayName(matrixId, displayName);
-    }
+  } catch (err) {
+    console.error(
+      `${FG_RED}Error:${RESET} ${err instanceof Error ? err.message : String(err)}`,
+    );
+    process.exit(1);
+  }
+
+  if (isUpdate) {
     if (matrixUrl || realmServerUrl) {
       const urlsChanged = manager.updateUrls(matrixId, {
         matrixUrl,
@@ -483,20 +497,6 @@ async function addProfileNonInteractive(
     return;
   }
 
-  try {
-    await manager.addProfile(
-      matrixId,
-      password,
-      displayName,
-      matrixUrl,
-      realmServerUrl,
-    );
-  } catch (err) {
-    console.error(
-      `${FG_RED}Error:${RESET} ${err instanceof Error ? err.message : String(err)}`,
-    );
-    process.exit(1);
-  }
   console.log(
     `${FG_GREEN}\u2713${RESET} Profile created: ${formatProfileBadge(matrixId)}`,
   );
@@ -538,7 +538,7 @@ async function migrateFromEnv(manager: ProfileManager): Promise<void> {
       );
     } else {
       console.log(
-        `${FG_YELLOW}Profile ${formatProfileBadge(result.profileId)} already exists.${RESET} Password has been updated if it changed.`,
+        `${FG_GREEN}\u2713${RESET} Refreshed profile: ${formatProfileBadge(result.profileId)}`,
       );
       console.log(
         `\n${DIM}Use 'boxel profile add -u ${result.profileId} -p <password>' to update other fields.${RESET}`,

package/src/commands/realm/index.ts

@@ -4,11 +4,13 @@ import { registerCreateCommand } from './create';
 import { registerHistoryCommand } from './history';
 import { registerListCommand } from './list';
 import { registerMilestoneCommand } from './milestone';
+import { registerPublishCommand } from './publish';
 import { registerPullCommand } from './pull';
 import { registerPushCommand } from './push';
 import { registerRemoveCommand } from './remove';
 import { registerStatusCommand } from './status';
 import { registerSyncCommand } from './sync';
+import { registerUnpublishCommand } from './unpublish';
 import { registerWaitForReadyCommand } from './wait-for-ready';
 import { registerWatchCommand } from './watch';
 
@@ -22,11 +24,13 @@ export function registerRealmCommand(program: Command): void {
   registerHistoryCommand(realm);
   registerListCommand(realm);
   registerMilestoneCommand(realm);
+  registerPublishCommand(realm);
   registerPullCommand(realm);
   registerPushCommand(realm);
   registerRemoveCommand(realm);
   const sync = registerSyncCommand(realm);
   registerStatusCommand(sync);
+  registerUnpublishCommand(realm);
   registerWaitForReadyCommand(realm);
   registerWatchCommand(realm);
 }

package/src/commands/realm/publish.ts

@@ -0,0 +1,291 @@
+import type { Command } from 'commander';
+import { ensureTrailingSlash } from '@cardstack/runtime-common/paths';
+import {
+  getProfileManager,
+  NO_ACTIVE_PROFILE_ERROR,
+  type ProfileManager,
+} from '../../lib/profile-manager';
+import { unpublishRealm } from './unpublish';
+import { FG_CYAN, FG_GREEN, FG_RED, RESET } from '../../lib/colors';
+
+const DEFAULT_TIMEOUT_MS = 300_000;
+const READINESS_POLL_INTERVAL_MS = 1000;
+
+export interface PublishOptions {
+  /** Wait for the published realm to pass readiness check (default: true). */
+  waitForReady?: boolean;
+  /** Readiness-poll timeout in milliseconds (default: 300_000). */
+  timeoutMs?: number;
+  /**
+   * When the server returns 400/409 (e.g. an existing publication conflicts),
+   * unpublish the target URL first and retry once. Default: true.
+   */
+  republish?: boolean;
+  profileManager?: ProfileManager;
+}
+
+export interface PublishRealmResult {
+  publishedRealmURL: string;
+  publishedRealmId: string;
+  lastPublishedAt: string;
+  status: string;
+}
+
+/**
+ * Publish a source realm to a published-realm URL.
+ *
+ * Speaks the contract documented at
+ * `packages/realm-server/handlers/handle-publish-realm.ts`: the server
+ * accepts the publish, returns `202 Accepted` with `status: "pending"`,
+ * and the client polls `/<publishedRealmURL>/_readiness-check` until
+ * the realm is mounted and indexed. 200/201 are accepted too so this
+ * function survives any future move back to a synchronous handler.
+ */
+export async function publishRealm(
+  sourceRealmURL: string,
+  publishedRealmURL: string,
+  options: PublishOptions = {},
+): Promise<PublishRealmResult> {
+  let pm = options.profileManager ?? getProfileManager();
+  let active = pm.getActiveProfile();
+  if (!active) {
+    throw new Error(NO_ACTIVE_PROFILE_ERROR);
+  }
+
+  let normalizedSource = ensureTrailingSlash(sourceRealmURL);
+  let normalizedPublished = ensureTrailingSlash(publishedRealmURL);
+  let realmServerUrl = active.profile.realmServerUrl.replace(/\/$/, '');
+
+  let response = await postPublish(
+    pm,
+    realmServerUrl,
+    normalizedSource,
+    normalizedPublished,
+  );
+
+  if (
+    (response.status === 400 || response.status === 409) &&
+    options.republish !== false
+  ) {
+    let conflictBody = await safeReadResponseText(response);
+    console.log(
+      `Publish returned ${response.status} (${conflictBody.slice(0, 200)}). Unpublishing and retrying.`,
+    );
+    let unpublishResult = await unpublishRealm(normalizedPublished, {
+      profileManager: pm,
+      tolerateMissing: true,
+    });
+    if (!unpublishResult.unpublished && !unpublishResult.notFound) {
+      throw new Error(
+        `Conflict on publish; unpublish-then-retry also failed: ${
+          unpublishResult.error ?? 'unknown'
+        }`,
+      );
+    }
+    response = await postPublish(
+      pm,
+      realmServerUrl,
+      normalizedSource,
+      normalizedPublished,
+    );
+  }
+
+  if (
+    response.status !== 200 &&
+    response.status !== 201 &&
+    response.status !== 202
+  ) {
+    let body = await safeReadResponseText(response);
+    throw new Error(
+      `Publish failed: HTTP ${response.status}: ${body.slice(0, 1000)}`,
+    );
+  }
+
+  let body = (await response.json()) as PublishResponseBody;
+  let attrs = body?.data?.attributes;
+  if (!attrs?.publishedRealmURL) {
+    throw new Error(
+      `Publish response missing data.attributes.publishedRealmURL: ${JSON.stringify(
+        body,
+      ).slice(0, 500)}`,
+    );
+  }
+
+  let result: PublishRealmResult = {
+    publishedRealmURL: ensureTrailingSlash(attrs.publishedRealmURL),
+    publishedRealmId: body.data.id,
+    lastPublishedAt: attrs.lastPublishedAt,
+    status: attrs.status,
+  };
+
+  if (options.waitForReady !== false) {
+    let timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let realmToken: string | undefined;
+    try {
+      let serverToken = await pm.getOrRefreshServerToken();
+      realmToken = await pm.fetchAndStoreRealmToken(
+        result.publishedRealmURL,
+        serverToken,
+      );
+    } catch {
+      // The published realm is permission-public-read; fall through to
+      // poll without an Authorization header.
+    }
+    await waitForPublishedRealmReady(
+      result.publishedRealmURL,
+      realmToken,
+      timeoutMs,
+    );
+  }
+
+  return result;
+}
+
+interface PublishResponseBody {
+  data: {
+    type: 'published_realm';
+    id: string;
+    attributes: {
+      sourceRealmURL: string;
+      publishedRealmURL: string;
+      lastPublishedAt: string;
+      status: string;
+    };
+  };
+}
+
+async function postPublish(
+  pm: ProfileManager,
+  realmServerUrl: string,
+  sourceRealmURL: string,
+  publishedRealmURL: string,
+): Promise<Response> {
+  return pm.authedRealmServerFetch(`${realmServerUrl}/_publish-realm`, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/vnd.api+json',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ sourceRealmURL, publishedRealmURL }),
+  });
+}
+
+async function waitForPublishedRealmReady(
+  publishedRealmURL: string,
+  realmToken: string | undefined,
+  timeoutMs: number,
+): Promise<void> {
+  let readinessUrl = new URL('_readiness-check', publishedRealmURL).href;
+  let startedAt = Date.now();
+  let lastError: string | undefined;
+
+  while (Date.now() - startedAt < timeoutMs) {
+    try {
+      let headers: Record<string, string> = {
+        Accept: 'application/vnd.api+json',
+      };
+      if (realmToken) {
+        headers.Authorization = realmToken;
+      }
+      let response = await fetch(readinessUrl, { headers });
+      if (response.ok) {
+        return;
+      }
+      lastError = `HTTP ${response.status}`;
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+    }
+    let remaining = timeoutMs - (Date.now() - startedAt);
+    if (remaining <= 0) break;
+    await new Promise((r) =>
+      setTimeout(r, Math.min(READINESS_POLL_INTERVAL_MS, remaining)),
+    );
+  }
+
+  throw new Error(
+    `Timed out after ${timeoutMs}ms waiting for ${publishedRealmURL} to pass readiness check${
+      lastError ? `: ${lastError}` : ''
+    }`,
+  );
+}
+
+async function safeReadResponseText(response: Response): Promise<string> {
+  try {
+    return await response.text();
+  } catch {
+    return '<no response body>';
+  }
+}
+
+export interface PublishCliOptions {
+  // Commander exposes `--no-wait` / `--no-republish` on the positive
+  // keys (`wait` / `republish`), defaulting to `true` and flipping to
+  // `false` when the negated flag is passed.
+  wait?: boolean;
+  timeout?: number;
+  republish?: boolean;
+}
+
+export function publishCliOptsToOptions(
+  opts: PublishCliOptions,
+): PublishOptions {
+  return {
+    waitForReady: opts.wait !== false,
+    timeoutMs: opts.timeout,
+    republish: opts.republish !== false,
+  };
+}
+
+export function registerPublishCommand(realm: Command): void {
+  realm
+    .command('publish')
+    .description(
+      'Publish a source realm to a published-realm URL, polling readiness until ready',
+    )
+    .argument('<source-realm-url>', 'URL of the source realm to publish')
+    .argument(
+      '<published-realm-url>',
+      'Public-facing URL the published copy will serve at',
+    )
+    .option('--no-wait', 'Return as soon as the server accepts the publish')
+    .option(
+      '--timeout <ms>',
+      `Readiness-poll timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS})`,
+      parseTimeoutOption,
+    )
+    .option(
+      '--no-republish',
+      'Do not auto-unpublish + retry when the server returns 400/409',
+    )
+    .action(
+      async (
+        sourceRealmURL: string,
+        publishedRealmURL: string,
+        opts: PublishCliOptions,
+      ) => {
+        try {
+          let result = await publishRealm(
+            sourceRealmURL,
+            publishedRealmURL,
+            publishCliOptsToOptions(opts),
+          );
+          console.log(
+            `${FG_GREEN}Published:${RESET} ${FG_CYAN}${result.publishedRealmURL}${RESET}`,
+          );
+        } catch (err) {
+          console.error(
+            `${FG_RED}Error:${RESET} ${err instanceof Error ? err.message : String(err)}`,
+          );
+          process.exit(1);
+        }
+      },
+    );
+}
+
+function parseTimeoutOption(value: string): number {
+  let n = Number.parseInt(value, 10);
+  if (!Number.isFinite(n) || n < 0 || String(n) !== value.trim()) {
+    throw new Error('--timeout must be a non-negative integer (milliseconds).');
+  }
+  return n;
+}

package/src/commands/realm/unpublish.ts

@@ -0,0 +1,150 @@
+import type { Command } from 'commander';
+import { ensureTrailingSlash } from '@cardstack/runtime-common/paths';
+import {
+  getProfileManager,
+  NO_ACTIVE_PROFILE_ERROR,
+  type ProfileManager,
+} from '../../lib/profile-manager';
+import { FG_CYAN, FG_GREEN, FG_RED, RESET } from '../../lib/colors';
+
+export interface UnpublishOptions {
+  /**
+   * When true, do not fail if the server reports the realm was already
+   * unpublished. Useful for cleanup paths that must be idempotent (e.g.
+   * a PR-close hook that runs even if a previous close already unpublished).
+   * Default: false.
+   */
+  tolerateMissing?: boolean;
+  profileManager?: ProfileManager;
+}
+
+export interface UnpublishRealmResult {
+  publishedRealmURL: string;
+  unpublished: boolean;
+  notFound?: boolean;
+  error?: string;
+}
+
+/**
+ * Unpublish a published realm. Mirrors `boxel realm publish`'s contract
+ * with `/_unpublish-realm`.
+ *
+ * The realm-server returns 200 on success and 422 with a "not found" body
+ * when the URL isn't currently published. We special-case the latter (and
+ * 404, defensively) so cleanup callers can run unconditionally.
+ */
+export async function unpublishRealm(
+  publishedRealmURL: string,
+  options: UnpublishOptions = {},
+): Promise<UnpublishRealmResult> {
+  let normalized = ensureTrailingSlash(publishedRealmURL);
+  let pm = options.profileManager ?? getProfileManager();
+  let active = pm.getActiveProfile();
+  if (!active) {
+    return {
+      publishedRealmURL: normalized,
+      unpublished: false,
+      error: NO_ACTIVE_PROFILE_ERROR,
+    };
+  }
+
+  let realmServerUrl = active.profile.realmServerUrl.replace(/\/$/, '');
+
+  let response: Response;
+  try {
+    response = await pm.authedRealmServerFetch(
+      `${realmServerUrl}/_unpublish-realm`,
+      {
+        method: 'POST',
+        headers: {
+          Accept: 'application/vnd.api+json',
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ publishedRealmURL: normalized }),
+      },
+    );
+  } catch (err) {
+    return {
+      publishedRealmURL: normalized,
+      unpublished: false,
+      error: `Failed to reach realm server: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    };
+  }
+
+  if (response.ok) {
+    return { publishedRealmURL: normalized, unpublished: true };
+  }
+
+  let body = await safeReadResponseText(response);
+  let looksLikeNotFound =
+    response.status === 404 ||
+    (response.status === 422 && /not found/i.test(body));
+
+  if (looksLikeNotFound) {
+    if (options.tolerateMissing) {
+      return {
+        publishedRealmURL: normalized,
+        unpublished: false,
+        notFound: true,
+      };
+    }
+    return {
+      publishedRealmURL: normalized,
+      unpublished: false,
+      notFound: true,
+      error: `Published realm ${normalized} is not currently published`,
+    };
+  }
+
+  return {
+    publishedRealmURL: normalized,
+    unpublished: false,
+    error: `Realm server returned ${response.status}: ${body.slice(0, 500)}`,
+  };
+}
+
+async function safeReadResponseText(response: Response): Promise<string> {
+  try {
+    return await response.text();
+  } catch {
+    return '<no response body>';
+  }
+}
+
+interface UnpublishCliOptions {
+  tolerateMissing?: boolean;
+}
+
+export function registerUnpublishCommand(realm: Command): void {
+  realm
+    .command('unpublish')
+    .description('Unpublish a published realm by its public-facing URL')
+    .argument('<published-realm-url>', 'URL of the published realm to remove')
+    .option(
+      '--tolerate-missing',
+      'Exit successfully when the realm is already unpublished',
+    )
+    .action(async (publishedRealmURL: string, opts: UnpublishCliOptions) => {
+      let result = await unpublishRealm(publishedRealmURL, {
+        tolerateMissing: opts.tolerateMissing === true,
+      });
+
+      if (result.error) {
+        console.error(`${FG_RED}Error:${RESET} ${result.error}`);
+        process.exit(1);
+      }
+
+      if (result.notFound) {
+        console.log(
+          `Already unpublished: ${FG_CYAN}${result.publishedRealmURL}${RESET}`,
+        );
+        return;
+      }
+
+      console.log(
+        `${FG_GREEN}Unpublished:${RESET} ${FG_CYAN}${result.publishedRealmURL}${RESET}`,
+      );
+    });
+}

package/src/lib/auth.ts

@@ -7,6 +7,17 @@ export interface MatrixAuth {
 
 export type RealmTokens = Record<string, string>;
 
+// Thrown when Matrix rejects an access token (401/403). Callers can catch
+// this specifically to drive interactive re-auth without parsing messages.
+export class MatrixAuthError extends Error {
+  status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = 'MatrixAuthError';
+    this.status = status;
+  }
+}
+
 interface MatrixLoginResponse {
   access_token: string;
   device_id: string;
@@ -69,6 +80,12 @@ async function getOpenIdToken(
 
   if (!response.ok) {
     let text = await response.text();
+    if (response.status === 401 || response.status === 403) {
+      throw new MatrixAuthError(
+        response.status,
+        `OpenID token request failed: ${response.status} ${text}`,
+      );
+    }
     throw new Error(`OpenID token request failed: ${response.status} ${text}`);
   }
 
@@ -138,17 +155,30 @@ function userRealmsAccountDataUrl(matrixAuth: MatrixAuth): string {
 export async function getUserRealmsFromMatrixAccountData(
   matrixAuth: MatrixAuth,
 ): Promise<string[]> {
+  let response: Response;
   try {
-    let response = await fetch(userRealmsAccountDataUrl(matrixAuth), {
+    response = await fetch(userRealmsAccountDataUrl(matrixAuth), {
       headers: { Authorization: `Bearer ${matrixAuth.accessToken}` },
     });
-    if (!response.ok) {
-      return [];
-    }
+  } catch {
+    // Network unreachable / DNS / similar — treat as empty (best-effort).
+    return [];
+  }
+  if (response.status === 401 || response.status === 403) {
+    let text = await response.text();
+    throw new MatrixAuthError(
+      response.status,
+      `Matrix account_data fetch failed: ${response.status} ${text}`,
+    );
+  }
+  if (!response.ok) {
+    // 404 just means the event has never been set — return empty list.
+    return [];
+  }
+  try {
     let data = (await response.json()) as { realms?: string[] };
     return Array.isArray(data.realms) ? [...data.realms] : [];
   } catch {
-    // Best-effort — treat unreachable account data as an empty list
     return [];
   }
 }
@@ -171,6 +201,12 @@ export async function addRealmToMatrixAccountData(
     });
     if (!putResponse.ok) {
       let text = await putResponse.text();
+      if (putResponse.status === 401 || putResponse.status === 403) {
+        throw new MatrixAuthError(
+          putResponse.status,
+          `Failed to update Matrix account data: ${putResponse.status} ${text}`,
+        );
+      }
       throw new Error(
         `Failed to update Matrix account data: ${putResponse.status} ${text}`,
       );
@@ -205,6 +241,12 @@ export async function removeRealmFromMatrixAccountData(
   });
   if (!putResponse.ok) {
     let text = await putResponse.text();
+    if (putResponse.status === 401 || putResponse.status === 403) {
+      throw new MatrixAuthError(
+        putResponse.status,
+        `Failed to update Matrix account data: ${putResponse.status} ${text}`,
+      );
+    }
     throw new Error(
       `Failed to update Matrix account data: ${putResponse.status} ${text}`,
     );