@velarscript/cli 0.17.0 → 0.18.0

package/dist/version.d.ts

@@ -1,3 +1,3 @@
-export declare const VELAR_VERSION = "0.17.0";
+export declare const VELAR_VERSION = "0.18.0";
 export { VELAR_STANDARD_API_VERSION } from "@velarscript/core";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
-export const VELAR_VERSION = "0.17.0";
+export const VELAR_VERSION = "0.18.0";
 export { VELAR_STANDARD_API_VERSION } from "@velarscript/core";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velarscript/cli",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "The VelarScript command-line compiler, dev server, test runner, and language server.",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,13 +30,13 @@
     "velar": "./dist/cli.js"
   },
   "dependencies": {
-    "@velarscript/compiler": "0.17.0",
-    "@velarscript/core": "0.17.0",
-    "@velarscript/desktop": "0.17.0",
-    "@velarscript/node": "0.17.0",
-    "@velarscript/server": "0.17.0",
-    "@velarscript/web": "0.17.0",
-    "create-velar": "0.17.0",
+    "@velarscript/compiler": "0.18.0",
+    "@velarscript/core": "0.18.0",
+    "@velarscript/desktop": "0.18.0",
+    "@velarscript/node": "0.18.0",
+    "@velarscript/server": "0.18.0",
+    "@velarscript/web": "0.18.0",
+    "create-velar": "0.18.0",
     "esbuild": "^0.28.1",
     "playwright": "^1.58.2"
   }

package/skill/ai-skill-node.md

@@ -52,7 +52,6 @@ export async def start():
         host: "127.0.0.1",
         port: 3000,
         http: routes,
-        path: "/api/events",
         origins: ["https://app.example.com"],
         maxBodyBytes: 16777216,
     })
@@ -69,7 +68,7 @@ second runtime configuration source.
 `@` remains the language-wide annotation introducer, and `@name` is a context
 annotation with a compiler-owned compile-time role. In a `server` block, the
 available annotations are `@get`, `@post`, `@put`, `@patch`, `@delete`,
-`@notFound`, and `@response`. They are not decorators, functions, imports, user-defined
+`@websocket`, `@notFound`, and `@response`. They are not decorators, functions, imports, user-defined
 annotations, first-class values, or user extension points.
 
 ## Routes and checked inputs
@@ -84,23 +83,24 @@ type CreateArticle:
 
 export server articles:
     /// Reports whether this service is ready.
-    @get(path=p"/health") => {ok: true}
+    @get(p"/health") => {ok: true}
 
-    @get(path=p"/articles/{id:number}?{details:bool?}"):
-        const id = path.params.id
+    @get(p"/articles/{id:number}?{details:bool?}"):
         if id < 1:
             throw HttpProblem({status: 404, code: "article.not_found", title: "Article not found"})
-        return {id, details: path.query.details ?? false}
+        return {id, details: details ?? false}
 
-    @post(path=p"/articles", input: CreateArticle):
+    @post(p"/articles", input: CreateArticle):
         return created({id: 1, title: input.title})
 
 ```
 
-`p"..."` is a first-class `RoutePattern`. A route receives one compiler-owned
-`path` value: `path.params` contains typed path captures, `path.query` contains
-typed query fields, `path.definition` and `str(path)` return the complete
-declaration. Query shorthand `?{details:bool?}` uses the field name on the
+`p"..."` is a first-class `RoutePattern`. An inline pattern projects its typed
+path captures and query fields directly as immutable handler locals. A pattern
+stored elsewhere must use an explicit binding such as `@get(articlePath as
+route)`; its `RouteMatch` contains `pattern`, `pathname`, `params`, and `query`,
+and `str(route)` or `str(route.pattern)` returns the complete declaration. Query shorthand
+`?{details:bool?}` uses the field name on the
 wire; `?details={details:bool?}` spells it explicitly, and
 `?include-details={details:bool?}` maps a different wire name. The trailing
 `?` makes a query field optional; without it the framework rejects a missing
@@ -109,8 +109,10 @@ an ASCII half-width `:` and accept `string`, `number`, `bool`, or a named enum.
 The explicit same-name form remains valid but reports advisory `A11`; its
 mechanical fix removes the redundant `details=` prefix. Different-name aliases
 do not report it.
-Route catalogs may keep patterns in exported `const` objects and routes may
-refer to those members directly.
+Route catalogs may keep patterns in exported `const` objects. Referenced
+patterns require `as name` so the compiler never injects identifiers that are
+hidden inside another declaration. The old `path=` spelling is an error with a
+mechanical fix to the positional form and `as path`.
 
 On `POST`, `PUT`, or `PATCH`, one concrete Data parameter is the
 checked JSON body. A `Request` parameter explicitly requests the complete
@@ -184,13 +186,13 @@ const currentUser = provide(
 )
 
 server account:
-    @get(path=p"/me",
+    @get(p"/me",
         user=input.dependency(currentUser),
         tenant=input.header("x-tenant"),
         session=input.cookie("session", default=null),
     ) => {id: user.id, tenant, session}
 
-    @post(path=p"/images",
+    @post(p"/images",
         metadata=input.form(UploadMetadata),
         image=input.upload("image", maxBytes=8_388_608),
     ) => {title: metadata.title, filename: image.filename}
@@ -308,13 +310,33 @@ total stream are bounded. SSE accepts text or checked
 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. Set
+upgrades on one native server and owns the application lifecycle. A declarative
+session belongs in the route table:
+
+```velar
+import {WebSocketConnection} from "velar/websocket"
+
+server realtime:
+    @websocket(p"/worlds/{worldId:string}/realtime", connection: WebSocketConnection):
+        async for message in connection:
+            await connection.send(message)
+```
+
+Matching, path/query decoding, dependencies, security, headers, cookies, and
+the optional `Request` are resolved before upgrade. Exactly one
+`WebSocketConnection` is supplied by the framework, the handler must finish
+with `null`, and its lifetime is joined with shutdown. Inline patterns project
+captures directly; referenced patterns require `as route`. A listener whose app
+contains these routes rejects its legacy single `path` option and does not offer
+accepted sessions through `WebSocketServer.next()`.
+
+Set
 `maxBodyBytes` to the supplied application value. `origins` contains exact
 canonical HTTP/HTTPS origins. The default rejects any upgrade carrying
 `Origin`; no-Origin non-browser clients remain allowed. Use `["*"]` only for an
 intentional unrestricted policy. A rejected browser origin receives 403 before
 it consumes connection-queue capacity. Connections are pull-based. Always
-consume `next()`, handle backpressure, and stop the server.
+consume each connection's `next()`, handle backpressure, and stop the server.
 
 ## Tests
 

package/skill/ai-skill-server.md

@@ -13,7 +13,7 @@ browser application activates `@velarscript/web`:
 ```json
 {
   "dependencies": {
-    "@velarscript/server": "0.17.0"
+    "@velarscript/server": "0.18.0"
   }
 }
 ```
@@ -62,7 +62,7 @@ All three fields are optional. Their defaults are `127.0.0.1`, `3000`, and
 import {application} from "velar/server"
 
 export server routes:
-    @get(path=p"/health") => {status: "ready"}
+    @get(p"/health") => {status: "ready"}
 
 export const start = application(routes)
 ```
@@ -127,7 +127,7 @@ async def verifyAccessToken(token: string) -> Principal?:
 const currentPrincipal = authenticate(security.bearer(), verifyAccessToken)
 
 export server accountRoutes:
-    @get(path=p"/me", principal=input.dependency(currentPrincipal)) => {
+    @get(p"/me", principal=input.dependency(currentPrincipal)) => {
         subject: principal.subject,
     }
 ```
@@ -168,7 +168,7 @@ const connection = database(
 )
 
 export server databaseRoutes:
-    @get(path=p"/database", value=input.dependency(connection)) => {name: value.name}
+    @get(p"/database", value=input.dependency(connection)) => {name: value.name}
 ```
 
 The framework owns only this connect/inject/disconnect lifecycle. Concrete
@@ -179,8 +179,9 @@ syntax to `@velarscript/server` or `@velarscript/node`.
 
 ## Custom shared HTTP/WebSocket startup
 
-A service that needs one custom shared HTTP/WebSocket listener may load the same
-typed configuration and export an exact zero-argument async startup function:
+A service whose route table contains `@websocket` declarations may load the
+same typed configuration and export an exact zero-argument async startup
+function for the shared HTTP/WebSocket listener:
 
 ```velar fragment
 import {configuration} from "velar/server"
@@ -201,7 +202,6 @@ export async def start():
         host: settings.server.host,
         port: settings.server.port,
         http: routes,
-        path: "/events",
         origins: ["https://app.example.com"],
         maxBodyBytes: settings.server.maxBodyBytes,
     })
@@ -209,7 +209,9 @@ export async def start():
 
 The result must be exactly `Promise<WebSocketServer>`. The launcher supplies no
 host, port, or body-limit arguments; the root application configuration remains
-the single runtime authority.
+the single runtime authority. Each `@websocket` RoutePattern owns its own path,
+typed captures, admission inputs, and session handler, so this declarative mode
+does not accept the listener's legacy single `path` option.
 
 Use direct `serve(app, port=0)` in tests or embedded low-level adapters. Use
 `velar/server-test` only from `*.test.vel`. Route, provider, transport,