@cardstack/boxel-cli 0.3.2-unstable.61 → 0.4.0-unstable.1

package/src/commands/realm/publish.ts

@@ -1,17 +1,20 @@
 import type { Command } from 'commander';
 import { ensureTrailingSlash } from '@cardstack/runtime-common/paths';
 import {
+  fetchPublishabilityReport,
   publishRealm as publishRealmOperation,
   type PublishRealmOutput,
   RealmOperationError,
   waitForReady,
 } from '@cardstack/runtime-common/realm-operations';
+import type { PublishabilityViolation } from '@cardstack/runtime-common/publishability';
 import { buildCliRealmClient } from '../../lib/realm-client.ts';
 import {
   getProfileManager,
   type ProfileManager,
 } from '../../lib/profile-manager.ts';
 import { unpublishRealm } from './unpublish.ts';
+import { cliLog } from '../../lib/cli-log.ts';
 import { FG_CYAN, FG_GREEN, FG_RED, RESET } from '../../lib/colors.ts';
 
 const DEFAULT_TIMEOUT_MS = 300_000;
@@ -26,6 +29,11 @@ export interface PublishOptions {
    * unpublish the target URL first and retry once. Default: true.
    */
   republish?: boolean;
+  /**
+   * Skip the publishability gate (private-dependency / error-document check).
+   * Default: false — the gate runs and blocks publishing on violations.
+   */
+  force?: boolean;
   profileManager?: ProfileManager;
 }
 
@@ -39,7 +47,9 @@ export interface PublishRealmResult {
 /**
  * Publish a source realm to a published-realm URL.
  *
- * Speaks the contract documented at
+ * Before publishing, runs the publishability gate (private-dependency /
+ * error-document check) and refuses to publish on violations unless `force`
+ * is set. Then 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
@@ -57,6 +67,18 @@ export async function publishRealm(
   let normalizedSource = ensureTrailingSlash(sourceRealmURL);
   let normalizedPublished = ensureTrailingSlash(publishedRealmURL);
 
+  // Pre-publish gate: refuse to publish a realm with private-dependency or
+  // error-document violations (which would break the published site) unless
+  // the caller forces it.
+  if (!options.force) {
+    let report = await fetchPublishabilityReport(client, {
+      realmURL: normalizedSource,
+    });
+    if (!report.publishable) {
+      throw new Error(describeViolations(report.violations));
+    }
+  }
+
   let output: PublishRealmOutput;
   try {
     output = await publishRealmOperation(client, {
@@ -71,7 +93,9 @@ export async function publishRealm(
       (err.status === 400 || err.status === 409) &&
       options.republish !== false
     ) {
-      console.log(
+      // Progress, not payload: route to stderr via cliLog.info so it never
+      // corrupts stdout when the caller passed --json (stdout is JSON-only).
+      cliLog.info(
         `Publish returned ${err.status} (${(err.body ?? '').slice(0, 200)}). Unpublishing and retrying.`,
       );
       let unpublishResult = await unpublishRealm(normalizedPublished, {
@@ -118,6 +142,8 @@ export interface PublishCliOptions {
   wait?: boolean;
   timeout?: number;
   republish?: boolean;
+  force?: boolean;
+  json?: boolean;
 }
 
 export function publishCliOptsToOptions(
@@ -127,6 +153,7 @@ export function publishCliOptsToOptions(
     waitForReady: opts.wait !== false,
     timeoutMs: opts.timeout,
     republish: opts.republish !== false,
+    force: opts.force === true,
   };
 }
 
@@ -134,7 +161,7 @@ export function registerPublishCommand(realm: Command): void {
   realm
     .command('publish')
     .description(
-      'Publish a source realm to a published-realm URL, polling readiness until ready',
+      'Publish a source realm to a published-realm URL: runs the publishability gate (use --force to skip), then polls readiness until ready',
     )
     .argument('<source-realm-url>', 'URL of the source realm to publish')
     .argument(
@@ -151,6 +178,11 @@ export function registerPublishCommand(realm: Command): void {
       '--no-republish',
       'Do not auto-unpublish + retry when the server returns 400/409',
     )
+    .option(
+      '--force',
+      'Publish even if the realm has publishability violations (skips the gate)',
+    )
+    .option('--json', 'Output the result as JSON')
     .action(
       async (
         sourceRealmURL: string,
@@ -163,20 +195,27 @@ export function registerPublishCommand(realm: Command): void {
             publishedRealmURL,
             publishCliOptsToOptions(opts),
           );
-          console.log(
-            `${FG_GREEN}Published:${RESET} ${FG_CYAN}${result.publishedRealmURL}${RESET}`,
-          );
+          if (opts.json) {
+            cliLog.output(JSON.stringify(result, null, 2));
+          } else {
+            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)}`,
-          );
-          // Node's fetch surfaces the actual transport error (ECONNRESET,
-          // TLS failure, undici socket error, etc.) on `error.cause`. Print
-          // it so opaque "fetch failed" messages don't strand the caller.
-          // `!= null` rather than a truthy check so we don't drop
-          // falsy-but-defined causes (`''`, `0`, `false`, `NaN`).
-          if (err instanceof Error && err.cause != null) {
-            console.error(`${FG_RED}Caused by:${RESET}`, err.cause);
+          let message = err instanceof Error ? err.message : String(err);
+          if (opts.json) {
+            cliLog.output(JSON.stringify({ error: message }, null, 2));
+          } else {
+            console.error(`${FG_RED}Error:${RESET} ${message}`);
+            // Node's fetch surfaces the actual transport error (ECONNRESET,
+            // TLS failure, undici socket error, etc.) on `error.cause`. Print
+            // it so opaque "fetch failed" messages don't strand the caller.
+            // `!= null` rather than a truthy check so we don't drop
+            // falsy-but-defined causes (`''`, `0`, `false`, `NaN`).
+            if (err instanceof Error && err.cause != null) {
+              console.error(`${FG_RED}Caused by:${RESET}`, err.cause);
+            }
           }
           process.exit(1);
         }
@@ -184,6 +223,38 @@ export function registerPublishCommand(realm: Command): void {
     );
 }
 
+// Summarizes publishability violations into a single actionable error message.
+// Mirrors the host PublishRealmCommand's gate messaging.
+export function describeViolations(
+  violations: PublishabilityViolation[],
+): string {
+  let privateCount = violations.filter(
+    (v) => v.kind === 'private-dependency',
+  ).length;
+  let errorCount = violations.filter((v) => v.kind === 'error-document').length;
+
+  let parts: string[] = [];
+  if (privateCount) {
+    parts.push(`${privateCount} private-dependency violation(s)`);
+  }
+  if (errorCount) {
+    parts.push(`${errorCount} error-document violation(s)`);
+  }
+  let summary = parts.length
+    ? parts.join(', ')
+    : `${violations.length} violation(s)`;
+
+  let resources = violations
+    .map((v) => v.resource)
+    .filter(Boolean)
+    .slice(0, 5)
+    .join(', ');
+
+  return `Realm is not publishable (${summary}). Resolve them or pass --force to override.${
+    resources ? ` Affected: ${resources}` : ''
+  }`;
+}
+
 function parseTimeoutOption(value: string): number {
   let n = Number.parseInt(value, 10);
   if (!Number.isFinite(n) || n < 0 || String(n) !== value.trim()) {

package/src/commands/realm/pull.ts

@@ -232,20 +232,16 @@ export async function pull(
   localDir: string,
   options: PullCommandOptions,
 ): Promise<{ files: string[]; error?: string }> {
-  let authenticator: RealmAuthenticator;
-  if (options.authenticator) {
-    authenticator = options.authenticator;
-  } else {
-    const resolution = resolveRealmAuthenticator({
-      realmUrl,
-      realmSecretSeed: options.realmSecretSeed,
-      profileManager: options.profileManager,
-    });
-    if (!resolution.ok) {
-      return { files: [], error: resolution.error };
-    }
-    authenticator = resolution.authenticator;
+  const resolution = resolveRealmAuthenticator({
+    realmUrl,
+    realmSecretSeed: options.realmSecretSeed,
+    profileManager: options.profileManager,
+    authenticator: options.authenticator,
+  });
+  if (!resolution.ok) {
+    return { files: [], error: resolution.error };
   }
+  const authenticator = resolution.authenticator;
 
   try {
     const puller = new RealmPuller(

package/src/commands/realm/push.ts

@@ -393,21 +393,17 @@ export async function pushCommand(
   realmUrl: string,
   options: PushCommandOptions,
 ): Promise<void> {
-  let authenticator: RealmAuthenticator;
-  if (options.authenticator) {
-    authenticator = options.authenticator;
-  } else {
-    const resolution = resolveRealmAuthenticator({
-      realmUrl,
-      realmSecretSeed: options.realmSecretSeed,
-      profileManager: options.profileManager,
-    });
-    if (!resolution.ok) {
-      console.error(`Error: ${resolution.error}`);
-      process.exit(1);
-    }
-    authenticator = resolution.authenticator;
+  const resolution = resolveRealmAuthenticator({
+    realmUrl,
+    realmSecretSeed: options.realmSecretSeed,
+    profileManager: options.profileManager,
+    authenticator: options.authenticator,
+  });
+  if (!resolution.ok) {
+    console.error(`Error: ${resolution.error}`);
+    process.exit(1);
   }
+  const authenticator = resolution.authenticator;
 
   if (!(await pathExists(localDir))) {
     console.error(`Local directory does not exist: ${localDir}`);

package/src/commands/realm/status.ts

@@ -303,26 +303,22 @@ export async function status(
     // best-effort only
   }
 
-  let authenticator: RealmAuthenticator;
-  if (options.authenticator) {
-    authenticator = options.authenticator;
-  } else {
-    const resolution = resolveRealmAuthenticator({
+  const resolution = resolveRealmAuthenticator({
+    realmUrl: manifest.realmUrl,
+    realmSecretSeed: options.realmSecretSeed,
+    profileManager: options.profileManager,
+    authenticator: options.authenticator,
+  });
+  if (!resolution.ok) {
+    return {
+      ...baseResult,
       realmUrl: manifest.realmUrl,
-      realmSecretSeed: options.realmSecretSeed,
-      profileManager: options.profileManager,
-    });
-    if (!resolution.ok) {
-      return {
-        ...baseResult,
-        realmUrl: manifest.realmUrl,
-        manifestMtime,
-        hasError: true,
-        error: resolution.error,
-      };
-    }
-    authenticator = resolution.authenticator;
+      manifestMtime,
+      hasError: true,
+      error: resolution.error,
+    };
   }
+  const authenticator = resolution.authenticator;
 
   const inspector = new RealmStatusInspector(
     {

package/src/commands/realm/sync.ts

@@ -619,20 +619,16 @@ export async function sync(
   realmUrl: string,
   options: SyncCommandOptions,
 ): Promise<SyncResult> {
-  let authenticator: RealmAuthenticator;
-  if (options.authenticator) {
-    authenticator = options.authenticator;
-  } else {
-    const resolution = resolveRealmAuthenticator({
-      realmUrl,
-      realmSecretSeed: options.realmSecretSeed,
-      profileManager: options.profileManager,
-    });
-    if (!resolution.ok) {
-      return emptyResult({ error: resolution.error });
-    }
-    authenticator = resolution.authenticator;
+  const resolution = resolveRealmAuthenticator({
+    realmUrl,
+    realmSecretSeed: options.realmSecretSeed,
+    profileManager: options.profileManager,
+    authenticator: options.authenticator,
+  });
+  if (!resolution.ok) {
+    return emptyResult({ error: resolution.error });
   }
+  const authenticator = resolution.authenticator;
 
   const strategies = [
     options.preferLocal,

package/src/commands/realm/unpublish.ts

@@ -10,6 +10,7 @@ import {
   NO_ACTIVE_PROFILE_ERROR,
   type ProfileManager,
 } from '../../lib/profile-manager.ts';
+import { cliLog } from '../../lib/cli-log.ts';
 import { FG_CYAN, FG_GREEN, FG_RED, RESET } from '../../lib/colors.ts';
 import { describeFetchError } from '../../lib/describe-fetch-error.ts';
 
@@ -99,6 +100,7 @@ export async function unpublishRealm(
 
 interface UnpublishCliOptions {
   tolerateMissing?: boolean;
+  json?: boolean;
 }
 
 export function registerUnpublishCommand(realm: Command): void {
@@ -110,11 +112,20 @@ export function registerUnpublishCommand(realm: Command): void {
       '--tolerate-missing',
       'Exit successfully when the realm is already unpublished',
     )
+    .option('--json', 'Output the result as JSON')
     .action(async (publishedRealmURL: string, opts: UnpublishCliOptions) => {
       let result = await unpublishRealm(publishedRealmURL, {
         tolerateMissing: opts.tolerateMissing === true,
       });
 
+      if (opts.json) {
+        cliLog.output(JSON.stringify(result, null, 2));
+        if (result.error) {
+          process.exit(1);
+        }
+        return;
+      }
+
       if (result.error) {
         console.error(`${FG_RED}Error:${RESET} ${result.error}`);
         process.exit(1);

package/src/lib/auth-resolver.ts

@@ -16,15 +16,25 @@ export interface AuthResolverOptions {
   realmSecretSeed?: string;
   /** Override the ProfileManager (tests). When seed mode is active we won't touch it. */
   profileManager?: ProfileManager;
+  /**
+   * Already-constructed authenticator (the commands' `@internal` test hook).
+   * Takes precedence over both seed and profile resolution.
+   */
+  authenticator?: RealmAuthenticator;
 }
 
 export type AuthResolution =
-  | { ok: true; authenticator: RealmAuthenticator; mode: 'seed' | 'profile' }
+  | {
+      ok: true;
+      authenticator: RealmAuthenticator;
+      mode: 'injected' | 'seed' | 'profile';
+    }
   | { ok: false; error: string };
 
 /**
- * Pick between seed-based auth and profile-based auth.
+ * Pick the authenticator for a realm command.
  *
+ *  - If `authenticator` is supplied (test hook), use it as-is.
  *  - If `realmSecretSeed` is present, use `SeedAuthenticator`. We do NOT
  *    require a profile in this mode — operators using the seed typically
  *    don't have a Matrix account configured.
@@ -33,6 +43,9 @@ export type AuthResolution =
 export function resolveRealmAuthenticator(
   options: AuthResolverOptions,
 ): AuthResolution {
+  if (options.authenticator) {
+    return { ok: true, authenticator: options.authenticator, mode: 'injected' };
+  }
   if (options.realmSecretSeed) {
     // registerRealmUrl throws on a malformed realm URL; surface that as a
     // resolver error so pull/push/sync keep their friendly CLI error path.

package/bundled-test-harness/assets/adapter-Dk9jvNQb.js

@@ -1,2 +0,0 @@
-import { mt as TestRealmAdapter } from "./mock-matrix-CD6YHaHR.js";
-export { TestRealmAdapter };

package/bundled-test-harness/assets/live-test-B7uB4aVp.js

@@ -1,2 +0,0 @@
-import { t as loadRealmTests } from "./live-test-pbHzyWf7.js";
-export { loadRealmTests };

package/bundled-test-harness/assets/user-message-B8olA3Ml.css

@@ -1,18 +0,0 @@
-
-  .user-message-bubble[data-scopedcss-7eb12e1519-cac362804b] {
-    padding: var(--boxel-sp-sm);
-    background-color: var(--boxel-light);
-    color: var(--boxel-dark);
-    border-radius: var(--boxel-border-radius-xxl);
-    border-top-left-radius: var(--boxel-border-radius-xs);
-  }
-  .is-pending[data-scopedcss-7eb12e1519-cac362804b] {
-    --pill-background-color: var(--boxel-200);
-    --pill-font-color: var(--boxel-500);
-    background-color: var(--boxel-200);
-    color: var(--boxel-500);
-  }
-  [data-scopedcss-7eb12e1519-cac362804b] a:hover {
-    /* use this highlight text color on light-background */
-    color: var(--boxel-highlight-hover);
-  }