@once-ui-system/core 1.7.12 → 1.7.13

package/scripts/init-agent.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * Scaffold agent harness pointers in a consumer project.
+ * Usage: npx once-ui-init-agent [--force] [--dry-run]
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const PACKAGE_ROOT = path.join(__dirname, "..");
+const MARKER_START = "<!-- once-ui-agent-harness:start -->";
+const MARKER_END = "<!-- once-ui-agent-harness:end -->";
+
+const PROJECT_AGENTS_SECTION = `${MARKER_START}
+## Once UI codegen harness
+
+Before generating Once UI code, load the harness from your installed package (not full doc pages):
+
+1. Read \`node_modules/@once-ui-system/core/ai/manifest.json\`
+2. Load bootstrap: \`ai/rules.compact.md\` + \`ai/catalog.json\`
+3. Match intent via \`ai/tasks/index.json\` → fetch task bundle + component slices
+4. Validate: \`npx once-ui-validate-ai-code path/to/file.tsx\`
+
+npm exports: \`@once-ui-system/core/ai/manifest.json\`
+
+Remote fallback: https://docs.once-ui.com/ai/manifest.json
+${MARKER_END}
+`;
+
+function parseArgs(argv) {
+  return {
+    force: argv.includes("--force"),
+    dryRun: argv.includes("--dry-run"),
+  };
+}
+
+function findProjectRoot(startDir = process.cwd()) {
+  let dir = path.resolve(startDir);
+
+  while (true) {
+    const pkgPath = path.join(dir, "package.json");
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        if (pkg.name !== "@once-ui-system/core") {
+          return dir;
+        }
+      } catch {
+        // keep walking
+      }
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+
+  return path.resolve(startDir);
+}
+
+function upsertMarkedSection(existing, section, force) {
+  if (existing.includes(MARKER_START) && existing.includes(MARKER_END)) {
+    if (!force) {
+      return { content: existing, changed: false, reason: "AGENTS.md already contains Once UI harness section" };
+    }
+
+    const start = existing.indexOf(MARKER_START);
+    const end = existing.indexOf(MARKER_END) + MARKER_END.length;
+    return {
+      content: `${existing.slice(0, start)}${section}${existing.slice(end)}`,
+      changed: true,
+    };
+  }
+
+  if (existing.trim().length === 0) {
+    return {
+      content: `# AGENTS.md\n\n${section}\n`,
+      changed: true,
+    };
+  }
+
+  return {
+    content: `${existing.trimEnd()}\n\n${section}\n`,
+    changed: true,
+  };
+}
+
+function writeFile(root, relativePath, content, { dryRun, force }) {
+  const target = path.join(root, relativePath);
+  const exists = fs.existsSync(target);
+
+  if (exists && !force) {
+    const current = fs.readFileSync(target, "utf8");
+    if (current === content) {
+      return { path: target, status: "unchanged" };
+    }
+    return { path: target, status: "skipped", reason: "already exists (use --force)" };
+  }
+
+  if (dryRun) {
+    return { path: target, status: "would-write" };
+  }
+
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, content, "utf8");
+  return { path: target, status: exists ? "updated" : "created" };
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const projectRoot = findProjectRoot();
+  const cursorRuleTemplate = fs.readFileSync(
+    path.join(PACKAGE_ROOT, "agent", "once-ui-codegen.mdc"),
+    "utf8",
+  );
+
+  const agentsPath = path.join(projectRoot, "AGENTS.md");
+  let agentsContent = "";
+  if (fs.existsSync(agentsPath)) {
+    agentsContent = fs.readFileSync(agentsPath, "utf8");
+  }
+
+  const agentsResult = upsertMarkedSection(agentsContent, PROJECT_AGENTS_SECTION, options.force);
+  const results = [];
+
+  if (agentsResult.changed) {
+    results.push(
+      writeFile(projectRoot, "AGENTS.md", agentsResult.content, options),
+    );
+  } else {
+    results.push({
+      path: agentsPath,
+      status: "unchanged",
+      reason: agentsResult.reason,
+    });
+  }
+
+  results.push(
+    writeFile(projectRoot, ".cursor/rules/once-ui-codegen.mdc", cursorRuleTemplate, options),
+  );
+
+  console.log(`Once UI agent harness setup (${options.dryRun ? "dry run" : "applied"})`);
+  console.log(`Project root: ${projectRoot}`);
+  for (const result of results) {
+    const suffix = result.reason ? ` (${result.reason})` : "";
+    console.log(`- ${result.status}: ${path.relative(projectRoot, result.path)}${suffix}`);
+  }
+
+  if (!options.dryRun) {
+    console.log("\nNext: open a .tsx file and ask your agent to build Once UI — it should load the harness from node_modules/@once-ui-system/core/ai/");
+  }
+}
+
+main();

package/scripts/validate-ai-code.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * Mechanical Once UI codegen validator.
+ * Usage: node scripts/validate-ai-code.js <file.tsx> [--fix]
+ *        node scripts/validate-ai-code.js --stdin < file.tsx
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.join(__dirname, "..");
+const SPEC_PATH = path.join(ROOT, "ai", "spec.json");
+
+function loadSpec() {
+  if (!fs.existsSync(SPEC_PATH)) return { components: {}, tokens: {} };
+  return JSON.parse(fs.readFileSync(SPEC_PATH, "utf8"));
+}
+
+function parseIconNames(spec) {
+  const raw = spec.tokens?.IconName || "";
+  const matches = raw.match(/"([^"]+)"/g) || [];
+  return new Set(matches.map((m) => m.slice(1, -1)));
+}
+
+function readInput(argv) {
+  const fileArg = argv.find((a) => !a.startsWith("-"));
+  if (argv.includes("--stdin")) {
+    return { source: fs.readFileSync(0, "utf8"), file: "<stdin>" };
+  }
+  if (!fileArg) {
+    console.error("Usage: validate-ai-code.js <file.tsx> [--fix] | --stdin");
+    process.exit(2);
+  }
+  return { source: fs.readFileSync(fileArg, "utf8"), file: fileArg };
+}
+
+function validate(source, spec, iconNames) {
+  const issues = [];
+
+  const add = (rule, message, fix) => issues.push({ rule, message, fix });
+
+  if (/fillWidth[\s\S]{0,80}fillHeight|<Flex[^>]*direction="column"|<Flex[^>]*direction="row"/.test(source)) {
+    if (/fillWidth[\s\S]{0,120}fillHeight/.test(source)) {
+      add("layout.shorthands", "Use fill instead of fillWidth + fillHeight", "fill");
+    }
+    if (/<Flex[^>]*direction="column"/.test(source)) {
+      add("layout.shorthands", "Use Column instead of Flex direction=\"column\"", "Column");
+    }
+    if (/<Flex[^>]*direction="row"/.test(source)) {
+      add("layout.shorthands", "Use Row instead of Flex direction=\"row\"", "Row");
+    }
+  }
+
+  if (/horizontal="center"[\s\S]{0,80}vertical="center"/.test(source)) {
+    add("layout.shorthands", "Use center instead of horizontal=\"center\" vertical=\"center\"", "center");
+  }
+
+  if (/position="relative"/.test(source)) {
+    add("layout.defaults", "position=\"relative\" is the default — omit it");
+  }
+
+  if (/<Button[^>]*variant="primary"/.test(source)) {
+    add("layout.defaults", "variant=\"primary\" is the Button default — omit it");
+  }
+
+  if (/#[0-9a-fA-F]{3,8}\b|rgb\s*\(|rgba\s*\(/.test(source)) {
+    add("color.tokens", "Use semantic color tokens, not hex/rgb");
+  }
+
+  if (/<img[\s>/]|<a[\s>/]|<button[\s>/]/.test(source)) {
+    add("components.primitives", "Use Once UI components (Media, SmartLink, Button) instead of raw HTML");
+  }
+
+  const cardMatches = source.match(/<Card\b[^>]*>/g) || [];
+  for (const tag of cardMatches) {
+    if (!/\b(href|onClick)=/.test(tag)) {
+      add("Card.interactive", "Card without href/onClick — use Column + surface recipe for static panels");
+      break;
+    }
+  }
+
+  const iconPropRe = /(?:prefixIcon|suffixIcon|name)=["']([^"']+)["']/g;
+  let iconMatch;
+  while ((iconMatch = iconPropRe.exec(source)) !== null) {
+    const name = iconMatch[1];
+    if (iconNames.size && !iconNames.has(name)) {
+      add("Icon.names", `Unknown icon name "${name}" — use IconName from spec.json`);
+    }
+  }
+
+  if (/delay=\{[^}]*\*\s*80/.test(source)) {
+    add("RevealFx.delay", "RevealFx delay is in seconds — use index * 0.1, not index * 80");
+  }
+
+  if (/<Fade[^>]*>[\s\S]*<(Column|Row)[^>]*overflowY/.test(source)) {
+    add("Fade.edge", "Fade wrapping scroll content — use as absolute edge strip instead");
+  }
+
+  if (/style=\{\{[^}]*(gap|padding|margin|color|background):/.test(source)) {
+    add("spacing.tokens", "Use token props (gap, padding, background) instead of style={{}}");
+  }
+
+  return issues;
+}
+
+function applyFixes(source, issues) {
+  let out = source;
+  for (const issue of issues) {
+    if (issue.fix === "fill") {
+      out = out.replace(/\bfillWidth\b\s*\n?\s*\bfillHeight\b/g, "fill");
+    }
+    if (issue.fix === "center") {
+      out = out.replace(/\bhorizontal="center"\s*\n?\s*vertical="center"/g, "center");
+    }
+  }
+  return out;
+}
+
+function main() {
+  const spec = loadSpec();
+  const iconNames = parseIconNames(spec);
+  const fix = process.argv.includes("--fix");
+  const { source, file } = readInput(process.argv.slice(2));
+
+  const issues = validate(source, spec, iconNames);
+
+  if (issues.length === 0) {
+    console.log(`✓ ${file}: no mechanical issues`);
+    process.exit(0);
+  }
+
+  console.log(`✗ ${file}: ${issues.length} issue(s)`);
+  for (const issue of issues) {
+    console.log(`  [${issue.rule}] ${issue.message}`);
+  }
+
+  if (fix) {
+    const fixed = applyFixes(source, issues);
+    if (fixed !== source && !process.argv.includes("--stdin")) {
+      const fileArg = process.argv.find((a) => a.endsWith(".tsx") || a.endsWith(".jsx"));
+      fs.writeFileSync(fileArg, fixed);
+      console.log(`Applied auto-fixes to ${fileArg}`);
+    }
+  }
+
+  process.exit(1);
+}
+
+main();