@sudajs/cli 0.4.3 → 0.5.0

package/dist/index.js

@@ -7,7 +7,7 @@ import { fileURLToPath, pathToFileURL } from 'url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createAgentPageSchemaOutput, checkThemeModule, formatThemeCheckResult, createThemeAgentManifest, validateAgentPageContentWithManifest, agentValidationResultSchema, createPageDataFromAgentContent, findAgentSection, createAgentComponentSchemaOutput, agentPageSchemaOutputSchema, agentComponentOutputSchema } from '@sudajs/theme-engine';
-import { FileSystemThemeRegistry } from '@sudajs/theme-engine/server';
+import { themeManifestSchema, FileSystemThemeRegistry } from '@sudajs/theme-engine/server';
 import { Command } from 'commander';
 import { build, context } from 'esbuild';
 import { z } from 'zod';
@@ -391,10 +391,20 @@ async function fetchJson(url, options = {}) {
   return await response.json();
 }
 function agentCacheDir() {
-  return path2.join(process.env.XDG_CACHE_HOME ?? path2.join(process.env.HOME ?? ".", ".cache"), "suda", "agent");
+  return path2.join(
+    process.env.XDG_CACHE_HOME ?? path2.join(process.env.HOME ?? ".", ".cache"),
+    "suda",
+    "agent"
+  );
 }
 function cachedThemeManifestPath(themeKey, version) {
-  return path2.join(agentCacheDir(), "themes", safeObjectKeyPart(themeKey), safeObjectKeyPart(version), "agent-manifest.json");
+  return path2.join(
+    agentCacheDir(),
+    "themes",
+    safeObjectKeyPart(themeKey),
+    safeObjectKeyPart(version),
+    "agent-manifest.json"
+  );
 }
 async function loadThemeModule(serverEntryPath) {
   const imported = await import(`${pathToFileURL(serverEntryPath).href}?t=${Date.now()}`);
@@ -410,6 +420,12 @@ function assertRecord(value, label) {
 }
 function validateThemeModule(module) {
   assertRecord(module.manifest, "manifest");
+  const parsedManifest = themeManifestSchema.safeParse(module.manifest);
+  if (!parsedManifest.success) {
+    const issues = parsedManifest.error.issues.map((issue) => `  - ${issue.path.join(".") || "<root>"}: ${issue.message}`).join("\n");
+    throw new Error(`manifest does not satisfy the Suda theme contract:
+${issues}`);
+  }
   if (!module.manifest.key || !module.manifest.version || !module.manifest.name) {
     throw new Error("manifest.key, manifest.version and manifest.name are required.");
   }
@@ -604,7 +620,9 @@ function createWatchLogPlugin(label) {
         }
         const errorCount = result.errors.length;
         if (errorCount > 0) {
-          console.log(`rebuild failed (${errorCount} error${errorCount === 1 ? "" : "s"}): ${label}`);
+          console.log(
+            `rebuild failed (${errorCount} error${errorCount === 1 ? "" : "s"}): ${label}`
+          );
           return;
         }
         const stamp = (/* @__PURE__ */ new Date()).toLocaleTimeString();
@@ -639,6 +657,10 @@ function createPreviewAssetResolver(resolveAssetPath) {
     });
   };
 }
+function createPreviewThemeAssetUrl(themeKey, themeVersion, relativePath) {
+  const normalizedRelativePath = relativePath.replace(/^\/+/, "");
+  return `${PREVIEW_PUBLIC_BASE_PATH}/${themeKey}/${themeVersion}/assets/${normalizedRelativePath}?v=${encodeURIComponent(themeVersion)}`;
+}
 async function loadThemeScopedRenderer(themeRoot) {
   const themeRequire = createRequire(path2.join(themeRoot, "package.json"));
   const reactPath = themeRequire.resolve("react");
@@ -671,7 +693,12 @@ function renderStarterPageHtml(theme, resolved, page, renderer) {
     })
   );
   const cssVarStyle = Object.entries(chrome.cssVariables).map(([key, value]) => `${key}: ${value};`).join(" ");
-  const stylesheetTag = resolved.runtime?.stylesheetUrl ? `<link rel="stylesheet" href="${escapeHtml(resolved.runtime.stylesheetUrl)}" />` : "";
+  const stylesheetUrl = resolved.runtime?.stylesheet ? createPreviewThemeAssetUrl(
+    theme.module.manifest.key,
+    theme.module.manifest.version,
+    resolved.runtime.stylesheet
+  ) : null;
+  const stylesheetTag = stylesheetUrl ? `<link rel="stylesheet" href="${escapeHtml(stylesheetUrl)}" />` : "";
   const customHead = chrome.customHeadCode ?? "";
   const customBody = chrome.customBodyCode ?? "";
   return [
@@ -728,7 +755,6 @@ async function startPreviewServer(theme, port) {
   const { createServer } = await import('http');
   const renderer = await loadThemeScopedRenderer(theme.root);
   const registry = new FileSystemThemeRegistry({
-    publicBasePath: PREVIEW_PUBLIC_BASE_PATH,
     artifacts: [
       {
         rootPath: theme.root,
@@ -901,7 +927,9 @@ async function screenshotTheme(root, options) {
   await captureScreenshot(theme, resolved);
 }
 async function loadLocalAgentManifest(root) {
-  const built = await readJsonIfExists(path2.join(root, "dist", "agent-manifest.json"));
+  const built = await readJsonIfExists(
+    path2.join(root, "dist", "agent-manifest.json")
+  );
   if (built) {
     return built;
   }
@@ -930,8 +958,11 @@ async function listAgentThemes(options) {
   }
   const catalog = await fetchJson(url.href, { token: auth.token });
   await mkdir(agentCacheDir(), { recursive: true });
-  await writeFile(path2.join(agentCacheDir(), "catalog.json"), `${JSON.stringify(catalog, null, 2)}
-`);
+  await writeFile(
+    path2.join(agentCacheDir(), "catalog.json"),
+    `${JSON.stringify(catalog, null, 2)}
+`
+  );
   return catalog.themes;
 }
 async function fetchAgentManifest(themeKey, options) {
@@ -953,11 +984,16 @@ async function fetchAgentManifest(themeKey, options) {
   if (cached) {
     return cached;
   }
-  const url = new URL(`/api/cli/agent/themes/${encodeURIComponent(resolvedKey)}/${encodeURIComponent(version)}/schema`, auth.baseUrl);
+  const url = new URL(
+    `/api/cli/agent/themes/${encodeURIComponent(resolvedKey)}/${encodeURIComponent(version)}/schema`,
+    auth.baseUrl
+  );
   if (resolvedOptions.projectId) {
     url.searchParams.set("projectId", resolvedOptions.projectId);
   }
-  const result = await fetchJson(url.href, { token: auth.token });
+  const result = await fetchJson(url.href, {
+    token: auth.token
+  });
   if (!result.agentManifest || !Array.isArray(result.agentManifest.sections)) {
     throw new Error(
       `Theme schema is not available for "${resolvedKey}@${version}". The theme may not be published, not active for the project, or its agent manifest is missing. Republish the theme or activate it before retrying.`
@@ -1270,11 +1306,10 @@ async function startMcpServer() {
 async function writeThemeArtifacts(theme) {
   const dist = path2.join(theme.root, "dist");
   const agentManifest = createThemeAgentManifest(theme.module);
-  await writeFile(
-    path2.join(dist, "manifest.json"),
-    `${JSON.stringify(theme.module.manifest, null, 2)}
-`
-  );
+  const manifestJson = `${JSON.stringify(theme.module.manifest, null, 2)}
+`;
+  await writeFile(path2.join(dist, "manifest.json"), manifestJson);
+  await writeFile(path2.join(theme.root, "manifest.json"), manifestJson);
   await writeFile(
     path2.join(dist, "starter-pages.json"),
     `${JSON.stringify(theme.module.starterPages, null, 2)}
@@ -1295,9 +1330,12 @@ function contentTypeFor(relativePath) {
   if (relativePath.endsWith(".css")) {
     return "text/css; charset=utf-8";
   }
-  if (relativePath.endsWith(".js")) {
+  if (relativePath.endsWith(".js") || relativePath.endsWith(".mjs")) {
     return "application/javascript; charset=utf-8";
   }
+  if (relativePath.endsWith(".map")) {
+    return "application/json; charset=utf-8";
+  }
   if (relativePath.endsWith(".json")) {
     return "application/json; charset=utf-8";
   }
@@ -1313,6 +1351,39 @@ function contentTypeFor(relativePath) {
   if (relativePath.endsWith(".webp")) {
     return "image/webp";
   }
+  if (relativePath.endsWith(".avif")) {
+    return "image/avif";
+  }
+  if (relativePath.endsWith(".gif")) {
+    return "image/gif";
+  }
+  if (relativePath.endsWith(".ico")) {
+    return "image/x-icon";
+  }
+  if (relativePath.endsWith(".woff2")) {
+    return "font/woff2";
+  }
+  if (relativePath.endsWith(".woff")) {
+    return "font/woff";
+  }
+  if (relativePath.endsWith(".ttf")) {
+    return "font/ttf";
+  }
+  if (relativePath.endsWith(".otf")) {
+    return "font/otf";
+  }
+  if (relativePath.endsWith(".mp4")) {
+    return "video/mp4";
+  }
+  if (relativePath.endsWith(".webm")) {
+    return "video/webm";
+  }
+  if (relativePath.endsWith(".txt")) {
+    return "text/plain; charset=utf-8";
+  }
+  if (relativePath.endsWith(".xml")) {
+    return "application/xml; charset=utf-8";
+  }
   return "application/octet-stream";
 }
 async function collectFiles(root, directory) {
@@ -1347,8 +1418,22 @@ async function collectThemeArtifactFiles(theme) {
       contentType: "text/css; charset=utf-8"
     });
   }
+  const rootManifestPath = path2.join(theme.root, "manifest.json");
+  if (await pathExists(rootManifestPath)) {
+    files.push({
+      absolutePath: rootManifestPath,
+      relativePath: "manifest.json",
+      contentType: "application/json; charset=utf-8"
+    });
+  }
   return files;
 }
+var SSR_REQUIRED_ARTIFACTS = [
+  "dist/index.js",
+  "dist/runtime.client.js",
+  "manifest.json",
+  "styles.css"
+];
 async function checksum(files) {
   const hash = createHash("sha256");
   for (const file of files.sort((a, b) => a.relativePath.localeCompare(b.relativePath))) {
@@ -1375,26 +1460,53 @@ ${lines.join("\n")}`;
   }
   return message;
 }
-async function publishTheme(root, skipBuild, skipCheck) {
+async function publishTheme(root, skipBuild, skipCheck, force) {
   const theme = skipBuild ? await validateTheme(root) : await buildTheme(root, false);
+  await writeThemeArtifacts(theme);
   if (!skipCheck) {
     const ok = runThemeCheck(theme);
     if (!ok) {
-      throw new Error(
-        "AI metadata check failed. Fix the errors above or rerun with --skip-check."
-      );
+      throw new Error("AI metadata check failed. Fix the errors above or rerun with --skip-check.");
     }
   }
   const files = await collectThemeArtifactFiles(theme);
   if (!theme.clientEntryPath) {
     throw new Error("Missing dist/runtime.client.js. Run `suda theme build` first.");
   }
+  const collectedPaths = new Set(files.map((f) => f.relativePath));
+  for (const required of SSR_REQUIRED_ARTIFACTS) {
+    if (!collectedPaths.has(required)) {
+      throw new Error(
+        `Missing required SSR artifact: ${required}. Run \`suda theme build\` and ensure ${required === "styles.css" ? "a `styles.css` file exists at the theme root" : `\`${required}\` is generated`}.`
+      );
+    }
+  }
   const config = await readAuthConfig();
   if (!config) {
     throw new Error("Not logged in. Run `suda auth login` to authenticate first.");
   }
   const baseUrl = `${protocolForHost2(config.host)}://${config.host}`;
   const { key, version } = theme.module.manifest;
+  const digest = await checksum(files);
+  if (force) {
+    const forceRes = await fetch(`${baseUrl}/api/cli/themes/publish-force`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${config.sessionToken}`
+      },
+      body: JSON.stringify({ key, version })
+    });
+    if (!forceRes.ok && forceRes.status !== 404) {
+      throw new Error(`Failed to force-clear ${key}@${version}: ${await formatHttpErrorBody(forceRes)}`);
+    }
+    if (forceRes.ok) {
+      const { deletedObjects } = await forceRes.json();
+      console.log(
+        `force-cleared ${key}@${version} (${deletedObjects ?? 0} objects removed). Republishing...`
+      );
+    }
+  }
   const intentRes = await fetch(`${baseUrl}/api/cli/themes/publish-intent`, {
     method: "POST",
     headers: {
@@ -1404,13 +1516,12 @@ async function publishTheme(root, skipBuild, skipCheck) {
     body: JSON.stringify({
       key,
       version,
+      checksum: digest,
       files: files.map((f) => ({ relativePath: f.relativePath, contentType: f.contentType }))
     })
   });
   if (!intentRes.ok) {
-    throw new Error(
-      `Failed to get publish intent: ${await formatHttpErrorBody(intentRes)}`
-    );
+    throw new Error(`Failed to get publish intent: ${await formatHttpErrorBody(intentRes)}`);
   }
   const { urls } = await intentRes.json();
   for (const file of files) {
@@ -1431,12 +1542,7 @@ async function publishTheme(root, skipBuild, skipCheck) {
     }
     console.log(`uploaded ${createThemeObjectKey(key, version, file.relativePath)}`);
   }
-  const digest = await checksum(files);
   const bundleArtifactRelative = "dist/index.js";
-  const bundleArtifactExists = files.some((f) => f.relativePath === bundleArtifactRelative);
-  if (!bundleArtifactExists) {
-    throw new Error(`Missing ${bundleArtifactRelative} in theme artifacts.`);
-  }
   const previewArtifactRelative = "dist/preview/desktop.png";
   const previewArtifactExists = await pathExists(path2.join(theme.root, previewArtifactRelative));
   const agentManifest = createThemeAgentManifest(theme.module);
@@ -1457,9 +1563,7 @@ async function publishTheme(root, skipBuild, skipCheck) {
     })
   });
   if (!completeRes.ok) {
-    throw new Error(
-      `Failed to complete publish: ${await formatHttpErrorBody(completeRes)}`
-    );
+    throw new Error(`Failed to complete publish: ${await formatHttpErrorBody(completeRes)}`);
   }
   console.log(`published ${key}@${version}`);
 }
@@ -1617,6 +1721,10 @@ export const sourceManifest: ThemeSourceManifest = {
   minEngineVersion: "0.0.0",
   entry: "dist/index.js",
   clientEntry: "dist/runtime.client.js",
+  // Required. SudaCloud currently hosts SSR themes only; CSR/Hybrid postures
+  // are on the roadmap. Authoring \`renderMode\` is the contract a theme uses
+  // to declare which posture it expects from the host.
+  renderMode: "ssr",
 };
 `
   );
@@ -2026,6 +2134,14 @@ export { pageConfig, layoutConfig, defaultLayout, starterPages };
 This directory is a Suda theme source project generated by \`suda theme init\`.
 It is a **standalone** npm package \u2014 it does not depend on the SudaCloud monorepo.
 
+## Render mode
+
+This theme contract requires \`renderMode: "ssr"\` in the source manifest
+(\`src/manifest.ts\`). SudaCloud's site runtime currently only supports SSR
+themes; CSR / Hybrid postures are on the roadmap. **Do not** introduce
+client-only entry points or assume browser-only globals at module scope \u2014
+the theme bundle must execute in a Node SSR context.
+
 ## What to edit
 
 - Add page sections in \`src/sections.tsx\` and register them in \`SECTION_COMPONENTS\`.
@@ -2166,6 +2282,10 @@ Read \`AGENTS.md\` first. It is the canonical guide for this Suda theme project.
 A Suda theme scaffolded with \`suda theme init\`. This is a standalone
 package; it does not need to live inside the SudaCloud monorepo.
 
+This theme targets SudaCloud's SSR runtime (\`renderMode: "ssr"\` in
+\`src/manifest.ts\`); CSR / Hybrid postures are not yet supported by the
+host.
+
 ## Setup
 
 \`\`\`bash
@@ -2181,6 +2301,10 @@ pnpm dev            # watch the browser runtime and start preview server
 pnpm validate       # validate the dist artifact
 \`\`\`
 
+> \`renderMode\` currently only accepts \`"ssr"\`. \`suda theme validate\` and
+> \`suda theme check\` will reject manifests that omit it or set a different
+> value.
+
 ## Agent tooling
 
 \`\`\`bash
@@ -2216,10 +2340,7 @@ function buildProgram() {
       );
     }
   });
-  theme.command("build").description("Build server dist (via package script) and browser runtime.").option("--theme-root <path>", "Theme source/artifact root.").option("--skip-theme-build", "Skip the theme package build script.").option(
-    "--skip-check",
-    "Skip the AI metadata check that normally runs after build."
-  ).action(async (options) => {
+  theme.command("build").description("Build server dist (via package script) and browser runtime.").option("--theme-root <path>", "Theme source/artifact root.").option("--skip-theme-build", "Skip the theme package build script.").option("--skip-check", "Skip the AI metadata check that normally runs after build.").action(async (options) => {
     const result = await buildTheme(resolveThemeRoot(options), options.skipThemeBuild === true);
     console.log(`built ${result.module.manifest.key}@${result.module.manifest.version}`);
     if (options.skipCheck !== true) {
@@ -2248,19 +2369,18 @@ function buildProgram() {
       Number.isFinite(port) ? port : 4177
     );
   });
-  theme.command("screenshot").description(
-    "Capture a desktop preview screenshot of the home starter page using Playwright."
-  ).option("--theme-root <path>", "Theme source/artifact root.").option("--output <path>", "Output PNG path relative to theme root.").option("--width <px>", "Viewport width in pixels.", "1280").option("--height <px>", "Viewport height in pixels.", "800").option("--port <port>", "Preview server port used during capture.", "4178").option("--skip-build", "Skip rebuilding the theme before capturing.").action(async (options) => {
+  theme.command("screenshot").description("Capture a desktop preview screenshot of the home starter page using Playwright.").option("--theme-root <path>", "Theme source/artifact root.").option("--output <path>", "Output PNG path relative to theme root.").option("--width <px>", "Viewport width in pixels.", "1280").option("--height <px>", "Viewport height in pixels.", "800").option("--port <port>", "Preview server port used during capture.", "4178").option("--skip-build", "Skip rebuilding the theme before capturing.").action(async (options) => {
     await screenshotTheme(resolveThemeRoot(options), options);
   });
-  theme.command("publish").description("Upload artifact to S3 and upsert ThemePackage/ThemeVersion.").option("--theme-root <path>", "Theme source/artifact root.").option("--skip-build", "Publish existing dist files without rebuilding.").option(
-    "--skip-check",
-    "Skip the AI metadata check that normally runs before upload."
+  theme.command("publish").description("Upload artifact to S3 and upsert ThemePackage/ThemeVersion.").option("--theme-root <path>", "Theme source/artifact root.").option("--skip-build", "Publish existing dist files without rebuilding.").option("--skip-check", "Skip the AI metadata check that normally runs before upload.").option(
+    "--force",
+    "Development recovery only: clear the existing themes/<key>/<version>/ prefix and ThemeVersion row before republishing. Re-published clients pinned to this version are unavailable until the new publish completes."
   ).action(async (options) => {
     await publishTheme(
       resolveThemeRoot(options),
       options.skipBuild === true,
-      options.skipCheck === true
+      options.skipCheck === true,
+      options.force === true
     );
   });
   const agent = program.command("agent").description("Agent-friendly theme and page tooling.");
@@ -2295,12 +2415,16 @@ function buildProgram() {
   const agentTheme = agent.command("theme").description("Inspect a single theme.");
   agentTheme.command("describe").description("Describe a theme's AI-first page schema.").argument("<theme>", "Theme key.").option("--version <version>", "Theme version.").option("--project-id <projectId>", "Project scope.").option("--theme-root <path>", "Read a local theme.").option("--example", "Include example page content.").action(async (themeKey, options) => {
     const manifest = await fetchAgentManifest(themeKey, options);
-    printJson(createAgentPageSchemaOutput(manifest, { includeExample: options.example === true }));
+    printJson(
+      createAgentPageSchemaOutput(manifest, { includeExample: options.example === true })
+    );
   });
   const agentPage = agent.command("page").description("AI-first page content tooling.");
   agentPage.command("schema").description("Print the AI-first page content output schema for a theme.").argument("<theme>", "Theme key.").option("--version <version>", "Theme version.").option("--project-id <projectId>", "Project scope.").option("--theme-root <path>", "Read a local theme.").option("--example", "Include example page content.").action(async (themeKey, options) => {
     const manifest = await fetchAgentManifest(themeKey, options);
-    printJson(createAgentPageSchemaOutput(manifest, { includeExample: options.example === true }));
+    printJson(
+      createAgentPageSchemaOutput(manifest, { includeExample: options.example === true })
+    );
   });
   agentPage.command("validate").description("Validate an AI-generated Suda page content JSON document.").requiredOption("--theme <theme>", "Theme key.").requiredOption("--input <file>", "JSON file containing Suda page content.").option("--version <version>", "Theme version.").option("--project-id <projectId>", "Project scope.").option("--theme-root <path>", "Read a local theme.").action(async (options) => {
     await validateAgentPage(options.theme, options.input, options);
@@ -2317,7 +2441,11 @@ function buildProgram() {
     await startMcpServer();
   });
   const authCmd = program.command("auth").description("Manage Suda authentication.");
-  authCmd.command("login").description("Authenticate Suda CLI with a SudaCloud workspace.").option("--host <host>", "The SudaCloud workspace host to authenticate against.", "app.sudayun.cn").action(async (options) => {
+  authCmd.command("login").description("Authenticate Suda CLI with a SudaCloud workspace.").option(
+    "--host <host>",
+    "The SudaCloud workspace host to authenticate against.",
+    "app.sudayun.cn"
+  ).action(async (options) => {
     await login(options.host);
   });
   authCmd.command("status").description("Check current authentication status.").action(async () => {