fix(cli): surface a broken metaobjects.config.ts in meta docs instead of silently swallowing

Only attempt config load when the file exists (absence = expected config-less
case, stay silent); a config that EXISTS but fails to load now warns with the
real error rather than degrading silently to provider-less docs — otherwise a
custom-type project would later fail with a cryptic unknown-subtype error.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

server/typescript/packages/cli/src/commands/docs.ts

@@ -96,13 +96,24 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   // back to defaults; the loader still surfaces a stable unknown-subtype error
   // if the metadata genuinely uses an unregistered type.
   let configProviders: NonNullable<Awaited<ReturnType<typeof loadMetaobjectsConfig>>["providers"]> | undefined;
-  try {
-    // The config lives alongside metaobjects/ at the metadata root (metaRoot);
-    // projectRoot only diverges when --templates overrides the template lookup.
-    const forgeConfig = await loadMetaobjectsConfig(metaRoot);
-    configProviders = forgeConfig.providers;
-  } catch {
-    configProviders = undefined;
+  // The config lives alongside metaobjects/ at the metadata root (metaRoot);
+  // projectRoot only diverges when --templates overrides the template lookup.
+  // Only attempt the load when the file is actually present: absence is the
+  // expected config-less case (stay silent), but a config that EXISTS yet fails
+  // to load is surfaced as a warning rather than silently degrading to
+  // provider-less docs — otherwise a custom-type project would later fail with a
+  // cryptic unknown-subtype error instead of the real config error.
+  if (existsSync(join(metaRoot, "metaobjects.config.ts"))) {
+    try {
+      const forgeConfig = await loadMetaobjectsConfig(metaRoot);
+      configProviders = forgeConfig.providers;
+    } catch (err) {
+      log.warn(
+        `docs: metaobjects.config.ts failed to load (${(err as Error).message}); ` +
+          `generating docs without its providers`,
+      );
+      configProviders = undefined;
+    }
   }
 
   // Load metadata standalone — same loader path as migrate/gen. Threads any

server/typescript/packages/cli/test/docs-command.test.ts

@@ -196,6 +196,40 @@ describe("meta docs — standalone neutral metadata docs", () => {
     expect(files).toContain("Place.md");
   });
 
+  test("a broken metaobjects.config.ts is surfaced (not silently swallowed), docs still generate", async () => {
+    // Basic metadata (no custom types) + a config that THROWS on load. Docs must
+    // still succeed config-less, but the real config error must be surfaced as a
+    // warning rather than silently degrading to provider-less docs.
+    const root = await project();
+    await writeFile(
+      join(root, "metaobjects.config.ts"),
+      "throw new Error('broken config boom');\n",
+      "utf8",
+    );
+    const out = join(root, "out-brokencfg");
+
+    const errLogged: string[] = [];
+    const origErr = console.error;
+    console.error = (...args: unknown[]) => {
+      errLogged.push(args.map(String).join(" "));
+    };
+    let code: number;
+    try {
+      code = await docsCommand([root, "--out", out], root);
+    } finally {
+      console.error = origErr;
+    }
+
+    expect(code).toBe(0); // config-less generation still works
+    const files = await readdir(out);
+    expect(files.length).toBeGreaterThan(0);
+    // The config failure is SURFACED (warning on stderr), not silently swallowed,
+    // and carries the loader's real diagnostic so the user can fix it.
+    const stderr = errLogged.join("\n");
+    expect(stderr).toContain("metaobjects.config.ts failed to load");
+    expect(stderr).toContain("generating docs without its providers");
+  });
+
   test("exits non-zero with a clear message when metadata is missing", async () => {
     const empty = await mkdtemp(join(tmpdir(), "meta-docs-empty-"));
     dirs.push(empty);