@jay-framework/jay-stack-cli 0.12.0 → 0.14.0

package/agent-kit-template/INSTRUCTIONS.md

@@ -26,11 +26,11 @@ There is no standalone "interactive" phase. Any tag with `type: interactive` (re
 ## Workflow
 
 1. **Read this file** for overview and workflow
-2. **Discover plugins** — read `materialized-contracts/plugins-index.yaml` to see available plugins and their contracts. Read `materialized-contracts/contracts-index.yaml` for the full contract list.
-3. **Read plugin.yaml** — for each plugin, read its `plugin.yaml` (at the path from plugins-index) to see contract descriptions and available **actions** (e.g., `searchProducts`, `getCategories`).
-4. **Read contracts** — read the `.jay-contract` files to understand data shapes, tag types, phases, and props.
+2. **Discover plugins** — read `plugins-index.yaml` to see available plugins, contracts, and actions.
+3. **Read contracts** — read the `.jay-contract` files (paths from plugins-index) to understand data shapes, tag types, phases, and props.
+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.
 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.
-6. **Discover data** — run `jay-stack params <plugin>/<contract>` for SSG route params, `jay-stack action <plugin>/<action>` for data discovery (action names come from plugin.yaml). Use reference files (step 5) first when available — they're faster than running CLI commands.
+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.
 7. **Create pages** — write `.jay-html` files under `src/pages/` following directory-based routing.
 8. **Validate** — run `jay-stack validate` to check for errors.
 9. **Test** — run `jay-stack dev --test-mode` and verify pages render.
@@ -42,7 +42,7 @@ There is no standalone "interactive" phase. Any tag with `type: interactive` (re
 | [project-structure.md](project-structure.md)         | Project layout, styling patterns (CSS themes, design tokens), configuration files               |
 | [jay-html-syntax.md](jay-html-syntax.md)             | Jay-HTML template syntax: data binding, conditions, loops, headless components                  |
 | [routing.md](routing.md)                             | Directory-based routing: page structure, dynamic routes, route priority                         |
-| [contracts-and-plugins.md](contracts-and-plugins.md) | Reading contracts, plugin.yaml, and the materialized indexes                                    |
+| [contracts-and-plugins.md](contracts-and-plugins.md) | Reading contracts, plugin.yaml, .jay-action files, and the materialized indexes                 |
 | [cli-commands.md](cli-commands.md)                   | CLI commands: setup, validate, params, action, dev server                                       |
 | `references/<plugin>/`                               | Pre-generated discovery data: product catalogs, collection schemas (from `jay-stack agent-kit`) |
 
@@ -50,7 +50,7 @@ There is no standalone "interactive" phase. Any tag with `type: interactive` (re
 
 ### 1. Discover plugins and contracts
 
-Read `materialized-contracts/plugins-index.yaml`:
+Read `plugins-index.yaml`:
 
 ```yaml
 plugins:
@@ -60,6 +60,10 @@ plugins:
       - name: product-page
         type: static
         path: ./node_modules/@wix/stores/lib/contracts/product-page.jay-contract
+    actions:
+      - name: searchProducts
+        description: Search products with text/filter/sort/pagination
+        path: ./node_modules/@wix/stores/lib/actions/search-products.jay-action
 ```
 
 ### 2. Read a contract

package/agent-kit-template/cli-commands.md

@@ -50,8 +50,7 @@ jay-stack agent-kit --no-references
 
 Outputs:
 
-- `materialized-contracts/contracts-index.yaml`
-- `materialized-contracts/plugins-index.yaml`
+- `plugins-index.yaml`
 - `materialized-contracts/<plugin>/*.jay-contract` (dynamic contracts)
 - `references/<plugin>/` — plugin reference data (product catalogs, collection schemas, etc.)
 - Documentation files (INSTRUCTIONS.md and reference docs)
@@ -147,7 +146,7 @@ jay-stack action wix-stores/getProductBySlug --input '{"slug": "blue-shirt"}' -v
 
 Format: `<plugin-name>/<action-name>`
 
-Action names are listed in the plugin's `plugin.yaml` under `actions:`.
+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.
 
 Example output:
 

package/agent-kit-template/contracts-and-plugins.md

@@ -2,10 +2,9 @@
 
 ## Discovery: Plugins Index
 
-After running `jay-stack agent-kit`, read `materialized-contracts/plugins-index.yaml`:
+After running `jay-stack agent-kit`, read `plugins-index.yaml`:
 
 ```yaml
-materialized_at: '2026-02-09T...'
 jay_stack_version: '1.0.0'
 plugins:
   - name: wix-stores
@@ -17,6 +16,13 @@ plugins:
       - name: product-search
         type: static
         path: ./node_modules/@wix/stores/lib/contracts/product-search.jay-contract
+    actions:
+      - name: searchProducts
+        description: Search products with text/filter/sort/pagination
+        path: ./node_modules/@wix/stores/lib/actions/search-products.jay-action
+      - name: getProductBySlug
+        description: Get a single product by URL slug
+        path: ./node_modules/@wix/stores/lib/actions/get-product-by-slug.jay-action
 ```
 
 Fields:
@@ -26,18 +32,9 @@ Fields:
 - `contracts[].name` — contract name (use in `contract="..."` attributes)
 - `contracts[].type` — `static` (defined in source) or `dynamic` (generated at runtime)
 - `contracts[].path` — path to the `.jay-contract` file you can read
-
-## Discovery: Contracts Index
-
-`materialized-contracts/contracts-index.yaml` lists all contracts across all plugins:
-
-```yaml
-contracts:
-  - plugin: wix-stores
-    name: product-page
-    type: static
-    path: ./node_modules/@wix/stores/lib/contracts/product-page.jay-contract
-```
+- `actions[].name` — action name (use with `jay-stack action <plugin>/<action>`)
+- `actions[].description` — short description of what the action does
+- `actions[].path` — path to the `.jay-action` file with full input/output schemas
 
 ## Reading plugin.yaml
 
@@ -55,16 +52,20 @@ contracts:
     component: productSearch
     description: Headless product search page
 actions:
-  - searchProducts
-  - getProductBySlug
-  - getCategories
+  - name: searchProducts
+    action: search-products.jay-action
+  - name: getProductBySlug
+    action: get-product-by-slug.jay-action
+  - name: getCategories
+    action: get-categories.jay-action
 ```
 
 Key fields:
 
 - `contracts[].name` — use in `contract="..."` in jay-html
 - `contracts[].description` — what the component does (helps you decide which to use)
-- `actions[]` — action names you can run with `jay-stack action <plugin>/<action>`
+- `actions[].name` — action name (use with `jay-stack action <plugin>/<action>`)
+- `actions[].action` — path to `.jay-action` file with full metadata (description, input/output schemas)
 
 ## Reading .jay-contract Files
 
@@ -202,6 +203,56 @@ tags:
             elementType: HTMLButtonElement
 ```
 
+## Reading .jay-action Files
+
+Actions with `.jay-action` files have rich metadata: name, description, and typed input/output schemas. Read the file at the `path` from `plugins-index.yaml` (or from `plugin.yaml`'s `actions[].action` field).
+
+### .jay-action Format
+
+```yaml
+name: searchProducts
+description: Search products with text/filter/sort/pagination
+
+import:
+  productCard: product-card.jay-contract
+
+inputSchema:
+  query: string
+  filters?:
+    inStockOnly?: boolean
+    minPrice?: number
+    maxPrice?: number
+  sortBy?: enum(relevance | price_asc | price_desc)
+  pageSize?: number
+
+outputSchema:
+  products:
+    - productCard
+  totalCount: number
+  hasMore: boolean
+```
+
+### Jay-Type Notation
+
+Schemas use a compact type notation:
+
+| Notation                          | Meaning                                                  |
+| --------------------------------- | -------------------------------------------------------- |
+| `propName: string`                | Required string property                                 |
+| `propName?: number`               | Optional number property                                 |
+| `propName: boolean`               | Required boolean                                         |
+| `propName: enum(a \| b \| c)`     | Required enum                                            |
+| `propName:` + nested block        | Nested object                                            |
+| `propName:` + `- childProp: type` | Array of objects (YAML list)                             |
+| `propName: importedName`          | Type from `import:` block (references a `.jay-contract`) |
+| `- importedName`                  | Array of imported type                                   |
+
+### Using Action Metadata
+
+1. **Discovery** — read `plugins-index.yaml` for action names and descriptions
+2. **Details** — read the `.jay-action` file at the path for full input/output schemas
+3. **Run** — use `jay-stack action <plugin>/<action> --input '{...}'` with a JSON body matching the inputSchema
+
 ## From Contract to Jay-HTML
 
 ### Step by step

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { LogLevel } from '@jay-framework/logger';
-import { PublishMessage, PublishResponse, SaveImageMessage, SaveImageResponse, HasImageMessage, HasImageResponse, GetProjectInfoMessage, GetProjectInfoResponse } from '@jay-framework/editor-protocol';
-export { ContractIndexEntry, ContractsIndex, MaterializeContractsOptions, MaterializeResult, listContracts, materializeContracts } from '@jay-framework/stack-server-runtime';
+import { PublishMessage, PublishResponse, SaveImageMessage, SaveImageResponse, HasImageMessage, HasImageResponse, GetProjectInfoMessage, GetProjectInfoResponse, ExportMessage, ExportResponse, ImportMessage, ImportResponse, ProjectPage, Plugin } from '@jay-framework/editor-protocol';
+export { MaterializeContractsOptions, MaterializeResult, PluginContractEntry, PluginsIndex, PluginsIndexEntry, listContracts, materializeContracts } from '@jay-framework/stack-server-runtime';
 
 interface StartDevServerOptions {
     projectPath?: string;
@@ -35,6 +35,78 @@ declare function createEditorHandlers(config: Required<JayConfig>, tsConfigPath:
     onSaveImage: (params: SaveImageMessage) => Promise<SaveImageResponse>;
     onHasImage: (params: HasImageMessage) => Promise<HasImageResponse>;
     onGetProjectInfo: (params: GetProjectInfoMessage) => Promise<GetProjectInfoResponse>;
+    onExport: <TVendorDoc>(params: ExportMessage<TVendorDoc>) => Promise<ExportResponse>;
+    onImport: <TVendorDoc_1>(params: ImportMessage<TVendorDoc_1>) => Promise<ImportResponse<TVendorDoc_1>>;
 };
 
-export { type JayConfig, type StartDevServerOptions, createEditorHandlers, getConfigWithDefaults, loadConfig, startDevServer, updateConfig };
+/**
+ * Vendor Interface
+ *
+ * Each vendor (e.g., Figma, Sketch, Adobe XD) implements this interface
+ * to provide conversion from their native format to Jay HTML format.
+ */
+
+/**
+ * Result of vendor conversion containing body HTML, fonts, and contract data
+ */
+interface VendorConversionResult {
+    /**
+     * The body HTML content (without <html>, <head>, or <body> tags)
+     */
+    bodyHtml: string;
+    /**
+     * Set of font family names used in the document
+     */
+    fontFamilies: Set<string>;
+    /**
+     * Optional contract data for the page
+     * If provided, will be used to generate the jay-data script tag
+     */
+    contractData?: {
+        /**
+         * Contract name
+         */
+        name: string;
+        /**
+         * Contract tags in YAML format
+         */
+        tagsYaml: string;
+    };
+}
+interface Vendor<TVendorDoc = any> {
+    /**
+     * The unique identifier for this vendor (e.g., 'figma', 'sketch', 'xd')
+     */
+    vendorId: string;
+    /**
+     * Convert vendor document to body HTML with metadata
+     *
+     * @param vendorDoc - The vendor's native document format (e.g., Figma SectionNode)
+     * @param pageUrl - The page URL/route (e.g., '/home', '/products')
+     * @returns Conversion result with body HTML, fonts, and contract data
+     */
+    convertToBodyHtml(vendorDoc: TVendorDoc, pageUrl: string, projectPage: ProjectPage, plugins: Plugin[]): Promise<VendorConversionResult>;
+}
+
+/**
+ * Get a vendor by ID
+ *
+ * @param vendorId - The vendor ID
+ * @returns The vendor or undefined if not found
+ */
+declare function getVendor(vendorId: string): Vendor | undefined;
+/**
+ * Check if a vendor exists
+ *
+ * @param vendorId - The vendor ID
+ * @returns True if vendor exists
+ */
+declare function hasVendor(vendorId: string): boolean;
+/**
+ * Get all registered vendor IDs
+ *
+ * @returns Array of vendor IDs
+ */
+declare function getRegisteredVendors(): string[];
+
+export { type JayConfig, type StartDevServerOptions, type Vendor, createEditorHandlers, getConfigWithDefaults, getRegisteredVendors, getVendor, hasVendor, loadConfig, startDevServer, updateConfig };