synthesisui 0.4.10 → 0.4.12

package/README.md

@@ -1,48 +1,67 @@
 # synthesisui
 
-CLI to bring design systems published on [SynthesisUI](https://www.synthesisui.com)
-into any project. It materializes the system into `_synthesisui/ds/<slug>/` and injects
-a managed block into the root `CLAUDE.md`, so Claude Code builds components following the
-design system.
+The CLI for [SynthesisUI](https://www.synthesisui.com) - where your design
+system is born, scored against the classic design canon, and delivered to any
+coding agent.
 
-## Usage
+Your AI writes UI. This gives it a design system to write it in: tokens, typed
+components, whole pages and a `CLAUDE.md` manifest that Claude Code, Cursor,
+Copilot or any coding agent reads before writing a single line.
 
-Without installing anything:
+> This repository is a **read-only mirror** of `packages/cli` in the SynthesisUI
+> monorepo, published so you can audit exactly what runs in your repo.
+> Issues and bug reports are very welcome here; pull requests can't land on a
+> mirror - open an issue instead.
+
+## Quickstart
 
 ```bash
-npx synthesisui login        # connect the CLI to your account (device-flow in the browser)
-npx synthesisui list         # list the available design systems
-npx synthesisui add <slug>   # bring a DS into _synthesisui/ds/<slug>/
+npx synthesisui@latest init --styles tailwind --ds <slug>
 ```
 
-Or install globally:
+Pick any system from the [gallery](https://www.synthesisui.com) - or create
+your own in two minutes.
 
-```bash
-npm install -g synthesisui
-synthesisui add halogen
-```
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `init` | One-shot setup: materialize a system + wire your project for it |
+| `login` | Connect to your account (device-flow in the browser) |
+| `list` | List the design systems available to you |
+| `add <slug>` | Materialize a system into `_synthesisui/ds/<slug>/` |
+| `use <slug>` | Generate the agent prompt to apply the system to your app |
+| `component <slug> <name>` | Bring one typed component into your components dir |
+| `template <slug> <name>` | Generate a whole page (landing, dashboard, onboarding…) |
+| `generate` | Generate a page from a saved guide structure |
+| `advise` | Grounded design advice for this repo, from your system's rules |
+| `refit <file>` | Send an app component back into your design system |
+| `upgrade <slug>` | Diff your `.lock` against the latest version and migrate |
+| `clean` | Remove materialized files and the managed CLAUDE.md block |
 
-### What `add` materializes
+## What `add` materializes
 
-In `_synthesisui/ds/<slug>/`:
+Inside `_synthesisui/ds/<slug>/`:
 
-- `design-system.json` — the canonical source of truth of the design system
-- `tokens.css` — CSS custom properties scoped by `data-ds`
-- `theme.css` — optional Tailwind v4 `@theme` adapter (use `bg-primary`, `p-md`, … backed by the tokens)
-- `GUIDE.md` — instructions for the agent (semantic roles, mood, recipes, how to add components)
-- `.lock` — pinned slug + version (reproducible)
+- `design-system.json` - the canonical source of truth
+- `tokens.css` - CSS custom properties scoped by `data-ds`
+- `theme.css` - optional Tailwind v4 `@theme` adapter (`bg-primary`, `p-md`, …)
+- `GUIDE.md` - agent instructions: semantic roles, mood, recipes
+- `rules.md` - the governance your agent must follow
+- `.lock` - pinned slug + version (reproducible upgrades)
 
-And it injects an idempotent `<!-- synthesisui:start/end -->` block into the root `CLAUDE.md`,
-reflecting every installed DS.
+Plus an idempotent `<!-- synthesisui:start/end -->` block in your root
+`CLAUDE.md` listing every installed system and its component manifest.
 
 ## Authentication
 
-`synthesisui login` uses device-flow (RFC 8628): it opens the browser, you confirm a code,
-and the token is saved to `~/.synthesisui/credentials.json` (per machine). Logout = delete that file.
+`synthesisui login` uses device-flow (RFC 8628): it opens the browser, you
+confirm a code, and the token lands in `~/.synthesisui/credentials.json`
+(per machine, chmod 600). Logout = delete that file.
 
 ## Registry
 
-By default it points to `https://www.synthesisui.com`. Override it with:
+Defaults to `https://www.synthesisui.com`. Override with:
 
 ```bash
 synthesisui list --registry http://localhost:3000

package/dist/commands/clean.js

@@ -90,7 +90,9 @@ export async function clean(opts) {
     // 4. Default README.
     const readmePath = join(root, "README.md");
     const readmeSrc = await readIf(readmePath);
-    if (readmeSrc && /create-next-app/.test(readmeSrc) && /Getting Started/.test(readmeSrc)) {
+    if (readmeSrc &&
+        /create-next-app/.test(readmeSrc) &&
+        /Getting Started/.test(readmeSrc)) {
         actions.push({
             verb: "remove",
             path: "README.md",

package/dist/commands/template.js

@@ -16,14 +16,15 @@ export async function template(slug, name, opts) {
     const target = opts.target === "general" || opts.target === "next"
         ? opts.target
         : config.target;
-    console.log(`→ generating "${name}" from "${slug}" (${target}) …`);
-    const generated = await fetchTemplate(base, slug, name, target, opts.version);
+    const asName = opts.as && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(opts.as) ? opts.as : undefined;
+    console.log(`→ generating "${name}"${asName ? ` as "${asName}"` : ""} from "${slug}" (${target}) …`);
+    const generated = await fetchTemplate(base, slug, name, target, opts.version, asName);
     // --out targets the page (1st file); sibling files (e.g. the CSS) land in the
     // same directory. Without --out, everything goes under templates/<name>/ -
     // a loose landing.tsx at the app/ root read as a route without being one,
     // and a second template turned the app dir into soup.
     const [pageFile, ...siblings] = generated.files;
-    const defaultDir = join("templates", name);
+    const defaultDir = join("templates", asName ?? name);
     const pageRel = opts.out ?? join(defaultDir, pageFile.filename);
     const pageDir = dirname(join(root, pageRel));
     await mkdir(pageDir, { recursive: true });

package/dist/index.js

@@ -21,6 +21,7 @@ Usage - deterministic, FREE:
   synthesisui add <slug> [options]         materialize a DS into _synthesisui/ds/<slug>/
   synthesisui component <slug> <name>      bring one EXISTING component in as YOUR <Pascal>.tsx
   synthesisui template <slug> <name>       materialize a whole page from a DS template
+                                           (--as landing-home names the output - multi-page safe)
   synthesisui upgrade <slug>               update an installed DS + regenerate your components + migration brief
   synthesisui use <slug> "<intent>"        print a ready-to-paste agent prompt to build/modify on-system
   synthesisui clean [--force]              strip create-next-app boilerplate (dry run without --force)
@@ -178,7 +179,15 @@ async function main() {
             }
             const target = typeof flags.target === "string" ? flags.target : undefined;
             const out = typeof flags.out === "string" ? flags.out : undefined;
-            await template(slug, name, { registry, dir, out, target, version });
+            const as_ = typeof flags.as === "string" ? flags.as : undefined;
+            await template(slug, name, {
+                registry,
+                dir,
+                out,
+                target,
+                version,
+                as: as_,
+            });
             break;
         }
         case "component": {

package/dist/registry.js

@@ -46,12 +46,14 @@ export async function fetchDesignSystem(base, slug, version) {
  * Fetches a whole page generated from a DS template (`?template=&target=`). The
  * server codegens it from `document.layouts[<template>]`; the CLI just writes it.
  */
-export async function fetchTemplate(base, slug, template, target, version) {
+export async function fetchTemplate(base, slug, template, target, version, as_) {
     const url = new URL(`${base}/api/registry/ds/${encodeURIComponent(slug)}`);
     url.searchParams.set("template", template);
     url.searchParams.set("target", target);
     if (version != null)
         url.searchParams.set("version", String(version));
+    if (as_)
+        url.searchParams.set("as", as_);
     const res = await request(url.toString());
     if (res.status === 404) {
         const body = (await res.json().catch(() => ({})));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "synthesisui",
-  "version": "0.4.10",
-  "description": "Traz design systems do SynthesisUI para qualquer projeto (materializa em _local/ds/).",
+  "version": "0.4.12",
+  "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {
     "synthesisui": "dist/index.js"
@@ -19,11 +19,10 @@
   "homepage": "https://www.synthesisui.com",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/SynthesisUI/synthesisui-hub.git",
-    "directory": "packages/cli"
+    "url": "git+https://github.com/SynthesisUI/cli.git"
   },
   "bugs": {
-    "url": "https://github.com/SynthesisUI/synthesisui-hub/issues"
+    "url": "https://github.com/SynthesisUI/cli/issues"
   },
   "author": "SynthesisUI",
   "engines": {