synthesisui 0.1.12 → 0.1.14

package/dist/commands/add.js

@@ -53,6 +53,17 @@ export async function add(slug, opts) {
         fetchedAt: new Date().toISOString(),
     };
     await writeFile(rootLockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+    // 5b. governance rules (personal DS) → rules.md at the slug root (stable path,
+    //     highest authority; the GUIDE tells the agent to read it first)
+    const rules = payload.rules ?? [];
+    if (rules.length > 0) {
+        const body = `# ${payload.name} — Rules\n\n` +
+            "> Accumulated rules for this design system. **Max authority — follow these first.**\n" +
+            `> Managed by synthesisui (edit in the studio). ${rules.length} rule(s).\n\n${rules
+                .map((r) => `- ${r}`)
+                .join("\n")}\n`;
+        await writeFile(join(slugDir, "rules.md"), body, "utf8");
+    }
     // 6. discovery by the agent
     const claudeMd = await syncClaudeMd(projectRoot);
     // outcome line
@@ -75,6 +86,9 @@ export async function add(slug, opts) {
         "GUIDE.md",
     ];
     console.log(`  v${v}/: ${files.join(", ")}`);
+    if (rules.length > 0) {
+        console.log(`  rules.md → ${rules.length} rule(s) (read these first)`);
+    }
     console.log(`  CLAUDE.md ${claudeMd.created ? "created" : "updated"} (${claudeMd.count} system(s) installed)`);
     console.log("");
     console.log("Next steps:");

package/dist/commands/init.js

@@ -0,0 +1,21 @@
+import { DEFAULT_CONFIG, writeProjectConfig } from "../config.js";
+/**
+ * Writes `_synthesisui/config.json` — where `synthesisui page` materializes
+ * pages and which framework to target. Committable; safe to re-run.
+ */
+export async function init(opts) {
+    const root = opts.dir ?? process.cwd();
+    const target = opts.target === "general" ? "general" : "next";
+    const config = {
+        target,
+        pagesDir: opts.pagesDir ?? (target === "next" ? "app" : DEFAULT_CONFIG.pagesDir),
+    };
+    await writeProjectConfig(root, config);
+    console.log("✓ wrote _synthesisui/config.json");
+    console.log(`  target:   ${config.target}`);
+    console.log(`  pagesDir: ${config.pagesDir}`);
+    console.log("");
+    console.log("Next steps:");
+    console.log("  • synthesisui add <slug>            bring a design system in");
+    console.log("  • synthesisui page <slug> <template>  materialize a full page");
+}

package/dist/commands/page.js

@@ -0,0 +1,32 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { readProjectConfig, resolveRegistry } from "../config.js";
+import { fetchPage } from "../registry.js";
+/**
+ * Materializes a whole page from a DS template into the project (hybrid
+ * codegen-first): the server codegens a deterministic file, we write it, and
+ * the agent refines it in place. The page uses the DS's `.ds-*` classes +
+ * inline token vars, so it re-vests once `tokens.css` is imported.
+ */
+export async function page(slug, template, opts) {
+    const base = resolveRegistry(opts.registry);
+    const root = opts.dir ?? process.cwd();
+    const config = await readProjectConfig(root);
+    const target = opts.target === "general" || opts.target === "next"
+        ? opts.target
+        : config.target;
+    console.log(`→ generating "${template}" from "${slug}" (${target}) …`);
+    const generated = await fetchPage(base, slug, template, target, opts.version);
+    // --out wins; otherwise <pagesDir>/<filename> (e.g. app/dashboard.tsx).
+    const relPath = opts.out ?? join(config.pagesDir, generated.filename);
+    const outPath = join(root, relPath);
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, generated.code, "utf8");
+    console.log(`✓ wrote ${relPath}  (${slug} v${generated.version})`);
+    console.log("");
+    console.log("Next steps:");
+    console.log(`  • ensure the DS is installed: synthesisui add ${slug} (provides tokens.css)`);
+    console.log(`  • @import "_synthesisui/ds/${slug}/tokens.css" in your global CSS`);
+    console.log("  • refine the file: wire real data, split into components, swap placeholders");
+    console.log(`  • keep the data-ds="${slug}" wrapper and the ds-* classes (stays on-system)`);
+}

package/dist/config.js

@@ -35,3 +35,31 @@ export async function writeToken(token, registry) {
         mode: 0o600,
     });
 }
+/** Project-level config (committed): `<root>/_synthesisui/config.json`. */
+export const DEFAULT_CONFIG = {
+    target: "next",
+    pagesDir: "app",
+};
+const projectConfigPath = (root) => join(root, "_synthesisui", "config.json");
+/** Reads the project config, falling back to defaults when absent/invalid. */
+export async function readProjectConfig(root) {
+    try {
+        const raw = await readFile(projectConfigPath(root), "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            target: parsed.target === "general" ? "general" : "next",
+            pagesDir: typeof parsed.pagesDir === "string" && parsed.pagesDir
+                ? parsed.pagesDir
+                : DEFAULT_CONFIG.pagesDir,
+        };
+    }
+    catch {
+        return DEFAULT_CONFIG;
+    }
+}
+/** Writes the project config (committable, plain JSON). */
+export async function writeProjectConfig(root, config) {
+    const path = projectConfigPath(root);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}

package/dist/guide.js

@@ -100,6 +100,38 @@ its typographic identity. Load them once (any one approach):
     const artifactList = Object.keys(payload.artifacts)
         .map((f) => `\`${f}\``)
         .join(", ");
+    const layoutNames = Object.keys(doc.layouts ?? {});
+    const pagesSection = layoutNames.length > 0
+        ? `
+## Full pages (templates)
+
+This system ships whole-page templates: ${layoutNames.map((n) => `\`${n}\``).join(", ")}.
+
+Materialize one as a real file:
+\`\`\`bash
+synthesisui page ${slug} ${layoutNames[0]}                 # Next .tsx (default)
+synthesisui page ${slug} ${layoutNames[0]} --target general  # plain HTML
+\`\`\`
+It writes a **deterministic scaffold** using this DS's \`.ds-*\` classes + inline token vars. **Refine it
+in place** — wire real data, split into components, swap the chart/icon/media placeholders — but keep the
+\`data-ds="${slug}"\` wrapper and the \`.ds-*\` classes so it stays on-system. Run \`synthesisui init\` once
+to set the target (next/general) and the output folder.
+
+---
+`
+        : "";
+    const hasRules = (payload.rules?.length ?? 0) > 0;
+    const rulesNote = hasRules
+        ? `
+## Rules — highest authority
+
+**Read \`_synthesisui/ds/${slug}/rules.md\` FIRST and obey it above everything else in this guide.**
+It carries this system's accumulated, project-specific rules; on any conflict they win over the
+generic guidance below.
+
+---
+`
+        : "";
     return `# Design System: ${name}
 
 > Generated by \`synthesisui add ${slug}\` (v${version}). **Do not edit by hand** —
@@ -114,7 +146,7 @@ ${meta.sourceUrl ? `**Reinterpretation of:** ${meta.sourceUrl}` : "**Original sy
 ${meta.narrative}
 
 ---
-
+${rulesNote}
 ## How to apply
 
 1. Import the tokens once in your project's global CSS:
@@ -180,7 +212,7 @@ those, not the versioned ones. The pinned files for this version — ${artifactL
 \`_synthesisui/ds/${slug}/v${version}/\`.
 
 ---
-
+${pagesSection}
 ## Building with the system
 
 **This system is for building real product UI** — pages, layouts, dashboards, whole flows.

package/dist/index.js

@@ -2,17 +2,21 @@
 import { add } from "./commands/add.js";
 import { advise } from "./commands/advise.js";
 import { generate } from "./commands/generate.js";
+import { init } from "./commands/init.js";
 import { list } from "./commands/list.js";
 import { login } from "./commands/login.js";
+import { page } from "./commands/page.js";
 import { RegistryError } from "./registry.js";
 const HELP = `synthesisui — bring SynthesisUI design systems into your project
 
 Usage:
-  synthesisui login [options]          connect the CLI to your account (device-flow)
-  synthesisui list [options]           list the published design systems
-  synthesisui add <slug> [options]     materialize a DS into _synthesisui/ds/<slug>/
-  synthesisui advise "<value prop>"    engagement-pattern proposals for this project (login required)
-  synthesisui generate "<desc>"        generate a token-only component recipe for your DS (login required)
+  synthesisui login [options]              connect the CLI to your account (device-flow)
+  synthesisui init [options]               write _synthesisui/config.json (target + pages dir)
+  synthesisui list [options]               list the published design systems
+  synthesisui add <slug> [options]         materialize a DS into _synthesisui/ds/<slug>/
+  synthesisui page <slug> <template>       materialize a whole page from a DS template
+  synthesisui advise "<value prop>"        engagement-pattern proposals for this project (login required)
+  synthesisui generate "<desc>"            generate a token-only component recipe for your DS (login required)
 
 Options:
   --registry <url>   registry URL (or env SYNTHESISUI_REGISTRY_URL)
@@ -20,14 +24,18 @@ Options:
   --version <n>      install a specific version (default: latest)
   --ds <slug>        target design system for generate (default: the installed one)
   --name <name>      preferred component name for generate
+  --target <t>       page/init target: next | general (default: next)
+  --out <path>       output path for the generated page (default: <pagesDir>/<file>)
   -h, --help         this help
 
 Examples:
   synthesisui login
+  synthesisui init --target next
   synthesisui list
   synthesisui add halogen
   synthesisui add halogen --version 3
-  synthesisui add halogen --registry http://localhost:3737
+  synthesisui page halogen dashboard-sidebar
+  synthesisui page halogen landing --out app/page.tsx
   synthesisui advise "habit-building app for tracking personal finances"
   synthesisui generate "an upgrade banner with a title, message and a primary CTA"
 `;
@@ -92,6 +100,33 @@ async function main() {
         case "login":
             await login({ registry });
             break;
+        case "init": {
+            const target = typeof flags.target === "string" ? flags.target : undefined;
+            await init({ dir, target });
+            break;
+        }
+        case "page": {
+            const slug = args[0];
+            const template = args[1];
+            if (!slug || !template) {
+                console.error("error: provide slug and template — `synthesisui page <slug> <template>`");
+                process.exitCode = 1;
+                return;
+            }
+            let version;
+            if (typeof flags.version === "string") {
+                version = Number.parseInt(flags.version.replace(/^v/i, ""), 10);
+                if (!Number.isInteger(version) || version < 1) {
+                    console.error(`error: invalid --version "${flags.version}" — use an integer ≥ 1`);
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+            const target = typeof flags.target === "string" ? flags.target : undefined;
+            const out = typeof flags.out === "string" ? flags.out : undefined;
+            await page(slug, template, { registry, dir, out, target, version });
+            break;
+        }
         case "advise": {
             const valueProp = args.join(" ").trim();
             if (!valueProp) {

package/dist/registry.js

@@ -42,6 +42,27 @@ export async function fetchDesignSystem(base, slug, version) {
     }
     return (await res.json());
 }
+/**
+ * Fetches a whole page generated from a DS template (`?page=&target=`). The
+ * server codegens it from `document.layouts[<template>]`; the CLI just writes it.
+ */
+export async function fetchPage(base, slug, template, target, version) {
+    const url = new URL(`${base}/api/registry/ds/${encodeURIComponent(slug)}`);
+    url.searchParams.set("page", template);
+    url.searchParams.set("target", target);
+    if (version != null)
+        url.searchParams.set("version", String(version));
+    const res = await request(url.toString());
+    if (res.status === 404) {
+        const body = (await res.json().catch(() => ({})));
+        throw new RegistryError(body.message ??
+            `No template "${template}" in "${slug}". Run \`synthesisui list\` and check the DS templates.`);
+    }
+    if (!res.ok) {
+        throw new RegistryError(`Registry responded ${res.status} while generating "${template}".`);
+    }
+    return (await res.json());
+}
 /**
  * Calls the hosted advisor (`POST /api/ai/advisor`). Gated + metered server-side:
  * 401 = not logged in, 429 = daily quota reached. Sends the Bearer token if present.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Traz design systems do SynthesisUI para qualquer projeto (materializa em _local/ds/).",
   "type": "module",
   "bin": {