@jay-framework/jay-stack-cli 0.6.9 → 0.6.10

package/README.md

@@ -32,6 +32,7 @@ The CLI uses a `.jay` configuration file (YAML format) to customize port ranges
 devServer:
   portRange: [3000, 3100]
   pagesBase: './src/pages' # Directory containing your Jay pages
+  componentsBase: './src/components' # Directory containing your Jay components
   publicFolder: './public' # Directory for static files (CSS, JS, images, etc.)
 editorServer:
   portRange: [3101, 3200]
@@ -42,6 +43,7 @@ If no `.jay` file is found, the CLI will use default values:
 
 - **Dev Server Port Range**: `3000-3100`
 - **Pages Directory**: `./src/pages`
+- **Components Directory**: `./src/components`
 - **Public Folder**: `./public`
 - **Editor Server Port Range**: `3101-3200`
 
@@ -54,6 +56,7 @@ The CLI automatically finds available ports within these ranges using the `get-p
 The CLI uses the following default configuration:
 
 - **Pages Directory**: `./src/pages` - All Jay pages should be placed in this directory
+- **Components Directory**: `./src/components` - All Jay components should be placed in this directory
 - **Public Folder**: `./public` - Static files (CSS, JS, images) are served from this directory
 - **TypeScript Config**: `./tsconfig.json` - Uses the project's TypeScript configuration
 - **Output Directory**: `build/@jay-framework/runtime` - Compiled Jay runtime files
@@ -68,18 +71,25 @@ Your project should have the following structure:
 ```
 your-project/
 ├── src/
-│   └── pages/                      # Your Jay pages go here
-│       ├── page.jay-html           # homepage
-│       ├── page.ts                 # optional logic for the page
-│       └── page2/
-│           ├── page.jay-html       # a page with the url /page2
-│           └── page.ts             # optional logic for page2
-│       └── segment/
-│           ├── page.jay-html       # the root page for the url subdirectory /segment
-│           ├── page.ts             # optional logic for the segment root page
-│           └── [slug]/             # parameterized segment
-│               ├── page.jay-html   # a page with url parameters
-│               ├── page.ts         # optional logic for the segment parameterized page
+│   ├── pages/                      # Your Jay pages go here
+│   │   ├── page.jay-html           # homepage
+│   │   ├── page.jay-contract       # optional contract for homepage (headless pages)
+│   │   ├── page.ts                 # optional logic for the page
+│   │   └── page2/
+│   │       ├── page.jay-html       # a page with the url /page2
+│   │       ├── page.jay-contract   # optional contract for page2
+│   │       └── page.ts             # optional logic for page2
+│   │   └── segment/
+│   │       ├── page.jay-html       # the root page for the url subdirectory /segment
+│   │       ├── page.ts             # optional logic for the segment root page
+│   │       └── [slug]/             # parameterized segment
+│   │           ├── page.jay-html   # a page with url parameters
+│   │           ├── page.ts         # optional logic for the segment parameterized page
+│   └── components/                 # Your Jay components go here
+│       ├── Button.jay-html         # reusable button component
+│       ├── Button.jay-contract     # optional contract for headless components
+│       ├── Button.ts               # optional logic for the button
+│       └── Counter.jay-html        # another component
 ├── public/                         # Static files (CSS, JS, images, etc.)
 │   ├── styles.css
 │   ├── script.js
@@ -88,6 +98,41 @@ your-project/
 └── package.json
 ```
 
+## Editor Integration & Contract Publishing
+
+The Jay Stack CLI supports publishing both pages and components through editor integrations. This includes support for **jay-contract files** which enable headless component functionality:
+
+### Contract Files
+
+Contract files (`.jay-contract`) define the interface for headless components:
+
+- **Data Structure**: Defines what data the component expects
+- **Refs Interface**: Specifies interactive elements and their types
+- **Component Name**: Identifies the component for imports
+
+### Publishing Support
+
+When using design tools or editor integrations, you can publish:
+
+1. **Pages**: `page.jay-html` + optional `page.jay-contract`
+2. **Components**: `{name}.jay-html` + optional `{name}.jay-contract`
+
+Contract files are automatically placed alongside their corresponding jay-html files and can be referenced in headless imports:
+
+```html
+<script
+  type="application/jay-headless"
+  contract="./Button.jay-contract"
+  src="./Button"
+  name="button"
+  key="button"
+></script>
+```
+
+### Backward Compatibility
+
+Contract publishing is completely optional and maintains full backward compatibility with existing Jay Stack projects.
+
 ## Development
 
 The CLI is built using:

package/dist/index.js

@@ -15934,6 +15934,12 @@ async function handlePagePublish(resolvedConfig2, page) {
     const fullPath = path.join(dirname, PAGE_FILENAME);
     await fs.promises.mkdir(dirname, { recursive: true });
     await fs.promises.writeFile(fullPath, page.jayHtml, "utf-8");
+    let contractPath;
+    if (page.contract) {
+      contractPath = path.join(dirname, `page${JAY_CONTRACT_EXTENSION}`);
+      await fs.promises.writeFile(contractPath, page.contract, "utf-8");
+      console.log(`📄 Published page contract: ${contractPath}`);
+    }
     const createdJayHtml = {
       jayHtml: page.jayHtml,
       filename: PAGE_FILENAME,
@@ -15944,7 +15950,8 @@ async function handlePagePublish(resolvedConfig2, page) {
     return [
       {
         success: true,
-        filePath: fullPath
+        filePath: fullPath,
+        contractPath
       },
       createdJayHtml
     ];
@@ -15966,6 +15973,11 @@ async function handleComponentPublish(resolvedConfig2, component) {
     const fullPath = path.join(dirname, filename);
     await fs.promises.mkdir(dirname, { recursive: true });
     await fs.promises.writeFile(fullPath, component.jayHtml, "utf-8");
+    let contractPath;
+    if (component.contract) {
+      contractPath = path.join(dirname, `${component.name}${JAY_CONTRACT_EXTENSION}`);
+      await fs.promises.writeFile(contractPath, component.contract, "utf-8");
+    }
     const createdJayHtml = {
       jayHtml: component.jayHtml,
       filename,
@@ -15976,7 +15988,8 @@ async function handleComponentPublish(resolvedConfig2, component) {
     return [
       {
         success: true,
-        filePath: fullPath
+        filePath: fullPath,
+        contractPath
       },
       createdJayHtml
     ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/jay-stack-cli",
-  "version": "0.6.9",
+  "version": "0.6.10",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -23,13 +23,13 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/dev-server": "^0.6.9",
-    "@jay-framework/editor-server": "^0.6.9",
+    "@jay-framework/dev-server": "^0.6.10",
+    "@jay-framework/editor-server": "^0.6.10",
     "express": "^5.0.1",
     "vite": "^5.0.11"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.6.9",
+    "@jay-framework/dev-environment": "^0.6.10",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",