@jay-framework/aiditor 0.17.3 → 0.18.0

package/README.md

@@ -23,11 +23,7 @@ The plugin auto-registers with the Jay dev server — no additional configuratio
 
 ## Requirements
 
-The AI agent runs server-side via the Claude Agent SDK. Set your API key as an environment variable:
-
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...
-```
+The AI agent runs server-side via the Claude Agent SDK (`query()`). Authentication matches Claude Code — set `ANTHROPIC_API_KEY` or run `claude login`.
 
 ## Usage
 

package/dist/actions/check-add-page-route.jay-action

@@ -0,0 +1,12 @@
+name: checkAddPageRouteAction
+description: Validate and normalize an Add Page route; check if it already exists
+
+inputSchema:
+  pageRoute: string
+
+outputSchema:
+  normalizedRoute: string
+  routeKind: static | dynamic
+  routeExists: boolean
+  valid: boolean
+  error?: string

package/dist/actions/check-add-page-route.jay-action.d.ts

@@ -0,0 +1,10 @@
+export interface CheckAddPageRouteActionInput {
+  pageRoute: string;
+}
+
+export interface CheckAddPageRouteActionOutput {
+  normalizedRoute: string;
+  routeExists: boolean;
+  valid: boolean;
+  error?: string;
+}

package/dist/actions/check-page-add-page-brief.jay-action

@@ -0,0 +1,9 @@
+name: checkPageAddPageBriefAction
+description: Check whether a Jay page has saved Add Page brief files next to its jay-html
+
+inputSchema:
+  jayHtmlPath: string
+  pageRoute?: string
+
+outputSchema:
+  hasBrief: boolean

package/dist/actions/check-page-add-page-brief.jay-action.d.ts

@@ -0,0 +1,8 @@
+export interface CheckPageAddPageBriefActionInput {
+  jayHtmlPath: string;
+  pageRoute?: string;
+}
+
+export interface CheckPageAddPageBriefActionOutput {
+  hasBrief: boolean;
+}

package/dist/actions/check-plugin-update.jay-action

@@ -0,0 +1,14 @@
+name: checkPluginUpdateAction
+description: Compare installed plugin version with latest on npm
+
+inputSchema:
+  pluginName: string
+
+outputSchema:
+  pluginName: string
+  packageName: string
+  installedVersion?: string
+  latestVersion?: string
+  updateAvailable: boolean
+  isLocalSource: boolean
+  message?: string

package/dist/actions/check-plugin-update.jay-action.d.ts

@@ -0,0 +1,13 @@
+export interface CheckPluginUpdateActionInput {
+  pluginName: string;
+}
+
+export interface CheckPluginUpdateActionOutput {
+  pluginName: string;
+  packageName: string;
+  installedVersion?: string;
+  latestVersion?: string;
+  updateAvailable: boolean;
+  isLocalSource: boolean;
+  message?: string;
+}

package/dist/actions/ensure-project-plugin.jay-action

@@ -0,0 +1,9 @@
+name: ensureProjectPluginAction
+description: Install plugin package, run setup and agent-kit (stream)
+
+inputSchema:
+  pluginName: string
+  installSpec?: string
+
+outputSchema:
+  type: string

package/dist/actions/ensure-project-plugin.jay-action.d.ts

@@ -0,0 +1,8 @@
+export interface EnsureProjectPluginActionInput {
+  pluginName: string;
+  installSpec?: string;
+}
+
+export interface EnsureProjectPluginActionOutput {
+  type: string;
+}

package/dist/actions/generate-add-page-brief-from-image.jay-action

@@ -0,0 +1,20 @@
+name: generateAddPageBriefFromImageAction
+description: Generate Add Page Content or Design markdown from screenshot(s) via vision AI
+
+inputSchema:
+  target: content | design
+  requestId?: string
+  pageRoute?: string
+  contextNotes?: string
+  extraFiles?: record(file)
+
+outputSchema:
+  ok: boolean
+  markdown?: string
+  suggestedRoute?: string
+  suggestedRouteKind?: static | dynamic
+  referenceAttachments?:
+  - id: string
+    path: string
+    filename: string
+  error?: string

package/dist/actions/generate-add-page-brief-from-image.jay-action.d.ts

@@ -0,0 +1,20 @@
+import { JayFile } from '@jay-framework/fullstack-component';
+
+export interface GenerateAddPageBriefFromImageActionInput {
+  requestId?: string;
+  pageRoute?: string;
+  contextNotes?: string;
+  extraFiles?: Record<string, JayFile>;
+}
+
+export interface GenerateAddPageBriefFromImageActionOutput {
+  ok: boolean;
+  markdown?: string;
+  suggestedRoute?: string;
+  referenceAttachments?: Array<{
+      id: string;
+      path: string;
+      filename: string;
+    }>;
+  error?: string;
+}

package/dist/actions/get-plugin-setup-status.jay-action

@@ -0,0 +1,9 @@
+name: getPluginSetupStatusAction
+description: Query plugin setup status from cache or refresh
+
+inputSchema:
+  pluginName?: string
+  refresh?: boolean
+
+outputSchema:
+  plugins: array

package/dist/actions/get-plugin-setup-status.jay-action.d.ts

@@ -0,0 +1,6 @@
+export interface GetPluginSetupStatusActionInput {
+  pluginName?: string;
+  refresh?: boolean;
+}
+
+export type GetPluginSetupStatusActionOutput = Record<string, unknown>;

package/dist/actions/list-jay-plugins.jay-action

@@ -0,0 +1,8 @@
+name: listJayPluginsAction
+description: List Jay plugin catalog with install and setup status
+
+inputSchema:
+  refreshSetupStatus?: boolean
+
+outputSchema:
+  plugins: array

package/dist/actions/list-jay-plugins.jay-action.d.ts

@@ -0,0 +1,5 @@
+export interface ListJayPluginsActionInput {
+  refreshSetupStatus?: boolean;
+}
+
+export type ListJayPluginsActionOutput = Record<string, unknown>;

package/dist/actions/list-plugin-contracts.jay-action

@@ -0,0 +1,11 @@
+name: listPluginContractsAction
+description: List contracts for an installed plugin
+
+inputSchema:
+  pluginName: string
+
+outputSchema:
+  pluginName: string
+  installed: boolean
+  contracts: array
+  setupRequiredMessage?: string

package/dist/actions/list-plugin-contracts.jay-action.d.ts

@@ -0,0 +1,9 @@
+export interface ListPluginContractsActionInput {
+  pluginName: string;
+}
+
+export interface ListPluginContractsActionOutput {
+  pluginName: string;
+  installed: boolean;
+  setupRequiredMessage?: string;
+}

package/dist/actions/open-add-page-from-brief.jay-action

@@ -0,0 +1,20 @@
+name: openAddPageFromBriefAction
+description: Load a page's saved Add Page brief into a new page request with a unique copy route
+
+inputSchema:
+  jayHtmlPath: string
+  sourcePageRoute: string
+
+outputSchema:
+  ok: boolean
+  error?: string
+  requestId?: string
+  pageRoute?: string
+  routeKind?: static | dynamic
+  contentMd?: string
+  designMd?: string
+  attachments?:
+    - id: string
+      path: string
+      role: reference | asset
+      filename: string

package/dist/actions/open-add-page-from-brief.jay-action.d.ts

@@ -0,0 +1,18 @@
+export interface OpenAddPageFromBriefActionInput {
+  jayHtmlPath: string;
+  sourcePageRoute: string;
+}
+
+export interface OpenAddPageFromBriefActionOutput {
+  ok: boolean;
+  error?: string;
+  requestId?: string;
+  pageRoute?: string;
+  contentMd?: string;
+  designMd?: string;
+  attachments?: Array<{
+      id: string;
+      path: string;
+      filename: string;
+    }>;
+}

package/dist/actions/reclassify-add-page-asset.jay-action

@@ -0,0 +1,12 @@
+name: reclassifyAddPageAssetAction
+description: Move an attachment between references/ and assets/ for an Add Page request
+
+inputSchema:
+  requestId: string
+  attachmentId: string
+  newRole: reference | asset
+
+outputSchema:
+  ok: boolean
+  path: string
+  markdownRef?: string

package/dist/actions/reclassify-add-page-asset.jay-action.d.ts

@@ -0,0 +1,10 @@
+export interface ReclassifyAddPageAssetActionInput {
+  requestId: string;
+  attachmentId: string;
+}
+
+export interface ReclassifyAddPageAssetActionOutput {
+  ok: boolean;
+  path: string;
+  markdownRef?: string;
+}

package/dist/actions/rerun-plugin-setup.jay-action

@@ -0,0 +1,12 @@
+name: rerunPluginSetupAction
+description: Re-run jay-stack setup for a plugin
+
+inputSchema:
+  pluginName: string
+  force?: boolean
+
+outputSchema:
+  pluginName: string
+  setupStatus: string
+  configCreated?: array
+  message?: string

package/dist/actions/rerun-plugin-setup.jay-action.d.ts

@@ -0,0 +1,10 @@
+export interface RerunPluginSetupActionInput {
+  pluginName: string;
+  force?: boolean;
+}
+
+export interface RerunPluginSetupActionOutput {
+  pluginName: string;
+  setupStatus: string;
+  message?: string;
+}

package/dist/actions/save-add-page-draft.jay-action

@@ -0,0 +1,10 @@
+name: saveAddPageDraftAction
+description: Persist Add Page composer markdown to the request folder
+
+inputSchema:
+  requestId: string
+  contentMd: string
+  designMd: string
+
+outputSchema:
+  ok: boolean

package/dist/actions/save-add-page-draft.jay-action.d.ts

@@ -0,0 +1,9 @@
+export interface SaveAddPageDraftActionInput {
+  requestId: string;
+  contentMd: string;
+  designMd: string;
+}
+
+export interface SaveAddPageDraftActionOutput {
+  ok: boolean;
+}

package/dist/actions/start-add-page-request.jay-action

@@ -0,0 +1,12 @@
+name: startAddPageRequestAction
+description: Mint an Add Page request folder under .aiditor/page-requests/
+
+inputSchema:
+  pageRoute: string
+  routeKind?: static | dynamic
+
+outputSchema:
+  requestId: string
+  requestDir: string
+  routeExists: boolean
+  routeExistsMessage?: string

package/dist/actions/start-add-page-request.jay-action.d.ts

@@ -0,0 +1,10 @@
+export interface StartAddPageRequestActionInput {
+  pageRoute: string;
+}
+
+export interface StartAddPageRequestActionOutput {
+  requestId: string;
+  requestDir: string;
+  routeExists: boolean;
+  routeExistsMessage?: string;
+}

package/dist/actions/submit-add-page.jay-action

@@ -0,0 +1,21 @@
+name: submitAddPageAction
+description: Run the Add Page implementation agent and validate the result (streaming)
+
+streaming: true
+
+inputSchema:
+  requestId: string
+  contentMd: string
+  designMd: string
+  pageRoute: string
+  routeKind?: static | dynamic
+  isRetry?: boolean
+
+outputSchema:
+  type: string
+  message?: string
+  text?: string
+  name?: string
+  result?: string
+  filePath?: string
+  validateErrors?: string[]

package/dist/actions/submit-add-page.jay-action.d.ts

@@ -0,0 +1,17 @@
+export interface SubmitAddPageActionInput {
+  requestId: string;
+  contentMd: string;
+  designMd: string;
+  pageRoute: string;
+  isRetry?: boolean;
+}
+
+export interface SubmitAddPageActionOutput {
+  type: string;
+  message?: string;
+  text?: string;
+  name?: string;
+  result?: string;
+  filePath?: string;
+  validateErrors?: Array<string>;
+}

package/dist/actions/submit-task.jay-action

@@ -4,6 +4,7 @@ streaming: true
 
 inputSchema:
   notes: string
+  messageKind?: string
   pageRoute?: string
   renderedUrl?: string
   visualTask?: string

package/dist/actions/submit-task.jay-action.d.ts

@@ -2,6 +2,7 @@ import { JayFile } from '@jay-framework/fullstack-component';
 
 export interface SubmitTaskActionInput {
   notes: string;
+  messageKind?: string;
   pageRoute?: string;
   renderedUrl?: string;
   visualTask?: string;

package/dist/actions/sync-add-page-plugin-manifest.jay-action

@@ -0,0 +1,11 @@
+name: syncAddPagePluginManifestAction
+description: Sync selected plugins to content.md managed section and request.json
+
+inputSchema:
+  requestId: string
+  selectedPlugins: array
+
+outputSchema:
+  ok: boolean
+  contentMd: string
+  error?: string

package/dist/actions/sync-add-page-plugin-manifest.jay-action.d.ts

@@ -0,0 +1,9 @@
+export interface SyncAddPagePluginManifestActionInput {
+  requestId: string;
+}
+
+export interface SyncAddPagePluginManifestActionOutput {
+  ok: boolean;
+  contentMd: string;
+  error?: string;
+}

package/dist/actions/upload-add-page-asset.jay-action

@@ -0,0 +1,13 @@
+name: uploadAddPageAssetAction
+description: Upload a reference or asset file for an Add Page request
+
+inputSchema:
+  requestId: string
+  role: reference | asset
+  file: file
+
+outputSchema:
+  id: string
+  path: string
+  markdownRef: string
+  markdownSnippet?: string

package/dist/actions/upload-add-page-asset.jay-action.d.ts

@@ -0,0 +1,13 @@
+import { JayFile } from '@jay-framework/fullstack-component';
+
+export interface UploadAddPageAssetActionInput {
+  requestId: string;
+  file: JayFile;
+}
+
+export interface UploadAddPageAssetActionOutput {
+  id: string;
+  path: string;
+  markdownRef: string;
+  markdownSnippet?: string;
+}

package/dist/actions/write-plugin-source.jay-action

@@ -0,0 +1,13 @@
+name: writePluginSourceAction
+description: Add or update a local plugin source in .aiditor/plugin-sources.yaml
+
+inputSchema:
+  pluginName: string
+  packageName: string
+  installSpec: string
+  label?: string
+  kind?: string
+  description?: string
+
+outputSchema:
+  ok: boolean

package/dist/actions/write-plugin-source.jay-action.d.ts

@@ -0,0 +1,12 @@
+export interface WritePluginSourceActionInput {
+  pluginName: string;
+  packageName: string;
+  installSpec: string;
+  label?: string;
+  kind?: string;
+  description?: string;
+}
+
+export interface WritePluginSourceActionOutput {
+  ok: boolean;
+}

package/dist/add-page-agent/SKILL.md

@@ -0,0 +1,79 @@
+# Add Page — implementation steps
+
+Follow these steps in order when creating a Jay Stack page from an Add Page brief.
+
+## 1. Read the brief
+
+1. Read `content.md` — behavior, plugins, contracts, copy, interactions.
+2. Read `design.md` — layout, typography, colors, spacing, responsive behavior.
+3. List files in `references/` and `assets/` under the request folder.
+
+## 2. Map route → page path
+
+Jay uses directory-based routing under `src/pages/`:
+
+| Route                    | Page directory                                  |
+| ------------------------ | ----------------------------------------------- |
+| `/`                      | `src/pages/page.jay-html`                       |
+| `/about`                 | `src/pages/about/page.jay-html`                 |
+| `/products/[slug]`       | `src/pages/products/[slug]/page.jay-html`       |
+| `/products/[[category]]` | `src/pages/products/[[category]]/page.jay-html` |
+
+Dynamic segment names must match contract `params` (e.g. `slug`, `category`, `prefix`).
+
+For static routes that use a dynamic contract, add:
+
+```html
+<script type="application/jay-params">
+  slug: my-product-slug
+</script>
+```
+
+## 3. Discover contracts
+
+1. Read `agent-kit/plugins-index.yaml` for installed plugins and contract paths.
+2. Read each selected contract's `.jay-contract` file — note `params`, tag types, phases, and refs.
+3. Consult `agent-kit/designer/routing.md`, `jay-html-syntax.md`, and `contracts-and-plugins.md` as needed.
+
+## 4. Scaffold the page
+
+Create `page.jay-html` (and `page.ts` / `page.jay-contract` only if the brief requires custom page logic).
+
+Minimum headless import:
+
+```html
+<script
+  type="application/jay-headless"
+  plugin="@jay-framework/wix-stores"
+  contract="product-page"
+  key="product"
+></script>
+```
+
+Use the plugin manifest from the user message for exact `plugin`, `contract`, and `key` values.
+
+## 5. Bind data and interactions
+
+- Data: `{contractKey.fieldName}` in text and attributes.
+- Conditionals: `<div if="condition">` — use `===` not `==`.
+- Loops: `<div forEach="items" trackBy="id">`.
+- Interactions: `ref="contractKey.refName"` on the target element.
+
+Read contract tags before binding — do not invent field names.
+
+## 6. Apply design
+
+- Match `design.md` for layout, colors, typography, and breakpoints.
+- Reuse patterns from existing pages (header, footer, nav) when requested.
+- Use `references/*` for spacing and composition inspiration only.
+
+## 7. Copy assets
+
+When `content.md` or `design.md` cites an asset file:
+
+1. Copy from the request folder's `assets/` into the project (`public/` or an appropriate path).
+2. Reference the copied path in the page (e.g. `src="/images/hero.png"`).
+
+## 8. Finish
+
+Summarize files created, how they satisfy the brief, and any blockers. Do not run `jay-stack validate` — the server validates after the agent completes.

package/dist/add-page-agent/system.md

@@ -0,0 +1,47 @@
+You are a Jay Stack page author working inside an existing Jay project.
+
+Your job is to create **one** page at the route given in the user message. Match the user's intent from their brief files as closely as possible.
+
+## Scope
+
+- Create or fix page files for **this route only** — do not refactor unrelated pages.
+- Read `content.md` and `design.md` in the request folder before writing code.
+- Follow `agent-kit/designer/INSTRUCTIONS.md` and `agent-kit/developer/INSTRUCTIONS.md` in the project.
+- Reuse existing site patterns (header, footer, typography, spacing) from other pages when the brief asks for consistency.
+
+## Headless components
+
+When the user message includes a plugin manifest table:
+
+- Add `<script type="application/jay-headless" plugin="..." contract="..." key="...">` for each entry.
+- Bind UI using contract ViewState fields and refs per agent-kit designer guides.
+- Read the materialized `.jay-contract` files listed in `agent-kit/plugins-index.yaml` before binding.
+
+If Wix or other plugin config is incomplete, still implement layout and headless imports. Live store data may be unavailable until config files are filled.
+
+## Attachments
+
+- `references/*` — inspiration only; do not copy verbatim unless the brief says so.
+- `assets/*` — copy cited assets from the request folder into appropriate project paths (`public/`, etc.) when implementing.
+
+## Dynamic routes
+
+- Map route segments to directory names under `src/pages/` per Jay routing conventions.
+- For static override routes (no dynamic segment), declare params with `<script type="application/jay-params">` (YAML body).
+- Use `jay-params` when a headless contract requires params that are not in the URL path.
+
+## Validation
+
+Do **not** run `jay-stack validate` yourself — the server runs validation after you finish.
+
+## Retry mode
+
+If the user message says retry mode, read existing page files at the route and **fix** issues rather than recreating from scratch.
+
+## Output
+
+When done, summarize:
+
+1. Files created or modified
+2. How the implementation covers the brief
+3. Any assumptions or blockers (missing config, ambiguous design, etc.)