spec-layer 0.2.1 → 0.4.0

package/README.md

@@ -11,19 +11,23 @@ and writes it to disk.
 ## Quick start
 
 After publishing a library from the plugin's Library screen, it shows a setup
-command. Run it in your repository:
+command. Run it once in your repository:
 
 ```bash
-SPEC_LAYER_KEY=sl_... npx spec-layer pull --id lib_...
+npx spec-layer setup --id lib_... --key sl_...
 ```
 
-That writes `.speclayer/` and is enough on its own. To avoid repeating the
-library id, record it once:
+That records the library id, stores the key in a gitignored
+`speclayer.local.json`, and writes `.speclayer/`. Every later command needs no
+flags at all:
 
 ```bash
-npx spec-layer init --id lib_...
+npx spec-layer pull
 ```
 
+`init` still writes the config without a key or a network call, for a repo
+that supplies the key from the environment instead.
+
 ## Installing, or not
 
 `npx` needs no install step: it fetches the package and runs it. That is the
@@ -47,17 +51,21 @@ npm install --save-dev spec-layer
 
 `npx spec-layer` then runs the pinned local copy, no `--yes` needed. Pinning
 also keeps `.speclayer/manifest.json` on one format: 0.1.0 wrote no
-`selection` field, and 0.2.0 does.
+`selection` field, and 0.2.0 onward does. `setup` needs 0.3.0 or later; earlier
+versions have no such command, so the setup command the plugin copies fails
+against them. The Foundation landing under `tokens/` as Design Tokens Format
+Module 2025.10 files, rather than `ai/foundation.yaml`, needs 0.4.0 or later.
 
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `init --id lib_... [--out DIR] [selection]` | Writes `speclayer.json` so later commands need no flags. |
+| `setup --id lib_... --key sl_... [--out DIR] [selection]` | Writes `speclayer.json`, stores the key in `speclayer.local.json`, then pulls. The command the plugin copies. |
+| `init --id lib_... [--out DIR] [selection]` | Writes `speclayer.json` so later commands need no flags. No key, no network. |
 | `pull [--id lib_...] [--key sl_...] [selection]` | Fetches the library and writes it into `DIR` (default `.speclayer`). |
 | `status [--id lib_...] [--key sl_...]` | Checks freshness without writing. Exits `2` when the local copy is behind. |
 | `list` | Lists every artifact in the last pull, with its file path or `not written`. |
-| `show foundation [--canonical]` | Prints the Foundation's AI YAML to stdout. |
+| `show foundation [--canonical]` | Prints the Foundation's DTCG document to stdout. |
 | `show component NAME [--canonical]` | Prints one component's AI YAML to stdout. |
 
 `--api URL` overrides the API origin (default `https://api.spec-layer.com`).
@@ -114,25 +122,70 @@ name, `show` refuses to guess and points you at `list`.
 
 ## The pull key
 
-Every command that talks to the server reads the pull key from `SPEC_LAYER_KEY`
-or `--key`. It is never written to disk, and `speclayer.json` never contains
-it. Treat it as a secret: it grants read access to the published bundle. If it
-leaks, rotate it from the plugin's Library screen. The old key stops working
-once the change propagates, which can take up to about a minute.
+`spec-layer setup` stores the key in `speclayer.local.json` next to
+`speclayer.json` and makes sure git ignores it before writing it. Every later
+command in that directory needs no key. On POSIX systems the file is written
+at mode `0600`; on Windows there is no equivalent permission bit, so it
+inherits whatever the directory allows.
+
+Commands that talk to the server resolve the key in this order:
+
+1. `--key sl_...`
+2. `SPEC_LAYER_KEY` in the environment
+3. `speclayer.local.json`, when it was issued for the same library
+
+Environment sits above the file so CI can supply a key without touching the
+working tree. A stored key issued for a different library is ignored, and the
+CLI says which library it belongs to rather than letting the server answer 401.
+
+Treat the key as a secret: it grants read access to the published bundle.
+`speclayer.local.json` is gitignored, never printed by any command, and never
+copied into `speclayer.json`, `bundle.json`, `manifest.json`, or anything under
+the output directory. If it leaks, rotate it from the plugin's Library screen,
+then run the new setup command. The old key stops working once the change
+propagates, which can take up to about a minute.
+
+Re-running `setup` replaces the stored key and keeps the rest of your setup:
+with no `--out` and no selection flag it preserves the output directory and the
+`include` block already in `speclayer.json` rather than resetting them to the
+defaults. Pass `--out` or a selection flag to change them. (`init` still
+overwrites `speclayer.json` outright, which is what a first run is for.)
+
+Outside a git working tree, the key is still stored and the CLI says it left
+`.gitignore` alone. Inside one, `setup` refuses to write the key whenever it
+cannot confirm the file will be ignored, and says what to do instead. Three
+cases refuse:
+
+- `.gitignore` cannot be written.
+- git itself could not be run, anywhere inside a working tree.
+- the entry is in `.gitignore`, but git still does not ignore the file. That
+  almost always means `speclayer.local.json` is already tracked, and the CLI
+  names `git rm --cached speclayer.local.json` as the way out.
+
+git decides in every case. The entry sitting in `.gitignore` is not taken as
+proof, because `git check-ignore` does not report a tracked file as ignored no
+matter what the ignore rules say.
 
 ## What `pull` writes
 
 ```text
 .speclayer/
-  bundle.json              the published bundle, verbatim
-  manifest.json            every artifact indexed by content hash and ai path, plus the selection
-  ai/foundation.yaml       tokens, styles, and modes (when selected and the library has a Foundation)
-  ai/components/<name>.yaml one file per selected component
+  bundle.json                the published bundle, verbatim
+  manifest.json               every artifact indexed by content hash and path, plus the selection
+  tokens/                    the Foundation as Design Tokens Format Module 2025.10 files
+    <collection>.<mode>.json one file per collection and mode, rooted at the collection name
+    styles.typography.json   text styles as typography composites (when present)
+    styles.effects.json      effect styles as shadow composites (when present)
+    resolver.json            Design Tokens Resolver Module 2025.10: sets, modifiers, order
+    spec-layer.meta.json     Figma ids, scopes, code syntax, publication, keyed by DTCG path
+    report.json              what DTCG could not express, with reasons and stable ids
+  ai/components/<name>.yaml  one file per selected component
 ```
 
-Point your agent at `.speclayer/ai/`. The YAML there is the same compact form
-the plugin's **Copy for AI** puts on your clipboard; `bundle.json` additionally
-holds the full canonical artifacts if you need them.
+Point your agent at `.speclayer/ai/` and `.speclayer/tokens/`. The component
+YAML is the same compact form the plugin's **Copy for AI** puts on your
+clipboard; `bundle.json` additionally holds the full canonical artifacts if
+you need them.
 
 In `manifest.json`, an artifact the selection left unwritten has `"aiPath":
 null`. A manifest from CLI 0.1.0 has no `selection` field and means
@@ -147,7 +200,32 @@ When nothing changed since the last pull with the same selection, `pull`
 prints `Already up to date` and writes nothing. Every republish stamps a new
 export id and time into the canonical artifacts, so `bundle.json` and
 `manifest.json` change on each republish even when the content did not. The
-`ai/` YAML files and the content hashes stay stable.
+`ai/` YAML files, the `tokens/` files, and the content hashes stay stable.
+
+## Configuring the token output
+
+`speclayer.json` may carry a `dtcg` block:
+
+    {
+      "libraryId": "lib_...",
+      "outDir": ".speclayer",
+      "dtcg": {
+        "values": "standard",
+        "units": { "Foundation/spacing/*": "px", "Foundation/radius/*": "px" }
+      }
+    }
+
+`values` is `standard` (the 2025.10 object forms, the default) or `legacy`
+(the string forms Style Dictionary 4 and Tokens Studio read today). `units`
+promotes a number whose Figma scopes state no unit to a dimension. Keys are a
+collection name, a slash, and a glob over the variable name. An override that
+contradicts a stated scope is ignored and listed in `report.json`. Nothing is
+inferred from a name. Changing the `dtcg` block re-projects `tokens/` on the
+next `pull` even when the library has not been republished.
+
+Point Style Dictionary at `.speclayer/tokens/` and load the files
+`resolver.json` names for the mode you are building. The metadata sidecar and
+the report are not token files; exclude them from token globs.
 
 ## Exit codes