@weft-js/cli 0.1.1 → 0.1.3

package/docs/state.md

@@ -3,14 +3,24 @@
 Every reactive function in one place. The rules for using them are `weft docs rules`; props are `weft docs props`.
 
 ```tsx
-import { derived, flush, onCleanup, onMount, state, watch } from '@weft-js/core'
+import {
+  derived,
+  flush,
+  onCleanup,
+  onMount,
+  state,
+  watch,
+} from '@weft-js/core'
 
 export function Counter() {
   const count = state(0)
   const label = derived(() => `Clicked ${count.value} times`)
   let input: HTMLInputElement | undefined
 
-  watch(() => label.value, text => { document.title = text; return () => (document.title = 'App') })
+  watch(() => label.value, text => {
+    document.title = text
+    return () => (document.title = 'App')
+  })
   onMount(() => input?.focus())
   onCleanup(() => console.log('Counter removed'))
 
@@ -21,8 +31,13 @@ export function Counter() {
   }
   return (
     <p>
-      <button type="button" onClick={() => count.value++}>{label.value}</button>
-      <input ref={(n: HTMLInputElement) => (input = n)} aria-label="Note" />
+      <button type="button" onClick={() => count.value++}>
+        {label.value}
+      </button>
+      <input
+        ref={(n: HTMLInputElement) => (input = n)}
+        aria-label="Note"
+      />
       <button type="button" onClick={reset}>Reset</button>
     </p>
   )
@@ -66,9 +81,20 @@ import { defineState, derived, state } from '@weft-js/core'
 import { z } from 'zod'
 
 export const cart = defineState('cart', () => {
-  const lines = state<Record<string, number>>({}, { persist: { in: 'local', schema: z.record(z.string(), z.number()), version: 1 }, sync: 'tabs' })
-  const count = derived(() => Object.values(lines.value).reduce((a, b) => a + b, 0))
-  const add = (id: string) => lines.set(d => { d[id] = (d[id] ?? 0) + 1 })
+  const lines = state<Record<string, number>>({}, {
+    persist: {
+      in: 'local',
+      schema: z.record(z.string(), z.number()),
+      version: 1,
+    },
+    sync: 'tabs',
+  })
+  const count = derived(() =>
+    Object.values(lines.value).reduce((a, b) => a + b, 0),
+  )
+  const add = (id: string) => lines.set(d => {
+    d[id] = (d[id] ?? 0) + 1
+  })
   return { lines, count, add }
 }, { history: { limit: 100 } })
 ```

package/docs/style.md

@@ -9,20 +9,43 @@ import { group } from '@weft-js/core/style'
 
 /** A summary card for one order in a list. */
 export const orderCard = group('order-card', {
-  base: { surface: 'raised', pad: 'group', radius: 'surface', layout: 'stack', gap: 'related' },
-  axes: { status: { open: { tone: 'info' }, shipped: { tone: 'positive' }, late: { tone: 'critical' } } },
-  parts: { title: { text: 'title' }, meta: { text: 'caption', ink: 'subtle' } },
+  base: {
+    surface: 'raised',
+    pad: 'group',
+    radius: 'surface',
+    layout: 'stack',
+    gap: 'related',
+  },
+  axes: {
+    status: {
+      open: { tone: 'info' },
+      shipped: { tone: 'positive' },
+      late: { tone: 'critical' },
+    },
+  },
+  parts: {
+    title: { text: 'title' },
+    meta: { text: 'caption', ink: 'subtle' },
+  },
   states: { selected: { ring: 'accent' } },
   defaults: { status: 'open' },
 })
 
-type Order = { name: string; date: string; status: 'open' | 'shipped' | 'late' }
+type Order = {
+  name: string
+  date: string
+  status: 'open' | 'shipped' | 'late'
+}
 
-export function OrderCard(props: { order: Order; selected: boolean }) {
+export function OrderCard(props: {
+  order: Order
+  selected: boolean
+}) {
+  const { order, selected } = props
   return (
-    <article {...orderCard({ status: props.order.status, selected: props.selected })}>
-      <h3 {...orderCard.title}>{props.order.name}</h3>
-      <p {...orderCard.meta}>{props.order.date}</p>
+    <article {...orderCard({ status: order.status, selected })}>
+      <h3 {...orderCard.title}>{order.name}</h3>
+      <p {...orderCard.meta}>{order.date}</p>
     </article>
   )
 }

package/docs/surface.md

@@ -11,19 +11,32 @@ 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))
+  // Or defineSurface<{ data: number[] }, 'canvas2d'>({ ... })
+  props: z.object({ data: z.array(z.number()) }),
+  // Runs once; props.data is live, so never destructure it.
+  setup(s, props) {
+    // Repaints on box changes; the canvas is cleared first.
+    s.draw(() => {
+      const { width, height } = s.size.value // CSS px, live
+      // Live theme colours: .css, or .linear for shaders.
+      s.ctx.fillStyle = s.tokens.accent.css
+      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" />
+  return (
+    <Surface
+      use={Bars}
+      data={rows.value}
+      aspect="16/9"
+      label="Sales by month"
+    />
+  )
 }
 ```
 
@@ -33,21 +46,43 @@ A control beside the surface needs only a box and a live prop. Nothing re-render
 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 the kind too, so s.ctx is typed.
+export const Stars = defineSurface<{ density: number }, 'canvas2d'>({
   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)
+    // Every tick; reading props.density here keeps it live.
+    s.frame(({ seconds }) => {
+      for (let i = 0; i < props.density; i++) {
+        const { width, height } = s.size.value
+        const x = (i * 37 + seconds * 20) % width
+        const y = (i * 91) % height
+        s.ctx.fillRect(x, y, 1, 1)
+      }
     })
   },
 })
 
 export function Sky() {
   const density = state(100)
+  const setDensity = (e: Event & {
+    currentTarget: HTMLInputElement
+  }) => (density.value = e.currentTarget.valueAsNumber)
   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 />
+    <input
+      type="range"
+      min="10"
+      max="500"
+      value={density.value}
+      onInput={setDensity}
+      aria-label="Density"
+    />
+    <Surface
+      use={Stars}
+      density={density.value}
+      aspect="16/9"
+      decorative
+    />
   </>
 }
 ```
@@ -78,7 +113,10 @@ Never `fillText` (X010). `s.text()` keeps a real element over the text, so selec
 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 })
+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, ... })`.
@@ -95,7 +133,13 @@ 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 {
+  canvasCalls,
+  clock,
+  fakeMeasure,
+  flush,
+  render,
+} from '@weft-js/core/test'
 import { expect, test } from 'vitest'
 import { Page } from './Page'   // the Bars page above
 
@@ -104,7 +148,9 @@ test('draws a bar per value', async () => {
   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)
+  const canvas = document.querySelector('canvas')!
+  const bars = canvasCalls(canvas).filter(c => c.name === 'fillRect')
+  expect(bars).toHaveLength(3)
 })
 ```
 

package/docs/testing.md

@@ -3,7 +3,8 @@
 A new app has no test runner. Add one:
 
 ```bash
-npm install -D vitest jsdom @testing-library/dom @testing-library/user-event
+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) -->
@@ -12,7 +13,10 @@ npm install -D vitest jsdom @testing-library/dom @testing-library/user-event
 import weft from '@weft-js/core/vite'
 import { defineConfig } from 'vitest/config'
 
-export default defineConfig({ plugins: [weft()], test: { environment: 'jsdom' } })
+export default defineConfig({
+  plugins: [weft()],
+  test: { environment: 'jsdom' },
+})
 ```
 
 Then `npx vitest run`. A test:
@@ -24,14 +28,20 @@ import { expect, test } from 'vitest'
 
 function Cart() {
   const count = state(0)
-  return <button type="button" onClick={() => count.value++}>Cart ({count.value})</button>
+  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 })
+  expect(screen.getByRole('button', { name: 'Cart (1)' }))
+    .toBeTruthy()
+  const click = () => user.click(screen.getByRole('button'))
+  await expect(click).toTouchAtMost(1, { runs: 2 })
 })
 ```
 

package/docs/theme.md

@@ -0,0 +1,182 @@
+# Theme: changing warp's look
+
+Three levels, in order. Stop at the first that gets you there; each one keeps the contrast check.
+
+1. `warp({ seed, dials, fields, radius, fonts, tokens })` in the weft config. Checked by D010 at the stops `dials` leave.
+   For your own names, per-element looks and named themes: `colors`, `system`, `parts`, `themes` (below).
+2. `src/theme.css`, unlayered: `[data-scope]` and `[data-part]` rules beat warp with no `!important`.
+3. Your own component, with warp's tokens.
+
+The Theme studio on the docs site (`/components/theme-studio`) edits level 1 with live components and contrast
+ratios, and copies the result as `weft.config.ts`.
+
+## warp() options
+
+| Option | Does |
+|---|---|
+| `seed.accent` | The hue family: `#rrggbb`, a name from `colors`, or `{ hue, chroma }`. Each theme solves its own lightness, and `weft build` prints where it landed |
+| `seed.neutral` | The tint of pages, surfaces and text, `#rrggbb` or `{ hue, chroma }` |
+| `dials` | Default `expression` (quiet balanced vivid), `density`, `flair`, `theme`. With `theme: 'light'`, dark isn't checked |
+| `fields` | `floating` (the default: the label floats in a notch) or `classic` (the label above the box) |
+| `radius` | `sharp` (2px), `soft`, `round`. Below 2px, set the radius tokens |
+| `fonts` | `body`, `display`, `mono`: a family or a whole stack |
+| `tokens` | Any `--warp-*`, set on every scope. Colours are `#rrggbb`, `oklch()`, `color-mix()` or `light-dark()` |
+
+App-wide values go in `warp()`. A `--warp-color-*` set in CSS on `:root` skips the check and is undone inside any scope that
+sets a dial, such as a Table's density.
+
+## colors, system, parts, themes
+
+| Option | Does |
+|---|---|
+| `colors` | `{ brand: '#e8590c' }`: `--warp-color-brand`, a tone (`tone="brand"`), and `bg-brand` via `.weft/tokens/warp.tailwind.css`. Lowercase names, `#rrggbb` |
+| `system` | The scales: `radius`, `space`, `pad`, `control`, `font`, `shadow`, `duration`, `ease`, `border`, `icon`, `text.<role>` |
+| `parts` | One element, at rest and per state (`hover focus press active open disabled`). Numbers are px (ms for `duration`); names are system steps or `colors` |
+| `themes` | `{ ocean: { seed, colors, system, parts } }` under `[data-palette="ocean"]`. `dials.palette` sets the default; `setPalette()` switches |
+
+Every part takes `bg text border borderWidth radius padding paddingX paddingY gap margin height minHeight width size
+shadow opacity scale duration easing font fontSize weight leading tracking case`. A part's own keys add to those or
+replace one of the same name with its own meaning (an underline's `width` is its thickness):
+
+| Part | For | Own keys | States |
+|---|---|---|---|
+| `button` | Button and ButtonLink | `bg` `text` `border` `radius` | hover focus press active open disabled |
+| `button.soft` |  | `bg` `text` `border` | hover focus press active open disabled |
+| `button.outline` |  | `bg` `text` `border` | hover focus press active open disabled |
+| `button.ghost` |  | `bg` `text` `border` | hover focus press active open disabled |
+| `button.frame` |  | `bg` `text` `border` | hover focus press active open disabled |
+| `button.link` |  | `bg` `text` `border` | hover focus press active open disabled |
+| `iconButton` | A button that holds only an icon (copy, close, menu): square by default | `radius` `icon` | hover focus press active open disabled |
+| `copy` | CopyButton | `radius` | hover focus press active open disabled |
+| `close` | The close button of a dialog, sheet, drawer, alert or side nav | — | hover focus press active open disabled |
+| `link` | Link: the text link with the drawn underline | — | hover focus press active open disabled |
+| `link.underline` |  | `color` `width` `offset` | hover focus |
+| `nav` | Nav: the row or column of links with the sliding bar | — | — |
+| `nav.item` |  | — | hover focus press active open disabled |
+| `nav.underline` |  | `color` `width` `duration` | — |
+| `tabs` | Tabs | — | — |
+| `tabs.tab` |  | `radius` | hover focus press active open disabled |
+| `tabs.underline` |  | `color` `width` | — |
+| `pill` | Pill and PillLink | `radius` | hover focus press active open disabled |
+| `badge` | Badge | — | hover focus press active open disabled |
+| `chip` | Chip | `radius` | hover focus press active open disabled |
+| `card` | Card and Surface | — | hover focus press active open disabled |
+| `field` | Text fields, selects and pickers | `bg` `radius` | hover focus press active open disabled |
+| `field.label` |  | `text` | hover focus |
+| `sweep` | The sweep: the stroke that draws round a control on hover and focus, and the text while it runs | `stroke` `base` `text` `width` `duration` | — |
+| `dialog` | Modal and Dialog | — | — |
+| `sheet` | Sheet and Drawer | — | — |
+| `popover` | Popover, Menu and Tooltip panels | — | — |
+| `toast` | Toast | — | — |
+
+A solid's `bg` and `text` move its tone channels, so hover, pull-out and sweep follow. `hover.bg` is the hover fill. Text
+set on a fill set in the same part is checked like a seed: below 4.5:1 is D010. Each named theme's seed is fitted the
+same way as the main one.
+
+```ts
+warp({
+  colors: { brand: '#e8590c', ink: '#1b1b1f' },
+  parts: {
+    button: {
+      bg: 'brand',
+      text: 'ink',
+      radius: 'pill',
+      hover: { bg: 'ink', text: 'white' },
+    },
+    sweep: { stroke: 'brand', width: 2 },
+    nav: {
+      item: { hover: { text: 'brand' } },
+      underline: { color: 'brand', width: 3 },
+    },
+  },
+  themes: {
+    ocean: {
+      seed: { accent: '#0b7285' },
+      colors: { brand: '#0b7285' },
+    },
+  },
+})
+```
+
+## Brutalist
+
+```ts
+warp({
+  dials: { expression: 'quiet', flair: 'none' },
+  fonts: {
+    display: 'ui-monospace, monospace',
+    body: 'ui-monospace, monospace',
+  },
+  tokens: {
+    '--warp-radius-mark': '0px',
+    '--warp-radius-control': '0px',
+    '--warp-radius-surface': '0px',
+  },
+})
+```
+
+```css
+/* src/theme.css */
+[data-scope="button"] {
+  --warp-tone-edge: var(--warp-color-text);
+  border-width: 2px;
+  box-shadow: 4px 4px 0 var(--warp-color-text);
+}
+[data-scope="surface"] {
+  border: 2px solid var(--warp-color-text);
+  box-shadow: none;
+}
+```
+
+Raw colours and shadows in `src/theme.css` or on a `[data-scope]` rule are D001 and D003 warnings, not errors.
+
+## Warm editorial
+
+```ts
+warp({
+  seed: { accent: '#9a3412', neutral: { hue: 70, chroma: 0.03 } },
+  dials: { expression: 'vivid' },
+  fonts: { display: '"Iowan Old Style", Georgia, serif' },
+})
+```
+
+## An exact brand
+
+A seed gives the hue, not the colour. To pin it, set the fill and its hover for both themes. One alone never re-derives the other.
+
+```ts
+warp({
+  seed: { accent: '#c8102e' },
+  tokens: {
+    '--warp-color-accent-solid': 'light-dark(#c8102e, #e5484d)',
+    '--warp-color-accent-solid-hover': 'light-dark(#a50d26, #f2666a)',
+  },
+})
+```
+
+## Button tone channels
+
+A rule that sets a button's `background` leaves its hover layer on the accent. Set the channels and fill, ink, edge and hover
+stay together, at every emphasis:
+
+| Channel | Paints |
+|---|---|
+| `--warp-tone-fill` | The background |
+| `--warp-tone-ink` | The text |
+| `--warp-tone-edge` | The border |
+| `--warp-tone-layer` | The hover layer that wipes across |
+
+```css
+[data-scope="button"][data-emphasis="solid"] {
+  --warp-tone-fill: #111111;
+  --warp-tone-ink: #ffffff;
+  --warp-tone-layer: #333333;
+}
+```
+
+The channels are on Button only. Fields read `--warp-field-*`, tables `--warp-table-*`.
+
+## D010
+
+Each failing pair is named with its stop. Change that token or the seed, or limit the stops with `dials`. `weft build` stops on
+it, because a refused config would ship warp's default look.

package/docs/ui-state.md

@@ -11,8 +11,13 @@ 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
+  const seen = derived(() =>
+    row.remote.value.hover ? 'someone is here' : '',
+  )
+  // Only your own hover triggers the request.
+  watch(() => row.hover.value, on => {
+    if (on) void fetch(`/api/todos/${todo.id}`)
+  })
   return (
     <li>
       <Checkbox ui={row}>{todo.title}</Checkbox>
@@ -53,7 +58,10 @@ Sharing with other clients is off until you say who may, in `src/realtime.server
 ```ts
 import { realtime } from '@weft-js/start'
 
-export default realtime({ share: ({ ctx, key }) => ctx.user !== null && key.startsWith('todo:') })
+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:
@@ -61,11 +69,16 @@ That rule runs once per key. If it reads a database, a 200-row list means 200 qu
 ```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[]>
+// One query 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) : []) },
+  share: {
+    keys: async ({ ctx, keys }) =>
+      ctx.user ? visibleKeys(ctx.user.id, keys) : [],
+  },
 })
 ```
 

package/docs/verify.md

@@ -46,3 +46,16 @@ touched.
 
 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.
+
+
+## Indexing intent
+
+For a site intended for public search, declare
+`build: { audit: { indexing: 'public' } }`. L024 then fails the build or audit if
+robots metadata or an HTTP X-Robots-Tag header says noindex. `private` or the
+backward-compatible `auto` leaves this a warning; neither removes a directive.
+After deployment, run `weft audit --url https://your-site.example --indexing public`:
+a host or proxy may add a header that a local build cannot see. Preserve intentional
+preview/private exclusions. A noindex finding is an indexing policy issue, not
+chat-agent traffic; use a clean profile before attributing other audit failures
+to application or framework code.

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "@weft-js/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "The weft command: dev, build, check, the agent layer and the MCP server",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ravonus/weft.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/Ravonus/weft/tree/main/packages/cli#readme",
+  "bugs": {
+    "url": "https://github.com/Ravonus/weft/issues"
+  },
   "type": "module",
   "bin": {
     "weft": "./bin/weft.mjs"
@@ -15,14 +24,14 @@
     "node": ">=26"
   },
   "dependencies": {
-    "@weft-js/create": "0.1.1",
+    "@weft-js/create": "0.1.3",
     "axe-core": "4.14.0",
     "typescript": "6.0.3",
     "yaml": "2.9.1",
     "zod": "4.6.7"
   },
   "peerDependencies": {
-    "@weft-js/core": "^0.1.1"
+    "@weft-js/core": "^0.1.3"
   },
   "publishConfig": {
     "access": "public"
@@ -38,4 +47,4 @@
     "README.md",
     "LICENSE"
   ]
-}
+}

package/src/add/config.mjs

@@ -0,0 +1,93 @@
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import ts from 'typescript'
+import { pluginFactory, pluginName } from '../load-config.mjs'
+import { refused } from './errors.mjs'
+
+/** The import to write: `<pkg>/plugin` when the package has one, and however it exports its factory. */
+function pluginImport(root, pkg) {
+  const require = createRequire(join(root, 'package.json'))
+  const name = pluginName(pkg)
+  for (const spec of [`${pkg}/plugin`, pkg]) {
+    let path
+    try {
+      path = require.resolve(spec)
+    } catch {
+      continue
+    }
+    const factory = pluginFactory(createRequire(import.meta.url)(path), pkg)
+    if (!factory)
+      throw refused(`${spec} exports no plugin factory to call, so nothing was changed.`)
+    return {
+      name: factory.name,
+      line: `import ${factory.named ? `{ ${factory.name} }` : factory.name} from '${spec}'`,
+    }
+  }
+  return { name, line: `import ${name} from '${pkg}'` } // not installed yet: only a dry run gets this far
+}
+
+/** The object literal `export default` gives, directly or through `defineConfig(…)`. */
+function configObject(sf) {
+  for (const st of sf.statements) {
+    if (!ts.isExportAssignment(st)) continue
+    const value = ts.isCallExpression(st.expression) ? st.expression.arguments[0] : st.expression
+    if (value && ts.isObjectLiteralExpression(value)) return value
+  }
+  return null
+}
+
+export function addToTs(root, file, text, pkg) {
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true)
+  const object = configObject(sf)
+  if (!object)
+    throw refused(
+      `${file} doesn't export a plain object, so \`weft add\` can't edit it. Add \`${pkg}\` to \`plugins\` by hand.`,
+    )
+  const { name, line } = pluginImport(root, pkg)
+  const prop = object.properties.find((p) => p.name?.getText(sf) === 'plugins')
+  if (prop && !(ts.isPropertyAssignment(prop) && ts.isArrayLiteralExpression(prop.initializer)))
+    throw refused(
+      `\`plugins\` in ${file} isn't a plain array, so \`weft add\` can't edit it. Add \`${pkg}\` by hand.`,
+    )
+  const edits = []
+  const imports = sf.statements.filter(ts.isImportDeclaration)
+  const after = imports.at(-1)?.end ?? 0
+  edits.push([after, `${imports.length ? '\n' : ''}${line}${imports.length ? '' : '\n'}`])
+  if (prop) {
+    const list = prop.initializer
+    const last = list.elements.at(-1)
+    edits.push(last ? [last.end, `, ${name}()`] : [list.getStart(sf) + 1, `${name}()`])
+  } else {
+    const last = object.properties.at(-1)
+    edits.push(
+      last
+        ? [
+            object.properties.end,
+            `${object.properties.hasTrailingComma ? '' : ','}\n  plugins: [${name}()],`,
+          ]
+        : [object.getStart(sf) + 1, `\n  plugins: [${name}()],\n`],
+    )
+  }
+  return edits
+    .toSorted((a, b) => b[0] - a[0])
+    .reduce((t, [at, insert]) => t.slice(0, at) + insert + t.slice(at), text)
+}
+
+export function addToData(file, text, pkg) {
+  if (file.endsWith('.json')) {
+    const data = JSON.parse(text)
+    data.plugins = [...(data.plugins ?? []), pkg]
+    return `${JSON.stringify(data, null, 2)}\n`
+  }
+  const { parseDocument } = createRequire(import.meta.url)('yaml')
+  const doc = parseDocument(text)
+  if (doc.has('plugins')) doc.addIn(['plugins'], pkg)
+  else doc.set('plugins', [pkg])
+  return doc.toString()
+}
+
+export const listed = (config, pkg) => (config.plugins ?? []).some((p) => p.name === pkg)
+
+/** The config names the package already (imported or listed), which a read can tell without loading it. */
+export const names = (text, pkg) =>
+  new RegExp(`['"]${pkg.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')}(/[\\w-]+)?['"]`).test(text)

package/src/add/errors.mjs

@@ -0,0 +1,2 @@
+export const usageError = (message) => Object.assign(new Error(message), { code: 'E_USAGE' })
+export const refused = (message) => Object.assign(new Error(message), { code: 'E_ADD' })