@weft-js/cli 0.0.0-stage → 0.1.0

package/docs/surface.md

@@ -0,0 +1,111 @@
+# Surfaces (`@weft-js/core/surface`)
+
+A canvas or WebGL view that sits in layout like any other child. `setup` runs once on the client, props are live, and
+nothing around it re-renders. Never write a raw `<canvas>`.
+
+```tsx
+import { state } from '@weft-js/core'
+import { defineSurface, Surface } from '@weft-js/core/surface'
+import { z } from 'zod'
+
+export const Bars = defineSurface({
+  name: 'bars',
+  kind: 'canvas2d',                                // or 'webgl2'
+  props: z.object({ data: z.array(z.number()) }),  // or defineSurface<{ data: number[] }, 'canvas2d'>({ ... })
+  setup(s, props) {                                // runs once; `props.data` is live, so never destructure it
+    s.draw(() => {                                 // repaints when a box it read changes; the canvas is cleared first
+      const { width, height } = s.size.value       // CSS px, live
+      s.ctx.fillStyle = s.tokens.accent.css        // live theme colours: `.css`, or `.linear` for shaders
+      props.data.forEach((v, i) => s.ctx.fillRect(i * 12, height - v, 10, v))
+    })
+  },
+})
+
+export function Page() {
+  const rows = state([3, 7, 5])
+  return <Surface use={Bars} data={rows.value} aspect="16/9" label="Sales by month" />
+}
+```
+
+A control beside the surface needs only a box and a live prop. Nothing re-renders when it moves:
+
+```tsx
+import { state } from '@weft-js/core'
+import { defineSurface, Surface } from '@weft-js/core/surface'
+
+export const Stars = defineSurface<{ density: number }, 'canvas2d'>({   // name the kind too, so `s.ctx` is typed
+  name: 'stars',
+  kind: 'canvas2d',
+  setup(s, props) {
+    s.frame(({ seconds }) => {                     // every tick; reading `props.density` here keeps it live
+      for (let i = 0; i < props.density; i++) s.ctx.fillRect((i * 37 + seconds * 20) % s.size.value.width, (i * 91) % s.size.value.height, 1, 1)
+    })
+  },
+})
+
+export function Sky() {
+  const density = state(100)
+  return <>
+    <input type="range" min="10" max="500" value={density.value} onInput={e => (density.value = e.currentTarget.valueAsNumber)} aria-label="Density" />
+    <Surface use={Stars} density={density.value} aspect="16/9" decorative />
+  </>
+}
+```
+
+**`<Surface>`:** `use`, your props, `aspect` (default `2/1`), `label` (required, X009) or `decorative`, `class`, `style`.
+The server renders a sized placeholder, so nothing shifts when the canvas mounts. Put pointer handlers on `s.el`.
+
+**`s`:**
+- `s.ctx` (`canvas2d`), `s.gl` (`webgl2`), `s.canvas`, `s.el`
+- `s.size`, `s.dpr`, `s.scale`: boxes. `canvas2d` draws in CSS px; `webgl2` has its viewport set for you
+- `s.tokens.accent`: `--accent`, else `--warp-accent`, as `{ css, linear }`
+- `s.draw(fn)`: paint when a box it read changes
+- `s.frame(t => ...)`: animate: `t.frame`, `t.seconds`, `t.delta`. Also repaints on a box change while paused
+- `s.invalidate()`: book a paint by hand
+- `s.text(text, options)`: text; see below
+- `return () => ...` from `setup` to clean up
+
+`defineSurface` also takes `fps` (default 60), `maxDpr` (default 2), `clear: false`, `context` (`getContext` attributes),
+and `pixel: { width, height }` for a fixed target with integer scale and nearest sampling.
+
+**The clock** is shared: `import { clock } from '@weft-js/core/surface'`, then `clock.pause()`, `clock.play()`, `clock.seek(seconds)`.
+`seek` paints every animated surface now, so a capture is deterministic. Under `prefers-reduced-motion: reduce` it
+starts paused on the first frame. Off-screen surfaces skip their paints.
+
+## Text
+
+Never `fillText` (X010). `s.text()` keeps a real element over the text, so selection, find, translation, screen readers,
+forced colours and print all work:
+
+```tsx
+const score = s.text(() => `Score ${props.score}`, { x: 8, y: 8, width: 200, font: '600 16px Inter', lineHeight: 22 })
+```
+
+- Options may be a function, for live positions: `() => ({ x: s.size.value.width / 2, ... })`.
+- `font` and `lineHeight` default to the CSS on the mirror. `color` defaults to the surface's. `align` is `left`,
+  `center` or `right`. Name a family (X002).
+- It returns `{ el, lineCount, height }`; the last two are boxes.
+- Canvas `s.text()` needs the `text.measure` slot, so add `text()` from `@weft-js/text` to `plugins` in
+  weft.config.ts (P101). Its engine loads lazily. On `webgl2` the mirror is the visible text, and no plugin is needed.
+- `s.decorative(() => ctx.fillText(...))` is for text that is truly decoration.
+
+## Testing
+
+jsdom has no canvas, so `@weft-js/core/test` gives it a recording one:
+
+<!-- example: skip imports the Page above from its own file -->
+```tsx
+import { canvasCalls, clock, fakeMeasure, flush, render } from '@weft-js/core/test'
+import { expect, test } from 'vitest'
+import { Page } from './Page'   // the Bars page above
+
+test('draws a bar per value', async () => {
+  clock.install()
+  render(Page, {}, { slots: { 'text.measure': fakeMeasure() } })
+  await flush()
+  await clock.advance(16)   // a frame
+  expect(canvasCalls(document.querySelector('canvas')!).filter(c => c.name === 'fillRect')).toHaveLength(3)
+})
+```
+
+`weft surfaces --json` (MCP `surfaces`) lists what the project already has.

package/docs/testing.md

@@ -0,0 +1,71 @@
+# Testing (`@weft-js/core/test`, vitest)
+
+A new app has no test runner. Add one:
+
+```bash
+npm install -D vitest jsdom @testing-library/dom @testing-library/user-event
+```
+
+<!-- example: skip @weft-js/core/vite has no type declarations yet (TS7016 under strict) -->
+```ts
+// vitest.config.ts
+import weft from '@weft-js/core/vite'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({ plugins: [weft()], test: { environment: 'jsdom' } })
+```
+
+Then `npx vitest run`. A test:
+
+```tsx
+import { state } from '@weft-js/core'
+import { render, screen, user } from '@weft-js/core/test'
+import { expect, test } from 'vitest'
+
+function Cart() {
+  const count = state(0)
+  return <button type="button" onClick={() => count.value++}>Cart ({count.value})</button>
+}
+
+test('adding to the cart', async () => {
+  render(Cart)
+  await user.click(screen.getByRole('button', { name: 'Cart (0)' }))
+  expect(screen.getByRole('button', { name: 'Cart (1)' })).toBeTruthy()
+  await expect(() => user.click(screen.getByRole('button'))).toTouchAtMost(1, { runs: 2 })
+})
+```
+
+- `render(Component, props, options)` mounts into the document with a fresh app; unmounted after each test.
+  `options.state` seeds `defineState` scopes, `options.storage` (`memoryStorage()`) is shared between renders to play
+  two tabs or a reload, and `options.slots` binds plugin slots. `scope(handle)` runs one scope with no UI.
+- `flush()` applies pending updates. Every `user` action and `clock.advance` already ends in one.
+- `screen` has role, label and text queries only (`getByRole`, `getByLabelText`, `getByText`, with `getAll`/`query`/`find`).
+- `user.click`, `dblClick`, `type`, `clear`, `keyboard`, `hover`, `unhover`, `tab`, `selectOptions`, `deselectOptions`,
+  `upload` and `paste` (`@testing-library/user-event`) each end in `flush()`: never sleep or `waitFor`.
+- `clock.install()` before the code schedules timers, then `await clock.advance(ms)` (or `clock.runAll()`): drives
+  timers, rAF, `Date` and the resources that wait on them, and flushes. Uninstalled after each test.
+- `touches(fn)` returns `{ mutations, runs, … }` for one interaction. `toTouchAtMost(n, { runs })` bounds both: DOM writes
+  alone miss identity bugs that re-run every row but write the DOM once (W014).
+
+## Junk tests: T001–T009
+
+`weft check` reports these on test files (`test.include` in the config). A test that finishes without an assertion
+also fails at runtime (T001). T012 and T013 are about open listeners and real sockets: `weft docs browser` and
+`weft docs start`; T010, T011 and T020 are the gate: `weft docs verify`.
+
+| Code | Catches | Instead |
+|---|---|---|
+| T001 | No assertion, or `expect(x)` with no matcher | Assert what the user sees |
+| T002 | `expect(true).toBe(true)`, `expect(x).toBe(x)` | Assert on the code's output |
+| T003 | `n.value = 5; expect(n.value).toBe(5)` | Act through the UI, assert what depends on it |
+| T004 | `setTimeout` sleeps, real timers, `waitFor` | `flush()`, `clock.advance(ms)` |
+| T005 | `container`, selectors, classes, `innerHTML`, test ids, app state in a component test (warning) | Role, label, text |
+| T006 | `vi.mock('@weft-js/core')`, mocking the component under test | Fake the edges (API, storage) |
+| T007 | Snapshots | Behavior assertions |
+| T008 | `expect` under `if`/`?:`/`&&`/`catch`, or only inside loops | Assert the condition, then assert unconditionally |
+| T009 | `.only`, `.skip`, `fit`, `xit` | Remove it; `test.fails` for a test meant to fail |
+
+A deliberate exception needs a reason: `// weft-allow T007: the exported SVG is the product`. In the file's header
+comments it covers the whole file; elsewhere, its own line and the next.
+
+Plugins can use this clock too: `fakePay` from `@weft-js/pay/test` plays a rail on it, through your real webhook and ledger. `weft docs pay`.

package/docs/ui-state.md

@@ -0,0 +1,92 @@
+# Shared UI state
+
+Hover, focus and press are usually a pile of event handlers. `interaction()` makes them plain values you can read, draw and share. An app that doesn't use it ships none of it.
+
+```tsx
+import { derived, watch } from '@weft-js/core'
+import { interaction } from '@weft-js/core/interaction'
+import { Button, Checkbox } from '@weft-js/warp'
+
+type Todo = { id: string; title: string }
+
+export function TodoRow({ todo }: { todo: Todo }) {
+  const row = interaction({ share: () => `todo:${todo.id}` })
+  const seen = derived(() => (row.remote.value.hover ? 'someone is here' : ''))
+  watch(() => row.hover.value, on => { if (on) void fetch(`/api/todos/${todo.id}`) }) // only ever your own hover
+  return (
+    <li>
+      <Checkbox ui={row}>{todo.title}</Checkbox>
+      <Button ui={row} emphasis="soft">Open</Button>
+      <small>{seen.value}</small>
+    </li>
+  )
+}
+```
+
+Give a warp component the row with `ui`, and it fills the row from real events and draws from it. Everything else is reading:
+
+| Read | It means | Who writes it |
+|---|---|---|
+| `row.hover.value`, `row.focus.value`, `row.pressed.value` | true or false, on this page | real events, or your code |
+| `row.remote.value.hover`, `.focus`, `.pressed` | how many others have it: other tabs and other clients. A count, never who. | only the network |
+
+**Yours and theirs never mix.** Someone else's hover can't set your `row.hover`, so a `watch` on it can't run for them and can't echo back. To draw both by hand, read both: `row.hover.value || row.remote.value.hover`. warp does this for you: a row lit from anywhere gets `data-hold`, and `data-remote` when it's only others.
+
+**What a press leaves behind is data.** `pressed` is true only while a button is held down, so others see the press and then it's gone. The tick a press leaves on a checkbox is the app's data, not UI state: share it the way you share any data, with `state(…, { persist, sync: 'tabs' })` for tabs or live data for other clients. The demo above does both.
+
+## How far it reaches
+
+| Where | How it travels | What you do |
+|---|---|---|
+| The same page | the same object: one key is one row | nothing |
+| Other tabs of this browser | `BroadcastChannel`, one post a frame at most | nothing |
+| Other browsers | one socket per browser, held by one tab | allow it, below |
+
+Drop `share` and the row is private to that one `interaction()` call. An app without `@weft-js/start` shares on the page only.
+
+When the tab holding the socket closes or crashes, another tab takes over; nothing flashes, and nobody sees a gap except, for one round trip, a hover made during the handover. When a tab or client goes, what it held clears.
+
+## Who may see what
+
+Sharing with other clients is off until you say who may, in `src/realtime.server.ts`:
+
+```ts
+import { realtime } from '@weft-js/start'
+
+export default realtime({ share: ({ ctx, key }) => ctx.user !== null && key.startsWith('todo:') })
+```
+
+That rule runs once per key. If it reads a database, a 200-row list means 200 queries, so answer them together instead. You get up to 400 keys in one call and give back the ones allowed:
+
+```ts
+import { realtime } from '@weft-js/start'
+
+// visibleKeys is yours: one query that returns the keys this user may see.
+declare function visibleKeys(userId: string, keys: string[]): Promise<string[]>
+
+export default realtime({
+  share: { keys: async ({ ctx, keys }) => (ctx.user ? visibleKeys(ctx.user.id, keys) : []) },
+})
+```
+
+Either form runs when a client joins and at each session re-check, and uses the same `ctx` as a channel's `authorize`. A rule that throws refuses what it was asked. With no `share` the socket refuses every key (R011), and a refused key still works between tabs. `() => true` must be written out.
+
+Peers see the three bits and an opaque connection id. No name, no pointer position, nothing typed. For names and cursors use `@weft-js/multiplayer`.
+
+**Hover tells people things.** What someone lingers on in a shared document, or which field of a form has focus, is a real signal. warp never shares by default: you opt in row by row, and it's worth telling your users.
+
+## Details
+
+- **Keys** are read once, so a prop goes in as a function: `share: () => `todo:${props.id}``. A plain string is fine when it's fixed. To change key, give the component a new `key`.
+- **Costs.** A 200-row list is one frame to join, and a joiner costs other clients nothing. High-frequency changes send at most one frame per 60 ms, carrying the latest value of every row that changed. `limits.shareKeys` (1000) caps keys per socket.
+- **Touch** has no hover, so `row.hover` stays false on a phone; press still works, and a phone can show someone else's hover.
+- **The server** renders every row as idle, so hydration has nothing to reconcile. Rows are live a moment after the page is.
+- **Components that take `ui`:** Button, Checkbox, Switch, Radio, Toggle, Chip, Card. Remote state never touches `aria-*` or focus: it is decoration.
+
+`weft check` flags keys that can't match (U001), keys built from what a user typed (U002), `share` with no rule (U003), writing `remote` (U004) and `ui` on a component that doesn't take it (U005).
+
+## One browser, one socket
+
+All tabs of a browser share one WebSocket, held by one tab, and `share`, `channel` and `live` all ride it. You don't set this up. To your code and to the server each tab is still its own connection: `exceptSelf`, `left`, presence and rate limits work per tab as they did. `limits.connections` now counts browsers.
+
+When the leader tab closes, another takes over within a few milliseconds. Every tab's channels rejoin and its live queries resubscribe, so presence in other tabs may blink once. A browser without Web Locks gives each tab its own socket. A host that can't do WebSockets falls back to `/_weft/rt` over SSE for `live`.

package/docs/verify.md

@@ -0,0 +1,48 @@
+# Verify your work
+
+Two checks before a change is done: see it work in the running app, and get its tests through the gate.
+
+## The running app: `weft browser` or `__weft__.agent`
+
+Run the app in dev: `weft dev`, or `vite` for an app without `@weft-js/start`. In dev, every page loads
+`@weft-js/core/agent`, as long as `@testing-library/dom` and `@testing-library/user-event` are installed (they are what
+`weft docs testing` adds; without them a page gets only the devtools graph). Drive it whichever way you can reach it:
+
+- **Your own browser** (a browser tool that runs JS, any agent): open the app's URL, then
+  `await __weft__.agent.run('snapshot')`, `await __weft__.agent.act({ role: 'button', name: 'Add' }, 'click')`, …
+- **The CLI or MCP**: `weft browser <command>` (tools `browser_*` in `weft mcp`). The dev server relays each command to
+  the open tab. Nothing open? Open the URL in your browser, or `weft browser launch` (a headless Chrome).
+
+Commands (CLI form; the JS and MCP forms take the same params):
+
+- `snapshot [--interactive] [--delta]`: roles, names and refs (`- button "Add Banana" [ref=e15]`), plus the reactive
+  graph with real names: `Cart.total = 4.5 ← Cart.lines → 1 binding in <Cart> (Cart.tsx:12)`. Big ones go to a file.
+- `act button "Add Banana" click`, `act label Coupon fill SAVE10`, `act @e15 click`: user-event, like `user` in
+  @weft-js/core/test. Returns what changed on the page.
+- `assert status - text "Total: $4.50"`; expectations: visible, absent, text, exactText, value, checked, unchecked,
+  disabled, enabled, focused, count. Retries briefly for async loads.
+- `graph Cart` and `set Cart.coupon '"SAVE10"'`: read the graph, write a box by name to reach a state fast.
+- `time pause [--reload]`, `time advance 3000`, `time resume`: the page's clock (timers, intervals, rAF, Date).
+  `--reload` pauses from page load, so startup timers are faked too.
+- `net offline|online|latency 300|drop|reset`: `navigator.onLine`, the events, `fetch`, open WebSockets and
+  EventSources. `drop` is a server restart; check the app reconnects.
+- `record start` … `record code --component App --from ./App --out src/App.test.tsx`: what you did (acts, asserts,
+  clicks and typing from any browser tool) as a `@weft-js/core/test` test. It then has to pass the gate.
+- `logs`: console errors and uncaught errors, with the binding they came from.
+
+## The test gate: `weft test --gate`
+
+Runs on the diff (`--base <ref>`, default the uncommitted change), in scratch copies; your working tree is never
+touched.
+
+- **T010, fail-before:** each new or changed test must fail on the code before the change. A test that passes on the
+  old code doesn't test the change.
+- **T011, mutants:** each new test must kill at least one mutant of the changed lines (operators, boundaries,
+  literals, conditions, removed calls, JSX text). Surviving mutants come back with what to assert. Sampled within
+  `test.gate.mutationBudgetSec` (default 60) and `maxMutants` (40); when sampled, T011 is a warning.
+- **T020, no weakening:** deleting, skipping or loosening an existing test (`toBe(3)` → `toBeTruthy()`) needs
+  `// weft-allow T020: <reason>` on it.
+- The static T-codes run on the changed tests; T005 (implementation queries) blocks here.
+
+Tests added for code that didn't change have nothing to fail on: fail-before is skipped, and the mutants come from
+the source files the tests import. `--refactor` promises no behavior change: then no test may change.

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@weft-js/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The weft command: dev, build, check, the agent layer and the MCP server",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "weft": "./bin/weft.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./config": "./src/config.mjs"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "dependencies": {
+    "@weft-js/create": "0.1.0",
+    "axe-core": "4.14.0",
+    "typescript": "6.0.3",
+    "yaml": "2.9.1",
+    "zod": "4.6.7"
+  },
+  "peerDependencies": {
+    "@weft-js/core": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "weft"
+  ],
+  "files": [
+    "bin",
+    "src",
+    "docs",
+    "ts-plugin",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/add-rust.mjs

@@ -0,0 +1,123 @@
+// `weft add rust [name]`: a crate, its server module and one working function, so `weft check` passes on the first run.
+// `native()` by default (one hot function in this process); `--remote` for a sidecar, the same crate behind HTTP. The
+// `weft` crate isn't on crates.io: it comes with @weft-js/start, so the app's crate and its TS can't disagree on a version.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { start } from './start.mjs'
+
+const refused = message => Object.assign(new Error(message), { code: 'E_ADD' })
+const usage = message => Object.assign(new Error(message), { code: 'E_USAGE' })
+const TOOLCHAIN = '1.99.1'
+
+const camel = name => name.replace(/[-_](.)/g, (_, c) => c.toUpperCase())
+const pascal = name => { const c = camel(name); return c[0].toUpperCase() + c.slice(1) }
+const lib = name => name.replaceAll('-', '_')
+
+const manifest = (name, crate, remote) => `[package]
+name = "${name}"
+version = "0.0.0"
+edition = "2024"
+publish = false
+${remote ? '' : `
+[lib]
+crate-type = ["cdylib"]
+`}
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+${remote ? `tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+weft = { path = "${crate}" }` : `weft = { path = "${crate}", default-features = false, features = ["native"] }`}
+
+[build-dependencies]
+weft = { path = "${crate}", default-features = false, features = ["build"] }
+
+# A rebuild in \`weft dev\` should stay quick and not be a hundred times slower than the real thing.
+[profile.dev]
+opt-level = 1
+
+[profile.release]
+lto = "fat"
+codegen-units = 1
+
+[workspace]
+`
+
+const body = (name, remote) => `weft::contract!(); // types and a \`Service\` trait, generated from your Zod: never hand-written
+use contract::*;
+
+struct ${pascal(name)};
+
+impl Service for ${pascal(name)} {
+    async fn digest(&self, _ctx: weft::Ctx, input: DigestInput) -> Result<DigestOutput, weft::Error> {
+        let hash = input.text.bytes().fold(0x811c9dc5u32, |h, b| (h ^ b as u32).wrapping_mul(0x01000193));
+        Ok(DigestOutput { bytes: input.text.len() as i64, hash: format!("{hash:08x}") })
+    }
+}
+${remote ? `
+#[tokio::main]
+async fn main() -> std::io::Result<()> {
+    weft::serve(weft::router(contract::functions(${pascal(name)}))).await
+}
+` : `
+weft::native!(contract::functions(${pascal(name)}));
+`}`
+
+const fn = (name, binding) => `import { query } from '@weft-js/start/data'
+import { z } from 'zod'
+import { ${binding} } from './rust'
+
+// \`crates/${name}\` is its body. Change the schema and \`weft check\` stops at the Rust it broke.
+export const digest = query({
+  input: z.object({ text: z.string().max(1_000_000) }),
+  output: z.object({ bytes: z.int(), hash: z.string() }),
+  impl: ${binding},
+})
+`
+
+/** The path Cargo gets. `crate/` is in a packed @weft-js/start; a linked one is in this repository, next to the crates. */
+async function weftCrate(root, dir) {
+  const { startDir } = await start(root, 'vite')
+  const found = [join(startDir, '..', 'crate'), join(startDir, '..', '..', '..', 'crates', 'weft')].find(d => existsSync(join(d, 'Cargo.toml')))
+  if (!found) throw refused('this @weft-js/start has no `weft` crate in it. Nothing was changed.')
+  return relative(dir, found).replaceAll('\\', '/')
+}
+
+export async function addRust(root, name = 'media', { remote = false, dryRun = false, install, installSpecs }) {
+  if (!/^[a-z][a-z0-9_-]*$/.test(name)) throw usage(`\`${name}\` isn't a service name: lower case, then letters, digits, \`-\` or \`_\``)
+  if (!existsSync(join(root, 'package.json'))) throw refused('`weft add rust` needs a package.json. Nothing was changed.')
+  const dir = join(root, 'crates', name)
+  const module = join(root, 'src', 'server', `${name}.ts`)
+  const taken = [dir, module].filter(existsSync).map(f => relative(root, f))
+  if (taken.length) throw refused(`${taken.join(', ')} already exist${taken.length > 1 ? '' : 's'}. Pick another name: \`weft add rust <name>\`. Nothing was changed.`)
+  const binding = camel(name)
+  const factory = remote ? 'remote' : 'native'
+  const call = remote ? `remote('rust://${name}')` : `native('${name}')`
+  const rustFile = join(root, 'src', 'server', 'rust.ts')
+  const had = existsSync(rustFile) ? readFileSync(rustFile, 'utf8') : '// The only place Rust targets are named.\n'
+  if (new RegExp(`\\b${binding}\\b`).test(had)) throw refused(`src/server/rust.ts already names \`${binding}\`. Nothing was changed.`)
+  const imported = new RegExp(`import\\s*\\{[^}]*\\b${factory}\\b[^}]*\\}\\s*from\\s*['"]@weft-js/start/rust['"]`).test(had)
+  const nextRust = `${imported ? had : had.replace(/^((?:\/\/.*\n)*)/, `$1import { ${factory} } from '@weft-js/start/rust'\n`)}${had.endsWith('\n') ? '' : '\n'}\nexport const ${binding} = ${call}\n`
+
+  const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+  const needsZod = !pkg.dependencies?.zod && !pkg.devDependencies?.zod
+  const gitignore = join(root, '.gitignore')
+  const ignored = existsSync(gitignore) && /^\/?target\/?$|^\*\*\/target\/?$/m.test(readFileSync(gitignore, 'utf8'))
+  const actions = [`create crates/${name}`, `create src/server/${name}.ts`, `add \`${binding}\` to src/server/rust.ts`, ...(needsZod && install ? ['install zod'] : []), ...(ignored ? [] : ['ignore target/']), 'this crate needs Rust (`cargo`, from rustup.rs); the rest of weft does not', 'next: `weft check`, then `weft dev`']
+  if (dryRun) return { ok: true, feature: 'rust', service: name, kind: factory, actions, dryRun: true }
+
+  const crate = await weftCrate(root, dir)
+  const write = (file, text) => {
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, text)
+  }
+  write(join(dir, 'Cargo.toml'), manifest(name, crate, remote))
+  write(join(dir, 'build.rs'), `fn main() {\n    weft::build::generate("${name}");\n}\n`)
+  write(join(dir, 'rust-toolchain.toml'), `[toolchain]\nchannel = "${TOOLCHAIN}"\n${remote ? '' : 'targets = ["wasm32-unknown-unknown"]\n'}`)
+  write(join(dir, 'src', remote ? 'main.rs' : 'lib.rs'), body(lib(name), remote))
+  write(module, fn(name, binding))
+  write(rustFile, nextRust)
+  if (!ignored) writeFileSync(gitignore, `${existsSync(gitignore) ? readFileSync(gitignore, 'utf8').replace(/\n?$/, '\n') : ''}target/\n`)
+  if (needsZod && install) installSpecs(['zod'])
+  return { ok: true, feature: 'rust', service: name, kind: factory, actions }
+}