@sudajs/cli 0.2.1 → 0.4.0

package/dist/index.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { createHash } from 'crypto';
 import fs, { mkdir, writeFile, readFile, stat, readdir } from 'fs/promises';
+import { createRequire } from 'module';
 import path2 from 'path';
-import { pathToFileURL } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createAgentPageSchemaOutput, createThemeAgentManifest, validateAgentPageContentWithManifest, agentValidationResultSchema, createPageDataFromAgentContent, findAgentSection, createAgentComponentSchemaOutput, agentPageSchemaOutputSchema, agentComponentOutputSchema } from '@sudajs/theme-engine';
+import { createAgentPageSchemaOutput, checkThemeModule, formatThemeCheckResult, createThemeAgentManifest, validateAgentPageContentWithManifest, agentValidationResultSchema, createPageDataFromAgentContent, findAgentSection, createAgentComponentSchemaOutput, agentPageSchemaOutputSchema, agentComponentOutputSchema } from '@sudajs/theme-engine';
 import { extractLayoutChrome, ThemeRender } from '@sudajs/theme-engine/server';
 import { Command } from 'commander';
 import { build, context } from 'esbuild';
@@ -42,9 +43,42 @@ async function clearAuthConfig() {
     }
   }
 }
+function protocolForHost(host) {
+  return host.includes("localhost") || host.includes("127.0.0.1") ? "http" : "https";
+}
+var CliAuthExpiredError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "CliAuthExpiredError";
+    this.code = code;
+  }
+};
+async function cliAuthFetch(pathname, init = {}) {
+  const config = await readAuthConfig();
+  if (!config) {
+    throw new CliAuthExpiredError(
+      "unauthorized",
+      "Not logged in. Run `suda auth login` to authenticate first."
+    );
+  }
+  const baseUrl = `${protocolForHost(config.host)}://${config.host}`;
+  const headers = new Headers(init.headers);
+  headers.set("Authorization", `Bearer ${config.sessionToken}`);
+  const res = await fetch(`${baseUrl}${pathname}`, { ...init, headers });
+  if (res.status === 401) {
+    const body = await res.clone().json().catch(() => ({}));
+    const code = ["token_invalid", "token_revoked", "token_expired"].includes(body.error ?? "") ? body.error : "unauthorized";
+    await clearAuthConfig();
+    throw new CliAuthExpiredError(
+      code,
+      body.message ?? "Authentication is no longer valid. Run `suda auth login` to authenticate again."
+    );
+  }
+  return res;
+}
 async function login(host = "app.sudayun.cn") {
-  const protocol = host.includes("localhost") || host.includes("127.0.0.1") ? "http" : "https";
-  const baseUrl = `${protocol}://${host}`;
+  const baseUrl = `${protocolForHost(host)}://${host}`;
   console.log(`Requesting device authorization from ${baseUrl}...`);
   const deviceRes = await fetch(`${baseUrl}/api/cli-auth/device`, {
     method: "POST"
@@ -96,30 +130,26 @@ async function status() {
     console.log("Not logged in. Run `suda auth login` to authenticate.");
     return;
   }
-  const protocol = config.host.includes("localhost") || config.host.includes("127.0.0.1") ? "http" : "https";
   let res;
   try {
-    res = await fetch(`${protocol}://${config.host}/api/auth/get-session`, {
-      headers: {
-        Authorization: `Bearer ${config.sessionToken}`
-      }
-    });
-  } catch {
+    res = await cliAuthFetch("/api/cli-auth/whoami");
+  } catch (err) {
+    if (err instanceof CliAuthExpiredError) {
+      console.log(err.message);
+      return;
+    }
     console.error(`Failed to connect to ${config.host}.`);
     return;
   }
   if (!res.ok) {
-    console.log("Session expired or invalid. Please run `suda auth login` again.");
-    await clearAuthConfig();
-    return;
-  }
-  const session = await res.json();
-  if (!session?.user) {
-    console.log("Session expired or invalid. Please run `suda auth login` again.");
-    await clearAuthConfig();
+    console.error(
+      `Failed to verify session (${res.status} ${res.statusText}). Try again later.`
+    );
     return;
   }
-  console.log(`Logged in as ${session.user.email || session.user.name} on ${config.host}`);
+  const data = await res.json();
+  const label = data.user?.email ?? data.user?.name ?? "your account";
+  console.log(`Logged in as ${label} on ${config.host}`);
 }
 async function logout() {
   const config = await readAuthConfig();
@@ -127,6 +157,17 @@ async function logout() {
     console.log("Not logged in.");
     return;
   }
+  try {
+    await cliAuthFetch("/api/cli-auth/revoke", { method: "POST" });
+  } catch (err) {
+    if (err instanceof CliAuthExpiredError) {
+      console.log("Logged out (token was already invalid).");
+      return;
+    }
+    console.warn(
+      `Could not contact ${config.host} to revoke token. The token will be cleared locally only.`
+    );
+  }
   await clearAuthConfig();
   console.log("Logged out successfully.");
 }
@@ -326,7 +367,7 @@ async function readJsonIfExists(filePath) {
   }
   return readJson(filePath);
 }
-function protocolForHost(host) {
+function protocolForHost2(host) {
   return host.includes("localhost") || host.includes("127.0.0.1") ? "http" : "https";
 }
 async function requireCliBaseUrl() {
@@ -335,7 +376,7 @@ async function requireCliBaseUrl() {
     throw new Error("Not logged in. Run `suda auth login` to authenticate first.");
   }
   return {
-    baseUrl: `${protocolForHost(config.host)}://${config.host}`,
+    baseUrl: `${protocolForHost2(config.host)}://${config.host}`,
     token: config.sessionToken
   };
 }
@@ -515,6 +556,16 @@ async function buildTheme(root, skipThemeBuild) {
   await writeThemeArtifacts(validated);
   return validateTheme(root);
 }
+function runThemeCheck(theme) {
+  const result = checkThemeModule(theme.module);
+  const text = formatThemeCheckResult(result);
+  if (result.ok) {
+    console.log(text);
+  } else {
+    console.error(text);
+  }
+  return result.ok;
+}
 async function watchTheme(root, skipThemeBuild) {
   if (!skipThemeBuild) {
     await runThemePackageBuild(root);
@@ -1162,8 +1213,16 @@ async function checksum(files) {
   }
   return hash.digest("hex");
 }
-async function publishTheme(root, skipBuild) {
+async function publishTheme(root, skipBuild, skipCheck) {
   const theme = skipBuild ? await validateTheme(root) : await buildTheme(root, false);
+  if (!skipCheck) {
+    const ok = runThemeCheck(theme);
+    if (!ok) {
+      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.");
@@ -1172,7 +1231,7 @@ async function publishTheme(root, skipBuild) {
   if (!config) {
     throw new Error("Not logged in. Run `suda auth login` to authenticate first.");
   }
-  const baseUrl = `${protocolForHost(config.host)}://${config.host}`;
+  const baseUrl = `${protocolForHost2(config.host)}://${config.host}`;
   const { key, version } = theme.module.manifest;
   const intentRes = await fetch(`${baseUrl}/api/cli/themes/publish-intent`, {
     method: "POST",
@@ -1240,8 +1299,54 @@ async function publishTheme(root, skipBuild) {
   }
   console.log(`published ${key}@${version}`);
 }
+var cachedCliPackageVersions;
+async function readCliPackageVersions() {
+  if (cachedCliPackageVersions) {
+    return cachedCliPackageVersions;
+  }
+  const here = fileURLToPath(import.meta.url);
+  const cliPkgPath = path2.resolve(path2.dirname(here), "..", "package.json");
+  let cliRaw;
+  try {
+    cliRaw = await readFile(cliPkgPath, "utf8");
+  } catch {
+    cachedCliPackageVersions = { themeEngine: "*", cli: "*" };
+    return cachedCliPackageVersions;
+  }
+  const cliPkg = JSON.parse(cliRaw);
+  const cliVersion = typeof cliPkg.version === "string" ? cliPkg.version : "0.0.0";
+  const declaredEngine = cliPkg.dependencies?.["@sudajs/theme-engine"];
+  let themeEngine;
+  if (declaredEngine && !declaredEngine.startsWith("workspace:")) {
+    themeEngine = declaredEngine;
+  } else {
+    let resolved;
+    try {
+      const require2 = createRequire(import.meta.url);
+      const enginePkgPath = require2.resolve("@sudajs/theme-engine/package.json");
+      const engineRaw = await readFile(enginePkgPath, "utf8");
+      const engineVersion = JSON.parse(engineRaw).version;
+      if (typeof engineVersion === "string" && engineVersion.length > 0) {
+        resolved = `^${engineVersion}`;
+      }
+    } catch {
+    }
+    if (!resolved) {
+      throw new Error(
+        "suda theme init: cannot determine the @sudajs/theme-engine version to scaffold. The CLI's package.json declares it as `workspace:*` (monorepo dev mode) but `@sudajs/theme-engine/package.json` could not be resolved from the CLI's runtime. Run `pnpm install` and re-run from the monorepo root, or install a published @sudajs/cli tarball (which pins a real semver range)."
+      );
+    }
+    themeEngine = resolved;
+  }
+  cachedCliPackageVersions = {
+    themeEngine,
+    cli: `^${cliVersion}`
+  };
+  return cachedCliPackageVersions;
+}
 async function initTheme(target) {
   const key = path2.basename(target).replace(/[^a-zA-Z0-9._-]/g, "-").toLowerCase();
+  const cliPackageVersions = await readCliPackageVersions();
   await mkdir(path2.join(target, "src"), { recursive: true });
   await writeFile(
     path2.join(target, "package.json"),
@@ -1267,11 +1372,11 @@ async function initTheme(target) {
           preview: "suda theme preview --theme-root ."
         },
         dependencies: {
-          "@sudajs/theme-engine": "^0.1.1"
+          "@sudajs/theme-engine": cliPackageVersions.themeEngine
         },
         devDependencies: {
           "@puckeditor/core": "^0.21.2",
-          "@sudajs/cli": "^0.1.0",
+          "@sudajs/cli": cliPackageVersions.cli,
           "@types/node": "^22.0.0",
           "@types/react": "^19.0.0",
           "@types/react-dom": "^19.0.0",
@@ -1354,10 +1459,17 @@ export const sourceManifest: ThemeSourceManifest = {
   );
   await writeFile(
     path2.join(target, "src", "sections.tsx"),
-    `import type { ComponentConfig } from "@puckeditor/core";
+    `import type { SudaComponentConfig } from "@sudajs/theme-engine";
 
-export const Hero: ComponentConfig = {
+export const Hero: SudaComponentConfig = {
   label: "Hero",
+  ai: {
+    instructions:
+      "Primary page introduction used to communicate the main value proposition. " +
+      "Place near the beginning of landing, product, service, or campaign pages. " +
+      "Include one concise headline, supporting copy, and one primary call to action. " +
+      "Use at most once per page. Do not use for ordinary section headings or article content.",
+  },
   fields: {
     eyebrow: { type: "text", label: "Eyebrow" },
     title: { type: "text", label: "Title" },
@@ -1382,8 +1494,14 @@ export const Hero: ComponentConfig = {
   ),
 };
 
-export const FeatureGrid: ComponentConfig = {
+export const FeatureGrid: SudaComponentConfig = {
   label: "Feature grid",
+  ai: {
+    instructions:
+      "Section that lists 3\u20136 short feature or benefit cards explaining what the product or service offers. " +
+      "Place after the hero / introduction and before the final call-to-action. " +
+      "Use when the page needs to communicate multiple distinct value points; do not use for testimonials, FAQs, or step-by-step processes.",
+  },
   fields: {
     title: { type: "text", label: "Title" },
     description: { type: "textarea", label: "Description" },
@@ -1421,8 +1539,14 @@ export const FeatureGrid: ComponentConfig = {
   ),
 };
 
-export const Testimonial: ComponentConfig = {
+export const Testimonial: SudaComponentConfig = {
   label: "Testimonial",
+  ai: {
+    instructions:
+      "Section that quotes a single customer or expert as social proof. " +
+      "Place mid-page after a feature or value section, or near the end before the final CTA. " +
+      "Do not invent quotes, names, or roles; only use content the user provides.",
+  },
   fields: {
     quote: { type: "textarea", label: "Quote" },
     author: { type: "text", label: "Author" },
@@ -1441,8 +1565,14 @@ export const Testimonial: ComponentConfig = {
   ),
 };
 
-export const CallToAction: ComponentConfig = {
+export const CallToAction: SudaComponentConfig = {
   label: "Call to action",
+  ai: {
+    instructions:
+      "Closing conversion section that invites the visitor to take a specific action (sign up, contact, buy, etc.). " +
+      "Place near the end of the page, after supporting content. " +
+      "Use at most once per page. Do not use as the page's first introduction \u2014 the Hero component fills that role.",
+  },
   fields: {
     title: { type: "text", label: "Title" },
     description: { type: "textarea", label: "Description" },
@@ -1470,7 +1600,8 @@ export const SECTION_COMPONENTS = { Hero, FeatureGrid, Testimonial, CallToAction
   await writeFile(
     path2.join(target, "src", "layout.tsx"),
     `import { getPageSlot } from "@sudajs/theme-engine/runtime";
-import type { ComponentConfig, Config } from "@puckeditor/core";
+import type { Config } from "@puckeditor/core";
+import type { SudaComponentConfig } from "@sudajs/theme-engine";
 import type { ReactElement, ReactNode } from "react";
 
 type PuckExtras = { puck?: { metadata?: Record<string, unknown> } };
@@ -1485,22 +1616,40 @@ export const rootConfig: NonNullable<Config["root"]> = {
   ),
 };
 
-export const Header: ComponentConfig = {
+export const Header: SudaComponentConfig = {
   label: "Header",
+  ai: {
+    instructions:
+      "Site-wide header rendered at the top of every page. " +
+      "Place once at the top of the layout (not inside page content). " +
+      "Used for branding and primary navigation, not for promotional content.",
+  },
   fields: { siteName: { type: "text", label: "Site name" } },
   defaultProps: { siteName: "${key}" },
   render: ({ siteName }) => <header className="${key}-header">{siteName}</header>,
 };
 
-export const PageOutlet: ComponentConfig = {
+export const PageOutlet: SudaComponentConfig = {
   label: "Page outlet",
+  ai: {
+    exclude: true,
+    instructions:
+      "Structural slot where each page's content is injected. " +
+      "Managed by the layout, never created or placed by AI.",
+  },
   fields: {},
   defaultProps: {},
   render: (props: PuckExtras): ReactElement => <>{getPageSlot(props.puck?.metadata)}</>,
 };
 
-export const Footer: ComponentConfig = {
+export const Footer: SudaComponentConfig = {
   label: "Footer",
+  ai: {
+    instructions:
+      "Site-wide footer rendered at the bottom of every page. " +
+      "Place once at the end of the layout. " +
+      "Used for legal text, copyright, and secondary links \u2014 not for primary CTAs.",
+  },
   fields: { text: { type: "text", label: "Text" } },
   defaultProps: { text: "\xA9 ${key}" },
   render: ({ text }) => <footer className="${key}-footer">{text}</footer>,
@@ -1720,14 +1869,110 @@ It is a **standalone** npm package \u2014 it does not depend on the SudaCloud mo
 - Prefer editing section props over changing render code when generating pages.
 - Do not edit files under \`dist/\`; they are generated.
 
+## AI metadata (required)
+
+Every component (and zone-level layout component) **must** declare \`ai.instructions\`.
+Without it the page-generation agent has no way to know what the component is for,
+and \`suda theme check\` (run automatically before publish) will fail.
+
+### Component-level \`ai\`
+
+Each \`ComponentConfig\` must include:
+
+\`\`\`ts
+import type { SudaComponentConfig } from "@sudajs/theme-engine";
+
+export const Hero: SudaComponentConfig = {
+  label: "Hero",
+  ai: {
+    instructions:
+      "Primary page introduction used to communicate the main value proposition. " +
+      "Place near the beginning of landing or product pages. " +
+      "Include one primary CTA. Use at most once per page. " +
+      "Do not use for ordinary section headings or article content.",
+  },
+  fields: { /* ... */ },
+  defaultProps: { /* ... */ },
+  render: (props) => /* ... */,
+};
+\`\`\`
+
+A good \`instructions\` covers, in plain English:
+
+1. **Purpose** \u2014 what role this component plays on a page.
+2. **Use when** \u2014 page types or scenarios where it should be selected.
+3. **Avoid when** \u2014 situations that look similar but call for a different component.
+4. **Placement** \u2014 where in the page it normally belongs (top, after features, near end, etc.).
+5. **Frequency / composition** \u2014 how many times it can appear, what it must contain, and any adjacency rules.
+
+Write executable, specific sentences (\`Use when...\`, \`Place after...\`, \`Use at most once per page.\`).
+Do **not** describe styling (colors, fonts, spacing) \u2014 those belong to the design system.
+Do **not** write vague filler like "modern", "engaging", "beautiful".
+
+If two components look similar (e.g. Hero vs. PageHeader vs. SectionHeader),
+their \`instructions\` must explicitly differentiate them, otherwise the agent
+will mix them up.
+
+### Hiding a component from AI
+
+Use \`ai.exclude: true\` for internal/debug components or anything the agent
+should never auto-create. Such components remain editable by humans:
+
+\`\`\`ts
+ai: { exclude: true, instructions: "Internal debug block; AI must not create it." }
+\`\`\`
+
+### Field-level \`ai\` (recommended, optional)
+
+Field-level metadata sharpens the generated content but is **not required**.
+Use it when a field's name and type alone don't fully convey the constraints:
+
+\`\`\`ts
+fields: {
+  title: {
+    type: "text",
+    ai: {
+      instructions:
+        "Main value-proposition headline. 4\u201312 words, focus on the visitor benefit, " +
+        "do not repeat the eyebrow or description.",
+      required: true,
+    },
+  },
+  imageUrl: {
+    type: "text",
+    ai: {
+      // Atomic values that cannot render correctly while half-streamed.
+      stream: false,
+      instructions: "Image that supports the section topic. Avoid logos, screenshots, or unrelated decoration.",
+    },
+  },
+}
+\`\`\`
+
+Supported field-level keys: \`instructions\`, \`required\`, \`exclude\`, \`stream\`,
+\`bind\` (delegate to a tool), and \`schema\` (only needed for \`custom\` / \`external\` /
+\`user\` fields whose runtime shape can't be inferred).
+
+### Verifying
+
+\`\`\`bash
+pnpm build              # also runs the AI metadata check
+suda theme check        # run the check on its own
+\`\`\`
+
+Missing component-level \`ai.instructions\` is reported as an **error** and blocks
+the build. Very short or label-repeating instructions are reported as
+**warnings**.
+
 ## Useful commands
 
 \`\`\`bash
 pnpm install
 pnpm typecheck
-pnpm build               # tsc + suda theme build --skip-theme-build
+pnpm build               # tsc + suda theme build --skip-theme-build (runs AI check)
 pnpm validate
 pnpm preview
+suda theme check         # AI metadata check only
 suda agent theme describe local --theme-root .
 suda agent section schema --theme local --section Hero --theme-root .
 suda agent page validate --theme local --input ./page.json --theme-root .
@@ -1799,9 +2044,29 @@ 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.").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) {
+      const ok = runThemeCheck(result);
+      if (!ok) {
+        throw new Error(
+          "AI metadata check failed. Fix the errors above or rerun with --skip-check."
+        );
+      }
+    }
+  });
+  theme.command("check").description(
+    "Run AI metadata checks on a built theme without rebuilding. Reports missing component-level ai.instructions as errors and weak content as warnings."
+  ).option("--theme-root <path>", "Theme source/artifact root.").action(async (options) => {
+    const theme2 = await validateTheme(resolveThemeRoot(options));
+    const ok = runThemeCheck(theme2);
+    if (!ok) {
+      process.exitCode = 1;
+    }
   });
   theme.command("dev").description("Watch and rebuild the browser runtime.").option("--theme-root <path>", "Theme source/artifact root.").option("--skip-theme-build", "Skip the theme package build script.").action(async (options) => {
     await watchTheme(resolveThemeRoot(options), options.skipThemeBuild === true);
@@ -1815,8 +2080,15 @@ function buildProgram() {
   ).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.").action(async (options) => {
-    await publishTheme(resolveThemeRoot(options), options.skipBuild === true);
+  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."
+  ).action(async (options) => {
+    await publishTheme(
+      resolveThemeRoot(options),
+      options.skipBuild === true,
+      options.skipCheck === true
+    );
   });
   const agent = program.command("agent").description("Agent-friendly theme and page tooling.");
   const agentProject = agent.command("project").description("Manage Suda projects from the CLI.");