create-jay 0.21.0

package/dist/index.js

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+
+// lib/index.ts
+import path2 from "node:path";
+import { execSync } from "node:child_process";
+import chalk from "chalk";
+
+// lib/prompts.ts
+import { input, checkbox } from "@inquirer/prompts";
+
+// lib/plugins.ts
+var PLUGINS = [
+  {
+    name: "@jay-framework/ui-kit",
+    label: "UI Kit",
+    description: "Headless primitives: popover, carousel, tabs, clipboard, split text",
+    group: "Jay Framework",
+    checked: true,
+    isDep: true
+  },
+  {
+    name: "@jay-framework/a11y-validator",
+    label: "Accessibility validator",
+    description: "WCAG accessibility checks for jay-html templates",
+    group: "Jay Framework",
+    checked: true,
+    isDep: false
+  },
+  {
+    name: "@jay-framework/seo-validator",
+    label: "SEO validator",
+    description: "SEO best practices: meta tags, heading hierarchy, image optimization",
+    group: "Jay Framework",
+    checked: true,
+    isDep: false
+  },
+  {
+    name: "@jay-framework/design-system-validator",
+    label: "Design system validator",
+    description: "Validates CSS against DESIGN.md tokens",
+    group: "Jay Framework",
+    checked: true,
+    isDep: false
+  },
+  {
+    name: "@jay-framework/wix-stores",
+    label: "Wix Stores",
+    description: "E-commerce: products, categories, search, product pages",
+    group: "Wix",
+    checked: false,
+    isDep: true
+  },
+  {
+    name: "@jay-framework/wix-cart",
+    label: "Wix Cart",
+    description: "Shopping cart: add/remove items, checkout, order summary",
+    group: "Wix",
+    checked: false,
+    isDep: true
+  },
+  {
+    name: "@jay-framework/wix-members",
+    label: "Wix Members",
+    description: "Authentication: login, register, member profiles, auth callback",
+    group: "Wix",
+    checked: false,
+    isDep: true
+  },
+  {
+    name: "@jay-framework/wix-media",
+    label: "Wix Media",
+    description: "Image optimization, media galleries, responsive images",
+    group: "Wix",
+    checked: false,
+    isDep: true
+  },
+  {
+    name: "@jay-framework/wix-data",
+    label: "Wix Data",
+    description: "CMS collections: dynamic pages, content management",
+    group: "Wix",
+    checked: false,
+    isDep: true
+  },
+  {
+    name: "@jay-framework/wix-deploy",
+    label: "Wix Deploy",
+    description: "Deployment to Wix infrastructure: CDN, hosting, domains",
+    group: "Wix",
+    checked: false,
+    isDep: true
+  },
+  {
+    name: "@jay-framework/wix-server-client",
+    label: "Wix Server Client",
+    description: "Server-side Wix API client: authentication, API access",
+    group: "Wix",
+    checked: false,
+    isDep: true
+  },
+  {
+    name: "@jay-framework/aiditor",
+    label: "AIditor",
+    description: "Visual AI editor: point-and-shoot editing with Claude",
+    group: "AIditor",
+    checked: false,
+    isDep: true
+  }
+];
+var CORE_DEPS = [
+  "@jay-framework/fullstack-component",
+  "@jay-framework/runtime",
+  "@jay-framework/stack-client-runtime",
+  "@jay-framework/stack-server-runtime"
+];
+var CORE_DEV_DEPS = [
+  "@jay-framework/jay-stack-cli",
+  "@jay-framework/compiler-jay-stack",
+  "@jay-framework/dev-environment",
+  "@jay-framework/jay-cli",
+  "typescript",
+  "vite"
+];
+
+// lib/prompts.ts
+async function runPrompts() {
+  const name = await input({
+    message: "Project name:",
+    validate: (value) => {
+      if (!value.trim())
+        return "Project name is required";
+      if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(value.trim())) {
+        return "Use lowercase letters, numbers, and hyphens (e.g., my-store)";
+      }
+      return true;
+    }
+  });
+  const groups = /* @__PURE__ */ new Map();
+  for (const plugin of PLUGINS) {
+    const group = groups.get(plugin.group) || [];
+    group.push(plugin);
+    groups.set(plugin.group, group);
+  }
+  const choices = [];
+  for (const [group, plugins] of groups) {
+    choices.push({ name: `\u2500\u2500 ${group} \u2500\u2500`, value: "__separator__", disabled: "" });
+    for (const plugin of plugins) {
+      choices.push({
+        name: `${plugin.label} \u2014 ${plugin.description}`,
+        value: plugin.name,
+        checked: plugin.checked
+      });
+    }
+  }
+  const selected = await checkbox({
+    message: "Select plugins to install:",
+    choices
+  });
+  const selectedPlugins = PLUGINS.filter((p) => selected.includes(p.name));
+  return { name: name.trim(), selectedPlugins };
+}
+
+// lib/scaffold.ts
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+var __dirname = path.dirname(fileURLToPath(import.meta.url));
+function templatesDir() {
+  const fromDist = path.join(__dirname, "..", "templates");
+  if (fs.existsSync(fromDist))
+    return fromDist;
+  return path.join(__dirname, "templates");
+}
+function readTemplate(name) {
+  return fs.readFileSync(path.join(templatesDir(), name), "utf-8");
+}
+function writeFile(projectDir, relativePath, content) {
+  const fullPath = path.join(projectDir, relativePath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, content, "utf-8");
+}
+function generatePackageJson(name, selectedPlugins) {
+  const deps = {};
+  for (const dep of CORE_DEPS) {
+    deps[dep] = "latest";
+  }
+  for (const plugin of selectedPlugins) {
+    if (plugin.isDep)
+      deps[plugin.name] = "latest";
+  }
+  const devDeps = {};
+  for (const dep of CORE_DEV_DEPS) {
+    devDeps[dep] = "latest";
+  }
+  for (const plugin of selectedPlugins) {
+    if (!plugin.isDep)
+      devDeps[plugin.name] = "latest";
+  }
+  const pkg = {
+    name,
+    version: "0.1.0",
+    type: "module",
+    private: true,
+    scripts: {
+      dev: "jay-stack dev",
+      build: "jay-cli definitions src && jay-stack build",
+      serve: "jay-stack serve",
+      validate: "jay-stack validate",
+      "agent-kit": "jay-stack agent-kit",
+      setup: "jay-stack setup",
+      clean: "rimraf dist && rimraf build"
+    },
+    dependencies: sortKeys(deps),
+    devDependencies: sortKeys(devDeps)
+  };
+  return JSON.stringify(pkg, null, 2) + "\n";
+}
+function sortKeys(obj) {
+  const sorted = {};
+  for (const key of Object.keys(obj).sort()) {
+    sorted[key] = obj[key];
+  }
+  return sorted;
+}
+function scaffoldProject(projectDir, name, selectedPlugins) {
+  fs.mkdirSync(projectDir, { recursive: true });
+  writeFile(projectDir, "package.json", generatePackageJson(name, selectedPlugins));
+  writeFile(projectDir, "src/pages/page.jay-html", readTemplate("page.jay-html").replace(/\{\{name\}\}/g, name));
+  writeFile(projectDir, "src/pages/page.ts", readTemplate("page.ts"));
+  writeFile(projectDir, "src/pages/page.jay-contract", readTemplate("page.jay-contract"));
+  writeFile(projectDir, "src/styles/theme.css", readTemplate("theme.css"));
+  writeFile(projectDir, ".jay", readTemplate("jay-config.yaml"));
+  writeFile(projectDir, "vite.config.ts", readTemplate("vite.config.ts"));
+  writeFile(projectDir, "tsconfig.json", readTemplate("tsconfig.json"));
+  const jaySkillPath = path.join(templatesDir(), "jay-skill.md");
+  if (fs.existsSync(jaySkillPath)) {
+    writeFile(projectDir, "jay-skill.md", fs.readFileSync(jaySkillPath, "utf-8"));
+  }
+  const hasDesignValidator = selectedPlugins.some(
+    (p) => p.name === "@jay-framework/design-system-validator"
+  );
+  if (hasDesignValidator) {
+    writeFile(projectDir, "DESIGN.md", readTemplate("DESIGN.md"));
+  }
+}
+
+// lib/index.ts
+function detectPackageManager() {
+  const agent = process.env.npm_config_user_agent || "";
+  if (agent.startsWith("yarn"))
+    return "yarn";
+  return "npm";
+}
+function run(cmd, cwd) {
+  execSync(cmd, { cwd, stdio: "inherit" });
+}
+async function main() {
+  const pm = detectPackageManager();
+  console.log("");
+  console.log(chalk.bold("  Create Jay Stack Project"));
+  console.log("");
+  const config = await runPrompts();
+  const projectDir = path2.resolve(process.cwd(), config.name);
+  console.log("");
+  console.log(`Creating project in ${chalk.cyan(`./${config.name}`)}...`);
+  scaffoldProject(projectDir, config.name, config.selectedPlugins);
+  console.log(chalk.green("  \u2713 Created project structure"));
+  console.log(chalk.dim("  Installing dependencies..."));
+  run(pm === "yarn" ? "yarn install" : "npm install", projectDir);
+  console.log(chalk.green("  \u2713 Installed dependencies"));
+  console.log(chalk.dim("  Generating agent-kit..."));
+  try {
+    run("npx jay-stack agent-kit", projectDir);
+    console.log(chalk.green("  \u2713 Generated agent-kit"));
+  } catch {
+    console.log(chalk.yellow("  \u26A0 Agent-kit generation skipped (can run later with: jay-stack agent-kit)"));
+  }
+  console.log(chalk.dim("  Running plugin setup..."));
+  try {
+    run("npx jay-stack setup", projectDir);
+    console.log(chalk.green("  \u2713 Plugin setup complete"));
+  } catch {
+    console.log(chalk.yellow("  \u26A0 Setup incomplete (can run later with: jay-stack setup)"));
+  }
+  const runCmd = pm === "yarn" ? "yarn dev" : "npm run dev";
+  console.log("");
+  console.log(chalk.bold("  Ready!"));
+  console.log("");
+  console.log(`  ${chalk.cyan(`cd ${config.name}`)}`);
+  console.log(`  ${chalk.cyan(runCmd)}`);
+  console.log("");
+}
+main().catch((err) => {
+  if (err.message?.includes("User force closed")) {
+    console.log("\nAborted.");
+    process.exit(0);
+  }
+  console.error(chalk.red("Error:"), err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "create-jay",
+  "version": "0.21.0",
+  "type": "module",
+  "description": "Create a new Jay Stack project",
+  "license": "Apache-2.0",
+  "bin": "./dist/index.js",
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build",
+    "test": ":"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "chalk": "^5.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3"
+  }
+}

package/templates/DESIGN.md

@@ -0,0 +1,71 @@
+---
+name: My Design System
+
+colors:
+  primary: '#2563eb'
+  primary-hover: '#1d4ed8'
+  secondary: '#64748b'
+  text: '#0f172a'
+  text-muted: '#64748b'
+  background: '#ffffff'
+  surface: '#f8fafc'
+  border: '#e2e8f0'
+  error: '#dc2626'
+  success: '#16a34a'
+
+typography:
+  headline-lg:
+    fontFamily: system-ui, sans-serif
+    fontSize: 2.5rem
+    fontWeight: 700
+    lineHeight: 1.2
+  headline-md:
+    fontFamily: system-ui, sans-serif
+    fontSize: 2rem
+    fontWeight: 600
+    lineHeight: 1.3
+  body-md:
+    fontFamily: system-ui, sans-serif
+    fontSize: 1rem
+    fontWeight: 400
+    lineHeight: 1.6
+  label-sm:
+    fontFamily: system-ui, sans-serif
+    fontSize: 0.875rem
+    fontWeight: 500
+    lineHeight: 1.5
+
+spacing:
+  xs: 0.25rem
+  sm: 0.5rem
+  md: 1rem
+  lg: 1.5rem
+  xl: 2rem
+  2xl: 3rem
+
+rounded:
+  none: 0
+  sm: 0.25rem
+  md: 0.5rem
+  lg: 0.75rem
+  full: 9999px
+
+animations:
+  micro:
+    duration: 150ms
+    easing: ease-in-out
+  normal:
+    duration: 300ms
+    easing: cubic-bezier(0, 0, 0.2, 1)
+
+rules:
+  max-font-weights: 3
+  max-primary-buttons: 1
+  require-contrast-aa: true
+---
+
+# My Design System
+
+Edit this file to define your design tokens. The design-system-validator plugin validates your CSS against these tokens during `jay-stack validate`.
+
+See `agent-kit/designer/design-system.md` for usage guide.

package/templates/jay-config.yaml

@@ -0,0 +1,4 @@
+devServer:
+  portRange: [3000, 3010]
+  pagesBase: './src/pages'
+  publicFolder: './public'

package/templates/jay-skill.md

@@ -0,0 +1,123 @@
+---
+name: jay
+description: Getting started with Jay Stack projects. Covers plugin setup, agent-kit generation, the four roles (designer, developer, plugin, devops), and key CLI commands.
+---
+
+# Jay Stack — Agent Skill
+
+Jay Stack is a full-stack framework. Plugins provide headless components (data + logic, no UI). Designers build UI in jay-html templates that bind to plugin contracts. Developers write page logic and services.
+
+## Getting Started with a Jay Project
+
+### Step 1: Setup plugins
+
+```bash
+yarn jay-stack-cli setup
+```
+
+This configures plugins — creates config templates, validates credentials, connects to external services. Run this once when starting a new project or after adding a plugin.
+
+### Step 2: Generate the agent kit
+
+```bash
+yarn jay-stack-cli agent-kit
+```
+
+This materializes contracts, generates reference data, and copies role guides into `agent-kit/`. Run this after setup, or any time you need fresh contract data.
+
+### Step 3: Read the agent kit
+
+The agent kit is your entry point. Start here:
+
+**`agent-kit/plugins-index.yaml`** — lists every plugin and what it provides:
+
+```yaml
+plugins:
+  - name: wix-stores
+    contracts:
+      - name: product-page
+        description: Product detail page with SSR
+    actions:
+      - name: searchProducts
+        description: Search the product catalog
+    services:
+      - name: products-db
+        description: Product catalog API
+    commands:
+      - name: sync-catalog
+        description: Sync product catalog from CMS
+```
+
+Use this file to discover what's available before writing any code.
+
+**`agent-kit/materialized-contracts/`** — the actual `.jay-contract` files. Read these to understand the data shapes, rendering phases, and refs for each component.
+
+**`agent-kit/references/<plugin>/`** — pre-generated discovery data (product catalogs, collection schemas, etc.). Check here before running CLI commands — it's faster.
+
+## The Four Roles
+
+The agent kit contains guides organized by role. Read the role that matches your task:
+
+| Folder                 | Role             | When to read                                                      |
+| ---------------------- | ---------------- | ----------------------------------------------------------------- |
+| `agent-kit/designer/`  | Designer         | Creating or editing `.jay-html` pages, styling, template syntax   |
+| `agent-kit/developer/` | Developer        | Writing `page.ts` components, services, state management, routing |
+| `agent-kit/plugin/`    | Plugin Developer | Creating headless components, contracts, actions, CLI commands    |
+| `agent-kit/devops/`    | DevOps           | Building, deploying, serving in production, invalidation          |
+
+Each folder has an `INSTRUCTIONS.md` that lists all available guides. Start there.
+
+## Key CLI Commands
+
+```bash
+# Development
+yarn jay-stack-cli dev                    # Start dev server
+yarn jay-stack-cli dev -v                 # Verbose mode
+
+# Validation
+yarn jay-stack-cli validate               # Validate all jay-html, contracts, actions
+
+# Discovery
+yarn jay-stack-cli agent-kit --list       # List available contracts
+yarn jay-stack-cli params <plugin>/<contract>  # Discover URL params for a contract
+yarn jay-stack-cli action <plugin>/<action> --input '{}'  # Run a plugin action
+
+# Plugin commands (admin/batch operations)
+yarn jay-stack-cli run --list             # List available plugin commands
+yarn jay-stack-cli run <plugin>/<command> # Run a plugin command
+
+# Production
+yarn jay-stack-cli build                  # Build production artifacts
+yarn jay-stack-cli serve                  # Start production server
+```
+
+## Project Structure
+
+```
+src/
+  pages/              # File-system routing
+    page.jay-html     # Root page (/)
+    products/
+      page.jay-html   # /products
+      [slug]/
+        page.jay-html # /products/:slug
+        page.ts       # Page component (optional)
+  plugins/            # Local plugins
+  components/         # Headfull components
+  init.ts             # Project service initialization
+agent-kit/            # Generated by jay-stack agent-kit
+  plugins-index.yaml  # Discovery index
+  designer/           # Designer role guides
+  developer/          # Developer role guides
+  plugin/             # Plugin developer guides
+  devops/             # DevOps guides
+  materialized-contracts/
+  references/
+```
+
+## Before Writing Code
+
+1. Read `agent-kit/plugins-index.yaml` to see what plugins and contracts exist
+2. Read the relevant contract file to understand the data shape
+3. Read the role guide that matches your task (designer/developer/plugin/devops)
+4. Check `agent-kit/references/<plugin>/` for pre-generated data before using CLI commands

package/templates/page.jay-contract

@@ -0,0 +1,12 @@
+name: page
+
+tags:
+  - tag: title
+    type: data
+    dataType: string
+    phase: slow
+
+  - tag: description
+    type: data
+    dataType: string
+    phase: slow

package/templates/page.jay-html

@@ -0,0 +1,35 @@
+<html lang="en">
+  <head>
+    <title>{{name}}</title>
+    <meta name="description" content="A Jay Stack project">
+    <script type="application/jay-data" contract="./page.jay-contract"></script>
+    <link rel="stylesheet" href="../styles/theme.css" />
+    <style>
+      .hero {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        min-height: 80vh;
+        text-align: center;
+        padding: 2rem;
+      }
+      .hero h1 {
+        font-size: 2.5rem;
+        font-weight: 700;
+        margin-bottom: 1rem;
+      }
+      .hero p {
+        font-size: 1.25rem;
+        color: #64748b;
+        max-width: 600px;
+      }
+    </style>
+  </head>
+  <body>
+    <main class="hero">
+      <h1>{title}</h1>
+      <p>{description}</p>
+    </main>
+  </body>
+</html>

package/templates/page.ts

@@ -0,0 +1,12 @@
+import { makeJayStackComponent, phaseOutput } from '@jay-framework/fullstack-component';
+import type { PageContract } from './page.jay-contract';
+
+export const page = makeJayStackComponent<PageContract>().withSlowlyRender(async () => {
+    return phaseOutput(
+        {
+            title: 'Welcome to Jay',
+            description: 'Your project is ready. Edit src/pages/page.jay-html to get started.',
+        },
+        {},
+    );
+});

package/templates/theme.css

@@ -0,0 +1,36 @@
+:root {
+  --color-text: #0f172a;
+  --color-text-muted: #64748b;
+  --color-bg: #ffffff;
+  --color-surface: #f8fafc;
+  --color-border: #e2e8f0;
+  --color-primary: #2563eb;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  font-family:
+    system-ui,
+    -apple-system,
+    sans-serif;
+  color: var(--color-text);
+  background: var(--color-bg);
+  line-height: 1.6;
+  -webkit-font-smoothing: antialiased;
+}
+
+a {
+  color: var(--color-primary);
+  text-decoration: none;
+}
+
+a:hover {
+  text-decoration: underline;
+}

package/templates/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@jay-framework/dev-environment/examples/tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+  },
+  "include": ["src"],
+}

package/templates/vite.config.ts

@@ -0,0 +1,12 @@
+import { resolve } from 'path';
+import { defineConfig } from 'vite';
+import { jayStackCompiler } from '@jay-framework/compiler-jay-stack';
+
+const jayOptions = {
+    tsConfigFilePath: resolve(__dirname, 'tsconfig.json'),
+    outputDir: 'build',
+};
+
+export default defineConfig({
+    plugins: [...jayStackCompiler(jayOptions)],
+});