@flashdsm/genome 0.2.0 → 0.4.0

package/README.md

@@ -32,7 +32,15 @@ In your app's folder, in a terminal or in your AI editor's chat:
 npx @flashdsm/genome@latest connect
 ```
 
-`connect` scans the folder (stylesheets, CSS inside JS/TS, Tailwind config, theme modules, tokens files; nothing else is read) and opens Flash in your browser, showing what it found and a short code that matches the one in your terminal. Click **Connect** there: Flash creates the system in your account, and the command links the repo (`genome.config.json`), writes the system into it (`pull --confirm`) and stores a token bound to that system under `~/.config/flash-dsm/`. Inside Claude Code it also adds Genome as the project's MCP server; elsewhere it prints the line to add. `--name` overrides the name, which otherwise comes from `package.json`; `--no-open` prints the link instead of opening it.
+`connect` scans the folder (stylesheets, CSS inside JS/TS, Tailwind config, theme modules, tokens files; nothing else is read) and opens Flash in your browser, showing what it found and a short code that matches the one in your terminal. Click **Connect** there: Flash creates the system in your account, and the command links the repo (`genome.config.json`), writes the system into it (`pull --confirm`), writes the files an agent reads (AGENTS.md, the skill, the Cursor rule) and stores a token bound to that system under `~/.config/flash-dsm/`. Inside Claude Code it also adds Genome as the project's MCP server; elsewhere it prints the line to add. `--name` overrides the name, which otherwise comes from `package.json`; `--no-open` prints the link instead of opening it.
+
+Run `connect` again in a folder that is already connected and it updates that system instead of making another: no scan, no Connect click; it pulls, refreshes the agent files and the live preview. `connect --new` makes a new system anyway. If the linked system is gone or this machine can't open it, connect says why and connects the folder as a new system.
+
+Your app keeps running on its own CSS: `tokens.css` is Flash's copy, and nothing imports it until you say so. `connect` ends with one question for you (or your agent to ask you): use Flash's colours, so a change in Flash shows up in the app? The steps it prints keep every variable name and leave the screen the same in light and dark. AGENTS.md carries the same steps, plus how changes move: while `genome watch` runs in the background, both ways happen by themselves. Change a token in Flash and Genome rewrites `tokens.css` within seconds, no Publish; save the app's CSS and Flash takes the change. Genome never writes over a hand edit to `tokens.css` that Flash doesn't hold. Without it, `pull --confirm` and `push --confirm` do the same once.
+
+When your app's dev server is running, `connect` also leaves a live preview in the background (localhost:4747): Flash's editor shows your real app and recolours it as you edit tokens, through its CSS variables. Nothing is written to your code. `npx @flashdsm/genome@latest preview` starts it again; `preview --stop` ends it.
+
+`connect` also leaves Genome watching the folder. Change a colour, a theme or a type size in your app's own stylesheets and, a couple of seconds after you save, Flash takes it and the editor says what changed, with Undo. Only what you changed comes in: a token edited in Flash since keeps Flash's value (the notice says so), nothing in Flash is deleted, and a comment or whitespace save does nothing. Genome's own files (`tokens.css`, `design-tokens.json`, `genome/`) are never read back. It rescans once an hour as a backup, and keeps running after the terminal closes; the watcher and the live preview are one background process. `npx @flashdsm/genome@latest watch` starts it again, `watch --stop` ends both, and `watch --once` sends one scan in the foreground and says what Flash did with it. The log is `~/.config/flash-dsm/genome-watch.log`.
 
 The link works once and expires after 15 minutes. `init --code` does the same with a setup code instead of the browser.
 
@@ -112,13 +120,27 @@ diff behind.
 | Tool           | What it does                                                                                          |
 | -------------- | ----------------------------------------------------------------------------------------------------- |
 | `detect_drift` | Read-only. Whether the repo's pulled files moved, whether Flash moved, and which token values changed |
-| `push_to_web`  | Proposes the changed token values to Flash as one change set, reviewed on the Sync page               |
+| `push_to_web`  | Proposes what the code changed to Flash as one change set, reviewed on the Sync page                  |
+
+`push_to_web` reads the code two ways and sends both in one change set:
+
+- **The app's own stylesheets.** A file layered on Flash's `tokens.css`
+  counts: a light block, `--danger: var(--danger-400)`, new `--text-*`
+  sizes. The files the pull wrote (listed in `genome/genome.lock`) are
+  never read as code.
+- **The pulled `design-tokens.json`.** Value edits, aliases re-pointed
+  (`{color.danger-400}`), tokens added, and a light or dark value for a
+  colour Flash holds in the other theme only.
+
+Flash merges them with one set of rules. A `var(--step)` re-points the
+alias. A colour equal to a ramp step points at that step; a colour no step
+holds gets a step of its own (`neutral-150`) in both themes, so nothing in
+Semantic becomes a bare hex. New names are added, a value Flash has no
+theme for is added and said so, and nothing is deleted. The plan says why
+for every row that is more than a new value.
 
-`push_to_web` reads the `design-tokens.json` the pull wrote, compares it
-with the design system as it is now, and proposes value changes to tokens
-Flash already has. Nothing is applied until someone with edit rights says
-yes. A token added, deleted or re-aliased in the file is flagged rather than
-sent: create, remove and re-point tokens in Flash, then pull.
+Nothing is applied until someone with edit rights says yes. A token deleted
+from the file is flagged, never sent as a delete.
 
 It is a dry run without `confirm: true`, and it refuses to push while Flash
 is ahead of `genome/genome.lock`, because a value left over from the last
@@ -221,7 +243,7 @@ Scripts and CI need no MCP client. These run the same code as the MCP tools
 ```bash
 flash-genome pull                 # print what would be written; writes nothing
 flash-genome pull --confirm       # write the token files, the mirror and genome.lock
-flash-genome push                 # print the token edits that would be proposed
+flash-genome push                 # print what the code changed, as Flash would propose it
 flash-genome push --confirm       # open the change set for review in Flash
 flash-genome drift                # has the repo moved, has Flash, which tokens
 flash-genome drift --json         # the same, as one JSON object (for watchers)
@@ -288,7 +310,8 @@ otherwise only added).
 }
 ```
 
-`state` is one of `in-step`, `flash-ahead` (Flash published since the pull),
+`state` is one of `in-step`, `flash-ahead` (Flash changed since the pull: its
+revision moved, published or not),
 `repo-dirty` (a pulled file changed or is missing), `both`, `never-pulled`.
 `flashAhead` and `dirty` are the booleans behind it; `changedTokens` lists
 the token values the repo changed (`code: "repo-edit"`, what `push` would

package/dist/{chunk-PHEWKKKF.js → chunk-YA26VZWF.js}

@@ -498,6 +498,7 @@ export {
   parseFlashAtomicDocument,
   GENOME_CONFIG_FILENAME,
   LEGACY_CONFIG_FILENAME,
+  GenomeOutputsSchema,
   GenomeConfigSchema,
   normalizeTokenDocument,
   configCandidates,

package/dist/index.d.ts

@@ -2,7 +2,15 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { WorkspaceScanResult } from '@flash-ds/core';
 
-declare function scanWorkspace(workspaceRoot: string): Promise<WorkspaceScanResult>;
+/**
+ * `skip` leaves files out by their path from the root. A push passes the
+ * files its lock lists: the core rulebook finds them through
+ * `genome.config.json`, which a repo linked with `--config elsewhere` does
+ * not keep at the root.
+ */
+declare function scanWorkspace(workspaceRoot: string, opts?: {
+    skip?: (rel: string) => boolean;
+}): Promise<WorkspaceScanResult>;
 
 type ApiClient = {
     health(): Promise<{
@@ -75,8 +83,22 @@ declare function parseCliArgs(argv: string[]): {
     name?: string;
     /** connect: print the link instead of opening the browser. */
     noOpen: boolean;
+    /** connect: a new system even when this folder is already connected. */
+    fresh: boolean;
+    /** preview: run the proxy in this process (what the background child runs). */
+    serve: boolean;
+    /** preview / watch: stop the background process. */
+    stop: boolean;
+    /** watch: one scan, sent in the foreground, then exit. */
+    once: boolean;
+    /** preview --serve: the app's dev server, the system, Flash's origin. */
+    devUrl?: string;
+    system?: number;
+    origin?: string;
     /** pull / push: write, rather than print the plan. */
     confirm: boolean;
+    /** pull: write even when it renames variables the app reads. */
+    acceptRename: boolean;
     /** pull / push / drift: one JSON object on stdout. */
     json: boolean;
 };