@flashdsm/genome 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Itay Haephrati
+
+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

@@ -0,0 +1,157 @@
+# @flashdsm/genome
+
+Flash Genome: the local MCP server for a [Flash DSM](https://flashdsm.com) design system, over stdio.
+
+Point it at a `design-tokens.json` and every MCP client - Cursor, Claude
+Desktop, Claude Code - can read your real tokens and component specs instead of
+guessing hex values. It also lints code against the system and proposes the
+token you should have used. Deterministic tools, no LLM inside: the AI is on
+the other end of the protocol.
+
+Works standalone with any token file - a plain `design-tokens.json` next to
+your project is enough.
+
+## Connect it to a Flash design system
+
+Mint an MCP token in Flash under Connect, then in your repository:
+
+```bash
+export FLASH_GENOME_TOKEN=flash_mcp_…
+npx @flashdsm/genome link
+```
+
+`link` asks the server which system the token belongs to and writes
+`genome.config.json` next to your code: the system's id, its revision, and
+where token files and agent context live. The token is never written to that
+file - it is committed, and a token in it would be a token in the
+repository's history.
+
+## Quick start
+
+```bash
+npx @flashdsm/genome --tokens ./design-tokens.json
+```
+
+Cursor (`.cursor/mcp.json`) or Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "flash-ds": {
+      "command": "npx",
+      "args": ["@flashdsm/genome", "--tokens", "./design-tokens.json"]
+    }
+  }
+}
+```
+
+With no flags it looks for `./genome.config.json`, then the older
+`./flash-ds.config.json` (`tokenFile` / `componentsFile`), then `./design-tokens.json` with a sibling
+`./components.json`, and finally falls back to a small bundled fixture so the
+server always boots. It logs which file it resolved to stderr.
+
+## Keeping a repo in sync
+
+Once linked:
+
+| Tool            | What it writes                                                                       |
+| --------------- | ------------------------------------------------------------------------------------ |
+| `pull_from_web` | The token files and mirrors named by `genome.config.json`, plus `genome/genome.lock` |
+| `sync_context`  | `AGENTS.md` (once), the Cursor rule, and the Agent Skill                             |
+
+Both are dry runs by default: they return a plan of what would be created,
+updated or skipped, and write only when called again with `confirm: true`.
+A second pull is all skips, lock included, whenever the revision, the file
+list and their contents all still agree, so pulling to check never leaves a
+diff behind.
+
+## Sending repo edits back
+
+| 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` 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.
+
+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
+pull would otherwise look like an edit and undo someone's change. Pull,
+re-apply your edits, then push.
+
+`AGENTS.md` is written once and then left alone however far it drifts: it is
+where a team puts its own instructions. The Cursor rule is Genome's to keep
+current, because a stale rule file is worse than none.
+
+## Asking the graph
+
+With `FLASH_GENOME_TOKEN` set, these answer from the design system itself, with
+the same walk and the same answers as the hosted server's tools of the same
+name. No linked repo needed.
+
+| Tool            | Args     | What it answers                                                                                                        |
+| --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `get_impact`    | `token`  | What breaks if this token changes: tokens that resolve through it, and the components and modules that use any of them |
+| `get_relations` | `token?` | A token's direct edges, or every alias edge, binding and module part                                                   |
+| `list_modules`  | -        | Every module, its part count, components and bindings                                                                  |
+| `get_module`    | `module` | One module, parts resolved to components                                                                               |
+
+## Tools
+
+| Tool                        | Args                | Description                                                      |
+| --------------------------- | ------------------- | ---------------------------------------------------------------- |
+| `get_tokens`                | `category?`         | Read tokens from the local token file. Read-only                 |
+| `list_components`           | `category?`         | List components from `components.json`                           |
+| `get_component`             | `name`              | One component spec                                               |
+| `get_brand_dna`             | -                   | Brand DNA from a sibling file or `tokens['dsm-brand-dna']`       |
+| `suggest_token`             | `context`           | Nearest-token suggestions for hex/px in a snippet. Deterministic |
+| `apply_token_patch`         | `patch`, `confirm?` | Upsert/remove tokens. Dry-run unless `confirm: true`             |
+| `generate_component_prompt` | `name`              | Handoff prompt for a component plus its tokens                   |
+| `check_violations`          | `file`              | Lint a source file for hardcoded colors / arbitrary Tailwind     |
+| `api_health`                | -                   | `GET {api}/health` against a Flash DSM backend                   |
+| `list_design_systems`       | -                   | List your systems from a Flash DSM backend (needs a token)       |
+
+Writes are guarded: `apply_token_patch` is a dry-run unless you pass
+`confirm: true`, so a curious agent cannot rewrite your tokens by accident.
+
+## CLI
+
+```bash
+flash-genome --tokens ./design-tokens.json
+flash-genome --config ./genome.config.json
+flash-genome --tokens ./design-tokens.json --components ./components.json
+```
+
+| Flag             | Env                                             | Default                                                       |
+| ---------------- | ----------------------------------------------- | ------------------------------------------------------------- |
+| `--tokens, -t`   | -                                               | resolved as above                                             |
+| `--components`   | -                                               | sibling `components.json`                                     |
+| `--config, -c`   | -                                               | `./genome.config.json`                                        |
+| `--api-url`      | `FLASH_GENOME_API_URL`, then `FLASH_DS_API_URL` | this repo's `genome.config.json`, then `https://flashdsm.com` |
+| `--token`        | `FLASH_GENOME_TOKEN`                            | none, and `link` needs it                                     |
+| `--access-token` | `FLASH_DS_ACCESS_TOKEN`                         | none, deprecated                                              |
+
+`link` uses the MCP token. The deprecated web JWT is only still read by
+`api_health` and `list_design_systems`; every other tool reads local files.
+Against a backend on your own machine, pass
+`--api-url http://localhost:8008`.
+
+## Hosted alternative
+
+If your design system lives in Flash DSM, you may not need this package at all:
+the app serves a remote MCP endpoint per design system
+(`https://flashdsm.com/api/v1/mcp` with a `flash_mcp_*` token). This package is
+the local-files variant for repos that vendor their tokens.
+
+## Development
+
+Source lives in the [Flash DSM Maker](https://github.com/itay1313/Flash-DSM-Maker)
+monorepo under `packages/genome`. `pnpm --filter @flashdsm/genome test`
+runs the tests, `... build` bundles with tsup, `... smoke` checks the built
+output against the fixtures.
+
+MIT.