@jay-framework/jay-stack-cli 0.11.0 โ 0.13.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.
- package/README.md +58 -0
- package/agent-kit-template/INSTRUCTIONS.md +120 -0
- package/agent-kit-template/cli-commands.md +229 -0
- package/agent-kit-template/contracts-and-plugins.md +293 -0
- package/agent-kit-template/jay-html-syntax.md +312 -0
- package/agent-kit-template/project-structure.md +242 -0
- package/agent-kit-template/routing.md +112 -0
- package/dist/index.d.ts +82 -2
- package/dist/index.js +2620 -629
- package/lib/vendors/README.md +510 -0
- package/lib/vendors/figma/README.md +396 -0
- package/package.json +13 -8
- package/test/vendors/figma/fixtures/README.md +164 -0
package/README.md
CHANGED
|
@@ -27,6 +27,57 @@ jay-stack dev ./my-project # Start dev server in specified directory
|
|
|
27
27
|
|
|
28
28
|
This will start both the development server and editor server with default configuration.
|
|
29
29
|
|
|
30
|
+
##### Test Mode
|
|
31
|
+
|
|
32
|
+
For automated testing, CI pipelines, and smoke tests, use the `--test-mode` flag:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
jay-stack dev --test-mode # Enable test endpoints
|
|
36
|
+
jay-stack dev --timeout 60 # Auto-shutdown after 60 seconds (implies --test-mode)
|
|
37
|
+
jay-stack dev --test-mode --timeout 120 # Both options
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Test mode enables special endpoints for reliable server management:
|
|
41
|
+
|
|
42
|
+
| Endpoint | Method | Description |
|
|
43
|
+
| ---------------- | ------ | ----------------------------------------------------------------------- |
|
|
44
|
+
| `/_jay/health` | GET | Returns `{"status":"ready","port":3300,"editorPort":3301,"uptime":5.2}` |
|
|
45
|
+
| `/_jay/shutdown` | POST | Gracefully shuts down the server, returns `{"status":"shutting_down"}` |
|
|
46
|
+
|
|
47
|
+
**Example smoke test workflow:**
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
# Start server with 2-minute timeout
|
|
51
|
+
jay-stack dev --test-mode --timeout 120 &
|
|
52
|
+
|
|
53
|
+
# Wait for health endpoint
|
|
54
|
+
for i in {1..30}; do
|
|
55
|
+
if curl -s http://localhost:3300/_jay/health | grep -q "ready"; then
|
|
56
|
+
break
|
|
57
|
+
fi
|
|
58
|
+
sleep 1
|
|
59
|
+
done
|
|
60
|
+
|
|
61
|
+
# Run your tests
|
|
62
|
+
curl -s http://localhost:3300/products/ | grep -q "<!doctype html"
|
|
63
|
+
|
|
64
|
+
# Clean shutdown
|
|
65
|
+
curl -X POST http://localhost:3300/_jay/shutdown
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
When test mode is enabled, the startup output includes the test endpoints:
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
๐ Jay Stack dev server started successfully!
|
|
72
|
+
๐ฑ Dev Server: http://localhost:3300
|
|
73
|
+
๐จ Editor Server: http://localhost:3301 (ID: init)
|
|
74
|
+
๐ Pages directory: ./src/pages
|
|
75
|
+
๐งช Test Mode: enabled
|
|
76
|
+
Health: http://localhost:3300/_jay/health
|
|
77
|
+
Shutdown: curl -X POST http://localhost:3300/_jay/shutdown
|
|
78
|
+
Timeout: 60s
|
|
79
|
+
```
|
|
80
|
+
|
|
30
81
|
#### `jay-stack validate [path]`
|
|
31
82
|
|
|
32
83
|
Validate all `.jay-html` and `.jay-contract` files in the project without creating output files:
|
|
@@ -203,6 +254,13 @@ The CLI is built using:
|
|
|
203
254
|
| `jay-stack validate [path]` | Validate jay-html and jay-contract files |
|
|
204
255
|
| `jay-stack validate-plugin [path]` | Validate a plugin package |
|
|
205
256
|
|
|
257
|
+
### Dev Command Options
|
|
258
|
+
|
|
259
|
+
| Option | Description |
|
|
260
|
+
| ------------------ | -------------------------------------------------------- |
|
|
261
|
+
| `--test-mode` | Enable test endpoints (`/_jay/health`, `/_jay/shutdown`) |
|
|
262
|
+
| `--timeout <secs>` | Auto-shutdown after N seconds (implies `--test-mode`) |
|
|
263
|
+
|
|
206
264
|
### Validate Command Options
|
|
207
265
|
|
|
208
266
|
| Option | Description |
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# Jay Stack Agent Kit
|
|
2
|
+
|
|
3
|
+
This folder contains everything you need to create jay-html pages for a jay-stack application.
|
|
4
|
+
|
|
5
|
+
## What is Jay Stack?
|
|
6
|
+
|
|
7
|
+
Jay Stack is a full-stack framework where:
|
|
8
|
+
|
|
9
|
+
- **Plugins** provide headless components (data + interactions, no UI)
|
|
10
|
+
- **Contracts** define the data shape and interaction points of each component
|
|
11
|
+
- **jay-html** templates provide the UI that binds to contract data
|
|
12
|
+
- **Rendering phases** determine when data is available (build-time, request-time, client-side)
|
|
13
|
+
|
|
14
|
+
Your job is to create `.jay-html` pages that bind to the data and interactions defined by contracts.
|
|
15
|
+
|
|
16
|
+
## Rendering Phases
|
|
17
|
+
|
|
18
|
+
| Phase | When | Use For |
|
|
19
|
+
| -------------------- | ------------------ | ------------------------------------------------- |
|
|
20
|
+
| **slow** | Build time (SSG) | Static content, SEO data, pre-rendered lists |
|
|
21
|
+
| **fast** | Request time (SSR) | Per-request data (prices, stock, personalization) |
|
|
22
|
+
| **fast+interactive** | Request + client | Data that also updates on the client |
|
|
23
|
+
|
|
24
|
+
There is no standalone "interactive" phase. Any tag with `type: interactive` (refs/interactions) is automatically `fast+interactive`. Tags without an explicit phase are available in all phases.
|
|
25
|
+
|
|
26
|
+
## Workflow
|
|
27
|
+
|
|
28
|
+
1. **Read this file** for overview and workflow
|
|
29
|
+
2. **Discover plugins** โ read `materialized-contracts/plugins-index.yaml` to see available plugins, contracts, and actions. Read `materialized-contracts/contracts-index.yaml` for the full contract list.
|
|
30
|
+
3. **Read contracts** โ read the `.jay-contract` files (paths from plugins-index) to understand data shapes, tag types, phases, and props.
|
|
31
|
+
4. **Read actions** โ read `.jay-action` files (paths from plugins-index) to see action descriptions, input schemas, and output schemas. This tells you what data each action accepts and returns.
|
|
32
|
+
5. **Read references** โ check `references/<plugin>/` for pre-generated discovery data (product catalogs, collection schemas, etc.). These are generated by `jay-stack agent-kit` and contain real data from the site.
|
|
33
|
+
6. **Discover data** โ run `jay-stack params <plugin>/<contract>` for SSG route params, `jay-stack action <plugin>/<action>` for data discovery. Use reference files (step 5) first when available โ they're faster than running CLI commands.
|
|
34
|
+
7. **Create pages** โ write `.jay-html` files under `src/pages/` following directory-based routing.
|
|
35
|
+
8. **Validate** โ run `jay-stack validate` to check for errors.
|
|
36
|
+
9. **Test** โ run `jay-stack dev --test-mode` and verify pages render.
|
|
37
|
+
|
|
38
|
+
## Reference Docs
|
|
39
|
+
|
|
40
|
+
| File | Topic |
|
|
41
|
+
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
42
|
+
| [project-structure.md](project-structure.md) | Project layout, styling patterns (CSS themes, design tokens), configuration files |
|
|
43
|
+
| [jay-html-syntax.md](jay-html-syntax.md) | Jay-HTML template syntax: data binding, conditions, loops, headless components |
|
|
44
|
+
| [routing.md](routing.md) | Directory-based routing: page structure, dynamic routes, route priority |
|
|
45
|
+
| [contracts-and-plugins.md](contracts-and-plugins.md) | Reading contracts, plugin.yaml, .jay-action files, and the materialized indexes |
|
|
46
|
+
| [cli-commands.md](cli-commands.md) | CLI commands: setup, validate, params, action, dev server |
|
|
47
|
+
| `references/<plugin>/` | Pre-generated discovery data: product catalogs, collection schemas (from `jay-stack agent-kit`) |
|
|
48
|
+
|
|
49
|
+
## Quick Start
|
|
50
|
+
|
|
51
|
+
### 1. Discover plugins and contracts
|
|
52
|
+
|
|
53
|
+
Read `materialized-contracts/plugins-index.yaml`:
|
|
54
|
+
|
|
55
|
+
```yaml
|
|
56
|
+
plugins:
|
|
57
|
+
- name: wix-stores
|
|
58
|
+
path: ./node_modules/@wix/stores
|
|
59
|
+
contracts:
|
|
60
|
+
- name: product-page
|
|
61
|
+
type: static
|
|
62
|
+
path: ./node_modules/@wix/stores/lib/contracts/product-page.jay-contract
|
|
63
|
+
actions:
|
|
64
|
+
- name: searchProducts
|
|
65
|
+
description: Search products with text/filter/sort/pagination
|
|
66
|
+
path: ./node_modules/@wix/stores/lib/actions/search-products.jay-action
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### 2. Read a contract
|
|
70
|
+
|
|
71
|
+
The `.jay-contract` file at the path from the index defines the data shape:
|
|
72
|
+
|
|
73
|
+
```yaml
|
|
74
|
+
name: ProductWidget
|
|
75
|
+
props:
|
|
76
|
+
- name: productId
|
|
77
|
+
type: string
|
|
78
|
+
required: true
|
|
79
|
+
tags:
|
|
80
|
+
- tag: name
|
|
81
|
+
type: data
|
|
82
|
+
dataType: string
|
|
83
|
+
phase: slow
|
|
84
|
+
- tag: inStock
|
|
85
|
+
type: variant
|
|
86
|
+
dataType: boolean
|
|
87
|
+
phase: fast+interactive
|
|
88
|
+
- tag: addToCart
|
|
89
|
+
type: interactive
|
|
90
|
+
elementType: HTMLButtonElement
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### 3. Create a page
|
|
94
|
+
|
|
95
|
+
Create `src/pages/page.jay-html`:
|
|
96
|
+
|
|
97
|
+
```html
|
|
98
|
+
<html>
|
|
99
|
+
<head>
|
|
100
|
+
<script
|
|
101
|
+
type="application/jay-headless"
|
|
102
|
+
plugin="wix-stores"
|
|
103
|
+
contract="product-page"
|
|
104
|
+
key="product"
|
|
105
|
+
></script>
|
|
106
|
+
</head>
|
|
107
|
+
<body>
|
|
108
|
+
<h1>{product.name}</h1>
|
|
109
|
+
<span if="product.inStock">In Stock</span>
|
|
110
|
+
<button ref="product.addToCart">Add to Cart</button>
|
|
111
|
+
</body>
|
|
112
|
+
</html>
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### 4. Validate and run
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
jay-stack validate
|
|
119
|
+
jay-stack dev
|
|
120
|
+
```
|
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
# CLI Commands Reference
|
|
2
|
+
|
|
3
|
+
## jay-stack setup
|
|
4
|
+
|
|
5
|
+
Run plugin setup. Plugins can create configuration files, generate reference data, and validate their prerequisites.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
# Run setup for all installed plugins
|
|
9
|
+
jay-stack setup
|
|
10
|
+
|
|
11
|
+
# Run setup for a specific plugin
|
|
12
|
+
jay-stack setup wix-stores
|
|
13
|
+
|
|
14
|
+
# Re-run setup (e.g., after config change)
|
|
15
|
+
jay-stack setup wix-data --force
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Plugins declare their setup handler in `plugin.yaml`. Setup does two things:
|
|
19
|
+
|
|
20
|
+
1. **Config templates**: Creates `config/<plugin>.yaml` with placeholder credentials if missing
|
|
21
|
+
2. **Credential validation**: Attempts to initialize services, reports success or failure
|
|
22
|
+
|
|
23
|
+
Reference data (product catalogs, collection schemas) is generated by `jay-stack agent-kit`, not by setup.
|
|
24
|
+
|
|
25
|
+
Run this after installing new plugins, before `jay-stack agent-kit`.
|
|
26
|
+
|
|
27
|
+
## jay-stack agent-kit
|
|
28
|
+
|
|
29
|
+
Materialize contracts, generate discovery indexes, and produce plugin reference data. Run this after setup.
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
# Default: writes to agent-kit/
|
|
33
|
+
jay-stack agent-kit
|
|
34
|
+
|
|
35
|
+
# Custom output directory for contracts
|
|
36
|
+
jay-stack agent-kit --output my-output/
|
|
37
|
+
|
|
38
|
+
# List contracts without writing files
|
|
39
|
+
jay-stack agent-kit --list
|
|
40
|
+
|
|
41
|
+
# Filter to specific plugin
|
|
42
|
+
jay-stack agent-kit --plugin wix-stores
|
|
43
|
+
|
|
44
|
+
# Force re-materialization
|
|
45
|
+
jay-stack agent-kit --force
|
|
46
|
+
|
|
47
|
+
# Skip reference data generation
|
|
48
|
+
jay-stack agent-kit --no-references
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Outputs:
|
|
52
|
+
|
|
53
|
+
- `materialized-contracts/contracts-index.yaml`
|
|
54
|
+
- `materialized-contracts/plugins-index.yaml`
|
|
55
|
+
- `materialized-contracts/<plugin>/*.jay-contract` (dynamic contracts)
|
|
56
|
+
- `references/<plugin>/` โ plugin reference data (product catalogs, collection schemas, etc.)
|
|
57
|
+
- Documentation files (INSTRUCTIONS.md and reference docs)
|
|
58
|
+
|
|
59
|
+
## jay-stack validate
|
|
60
|
+
|
|
61
|
+
Validate all `.jay-html` and `.jay-contract` files.
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
# Validate entire project
|
|
65
|
+
jay-stack validate
|
|
66
|
+
|
|
67
|
+
# Validate a specific path
|
|
68
|
+
jay-stack validate src/pages/products/
|
|
69
|
+
|
|
70
|
+
# Verbose (per-file status)
|
|
71
|
+
jay-stack validate -v
|
|
72
|
+
|
|
73
|
+
# JSON output
|
|
74
|
+
jay-stack validate --json
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Example output:
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
โ
Jay Stack validation successful!
|
|
81
|
+
Scanned 5 .jay-html files, 3 .jay-contract files
|
|
82
|
+
No errors found.
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
On failure:
|
|
86
|
+
|
|
87
|
+
```
|
|
88
|
+
โ Jay Stack validation failed
|
|
89
|
+
|
|
90
|
+
Errors:
|
|
91
|
+
โ src/pages/products/page.jay-html
|
|
92
|
+
Unknown ref "nonExistentRef" - not found in contract
|
|
93
|
+
|
|
94
|
+
1 error(s) found, 7 file(s) valid.
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Always run validate after creating or editing jay-html and contract files.
|
|
98
|
+
|
|
99
|
+
## jay-stack params
|
|
100
|
+
|
|
101
|
+
Discover load param values for SSG route generation.
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
# Discover slug values for product pages
|
|
105
|
+
jay-stack params wix-stores/product-page
|
|
106
|
+
|
|
107
|
+
# YAML output
|
|
108
|
+
jay-stack params wix-stores/product-page --yaml
|
|
109
|
+
|
|
110
|
+
# Verbose
|
|
111
|
+
jay-stack params wix-stores/product-page -v
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Format: `<plugin-name>/<contract-name>`
|
|
115
|
+
|
|
116
|
+
Example output:
|
|
117
|
+
|
|
118
|
+
```json
|
|
119
|
+
[
|
|
120
|
+
{ "slug": "ceramic-flower-vase" },
|
|
121
|
+
{ "slug": "blue-running-shoes" },
|
|
122
|
+
{ "slug": "organic-cotton-tshirt" }
|
|
123
|
+
]
|
|
124
|
+
|
|
125
|
+
โ
Found 3 param combination(s)
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Use this to discover what param values exist for dynamic routes like `[slug]`. Only works on contracts whose component has `loadParams`.
|
|
129
|
+
|
|
130
|
+
## jay-stack action
|
|
131
|
+
|
|
132
|
+
Run a plugin action from the CLI. Use to discover data for populating pages.
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
# Run with default input
|
|
136
|
+
jay-stack action wix-stores/searchProducts
|
|
137
|
+
|
|
138
|
+
# Run with input
|
|
139
|
+
jay-stack action wix-stores/searchProducts --input '{"query": "shoes", "limit": 5}'
|
|
140
|
+
|
|
141
|
+
# YAML output
|
|
142
|
+
jay-stack action wix-stores/getCategories --yaml
|
|
143
|
+
|
|
144
|
+
# Verbose
|
|
145
|
+
jay-stack action wix-stores/getProductBySlug --input '{"slug": "blue-shirt"}' -v
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Format: `<plugin-name>/<action-name>`
|
|
149
|
+
|
|
150
|
+
Action names are listed in `plugins-index.yaml` under each plugin's `actions:` array. Each action entry includes a `description` and a `path` to the `.jay-action` file. Read the `.jay-action` file to see the full input/output schemas before calling an action.
|
|
151
|
+
|
|
152
|
+
Example output:
|
|
153
|
+
|
|
154
|
+
```json
|
|
155
|
+
{
|
|
156
|
+
"items": [
|
|
157
|
+
{ "_id": "prod-1", "name": "Blue Shirt", "slug": "blue-shirt", "price": 29.99 },
|
|
158
|
+
{ "_id": "prod-2", "name": "Red Hat", "slug": "red-hat", "price": 19.99 }
|
|
159
|
+
],
|
|
160
|
+
"totalCount": 2
|
|
161
|
+
}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
If not found, lists available actions:
|
|
165
|
+
|
|
166
|
+
```
|
|
167
|
+
โ Action "badName" not found.
|
|
168
|
+
Available actions: searchProducts, getProductBySlug, getCategories
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## jay-stack dev
|
|
172
|
+
|
|
173
|
+
Start the development server.
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
# Normal dev mode
|
|
177
|
+
jay-stack dev
|
|
178
|
+
|
|
179
|
+
# Test mode (enables health/shutdown endpoints)
|
|
180
|
+
jay-stack dev --test-mode
|
|
181
|
+
|
|
182
|
+
# Auto-timeout (implies test mode)
|
|
183
|
+
jay-stack dev --timeout 60
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Test mode endpoints
|
|
187
|
+
|
|
188
|
+
| Endpoint | Method | Response |
|
|
189
|
+
| ---------------- | ------ | --------------------------------------------------------------- |
|
|
190
|
+
| `/_jay/health` | GET | `{"status":"ready","port":3300,"editorPort":3301,"uptime":5.2}` |
|
|
191
|
+
| `/_jay/shutdown` | POST | `{"status":"shutting_down"}` |
|
|
192
|
+
|
|
193
|
+
### Wait for server ready
|
|
194
|
+
|
|
195
|
+
Poll the health endpoint:
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
# Bash
|
|
199
|
+
for i in {1..30}; do
|
|
200
|
+
curl -s http://localhost:3300/_jay/health | grep -q "ready" && break
|
|
201
|
+
sleep 1
|
|
202
|
+
done
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
```typescript
|
|
206
|
+
// TypeScript
|
|
207
|
+
async function waitForServer(timeout = 30000): Promise<string> {
|
|
208
|
+
const start = Date.now();
|
|
209
|
+
while (Date.now() - start < timeout) {
|
|
210
|
+
try {
|
|
211
|
+
const res = await fetch('http://localhost:3300/_jay/health');
|
|
212
|
+
if (res.ok) {
|
|
213
|
+
const { port } = await res.json();
|
|
214
|
+
return `http://localhost:${port}`;
|
|
215
|
+
}
|
|
216
|
+
} catch {
|
|
217
|
+
/* not ready */
|
|
218
|
+
}
|
|
219
|
+
await new Promise((r) => setTimeout(r, 500));
|
|
220
|
+
}
|
|
221
|
+
throw new Error('Server not ready');
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
### Shutdown
|
|
226
|
+
|
|
227
|
+
```bash
|
|
228
|
+
curl -X POST http://localhost:3300/_jay/shutdown
|
|
229
|
+
```
|