@weft-js/cli 0.1.0 → 0.1.2

package/docs/plugins.md

@@ -8,8 +8,8 @@ own diagnostics and `weft add` steps. It uses only what any plugin can use, and
 
 ```
 packages/pay/                     packages/pay/ (`src/stripe.ts`)
-  plugin.mjs       the manifest     plugin.mjs       a `pay.rail` provider
-  src/index.ts     client-safe      src/index.ts     stripeRail(options)
+  plugin.mjs       the manifest     plugin.mjs  `pay.rail` provider
+  src/index.ts     client-safe      src/index.ts  stripeRail(options)
   src/server.ts    the ledger
   src/test.ts      fakePay, payRailSuite
   src/checks.mjs   PAY-codes
@@ -24,8 +24,12 @@ A rail is how a payment happens. `fakePay` is a second rail, which is how you kn
 
 ```js
 export const pay = definePlugin({
-  name: '@weft-js/pay', version: '0.1.0', weft: '*', namespace: 'PAY', permissions: {},
-  contribute: () => ({ provides: [...], diagnostics, check, docs, setup, agents, catalog, map }),
+  name: '@weft-js/pay',
+  version: '0.1.0', weft: '*', namespace: 'PAY', permissions: {},
+  contribute: () => ({
+    provides: [...], diagnostics, check, docs, setup,
+    agents, catalog, map,
+  }),
 })
 ```
 
@@ -42,8 +46,18 @@ imports lazily, on that side only. That's why an app that doesn't use a plugin c
 Pay provides `server.extension`, the slot for anything that needs a server presence:
 
 ```js
-provide(defineSlot({ id: 'server.extension', version: 1, cardinality: 'keyed', sides: ['server'] }),
-  { key: 'pay', sides: { server: { module: '@weft-js/pay/server', export: 'extension' } } })
+provide(
+  defineSlot({
+    id: 'server.extension', version: 1,
+    cardinality: 'keyed', sides: ['server'],
+  }),
+  {
+    key: 'pay',
+    sides: { server: {
+      module: '@weft-js/pay/server', export: 'extension',
+    } },
+  },
+)
 ```
 
 The key is the mount: `/_weft/x/pay/...`. A keyed provider also needs `src/<key>.server.ts`, the app's own configuration, and
@@ -82,7 +96,11 @@ and a good template for a provider.
 `diagnostics` declares each code: severity, what it catches, the fix. `check` finds them:
 
 ```js
-check: { include: ['src/**/*.{ts,tsx}'], run: ctx => import('./src/checks.mjs').then(c => c.run(ctx)) }
+check: {
+  include: ['src/**/*.{ts,tsx}'],
+  run: ctx => import('./src/checks.mjs')
+    .then(c => c.run(ctx)),
+}
 ```
 
 `run(ctx)` gets `files`, `read`, `exists`, `jsx`, `slots`, and returns findings: `{ code, file, start, end, why, help?, fix? }`.
@@ -108,9 +126,14 @@ sees what a user sees. It's imported from `@weft-js/pay/test`, since core can't
 ```js
 export const setup = {
   with: ['@weft-js/pay/stripe'],     // added too
-  needs: ['db', 'auth'],                 // refused, with nothing changed, until they're there
+  // Refused without changes until these are present.
+  needs: ['db', 'auth'],
   run({ engine, layer, read }) {
-    return { files: {...}, edits: {...}, env: { STRIPE_SECRET_KEY: 'sk_test_placeholder' }, next: ['...'] }
+    return {
+      files: {...}, edits: {...},
+      env: { STRIPE_SECRET_KEY: 'sk_test_placeholder' },
+      next: ['...'],
+    }
   },
 }
 ```

package/docs/props.md

@@ -7,10 +7,21 @@ Leave a component's props unannotated. weft infers them from its callers and its
 
 ```tsx
 function Row(props) {
-  return <li><button type="button" onClick={props.onPick}>{props.label.toUpperCase()}</button></li>
+  const { label, onPick } = props
+  return (
+    <li>
+      <button type="button" onClick={onPick}>
+        {label.toUpperCase()}
+      </button>
+    </li>
+  )
 }
 export default function List() {
-  return <ul><Row label="One" onPick={() => console.log('picked one')} /></ul>
+  return (
+    <ul>
+      <Row label="One" onPick={() => console.log('picked one')} />
+    </ul>
+  )
 }
 ```
 

package/docs/reactivity.md

@@ -0,0 +1,26 @@
+# Reading reactive values
+
+`state(initial)` returns a writable `State<T>`. Read or assign its `.value`.
+`derived(fn)` returns a read-only `Derived<T>`. Read `.value` to evaluate it and
+track its dependencies.
+
+Use `memo(fn)` when a caller needs an accessor instead of a box:
+
+```ts
+import { derived, memo, state } from '@weft-js/core'
+
+const count = state(1)
+const doubled = derived(() => count.value * 2)
+const readDoubled = memo(() => count.value * 2)
+
+console.log(doubled.value, readDoubled()) // 2, 2
+```
+
+Both forms cache their result and refresh it when a dependency changes. `memo`
+returns a function, so call it; it has no `.value` property. The compiler also uses
+this accessor form to cache component children.
+
+For side effects, `watch(source, callback)` tracks reads in `source`. Keep the
+source pure and give reactive work an owner with a component or `createRoot`.
+Graph tracking, mount queues and renderer helpers belong to
+`@weft-js/core/internal`; application code uses the public lifecycle APIs.

package/docs/rules.md

@@ -1,32 +1,39 @@
 ```tsx
 import { derived } from '@weft-js/core'
 
-export function Cart({ items, taxRate }: { items: { id: string; name: string; price: number }[]; taxRate: number }) {
-  const subtotal = derived(() => items.reduce((s, i) => s + i.price, 0))
+export function Cart({ items, taxRate }: {
+  items: { id: string; name: string; price: number }[]
+  taxRate: number
+}) {
+  const subtotal = derived(() =>
+    items.reduce((s, i) => s + i.price, 0),
+  )
   const total = derived(() => subtotal.value * (1 + taxRate))
   return (
     <section>
-      <ul>{items.map(item => <li key={item.id}>{item.name}</li>)}</ul>
+      <ul>
+        {items.map(item => <li key={item.id}>{item.name}</li>)}
+      </ul>
       <p>{total.value.toFixed(2)}</p>
     </section>
   )
 }
 ```
 
-1. **State is a box. Read and write `.value`.** Everywhere, JSX included (W015).
-2. **Anything computed from other values is `derived`.** Not in a `watch` or the component body (W001).
-3. **JSX is always live.** Every `{expr}` and attribute re-evaluates when what it reads changes.
-4. **Props are always current.** Destructure them (one level, W006). Read them in `derived`, `watch`, JSX or handlers.
-   `const x = props.y` is a live read-only alias. `let x = props.y` and `props.y =` write locally; only `bind:y={box}`
+1. **State is a box. Read and write `.value`**, including in JSX (W015).
+2. **Compute from other values with `derived`**, not `watch` or the component body (W001).
+3. **JSX is live.** Each `{expr}` and attribute re-evaluates when its inputs change.
+4. **Props are current.** Destructure one level (W006). Read in `derived`, `watch`, JSX or handlers.
+   `const x = props.y` is a live read-only alias; `let x = props.y` and `props.y =` write locally; only `bind:y={box}`
    writes out.
-5. **The component body runs once.** No early returns on state (W040), no `let` counters (W041). Branch in JSX.
+5. **The body runs once.** No state-based early returns (W040) or `let` counters (W041). Branch in JSX.
 6. **Pass a box only to give write access** (`value={coupon}`, child prop typed `State<string | null>`), or so list
    rows can read one entry: `cart.get(p.id)` re-runs one row, `cart[p.id]` or `cart.value[p.id]` re-runs them all
    (W017), in the list and in the row component alike.
-7. **Lists and conditionals the way you know them**: `.map` with `key` (W010), `&&`, ternaries. Keep list items
-   stable: replace only the item that changed (`p.id === id ? { ...p, price } : p`), never `({ ...p })` every item
+7. **Lists and conditionals**: `.map` with `key` (W010), `&&`, ternaries. Keep items
+   stable: replace only the changed item (`p.id === id ? { ...p, price } : p`), never `({ ...p })` every item
    (W014).
 8. **Copy a prop into state with `state.linked(() => prop)`**, not `state(prop)` (W005). `untrack(() => …)` is a
-   snapshot that never updates: not for anything you render (W018).
+   snapshot that never updates: never render it (W018).
 9. **Side effects go in `watch(() => source, value => cleanup?)`**; DOM work in `onMount`. `flush()` applies pending
    DOM updates now.

package/docs/rust.md

@@ -37,10 +37,16 @@ import { z } from 'zod'
 import { search } from './rust'
 
 export const searchDocs = query({
-  input: z.object({ q: z.string().trim().min(1).max(200), limit: z.int().min(1).max(50).default(10) }),
-  output: z.array(z.object({ id: z.string(), title: z.string(), score: z.number() })),
+  input: z.object({
+    q: z.string().trim().min(1).max(200),
+    limit: z.int().min(1).max(50).default(10),
+  }),
+  output: z.array(z.object({
+    id: z.string(), title: z.string(), score: z.number(),
+  })),
   tags: ['docs'],
-  impl: search,          // was: run: ({ input }) => rank(input.q, input.limit)
+  // Was: run: ({ input }) => rank(input.q, input.limit)
+  impl: search,
 })
 ```
 
@@ -54,8 +60,10 @@ serde = { version = "1", features = ["derive"] }
 tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
 weft = { path = "../../node_modules/@weft-js/start/crate" }
 
-[build-dependencies]
-weft = { path = "../../node_modules/@weft-js/start/crate", default-features = false, features = ["build"] }
+[build-dependencies.weft]
+path = "../../node_modules/@weft-js/start/crate"
+default-features = false
+features = ["build"]
 ```
 
 ```rust
@@ -65,13 +73,18 @@ fn main() { weft::build::generate("search"); }
 
 ```rust
 // crates/search/src/main.rs
-weft::contract!();          // types and a `Service` trait, generated from your Zod: never hand-written
+// Types and the `Service` trait are generated from Zod.
+weft::contract!();
 use contract::*;
 
 struct Search;
 
 impl Service for Search {
-    async fn search_docs(&self, ctx: weft::Ctx, input: SearchDocsInput) -> Result<SearchDocsOutput, weft::Error> {
+    async fn search_docs(
+        &self,
+        ctx: weft::Ctx,
+        input: SearchDocsInput,
+    ) -> Result<SearchDocsOutput, weft::Error> {
         ctx.touch("docs");
         Ok(vec![])
     }
@@ -97,7 +110,11 @@ use contract::*;
 
 struct Media;
 impl Service for Media {
-    async fn thumbnail(&self, ctx: weft::Ctx, input: ThumbnailInput) -> Result<ThumbnailOutput, weft::Error> { /* … */ }
+    async fn thumbnail(
+        &self,
+        ctx: weft::Ctx,
+        input: ThumbnailInput,
+    ) -> Result<ThumbnailOutput, weft::Error> { /* … */ }
 }
 
 weft::native!(contract::functions(Media));
@@ -106,7 +123,8 @@ weft::native!(contract::functions(Media));
 ```ts
 // src/server/rust.ts
 import { native } from '@weft-js/start/rust'
-export const media = native('media')          // options: timeout, claims, validate, as for remote()
+// Options: timeout, claims, validate, as for remote().
+export const media = native('media')
 ```
 
 - An addon runs each call on the worker pool, so a long one doesn't hold the event loop. `native()` sizes the pool to the
@@ -147,13 +165,24 @@ All three have `ctx.touch(table)`, `ctx.tag(tag)`, `ctx.remaining()`, `ctx.cance
 
 <!-- example: skip a fragment of src/server/docs.ts -->
 ```ts
-export const getDoc = query({ input, output, errors: { NotFound: z.object({ id: z.string() }) }, impl: search })
-// a TS body raises the same thing: run: () => raise('NotFound', { id })
+export const getDoc = query({
+  input, output,
+  errors: { NotFound: z.object({ id: z.string() }) },
+  impl: search,
+})
+// A TS body raises the same thing:
+// run: () => raise('NotFound', { id })
 ```
 
 ```rust
-async fn get_doc(&self, ctx: weft::Ctx, input: GetDocInput) -> Result<GetDocOutput, GetDocError> {
-    Err(GetDocError::NotFound(GetDocNotFound { id: input.id.to_string() }))
+async fn get_doc(
+    &self,
+    ctx: weft::Ctx,
+    input: GetDocInput,
+) -> Result<GetDocOutput, GetDocError> {
+    Err(GetDocError::NotFound(GetDocNotFound {
+        id: input.id.to_string(),
+    }))
 }
 ```
 
@@ -189,11 +218,12 @@ request id, and the detail stays in the sidecar's log.
 ```ts
 // weft.config.ts
 rust: {
-  unions: 'allow',                                   // let plain object unions through (R102)
+  unions: 'allow', // let plain object unions through (R102)
   services: {
-    search: { crate: 'native/search' },              // default: crates/<name>
-    core: { external: true },                        // built and run elsewhere: no cargo here
-    imaging: { wasm: false },                        // links C, and this host has an addon: no fallback (R104)
+    search: { crate: 'native/search' }, // default: crates/<name>
+    core: { external: true }, // built and run elsewhere: no cargo
+    // Links C; this host has an addon, so no fallback (R104).
+    imaging: { wasm: false },
   },
 }
 ```

package/docs/start-short.md

@@ -1,8 +1,9 @@
-`@weft-js/start` app: file routes in `src/routes` (`_layout.tsx`, `[id].tsx`, `load`, `meta`), server functions in `src/server/**` or `*.server.ts`. Read `weft docs start` first. Import your own code as `#/server/todos` (`src/server/todos`); generated files are `weft:slot/<id>` and `weft:tokens/<name>`.
+`@weft-js/start` app: file routes in `src/routes` (`_layout.tsx`, `[id].tsx`, `load`, `meta`), server functions in `src/server/**` or `*.server.ts`. Import your own code as `#/server/todos` (`src/server/todos`); generated files are `weft:slot/<id>` and `weft:tokens/<name>`.
 
 - **Reads:** `query({ tags: ['todos'], auth: 'user', run: ({ ctx }) => ctx.db.select().from(todos) })`. In a component `todos().value ?? []`; in `load` and handlers `await todos.fetch()`.
 - **Writes:** `mutation({ input, auth: 'user', invalidates: ['todos'], optimistic, run })`.
 - **Database:** Drizzle; `await` every statement. Schema change: `weft db generate` (Q015). Inputs: `schemas.todos.insert.pick({ title: true })`.
-- **Auth:** `ctx.user` is the user or `null`; `auth: 'user'` refuses anyone else (A002). A guard is `redirect('/login')` in a layout's `load`. `run` must still check who owns a row.
+- **Auth:** `ctx.user` is the user or `null`; `auth: 'user'` refuses anyone else (A002). A guard is `redirect('/login')` in a layout's `load`. `run` must still check who owns a row. Login is a database session: a signed cookie caches it for pages for 5 minutes, and mutations read the database (`session.cookieCache` in `createAuth`). JWTs are API-only (`api: { functions }`).
 - **Never** copy query results into `state`, import `db` from a component (Q012), `fetch` `/_weft/*`, or poll (`todos.live()`; rooms: `channel`).
+- **Navigation:** chrome shared across sections (sidebar, tabs) lives in the one layout above them, following `currentPath()`; a `_layout.tsx` per section is replaced on every move between sections. Route changes show a skeleton from the page's markup; `export const skeleton = Named` (a local function of plain markup: div/section/p/h1/ul/li…, class and data-* only) overrides it.
 - **Every page sets `meta` as you build it**, from `data` and `params`: `weft docs meta`.