@velarscript/cli 0.11.1 → 0.12.1

package/skill/ai-skill-node.md

@@ -0,0 +1,301 @@
+# The VelarScript Node AI skill brief
+
+Load this after `velar skill core`. This brief contains only the Node owner’s
+contract. Core does not learn server declarations, path-pattern strings, Node
+capabilities, or application configuration.
+
+## Ownership and application entry
+
+A Node service activates the extension and names one exported `ServeApp`:
+
+```json
+{
+  "formatVersion": 2,
+  "entry": "src/main.vel",
+  "outDir": "dist",
+  "publicDir": "public",
+  "extensions": ["@velarscript/node"],
+  "node": {
+    "app": "app",
+    "host": "127.0.0.1",
+    "port": 3000,
+    "maxBodyBytes": 16777216,
+    "build": {"sourceMaps": false}
+  }
+}
+```
+
+The entry exports application data; it does not need a manually named function
+or top-level `serve(...)` call:
+
+```velar fragment
+import {app as routes} from "./app.vel"
+
+export const app = routes
+```
+
+Use `velar dev` while editing, `velar serve` for checked production runtime
+behavior, and `velar build` for a standalone Node output directory. A direct
+`serve(app, port=0)` call is still correct in integration tests or an embedded
+server.
+
+`@name` keeps its one language-wide role: it qualifies a compiler-owned name
+in the current context. In a `server` block, the available names are `@get`,
+`@post`, `@put`, `@patch`, `@delete`, and `@notFound`. They are not decorators,
+functions, imports, annotations, first-class values, or user extension points.
+
+## Routes and checked inputs
+
+A server is an immutable anonymous route table:
+
+```velar
+import {HttpError, created} from "velar/serve"
+
+type CreateArticle:
+    title: string
+
+export server articles:
+    /// Reports whether this service is ready.
+    @get(p"/health") => {ok: true}
+
+    @get(p"/articles/{id:number}", details: bool = false):
+        if id < 1:
+            throw HttpError(404, {error: "article_not_found"})
+        return {id, details}
+
+    @post(p"/articles", input: CreateArticle):
+        return created({id: 1, title: input.title})
+
+```
+
+The path is written once. A capture such as `{id:number}` declares `id`
+directly in the route body, so never repeat it in the argument list. Captures
+require an ASCII half-width `:` and accept `string`, `number`, `bool`, or
+a named enum. The Node-only `p"..."` prefix marks a compile-time reverse
+matcher; an ordinary string is not accepted, and Core does not recognize this
+prefix.
+
+Unadorned scalar and `List<scalar>` parameters are query inputs. A default makes
+the input optional. Repeated query values populate a List; a repeated scalar is
+a 422 error. On `POST`, `PUT`, or `PATCH`, one concrete Data parameter is the
+checked JSON body. A `Request` parameter explicitly requests the complete
+request, including `queryAll` and cooperative `cancellation`. Ambiguous bodies,
+duplicate declarations, conflicting path shapes, and unsupported path types are
+compile errors.
+
+`@notFound()` is the one application fallback for a path that matches no
+route. It may omit its parameter or accept one explicitly typed `Request`.
+Returning Data keeps status 404; return an explicit response such as
+`json(value, status=410)` to choose another final status. A matched route's
+`HttpError` and framework 405 responses do not enter this fallback. Declare at
+most one on the final application; an app that owns `@notFound` cannot be moved
+under a non-root `prefix`, because a global fallback has no unambiguous prefix
+scope. Compose prefixed route tables first, then declare the fallback on the
+outer `server`. A catch-all route such as `staticFiles("/", ...)` is a matched
+route and therefore owns its own file fallback instead of entering
+`@notFound`.
+
+Use ordinary values for the cases that need more than inference:
+
+```velar
+import {input, provide, security} from "velar/serve"
+
+type User:
+    id: string
+
+type UploadMetadata:
+    title: string
+
+const currentUser = provide(
+    inputs={token: security.bearer()},
+    resolve=async values => {id: values.token},
+)
+
+server account:
+    @get(p"/me",
+        user=input.dependency(currentUser),
+        tenant=input.header("x-tenant"),
+        session=input.cookie("session", default=null),
+    ) => {id: user.id, tenant, session}
+
+    @post(p"/images",
+        metadata=input.form(UploadMetadata),
+        image=input.upload("image", maxBytes=8_388_608),
+    ) => {title: metadata.title, filename: image.filename}
+```
+
+`input.query`, `input.header`, and `input.cookie` select named scalar
+values. `input.form(Type)` checks URL-encoded or multipart fields, including
+repeated fields for `List<scalar>` properties; duplicate scalar fields fail.
+`input.upload` returns an `Upload` whose bytes are valid only for the request
+lifetime; copy or persist them before retaining data. `security.apiKey`,
+`basic`, `bearer`, `oauth2`, and `openId` parse credentials and also
+feed OpenAPI security schemes.
+
+`provide(inputs, resolve, scope="request", release=null, eager=false)` declares
+a dependency as data. A request-scoped provider resolves once per request even
+when injected repeatedly and releases after response/background completion.
+An app-scoped provider may depend only on other app-scoped providers, may be
+eager, and releases during shutdown. Cycles and provider-budget exhaustion fail
+closed. Do not build a controller or container layer around it.
+
+## Composition, lifecycle, and middleware
+
+Compose route tables as values:
+
+```velar fragment
+import {Request, RouteDocumentation, docs, lifecycle, middleware, prefix, staticFiles, use} from "velar/serve"
+
+const service = lifecycle(
+    prefix("/api", articles),
+    startup=async () => null,
+    shutdown=async () => null,
+)
+
+const hardened = use(service, [
+    middleware.trustedHosts(["api.example.com", "127.0.0.1"]),
+    middleware.cors(origins=["https://app.example.com"], credentials=true),
+    middleware.requestId(),
+    middleware.securityHeaders(),
+    middleware.compression(minimumBytes=1024),
+    middleware.timeout(10_000),
+    middleware.concurrency(256),
+])
+
+const articleDocs: RouteDocumentation = {summary: "Read article", tags: ["articles"], errors: Map([[404, "Article not found"]])}
+const routeDocs: Map<string, RouteDocumentation> = Map([["GET /api/articles/{id:number}", articleDocs]])
+
+export server app:
+    ...docs(hardened, title="Article API", version="1.0.0", routes=routeDocs)
+    ...staticFiles("/assets", root="public")
+    @notFound(request: Request) => {error: "route_not_found", path: request.path}
+```
+
+`prefix` changes a literal route prefix; `bodyLimit` narrows one route
+table’s body budget; `use` attaches middleware only to the routes it receives.
+A middleware continuation is single-use. Built-ins also include access logging
+and explicit error recovery. A timeout response does not pretend downstream
+work was cancelled: its request resources remain alive until that work really
+ends, and the runtime caps unfinished timed-out tasks.
+
+`lifecycle` owns paired startup and shutdown hooks. Successful startups unwind
+in reverse order; a failed startup does not run its paired shutdown.
+`background(response, task)` keeps request-scoped resources valid until the
+task finishes. `setCookie` and
+`clearCookie` add checked cookie headers, preserving separate `Set-Cookie`
+fields. Never start long-lived work by
+dropping a Promise; use an owned lifecycle, background task, Worker, or process.
+
+`docs` adds a bundled offline UI and OpenAPI 3.1 JSON. Compiler route types
+and response helpers supply parameter, body, response, content-type, and static
+success-status schemas. Applicable framework-generated 400, 401, 413, 415, and
+422 responses are included automatically; a preceding `///` comment supplies
+the route description. The optional ordinary typed
+`Map<string, RouteDocumentation>` can add
+summary, description, tags, success status, documented error statuses, or hide
+a route, keyed by strings such as `"GET /articles/{id:number}"`. This metadata
+is data, not another `@` category.
+
+## Responses and realtime
+
+Ordinary Data returns JSON. Use the explicit helpers only when transport
+semantics matter: `json`, `created`, `noContent`, `redirect`, `text`,
+`file`, `stream`, `sse`, `background`, `setCookie`, and
+`clearCookie`. `HttpError(status, body, headers=null)` is the expected HTTP
+failure. Unexpected failures are reported on stderr and become an opaque 500.
+
+`HEAD` reuses `GET` without a body. `OPTIONS` and 405 responses publish a
+complete `Allow` header. Final response statuses are 200 through 599; 204 and
+304 are bodyless. Streaming follows write backpressure; each chunk and the
+total stream are bounded. SSE accepts text or checked
+`{data, event?, id?, retry?}` events. Static and returned files are canonical
+root-contained, streamed reads with validators and one byte range.
+
+`velar/websocket.listen({http: app, ...})` serves a `ServeApp` and WebSocket
+upgrades on one native server and owns the application lifecycle. Connections
+are pull-based. Always consume `next()`, handle backpressure, and stop the
+server.
+
+## Tests
+
+Use `velar/server-test` only from `*.test.vel`. It runs the real ServeApp
+router, providers, lifecycle, cookies, forms, uploads, streams, and files in
+process without opening a port:
+
+```velar fragment
+import {client} from "velar/server-test"
+import {expect} from "velar/test"
+import {app} from "./app.vel"
+
+test "health endpoint":
+    const api = await client(app)
+    try:
+        const response = await api.get("/api/health")
+        expect(response.status).toBe(200)
+        expect(await response.text()).toContain("ok")
+    finally:
+        await api.close()
+```
+
+Pass a `Map<Provider, value>` as the second `client` argument to override
+dependencies. Request options support headers, JSON, text, form Maps, and file
+Maps. Test WebSocket behavior through a real local `velar/websocket` server,
+because WebSocket upgrades are a transport boundary rather than an in-process
+HTTP request.
+
+## Memory and ownership rules
+
+The runtime has hard ceilings; application code must preserve them:
+
+- Request bodies are at most 16 MiB, with narrower per-route and project limits.
+  HTTP request bodies, buffered responses, static files, and stream chunks also
+  share one 128 MiB isolated-host budget.
+- Live inbound HTTP requests and middleware concurrency are capped at 4,096.
+  ServeApp routes, request providers, app providers, and timed-out unfinished
+  work have separate count limits.
+- WebSocket queued bytes and pending-send bytes share a 128 MiB budget. Global
+  limits also cover active connections, pending connection objects, queued
+  message objects, and pending send Promises, including zero-byte messages.
+- Multipart parsing reuses bounded body storage; an `Upload` is invalidated
+  when its request scope ends. Provider caches and release lists are explicitly
+  cleared at request or application shutdown.
+- Development rebuilds serialize changes, retain one last-good child, stop the
+  old child before replacing it, and delete temporary build sandboxes.
+
+Set smaller limits for the domain instead of treating framework maxima as
+defaults. Stream large data, consume pull queues promptly, close every owned
+capability, and keep caches explicitly bounded.
+
+## Concurrency and shutdown rules
+
+Concurrency limits are admission control, not a lock around application data.
+The runtime guarantees that an application-scoped provider initializes once,
+concurrent `stop` or `close` calls join the same completion, shutdown refuses
+new work, requests receive cooperative cancellation, and provider release begins
+only after every admitted request has finished its response, timed-out
+continuation, background work, and request cleanup. `stop(grace=30000)` bounds
+the drain wait without releasing live request resources early. WebSocket stop
+closes connections in parallel with a bounded handshake and releases unread
+queues and pending-send reservations.
+
+Application code still owns business-level consistency. Do not use an
+unprotected module-level mutable record as a cross-request database. Put
+multi-write invariants in a database transaction or another capability that
+provides atomic operations. Always await stream writes, allow only one active
+pull from an async iterator, and make retryable handlers idempotent. A
+`middleware.concurrency` limit protects capacity; it does not make a shared
+read-modify-write sequence atomic.
+
+## Node capabilities and finish
+
+Use `velar/fs`, `velar/path`, `velar/process`, `velar/env`,
+`velar/terminal`, `velar/http`, `velar/worker`, and `velar/websocket` instead of
+ambient Node globals. Databases are ordinary external source packages: use the
+engine-neutral `@velarscript/database` model contract and install an adapter
+such as `@velarscript/sqlite`. Third-party packages cross a checked `extern
+module` adapter first; keep `import js unsafe` at one narrow validation
+boundary.
+
+Run `velar format --check`, `velar check`, `velar test`, and
+`velar build`. The complete runnable spelling lives in
+`examples/tour/node/`; current diagnostics outrank this brief.

package/skill/ai-skill-web.md

@@ -0,0 +1,150 @@
+# The VelarScript Web AI skill brief
+
+Load this after `velar skill core`. This file contains only the Web extension's
+contract; Core syntax stays owned by the Core brief. It ships with the
+toolchain and `velar skill web` prints it verbatim.
+
+## Ownership
+
+The manifest activates Web explicitly:
+
+```json
+{
+  "formatVersion": 2,
+  "entry": "src/main.vel",
+  "extensions": ["@velarscript/web"],
+  "web": {"title": "My App"}
+}
+```
+
+`@velarscript/web` owns `component`, JSX, `state`, `computed`, `resource`,
+`action`, `watch`, `look`, `keyframes`, `mount`, Web units, its standard
+modules, and the `web` manifest key. Without that extension these are not Core
+syntax. Web visual builders are named imports from `velar/look`; there is no
+`Look.` namespace.
+
+`@name` keeps the same language-wide role: it qualifies a compiler-owned name
+in the current context. Components own `@mounted:` and `@cleanup:`; Look owns
+conditions such as `@hover` and `@before`. They are not decorators, calls, or
+values, and user code cannot declare new `@` names.
+
+The toolchain writes `dist/index.html`; do not author it. `web.title` and
+`web.icon` supply document metadata, `public/` is copied through, and other
+assets are content-hashed.
+
+## Components and reactivity
+
+A component returns JSX directly. The four reactive cells have distinct jobs:
+
+- `state` owns a fact.
+- `computed name = ...` derives synchronously and is read bare.
+- `resource name: T = load()` owns async loading state.
+- `action name():` owns a user operation and exposes `pending` and `error`.
+
+```velar fragment
+component TicketPanel(id: string):
+    state draft = ""
+    resource ticket: Ticket = loadTicket(id)
+    computed heading = ticket.value?.title ?? "Loading"
+
+    action save():
+        await saveDraft(id, draft)
+
+    watch id:
+        async ticket.reload()
+
+    return <section>
+        <h2>{heading}</h2>
+        <textarea bind:value={draft}></textarea>
+        <button disabled={save.pending} on:click={save}>Save</button>
+    </section>
+```
+
+A resource loads once at mount. Refetching after an input changes is an
+explicit `watch` plus detached `async resource.reload()`. Actions do not queue;
+disable or otherwise guard a trigger when concurrent calls are unwanted.
+
+`@mounted:` runs after insertion and may await. `@cleanup:` runs before removal
+and is synchronous. A component may still declare ordinary methods named
+`mounted` or `cleanup` because compiler-owned names occupy a separate namespace.
+
+Events use `on:click={handler}`. Writable form paths use `bind:value`,
+`bind:checked`, or `bind:group`; do not read `event.target`. A JSX tag body is
+received only through an explicitly declared `children: WebNode` prop.
+Conditional rendering is an expression, and repeated children need stable
+`key` values.
+
+Props are live reactive inputs. Their data is mutable unless the author writes
+an explicit `readonly` view.
+
+## Look
+
+`look:` is checked visual data. CSS keywords are strings, property names use
+DOM camelCase, and units are literals:
+
+```velar fragment
+import {border, rgb, spacing} from "velar/look"
+
+const buttonLook = look:
+    border = border(0px, rgb(220, 224, 235))
+    borderRadius = 10px
+    padding = spacing(10px, 14px)
+    cursor = "pointer"
+
+    if @hover:
+        background = rgb(235, 240, 255)
+```
+
+A module-level Look literal is built once and cannot read reactive state. Put a
+changing visual on the element with `look={active ? enabledLook : disabledLook}`
+or a typed `look:color={...}` binding. Checked motion is a module-level
+`keyframes:` value passed to `animate` from `velar/look`; do not use a raw CSS
+animation string. Unsupported styling uses explicit `import css unsafe
+"./file.css" before look` or `after look`.
+
+## Storage and tests
+
+`velar/storage` stores JSON and validates on read. A generic type spelling is
+not a runtime value, so name the complete type:
+
+```velar fragment
+import {storage} from "velar/storage"
+
+type SavedItem:
+    title: string
+
+type SavedItems = List<SavedItem>
+
+const items = storage.get("reading", SavedItems, [])
+storage.set("reading", items)
+```
+
+Keep `src/main.vel` as the mounted entry and put testable components and logic
+in imported modules. Plain `*.test.vel` files run headlessly. A
+`*.browser.test.vel` file drives the already-built page through
+`velar/web-test`; it does not mount a second app and cannot use JSX or
+`document` in its test body:
+
+```velar fragment
+import {expect} from "velar/test"
+import {browser, localStorage} from "velar/web-test"
+
+test "adding a link shows it in the list":
+    await browser.open("/")
+    await browser.fill("#title", "Vel")
+    await browser.click("#add")
+    await browser.waitForText("[data-item]", "Vel")
+    expect(await browser.text("[data-count]")).toBe("1")
+    expect(await localStorage.get("reading")).toBe(`[{"title":"Vel"}]`)
+```
+
+Bare `velar test --browser` means Chromium; use `--browser=all` for a
+cross-browser claim. `velar/web-test` is legal only in browser-test modules.
+Application code that needs the page uses checked `velar/browser` APIs.
+
+## Finish
+
+Run `velar format`, `velar check`, `velar test`, the project's browser tests,
+and `velar build`. The complete runnable vocabulary lives in
+`examples/tour/web/`; diagnostics outrank this brief when the two appear to
+disagree.