synthesisui 0.1.18 → 0.1.19

package/dist/commands/use.js

@@ -0,0 +1,95 @@
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { readProjectConfig } from "../config.js";
+async function readRootLock(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `synthesisui use <slug> "<intent>"` - the platform↔app bridge (INS-10).
+ *
+ * Reads only LOCAL state (the installed `.lock`, the project `config.json`, and
+ * which guidance files exist) and prints a ready-to-paste prompt for your coding
+ * agent (Claude Code, Cursor, …) describing the task **on-system**: which files
+ * to read first, the scope attribute, the styling contract, and where files go.
+ * Works for both *bringing in* new UI ("a pricing section with 3 tiers") and
+ * *modifying* existing UI ("make the card shadow softer in components/Card.tsx").
+ *
+ * No network: the DS must already be installed (`synthesisui add <slug>`).
+ */
+export async function use(slug, intent, opts) {
+    const root = opts.dir ?? process.cwd();
+    const slugDir = join(root, "_synthesisui", "ds", slug);
+    const lock = await readRootLock(join(slugDir, ".lock"));
+    if (!lock) {
+        console.error(`error: "${slug}" is not installed in this project.\n` +
+            `  run \`synthesisui add ${slug}\` first (brings tokens.css + GUIDE.md), then retry.`);
+        process.exitCode = 1;
+        return;
+    }
+    const config = await readProjectConfig(root);
+    const { version, name } = lock;
+    const base = `_synthesisui/ds/${slug}`;
+    // Highest-authority guidance first; only list files that actually exist.
+    const hasRules = await exists(join(slugDir, "rules.md"));
+    const hasPhilosophy = await exists(join(slugDir, "philosophy.md"));
+    const readFirst = [
+        hasRules
+            ? `- ${base}/rules.md — project rules for this system; obey them above everything else`
+            : "",
+        hasPhilosophy
+            ? `- ${base}/philosophy.md — the mission, voice and principles; let it shape every screen`
+            : "",
+        `- ${base}/v${version}/GUIDE.md — how to apply the system, the recipes and the token vocabulary`,
+    ].filter(Boolean);
+    // The styling contract differs by target: Next projects in this product use
+    // Tailwind v4 backed by the DS; the "general" target is framework-agnostic CSS.
+    const stylingRule = config.target === "general"
+        ? `- Style with the design system only: reuse the \`.ds-*\` recipe classes and the ` +
+            `\`var(--ds-*)\` custom properties. Never use raw hex/px outside the system's scale.`
+        : `- Style with the design system only: reuse the \`.ds-*\` recipe classes and the ` +
+            `DS-backed Tailwind utilities (\`bg-primary\`, \`text-foreground\`, \`p-md\`, \`rounded-lg\`, ` +
+            `\`font-display\`…). Never use raw hex/px outside the system's scale.`;
+    const task = intent.trim() || "build the UI I describe next";
+    const prompt = [
+        `Use the "${name}" design system (slug: ${slug}, v${version}) to: ${task}`,
+        "",
+        "Read these files in the project first (highest authority first):",
+        ...readFirst,
+        "",
+        "Follow this contract:",
+        `- Scope the markup with \`data-ds="${slug}"\` (or rely on it at the app root).`,
+        stylingRule,
+        `- Target framework: ${config.target}. Put new components in \`${config.componentsDir}/\` ` +
+            `and pages in \`${config.pagesDir}/\`.`,
+        config.target === "next"
+            ? '- Make sure `tokens.css` + `theme.css` are imported in the global CSS (see the GUIDE\'s "How to apply").'
+            : '- Make sure `tokens.css` is imported in the global CSS (see the GUIDE\'s "How to apply").',
+        "- Wire the behavior yourself (open/close, focus, routing) - the system ships the looks, not the JS.",
+        "",
+        "Deliver senior-level, production-quality code: clean structure, accessible (ARIA + keyboard), and responsive.",
+    ].join("\n");
+    // Framing lines go to stderr so `synthesisui use … | pbcopy` copies only the
+    // prompt itself (stdout), while the human still sees the guidance.
+    console.error(`✓ ${name} v${version} · target ${config.target}\n`);
+    console.error("Copy the prompt below and paste it to your coding agent:\n");
+    console.error("──────────────────────────────────────────────────────────");
+    console.log(prompt);
+    console.error("──────────────────────────────────────────────────────────");
+    console.error("\nTip: `synthesisui use " +
+        slug +
+        ' "…" | pbcopy` (macOS) copies just the prompt.');
+}

package/dist/index.js

@@ -6,6 +6,7 @@ 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 { use } from "./commands/use.js";
 import { RegistryError } from "./registry.js";
 const HELP = `synthesisui - bring SynthesisUI design systems into your project
 
@@ -15,6 +16,7 @@ Usage:
   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 use <slug> "<intent>"        print a ready-to-paste agent prompt to build/modify on-system
   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)
 
@@ -39,6 +41,8 @@ Examples:
   synthesisui add halogen --version 3
   synthesisui page halogen dashboard-sidebar
   synthesisui page halogen landing --out app/page.tsx
+  synthesisui use halogen "a pricing section with three tiers and a highlighted plan"
+  synthesisui use halogen "make the card shadow softer in components/StatCard.tsx"
   synthesisui advise "habit-building app for tracking personal finances"
   synthesisui generate "an upgrade banner with a title, message and a primary CTA"
 `;
@@ -143,6 +147,17 @@ async function main() {
             await page(slug, template, { registry, dir, out, target, version });
             break;
         }
+        case "use": {
+            const slug = args[0];
+            if (!slug) {
+                console.error('error: provide the slug and your intent - `synthesisui use <slug> "<intent>"`');
+                process.exitCode = 1;
+                return;
+            }
+            const intent = args.slice(1).join(" ").trim();
+            await use(slug, intent, { dir });
+            break;
+        }
         case "advise": {
             const valueProp = args.join(" ").trim();
             if (!valueProp) {

package/package.json

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