@harperfast/template-vue-studio 1.13.6 → 1.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/.agents/skills/harper-best-practices/AGENTS.md +1260 -1113
  2. package/.agents/skills/harper-best-practices/rules/automatic-apis.md +118 -83
  3. package/.agents/skills/harper-best-practices/rules/checking-authentication.md +244 -256
  4. package/.agents/skills/harper-best-practices/rules/custom-resources.md +37 -42
  5. package/.agents/skills/harper-best-practices/rules/defining-relationships.md +86 -49
  6. package/.agents/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
  7. package/.agents/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
  8. package/.agents/skills/harper-best-practices/rules/load-env.md +27 -30
  9. package/.agents/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
  10. package/.agents/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
  11. package/.agents/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
  12. package/.agents/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
  13. package/.agents/skills/harper-best-practices/rules/vector-indexing.md +77 -68
  14. package/.agents/skills/harper-mcp/AGENTS.md +228 -155
  15. package/.agents/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
  16. package/.agents/skills/harper-mcp/rules/enabling-mcp.md +104 -92
  17. package/.agents/skills/harper-mcp/rules/rate-limiting.md +95 -28
  18. package/agent/skills/harper-best-practices/AGENTS.md +1260 -1113
  19. package/agent/skills/harper-best-practices/rules/automatic-apis.md +118 -83
  20. package/agent/skills/harper-best-practices/rules/checking-authentication.md +244 -256
  21. package/agent/skills/harper-best-practices/rules/custom-resources.md +37 -42
  22. package/agent/skills/harper-best-practices/rules/defining-relationships.md +86 -49
  23. package/agent/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
  24. package/agent/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
  25. package/agent/skills/harper-best-practices/rules/load-env.md +27 -30
  26. package/agent/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
  27. package/agent/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
  28. package/agent/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
  29. package/agent/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
  30. package/agent/skills/harper-best-practices/rules/vector-indexing.md +77 -68
  31. package/agent/skills/harper-mcp/AGENTS.md +228 -155
  32. package/agent/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
  33. package/agent/skills/harper-mcp/rules/enabling-mcp.md +104 -92
  34. package/agent/skills/harper-mcp/rules/rate-limiting.md +95 -28
  35. package/package.json +1 -1
  36. package/skills-lock.json +7 -7
@@ -12,29 +12,29 @@ metadata:
12
12
  - reference/v5/rest/overview.md#Content Types
13
13
  - reference/v5/rest/overview.md#OpenAPI
14
14
  - reference/v5/rest/websockets.md
15
- sourceCommit: 2cfb81318f17e0aca2d600109e6ad813d2d0443e
16
- inputHash: fc3e7ae596f475b2
15
+ sourceCommit: 0a29827da61afe7fff40ee8de87e1d4c2c286bea
16
+ inputHash: 0672da4654ca1a34
17
17
  ---
18
18
 
19
- # Automatic APIs
19
+ # Automatic REST and WebSocket APIs
20
20
 
21
- Instructions for the agent to follow when using Harper's automatically generated REST and WebSocket APIs for exported tables and resources.
21
+ Instructions for the agent to follow when exposing Harper tables and custom resources as REST and WebSocket endpoints using Harper's automatically generated API layer.
22
22
 
23
23
  **Instead of:** Hand-written CRUD routes (Express, Fastify, Next.js API routes). Use this rule rather than adding that service. See `harper-architecture`.
24
24
 
25
25
  ## When to Use
26
26
 
27
- Apply this rule when enabling HTTP REST endpoints or WebSocket subscriptions for Harper tables and custom resources. Use it whenever you need to configure the REST plugin, understand the auto-generated endpoint surface, or wire up real-time WebSocket connections. See [querying-rest-apis.md](querying-rest-apis.md) for query syntax and [real-time-apps.md](real-time-apps.md) for real-time patterns.
27
+ Apply this rule when enabling HTTP REST access to Harper tables, when configuring WebSocket subscriptions on resource paths, or when customizing how exported resources respond to standard HTTP methods. Use it any time you need to wire up `rest: true`, handle conditional requests, or implement a `connect()` handler.
28
28
 
29
29
  ## How It Works
30
30
 
31
- 1. **Enable the REST plugin** by adding `rest: true` to your application's `config.yaml`:
31
+ 1. **Enable the REST plugin** by adding `rest: true` to the application's `config.yaml`:
32
32
 
33
33
  ```yaml
34
34
  rest: true
35
35
  ```
36
36
 
37
- Extended options:
37
+ Additional options:
38
38
 
39
39
  ```yaml
40
40
  rest:
@@ -43,7 +43,9 @@ Apply this rule when enabling HTTP REST endpoints or WebSocket subscriptions for
43
43
  exactCount: true # opt in to Prefer: count=exact scans (off by default)
44
44
  ```
45
45
 
46
- 2. **Export the table in your schema** using `@export`. Tables are not exposed by default — `@export` is required for Harper to register a REST route:
46
+ A component directory with no `config.yaml` at all inherits a built-in default that enables `rest` and loads `*.graphql` from the component root. As soon as a `config.yaml` exists it is used verbatim — omitting `rest` turns REST off. Always write `rest: true` when adding a config file.
47
+
48
+ 2. **Export the table in the schema** using `@export`. Tables are not exported by default.
47
49
 
48
50
  ```graphql
49
51
  type Product @table @export {
@@ -53,41 +55,76 @@ Apply this rule when enabling HTTP REST endpoints or WebSocket subscriptions for
53
55
  }
54
56
  ```
55
57
 
56
- Without `@export`, the table has no REST route and callers receive `404`. Without `rest: true` in `config.yaml`, even an exported table does not respond to HTTP requests.
58
+ Reference the schema file from `config.yaml`:
59
+
60
+ ```yaml
61
+ graphqlSchema:
62
+ files: schema.graphql
63
+ rest: true
64
+ ```
65
+
66
+ Both `@export` and `rest: true` are required. Without `@export`, no REST route is registered and callers receive `404`. Without REST enabled, even an exported table does not respond to HTTP requests.
67
+
68
+ 3. **Understand the auto-generated endpoints**. With `Product` exported, Harper registers these routes on the application HTTP server port (default `9926`) with no handler code required:
69
+
70
+ | Endpoint | Description |
71
+ | ---------------------------- | --------------------------------------------------------------------------- |
72
+ | `GET /Product` | Resource description (table name, database, attributes) |
73
+ | `GET /Product/` | Record collection; append query parameters to filter/sort/page |
74
+ | `GET /Product/{id}` | Single record by primary key; `404` if not found |
75
+ | `GET /Product/{id}.property` | Single declared property of one record |
76
+ | `POST /Product/` | Creates a record; responds `201`; primary key returned in `Location` header |
77
+ | `PUT /Product/{id}` | Creates or replaces the record at `{id}` (upsert) |
78
+ | `PATCH /Product/{id}` | Shallow-merges body into existing record |
79
+ | `DELETE /Product/{id}` | Deletes the record at `{id}` |
80
+ | `DELETE /Product/?query` | Deletes every record matching the query |
57
81
 
58
- 3. **Understand the auto-generated endpoints**. With both `@export` and `rest: true` in place, Harper registers the following on the application HTTP server port (default `9926`):
82
+ The trailing slash is significant: `/Product` addresses the resource itself; `/Product/` addresses its record collection.
59
83
 
60
- | Endpoint | Description |
61
- | ---------------------------- | ------------------------------------------------------------------------------------ |
62
- | `GET /Product` | Resource description — table name, database, declared attributes |
63
- | `GET /Product/` | Record collection; append query parameters to filter, sort, page |
64
- | `GET /Product/{id}` | Single record by primary key; `404` if not found |
65
- | `GET /Product/{id}.property` | Single declared property of one record |
66
- | `POST /Product/` | Creates a record; responds `201`; primary key returned in `Location` header |
67
- | `PUT /Product/{id}` | Creates or replaces the record at `{id}` (upsert); omitted properties are removed |
68
- | `PATCH /Product/{id}` | Shallow-merges body into existing record; unspecified top-level properties preserved |
69
- | `DELETE /Product/{id}` | Deletes the record at `{id}` |
70
- | `DELETE /Product/?query` | Deletes every record matching the query |
71
- - `HEAD` is served exactly as `GET` with the response body omitted. `QUERY` is accepted on the collection path (`QUERY /Product/`) and runs a search taken from the request body rather than the URL.
84
+ 4. **Understand the URL structure**. Harper follows a consistent URL pattern across all resources:
72
85
 
73
- 4. **Use the correct URL structure**. The trailing slash is significant:
86
+ | Path | Description |
87
+ | -------------------------------------------- | ------------------------------------------------------------------------------------------------- |
88
+ | `/my-resource` | Root path — returns a description of the resource (e.g., table metadata) |
89
+ | `/my-resource/` | Trailing slash indicates a collection — represents all records; append query parameters to search |
90
+ | `/my-resource/record-id` | A specific record identified by its primary key |
91
+ | `/my-resource/record-id/` | Trailing slash — the collection of records with the given id prefix |
92
+ | `/my-resource/record-id/with/multiple/parts` | Record id with multiple path segments |
74
93
 
75
- | Path | Addresses |
76
- | ------------------------- | ---------------------------------------------- |
77
- | `/my-resource` | The resource itself (metadata) |
78
- | `/my-resource/` | The record collection |
79
- | `/my-resource/record-id` | A specific record by primary key |
80
- | `/my-resource/record-id/` | Collection of records with the given id prefix |
94
+ 5. **Handle HTTP methods correctly**:
95
+ - **GET** — Retrieves a record or collection. Use `GET /MyTable/123` for a single record, `GET /MyTable/?name=Harper` for a filtered collection. The `.msgpack` suffix (along with `.json`, `.cbor`, `.csv`) is a reserved content-type selector and takes precedence over property access via dot syntax.
96
+ - **POST** — Creates a record. The new record's primary key is returned in the `Location` response header. A `POST` to a key that already exists fails with `409`.
97
+ - **PUT** — Upserts a record. The stored record matches the body exactly; omitted properties are removed. Harper always re-stamps an `@updatedTime` attribute and preserves `@createdTime`.
98
+ - **PATCH** — Shallow-merges the body. Top-level unspecified properties are preserved; nested objects in the body replace the stored sub-object wholesale.
99
+ - **DELETE** — Deletes by id or by query. `DELETE /MyTable/` with no query parameters deletes every record.
81
100
 
82
- 5. **Handle `POST` primary keys via `Location`**. On a successful `POST`, the new record's primary key is returned in the `Location` response header — the value supplied by the body, or a Harper-assigned key if the body omitted the primary-key property.
101
+ 6. **Use conditional requests for caching**. GET responses include an `ETag` header. Clients send `If-None-Match` on subsequent requests; if the record is unchanged Harper returns `304 Not Modified` with no body.
83
102
 
84
- 6. **Use conditional GET requests for caching**. GET responses include an `ETag` header. Send `If-None-Match` on subsequent requests; if the record is unchanged, Harper returns `304 Not Modified` with no body.
103
+ 7. **Set the `Accept` header** to request a specific response format. Use `Content-Type` for request bodies. See [querying-rest-apis.md](querying-rest-apis.md) for the full query syntax and content-type details.
85
104
 
86
- 7. **Apply `@updatedTime` for write timestamps**. On `PUT`, Harper re-stamps any `@updatedTime` attribute with the time of the write, preserves any `@createdTime` value from the original record, and forces the primary key to match the `{id}` in the URL.
105
+ 8. **Use WebSocket subscriptions** on the same resource paths. WebSocket support is enabled automatically with `rest: true`. Connecting to a resource URL subscribes to change events:
87
106
 
88
- 8. **Control OpenAPI visibility**. Every non-hidden exported resource appears in the generated OpenAPI document at `GET /openapi`. To exclude a type, mark it `@hidden` in the schema, or set `static hidden = true` on a programmatic resource class.
107
+ ```javascript
108
+ let ws = new WebSocket('wss://server/my-resource/341');
109
+ ws.onmessage = (event) => {
110
+ let data = JSON.parse(event.data);
111
+ };
112
+ ```
113
+
114
+ Disable WebSocket support without disabling REST:
115
+
116
+ ```yaml
117
+ rest:
118
+ webSocket: false
119
+ ```
120
+
121
+ For MQTT over WebSockets, set the sub-protocol header:
122
+
123
+ ```
124
+ Sec-WebSocket-Protocol: mqtt
125
+ ```
89
126
 
90
- 9. **Implement a custom `connect()` handler** when default subscription behavior is insufficient. The method must return an async iterable that produces messages to send to the client:
127
+ 9. **Implement a custom `connect()` handler** on a resource class to control WebSocket behavior. The method must return an async iterable producing messages to send to the client:
91
128
 
92
129
  ```javascript
93
130
  export class Echo extends Resource {
@@ -99,28 +136,25 @@ Apply this rule when enabling HTTP REST endpoints or WebSocket subscriptions for
99
136
  }
100
137
  ```
101
138
 
102
- 10. **Connect via WebSocket**. WebSocket support is enabled automatically with `rest: true`. Connect to a resource URL to subscribe to change events:
139
+ 10. **Control OpenAPI visibility**. Every non-hidden exported resource is included in the generated OpenAPI document at `GET /openapi`. To exclude a type from the OpenAPI document, mark it `@hidden` in the schema:
103
140
 
104
- ```javascript
105
- let ws = new WebSocket('wss://server/my-resource/341');
106
- ws.onmessage = (event) => {
107
- let data = JSON.parse(event.data);
108
- };
141
+ ```graphql
142
+ type Secret @table @export @hidden {
143
+ id: Long @primaryKey
144
+ }
109
145
  ```
110
146
 
111
- Disable WebSocket support independently with `webSocket: false` under `rest`.
112
-
113
- 11. **Use MQTT over WebSockets** by setting the sub-protocol header:
147
+ Or set `static hidden = true` on a programmatic resource class:
114
148
 
149
+ ```javascript
150
+ export class Secret extends Resource {
151
+ static hidden = true;
152
+ }
115
153
  ```
116
- Sec-WebSocket-Protocol: mqtt
117
- ```
118
-
119
- 12. **Specify response format** using the `Accept` header. The suffixes `.json`, `.cbor`, `.msgpack`, and `.csv` are reserved as content-type selectors on property paths and take precedence over property names.
120
154
 
121
155
  ## Examples
122
156
 
123
- **Schema and config for a REST-enabled table:**
157
+ **Full schema and config setup:**
124
158
 
125
159
  ```graphql
126
160
  # schema.graphql
@@ -138,77 +172,78 @@ graphqlSchema:
138
172
  rest: true
139
173
  ```
140
174
 
141
- **Conditional GET with ETag caching:**
175
+ **Conditional GET with caching:**
142
176
 
143
- ```http
177
+ ```
144
178
  GET /Product/123
145
- If-None-Match: "abc123"
179
+ If-None-Match: "abc123etag"
146
180
  ```
147
181
 
148
182
  Response when unchanged:
149
183
 
150
184
  ```
151
185
  HTTP/1.1 304 Not Modified
152
- ETag: "abc123"
186
+ ETag: "abc123etag"
153
187
  ```
154
188
 
155
189
  **POST and read the Location header:**
156
190
 
157
- ```http
191
+ ```
158
192
  POST /Product/
159
193
  Content-Type: application/json
160
194
 
161
- { "name": "Widget" }
195
+ { "name": "Widget", "price": 9.99 }
162
196
  ```
163
197
 
198
+ Response:
199
+
164
200
  ```
165
201
  HTTP/1.1 201 Created
166
202
  Location: 7f3a9c
167
203
  ```
168
204
 
169
- **PATCH (shallow merge only):**
205
+ **PATCH shallow merge:**
170
206
 
171
- ```http
207
+ ```
172
208
  PATCH /Product/123
173
209
  Content-Type: application/json
174
210
 
175
- { "status": "active" }
211
+ { "price": 12.99 }
176
212
  ```
177
213
 
178
- **Custom WebSocket connect handler:**
214
+ Preserves `name` and all other top-level properties; replaces any nested object in `price` wholesale.
215
+
216
+ **Custom WebSocket connect handler with timer:**
179
217
 
180
218
  ```javascript
181
- export class Echo extends Resource {
182
- async *connect(incomingMessages) {
183
- for await (let message of incomingMessages) {
184
- yield message; // echo each message back
185
- }
186
- }
187
- }
188
- ```
219
+ export class Example extends Resource {
220
+ connect(incomingMessages) {
221
+ let outgoingMessages = super.connect();
189
222
 
190
- **Hide a resource from OpenAPI — schema directive:**
223
+ let timer = setInterval(() => {
224
+ outgoingMessages.send({ greeting: 'hi again!' });
225
+ }, 1000);
191
226
 
192
- ```graphql
193
- type InternalLog @table @export @hidden {
194
- id: Long @primaryKey
195
- }
196
- ```
227
+ incomingMessages.on('data', (message) => {
228
+ outgoingMessages.send(message);
229
+ });
197
230
 
198
- **Hide a resource from OpenAPI — programmatic class:**
231
+ outgoingMessages.on('close', () => {
232
+ clearInterval(timer);
233
+ });
199
234
 
200
- ```javascript
201
- export class InternalLog extends Resource {
202
- static hidden = true;
235
+ return outgoingMessages;
236
+ }
203
237
  }
204
238
  ```
205
239
 
206
240
  ## Notes
207
241
 
208
- - A component directory with **no** `config.yaml` inherits Harper's built-in default, which enables `rest` automatically. As soon as a `config.yaml` exists, it is used verbatim — omitting `rest` from it disables REST even if the directory previously had it without a config file. Always add `rest: true` when adding a config file.
209
- - `POST /Product` (no trailing slash) returns `404`. The trailing slash is required for collection operations.
210
- - A `POST` to a primary key that already exists fails with `409` rather than overwriting.
211
- - PATCH merge is **shallow** — a nested object in the body replaces the stored nested object wholesale; nested properties not included in the body are dropped.
212
- - The `.msgpack` suffix (along with `.json`, `.cbor`, `.csv`) is reserved as a content-type selector and cannot be used as a property name in dot-path access.
213
- - Server-Sent Events subscriptions are served on the same paths, negotiated via `Accept: text/event-stream`; they are not affected by the `webSocket` option.
214
- - See [querying-rest-apis.md](querying-rest-apis.md) for full query syntax on collection endpoints and [real-time-apps.md](real-time-apps.md) for real-time subscription patterns.
242
+ - The trailing slash is always significant: `/Product` is the resource descriptor; `/Product/` is the record collection. `POST /Product` (no slash) returns `404`.
243
+ - `HEAD` is served exactly as `GET` with the response body omitted. `QUERY` is accepted on the collection path (`QUERY /Product/`) and runs a search taken from the request body rather than the URL.
244
+ - `PUT` always forces the primary key to match the `{id}` in the URL, re-stamps `@updatedTime`, and preserves `@createdTime` from the original record.
245
+ - PATCH merge is shallow only. A nested object in the body replaces the entire stored sub-object; omitted nested properties are lost.
246
+ - Server-Sent Events subscriptions are served on the same paths, negotiated via `Accept: text/event-stream`. They are not affected by the `webSocket` option.
247
+ - Leaving `@export` on the schema while also exporting a same-named subclass produces conflicting endpoints. When a JavaScript subclass should own the URL, omit `@export` from the schema and export the class instead.
248
+ - See [real-time-apps.md](real-time-apps.md) for patterns around WebSocket and event-driven resource design.
249
+ - See [querying-rest-apis.md](querying-rest-apis.md) for filtering, sorting, pagination, and content-type details.