@syncline-design/cli 0.0.0-stage → 0.1.0-sandbox.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Istvan Polacsek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,305 @@
-# Temporary Holding Version
+# @syncline-design/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generates a React component library from a Figma export. It needs only Node:
+no nx, no monorepo tooling, and the generated library has no dependency on it.
+
+```bash
+npx @syncline-design/cli generate            # write the generated files
+npx @syncline-design/cli generate --check    # write nothing; exit 1 if they are out of date
+```
+
+Two release channels share this package:
+
+- **`@sandbox`**: `npx @syncline-design/cli@sandbox …` talks to the sandbox bridge by
+  default, so AI enrichment needs no bridge configuration.
+- **`latest`**: the stable release. It has no bridge baked in; enrichment is off
+  until you point it at one (see below).
+
+Until the first stable release only the `sandbox` tag exists.
+
+## What it reads and writes
+
+|        |                                                                                                                                                                       |
+| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Reads  | `.figma/design.json` (required), `.figma/assets.json`, `.figma/annotations.json` and `.figma/design.enriched.json` (optional), `syncline.config.json` (optional)      |
+| Writes | components, stories, vector assets, the theme and its `ThemeProvider`, Storybook docs and wiring (`.storybook/`), and the `tsconfig.json` entry for the theme typings |
+
+Output is formatted with **your own prettier config**, so it matches what your
+commit hooks produce and a re-run shows no formatting churn.
+
+Hand-editable files are written once and never overwritten unless you ask:
+stories (`stories.overwrite`), docs guidelines (`docs.overwriteGuidelines`) and
+a hand-written `.storybook/manager.ts`.
+
+## Options
+
+| Option            |                                                                                                 |
+| ----------------- | ----------------------------------------------------------------------------------------------- |
+| `--config <file>` | Config file (default `syncline.config.json`; every setting has a default, so no file is needed) |
+| `--cwd <dir>`     | Project root (default: the current directory)                                                   |
+| `--check`         | Drift check for CI: nothing is written; exit 1 if the output differs from what is on disk       |
+| `--verbose`       | List every warning instead of a per-phase count                                                 |
+| `--accept <path>` | After a merge conflict you resolved by hand: keep the file and record the new base (repeatable) |
+
+Warnings are design feedback (for example a fill that is not bound to a Figma
+variable), never failures.
+
+## `syncline.config.json`
+
+Every key is optional; this is the full shape with its defaults. The Figma plugin's first sync into a repo with no config adds one (framework, styling, library name and the paths below, for a single-level repo); after that it is yours to edit and syncs never touch it.
+
+```jsonc
+{
+  "framework": "react",
+  "styling": "styled-components",
+  "libraryName": "design-system", // names the docs and the Storybook chrome
+  "inputs": {
+    "design": ".figma/design.json",
+    "enriched": ".figma/design.enriched.json", // absent on disk => raw tier
+    "assets": ".figma/assets.json",
+    "annotations": ".figma/annotations.json", // the designer's intents; absent => none
+  },
+  "paths": {
+    "components": "src/components",
+    "assetsRoot": "src", // the design's `assets/...` paths are relative to it
+    "theme": "src/providers/ThemeProvider",
+    "docs": "src/docs",
+    "storybook": ".storybook", // null: leave Storybook alone
+    "tsconfig": "tsconfig.json", // null: don't add theme.d.ts to `files`
+  },
+  "stories": {
+    "enabled": true,
+    "target": "react-vite", // or "react-native"
+    "typesPackage": null, // override the Storybook types package
+    "groupByPage": false, // title stories "<Figma page>/<Component>"; otherwise "Components/<Component>" (never ungrouped)
+    "overwrite": false,
+  },
+  "tests": {
+    "enabled": false, // a Vitest + Testing Library spec per component; needs vitest, jsdom and @testing-library/react
+    "overwrite": false, // specs are hand-owned: an existing file is kept
+  },
+  "merge": {
+    "enabled": false, // keep hand edits to generated components when the design changes
+    "baseDir": ".figma/base", // the last generated version of each component; commit it
+    "llm": false, // paid: let the bridge resolve what a 3-way merge can't
+    "sendSource": false, // required with llm: the conflicting files' source is sent to the bridge
+  },
+  "theme": {
+    "cssReset": false, // global page state, so opt-in
+    "backgroundToken": "Background/Default/Default",
+    "brand": {
+      "title": "My DS",
+      "image": "src/assets/logo.svg", // inlined as a data URI, up to 100 KB
+      "colorToken": "Brand/60",
+      "surfaceToken": "Brand/Grey",
+    },
+  },
+  "dependencies": {
+    "install": false, // true: add missing react/styled-components/Storybook packages with your package manager
+  },
+  "docs": {
+    "enabled": true,
+    "includeHidden": false, // tokens hidden from publishing in Figma
+    "overwriteGuidelines": false,
+  },
+}
+```
+
+## For AI agents (`agent.enabled`)
+
+Off by default. With `"agent": { "enabled": true, "packageName": "@acme/ds" }` the run also writes what a coding agent needs to use the library without reading its sources:
+
+| File                           | Purpose                                                                                                                                                                                     |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent/llms.txt`               | Index of every component, one line each ([llmstxt.org](https://llmstxt.org) layout)                                                                                                         |
+| `agent/components/<Name>.json` | One component's contract: props (types, options, defaults), what it renders / what renders it, widget behaviour **and what it does not cover**, a compiling example                         |
+| `agent/components.json`        | The same for all components in one file (used by `syncline mcp`)                                                                                                                            |
+| `agent/tokens.json`            | Every token: name, the `theme[...]` expression, value per mode, the designer's note                                                                                                         |
+| `agent/eslint-tokens.mjs`      | ESLint flat-config fragment that flags raw colours in app code                                                                                                                              |
+| `AGENTS.md`                    | The library's rules for an agent. Written once, then yours to edit                                                                                                                          |
+| `src/index.ts`                 | A package entry exporting every component and the theme. Only written while the file is missing, `export {};` or generated by us; a hand-written entry is left alone (a diagnostic says so) |
+
+Options: `agent.dir` (default `agent`), `agent.entry` (`src/index.ts`), `agent.guide` (`AGENTS.md`). Ship `agent/` in the published package so the files travel with the library.
+
+`syncline mcp` serves the same data to an agent over MCP (stdio) with the tools `list_components`, `search_components`, `get_component` and `search_tokens`:
+
+```bash
+claude mcp add design-system -- npx @syncline-design/cli mcp
+```
+
+## Storybook preview (paid)
+
+```bash
+npx @syncline-design/cli preview publish --dir storybook-static
+```
+
+Uploads a built Storybook to the bridge, which hosts it until the pull request
+closes and links it from the sync in the Figma plugin. It needs the same bridge
+and credentials as enrichment, the paid plan, and a `pull_request` run of a PR a
+sync opened. Anything missing is reported and skipped (exit 0); only an unusable
+build directory (no `index.html`, unhostable file names, over the size limits)
+exits 1. The workflow a sync seeds runs it for accounts that have the plan.
+`generate` also writes a minimal `.storybook/main.ts` when the repo has none.
+
+## Push token (for the seeded workflow)
+
+`syncline ci push-token` asks the bridge for a short-lived token that lets the
+generation job push to the sync's pull request as the GitHub App. In Actions it
+masks the token and writes `token`, `name` and `email` to `$GITHUB_OUTPUT`;
+without one (no bridge, no credentials, app not installed) it says why and exits
+0, and the workflow pushes with its own token instead.
+
+## TypeScript and Storybook defaults
+
+- **`tsconfig.json`:** the generated components, ThemeProvider and Storybook decorator
+  use the automatic JSX runtime, so the project needs `"jsx": "react-jsx"`. A
+  repository with no tsconfig gets a minimal one (written once, never overwritten);
+  an existing self-contained one without `jsx` gets a warning instead of an edit.
+  `"paths": { "tsconfig": null }` opts out.
+- **Generated tests** (`tests.enabled`, off by default): `<Component>/<Component>.spec.tsx`,
+  written from what the generated component provably does (renders and its root tag,
+  ref and native props, the suggested aria attributes, bound and toggled text, every
+  variant option, `onClick`/`disabled` on a button root, the input and progressbar
+  behaviour of those archetypes). A case the component's shape can't prove is left
+  out. No model and no network are involved. The file declares its own jsdom
+  environment, so it runs with a plain `vitest run`; it is hand-owned once written.
+- **Stories are always titled** (`<Figma page>/<Name>` with `stories.groupByPage`,
+  else `Components/<Name>`), because Storybook lists ungrouped components above
+  every group. Existing stories files are hand-owned: set `stories.overwrite` once
+  to re-title them.
+- **Branding:** the Storybook chrome (title, logo, colours, docs theme) is generated
+  only with `theme.brand`. The first sync seeds it from what the designer picked in
+  the plugin's Branding group (or, without a choice, a guess from the design):
+  `{ "title": "<library name>", "image": "src/assets/<Logo>/<Logo>.svg",
+"colorToken": "Brand/…", "surfaceToken": "Brand/…" }`. `image` is a logo inlined up
+  to 100 KB; it may be one of the design's own exported assets even on the very
+  first run (the file does not need to exist yet). `colorToken` is the accent,
+  `surfaceToken` the sidebar background; both are colour variable names from
+  `design.json`. Edit them in the config afterwards.
+
+## Keeping hand edits (merge)
+
+By default a generated component is rewritten on every run, so a hand edit to
+it is lost. With `merge.enabled` the CLI records what it generated under
+`merge.baseDir` (`<path>.base` files, **commit them**) and the next run does a
+3-way merge of base, your file and the new output, for component sources only
+(`<Name>/<Name>.tsx`; stories, tests and guidelines are already yours):
+
+- you changed nothing: the new output is written, as before;
+- the generator changed nothing in that file: your file stays;
+- you and the generator changed different places: both changes are merged;
+- the same lines: **a conflict**. Your file stays untouched, the run reports it
+  (`--check` fails), and the base does not move, so it keeps being reported.
+  Resolve it by hand, then run `syncline generate --accept <path>` to record it.
+
+A repo with no recorded base behaves as before (the output wins). Conflict
+markers are never written into a source file.
+
+With `merge.llm` and `merge.sendSource` (both required) the paid bridge may
+resolve a conflict: **the base, your version and the new generated version of
+each conflicting component are sent to the bridge** (at most 5 files of 60,000
+characters per request; nothing else leaves the repo, and the bridge neither
+stores nor logs them). The answer is checked before it is used (it must parse,
+keep every export, and contain no conflict markers); anything else leaves the
+conflict to you. `--check` never calls the bridge, and a run without a bridge,
+credentials or the paid plan just reports the conflicts.
+
+## Dependencies
+
+The generated code imports `react`, `react-dom`, `styled-components` and, with
+stories, Storybook (`storybook`, `@storybook/react-vite`, `@storybook/addon-docs`,
+`vite`) and, with `tests.enabled`, `vitest`, `jsdom` and Testing Library. After writing, `generate` compares that list with the `package.json`
+files from the project up to the repository root and **warns** about what is
+missing. With `"dependencies": { "install": true }` it **installs** them as dev
+dependencies instead, using the package manager the repo's lockfile names (npm
+when there is none, creating a minimal `package.json` and `.gitignore` if the
+repo has neither). A failed install is a warning, never a failure; `--check`
+never installs.
+
+## In CI
+
+Regenerate after a design sync PR merges, and fail pull requests whose
+generated files are stale:
+
+```yaml
+name: synclineon:
+  push:
+    branches: [main]
+    paths: ['.figma/**', 'syncline.config.json']
+  pull_request:
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: npm ci
+      # Pull requests: fail when the committed output is out of date.
+      - if: github.event_name == 'pull_request'
+        run: npx @syncline-design/cli generate --check
+      # Main: regenerate and commit the result.
+      - if: github.event_name == 'push'
+        run: |
+          npx @syncline-design/cli generate
+          git config user.name "syncline[bot]"
+          git config user.email "syncline[bot]@users.noreply.github.com"
+          git add -A
+          git diff --cached --quiet || git commit -m "chore: regenerate from Figma" && git push
+```
+
+## AI enrichment (paid)
+
+Enrichment gives components semantic HTML tags, ARIA attributes and JSDoc. It
+runs on the hosted bridge, so it needs a bridge URL and credentials, and the
+GitHub account that owns the repository needs the paid plan with the bridge's
+GitHub App installed on the repository. Without any of that the CLI generates
+the raw tier and says why; **enrichment never makes a run fail**.
+
+```yaml
+permissions:
+  contents: write
+  id-token: write # lets the job request a GitHub OIDC token for the bridge
+```
+
+|             |                                                                                                                                                           |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Bridge URL  | `SYNCLINE_URL`, then `enrich.bridgeUrl` in the config, then the build's own default (the sandbox build defaults to the sandbox bridge; `latest` has none) |
+| Credentials | GitHub Actions' OIDC token (needs `id-token: write`), or `SYNCLINE_TOKEN` for local runs and other CI systems                                             |
+
+How a run behaves:
+
+- The result is written to `.figma/design.enriched.json`, which is also the
+  cache: a component is only sent again when its facts or the bridge's prompt
+  version change. Commit the file, so the next run (and `--check`) reuses it.
+- A component that fails is retried once, then left on the raw tier and retried
+  next run; everything that succeeded is kept. If the daily allowance runs out
+  mid-run, the rest are left for the next day.
+- `--check` never calls the bridge, so a drift check is free and repeatable.
+- The bridge only ever receives small per-component summaries, never
+  `design.json`.
+
+## Annotation overlay
+
+`.figma/annotations.json` holds the same annotation lines a Figma component
+description can carry (`@select`, `@input search`, `@continuous Progress 0..100`,
+see the generated _Figma annotations_ guideline), keyed by the component's Figma
+key, plus page entries (`@iconset` / `@iconset off`) for icon-set merging. The
+plugin's review step writes it into the sync PR so the Figma file stays
+untouched; you can also edit it by hand.
+
+```json
+{
+  "version": 1,
+  "components": { "<component key>": "@select" },
+  "pages": { "Icons": "@iconset" }
+}
+```
+
+A line already in the component's Figma description wins. Entries that match no
+component, or lines the generator does not read, are reported (`--verbose`) and
+skipped; a malformed file stops the run instead of being ignored.

package/THIRD-PARTY-NOTICES.txt

@@ -0,0 +1,95 @@
+THIRD-PARTY NOTICES
+
+This package bundles the third-party software listed below. Their licences
+require the following notices to accompany copies of it.
+
+------------------------------------------------------------------------------
+
+fflate@0.8.3 (MIT)
+https://github.com/101arrowz/fflate
+
+MIT License
+
+Copyright (c) 2026 Arjun Barrett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+------------------------------------------------------------------------------
+
+node-diff3@3.2.1 (MIT)
+https://github.com/bhousel/node-diff3
+
+### The MIT License (MIT)
+
+diff function extracted from Project Synchrotron.
+
+For more detail please visit:
+- https://leastfixedpoint.com/tonyg/kcbbs/projects/synchrotron.html
+- https://github.com/tonyg/synchrotron
+
+Copyright (c) 2006, 2008 Tony Garnock-Jones &lt;tonyg@lshift.net&gt;<br/>
+Copyright (c) 2006, 2008 LShift Ltd. &lt;query@lshift.net&gt;<br/>
+Copyright (c) 2019-2026 Bryan Housel &lt;bhousel@gmail.com&gt;<br/>
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation files
+(the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software,
+and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+------------------------------------------------------------------------------
+
+zod@4.6.5 (MIT)
+https://github.com/colinhacks/zod
+
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { r as e } from "./run-rzkK5v61.js";
+//#region src/bin.ts
+e(process.argv.slice(2), {
+	out: (e) => process.stdout.write(e),
+	err: (e) => process.stderr.write(e)
+}).then((e) => {
+	process.exitCode = e;
+});
+//#endregion

package/index.js

@@ -0,0 +1,2 @@
+import { a as e, c as t, d as n, f as r, g as i, h as a, i as o, l as s, m as c, n as l, o as u, p as d, r as f, s as p, t as m, u as h } from "./run-rzkK5v61.js";
+export { r as BridgeError, m as CLI_NAME, i as CLI_VERSION, c as CliConfigSchema, a as DEFAULT_CONFIG_FILE, t as bridgeClientProvider, d as createBridgeClient, s as enrichDesign, u as formatFiles, e as generate, n as getBridgeToken, h as hashFacts, l as helpText, o as loadCliConfig, f as run, p as runEnrichStep };

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@syncline-design/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-sandbox.0",
+  "description": "Generates a React component library from a Figma export (Syncline).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uxstudioteam/syncline.git"
+  },
+  "homepage": "https://syncline.design",
+  "type": "module",
+  "bin": {
+    "syncline": "./bin.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "*.js",
+    "README.md",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "prettier": "^3.9.6"
+  }
+}