@design-twin/dtwin 0.1.0-alpha.0 → 0.1.1

package/README.md

@@ -7,13 +7,31 @@ The plugin's hidden UI iframe is a WebSocket **client**; these processes are the
 (`127.0.0.1:8787`). Nothing touches the internet. See `../ARCHITECTURE.md` for the full design.
 
 ## Install (once)
-The `designtwin` package is not on npm; install it from a clone:
+It needs [Bun](https://bun.sh/install) ≥ 1.4.2 (`engines.bun`) on your PATH; Node is not supported. Install Bun
+first (`curl -fsSL https://bun.sh/install | bash`, or `powershell -c "irm bun.sh/install.ps1 | iex"` on Windows), then
+the package, `@design-twin/dtwin`, from npm:
+```
+bun add -g @design-twin/dtwin   # puts `dtwin` in ~/.bun/bin (on your PATH via the Bun installer)
+```
+`npm i -g @design-twin/dtwin` installs the same thing, but `dtwin` still runs on Bun: without Bun on PATH it stops at
+`env: bun: No such file or directory`. The package also carries the built Figma plugin (`figma-plugin/manifest.json`
+inside it — `dtwin init` prints the full path to import) and the design-to-code bundles the MCP server's
+`design_get_component` / `design_drift_lint` load (`layer/`).
+
+Or with Homebrew (macOS, Linux), which installs Bun for you and keeps both up to date with `brew upgrade`:
+```
+brew install its-magdy/tap/dtwin
+```
+The formula installs the same npm package into Homebrew's prefix; every release updates it. Paths `dtwin init` writes
+(the `.mcp.json` server entry, the plugin manifest it prints) are spelt through `$(brew --prefix)/opt/dtwin/…`, which
+survives an upgrade — not the versioned `Cellar/dtwin/<version>/` folder the next `brew upgrade` deletes.
+
+Or from a clone (to work on the code):
 ```
 git clone https://github.com/its-magdy/design-twin.git && cd design-twin
 bun install                     # @modelcontextprotocol/sdk (+ zod), for every workspace
 cd bridge && bun link           # puts `dtwin` in ~/.bun/bin (on your PATH); nothing to build
 ```
-It needs [Bun](https://bun.sh/install) ≥ 1.4.2 (`engines.bun`); Node is not supported.
 Or skip the link and run `bun --no-install --no-env-file /path/to/design-twin/bridge/src/figma-pull.ts` wherever
 this README says `dtwin` (those two flags are what the bin's shebang adds: without them, Bun loads the `.env` of the
 project you run it in and may fetch a missing package from the registry).
@@ -34,7 +52,7 @@ validated against them and exits rather than binding a port nothing could ever r
 **Languages:** the whole bridge is **TypeScript** (ESM) under `src/` — `figma-pull.ts` (read CLI),
 `server-core.ts` (WS core), `figma-mcp.ts` (MCP server), and the modules they share. From a checkout,
 Bun runs it directly with **zero build** (`bun bridge/src/figma-pull.ts …`, `bun bridge/src/figma-mcp.ts`), and the
-package ships the same TypeScript: its `dtwin` bin — what `bun link` puts on your PATH — is `src/figma-pull.ts`,
+package ships the same TypeScript: its `dtwin` bin — what `bun add -g` or `bun link` puts on your PATH — is `src/figma-pull.ts`,
 whose shebang is `#!/usr/bin/env -S bun --no-install --no-env-file` (so a `.env` or a missing package in the
 project you run it from can neither change its environment nor make Bun fetch a module from the registry;
 `env -S` needs GNU coreutils ≥ 8.30 or a BSD/macOS `env` — on BusyBox, call `bun --no-install --no-env-file` on
@@ -801,13 +819,38 @@ execution**, unlike some community servers; a `fill` / `color` must be a hex col
 `#rrggbb` or `#rrggbbaa` with the `#`, never a name like `red` — and anything else is refused (by the
 schema here, and by the plugin for a write from another client) instead of painted as a wrong colour; `dryRun: true` returns a preview of what each op would
 create or overwrite without touching the file — there is no undo from the MCP side, so preview anything
-that overwrites; refused outright when the file is in read-only Dev Mode), and two that read the export already on disk and
+that overwrites; refused outright when the file is in read-only Dev Mode — and **refused unless the designer has
+ticked "Allow edits"** in the plugin window, see below), and two that read the export already on disk and
 need no Figma connection — `design_get_component` (one component's variant node trees) and
 `design_drift_lint` (the component map vs the export; see below). The frame-walking export tools accept opt-in read flags
 `css` / `measurements` / `pluginData` / `motion` / `sharedData`; `figma_export_design_system` doesn't
 take them (it never walks a node — see below) but DOES take `variantVisuals`, since the component
 catalog it builds is exactly what that flag enriches.
 
+### "Allow edits" — the plugin changes nothing until the designer opts in
+The plugin window has an **Allow edits** checkbox, **off by default**. While it is off the plugin only reads:
+every `figma_write` batch is refused whole, before any op runs, and the tool returns this error (nothing in the
+file changed):
+
+> Edits are off in the Design Twin plugin — tick 'Allow edits' in the plugin window, then retry. Nothing in the file was changed.
+
+That is not something an agent can fix. **Ask the user to tick "Allow edits" in the Design Twin plugin window,
+then retry the same call.** The plugin's main thread holds the setting and checks it on every write; nothing on
+the bridge side can turn it on.
+
+- **Dry run still works while it is off.** `dryRun: true` previews the batch as before and adds `editsAllowed`
+  (read from the plugin's `whoami`): `false` → a real write would be refused right now (the preview also carries
+  `wouldRefuse` with the sentence above); `true` → it would be applied; `null` → unknown (no plugin connected,
+  several connected with no `client`, or a plugin built before the opt-in). Check it before asking the user to
+  review a preview, so the request to tick the box comes in the same breath.
+- **The setting is per user, for every file.** It is saved in Figma's `clientStorage`, which is already scoped
+  to one user and this plugin. It is not per file: the plugin cannot reliably name a file (`fileKey` is only for
+  private plugins, and file names repeat), and a per-file flag stored in the document would itself be an edit.
+  Untick it when you are done.
+- **No write is silent.** Each applied batch (and each refused one) shows a Figma toast and a line in the plugin
+  window, e.g. "Design Twin applied 3 edits to this file."
+- `dtwin whoami` prints the state (`edits: off — …` / `edits: ALLOWED — …`) and `editsAllowed` is in its JSON.
+
 ### `writeToDisk` — the export path that doesn't go through the context window
 Every export tool takes `writeToDisk: true` (plus an optional `outDir`). It writes the export through
 the same `write-out.ts` the CLI uses — same layout, by construction — and returns a **compact index**