@jay-framework/jay-stack-cli 0.16.0 → 0.16.1

package/agent-kit-template/developer/page-components.md

@@ -81,6 +81,37 @@ export const page = makeJayStackComponent<ProductPageContract>()
   });
 ```
 
+## Calling File Upload Actions
+
+Actions created with `.withFiles()` accept browser `File` objects directly. Use `oninput` events on file inputs to drive signals, then pass them to the action:
+
+```typescript
+import { createSignal } from '@jay-framework/component';
+import { uploadPhoto } from '../actions/upload.actions';
+
+.withInteractive(function UploadPage(props, refs, fastViewState) {
+    const [result, setResult] = createSignal('');
+    const [selectedFile, setSelectedFile] = createSignal<File | undefined>(undefined);
+
+    refs.fileInput.oninput(({ event }) => {
+        setSelectedFile((event.target as HTMLInputElement).files?.[0]);
+    });
+
+    refs.uploadBtn.onclick(async () => {
+        const file = selectedFile();
+        if (!file) return;
+        const res = await uploadPhoto({ caption: 'My photo', photo: file });
+        setResult(res.message);
+    });
+
+    return {
+        render: () => ({ result: result() }),
+    };
+})
+```
+
+No casting needed — browser `File` is assignable to `JayFile`.
+
 ## Combining with Headless Plugins
 
 A page component handles page-level data. Plugin headless components handle their own data independently. Both render into the same page:

package/agent-kit-template/plugin/actions-guide.md

@@ -38,12 +38,99 @@ makeJayAction('name')
   .withServices(SERVICE1, SERVICE2) // Inject services
   .withMethod('PUT') // Override HTTP method (default: POST for actions)
   .withCaching({ maxAge: 60 }) // Enable caching (queries only)
+  .withFiles({ maxFileSize: 5_000_000 }) // Accept file uploads (multipart/form-data)
   .withHandler(async (input, svc1, svc2) => {
     // Define handler
     return result;
   });
 ```
 
+## .withFiles() — File Uploads
+
+Actions can receive binary files (images, documents, etc.) via multipart/form-data.
+Add `.withFiles()` to the builder chain to enable file uploads.
+
+```typescript
+import { makeJayAction, type JayFile } from '@jay-framework/fullstack-component';
+import fs from 'fs';
+
+export const uploadPhoto = makeJayAction('photos.upload')
+  .withFiles({ maxFileSize: 5 * 1024 * 1024 }) // 5MB limit, 10 files max (default)
+  .withHandler(async (input: { caption: string; photo: JayFile }) => {
+    // JayFile provides: name, type, size, path (temp file on disk)
+    const data = fs.readFileSync(input.photo.path);
+    // Process file...
+    return { fileName: input.photo.name, size: input.photo.size };
+    // Temp file is automatically cleaned up after handler returns
+  });
+```
+
+### JayFile type
+
+```typescript
+interface JayFile {
+  name: string; // Original filename
+  type: string; // MIME type (e.g., 'image/png')
+  size: number; // File size in bytes
+  path: string; // Absolute path to temp file on disk
+}
+```
+
+### Multiple files
+
+Use an array type for the field — files with the same field name are grouped:
+
+```typescript
+.withHandler(async (input: { images: JayFile[] }) => {
+    for (const img of input.images) {
+      // Process each file
+    }
+});
+```
+
+**File fields must be top-level properties** — not nested inside objects. Dynamic file fields via index signatures are supported:
+
+```typescript
+{ notes: string; screenshot: JayFile; extras: JayFile[] }           // OK
+{ notes: string; [key: string]: string | JayFile | undefined }      // OK
+{ meta: { photo: JayFile } }                                        // NOT supported
+```
+
+### Streaming with files
+
+`makeJayStream` also supports `.withFiles()`:
+
+```typescript
+export const processImages = makeJayStream('images.process')
+  .withFiles()
+  .withHandler(async function* (input: { images: JayFile[] }) {
+    for (const img of input.images) {
+      yield { step: 'processing', fileName: img.name };
+    }
+    yield { step: 'done' };
+  });
+```
+
+### Client-side usage
+
+The client automatically sends `FormData` when `File` or `Blob` objects are present:
+
+```typescript
+refs.uploadBtn.onClick(async () => {
+  const fileInput = refs.fileInput.element as HTMLInputElement;
+  const file = fileInput.files?.[0];
+  const result = await uploadPhoto({ caption: 'My photo', photo: file });
+});
+```
+
+### FileUploadOptions
+
+```typescript
+.withFiles()                                       // Defaults: 10MB per file, 10 files max
+.withFiles({ maxFileSize: 2 * 1024 * 1024 })       // 2MB limit
+.withFiles({ maxFileSize: 20_000_000, maxFiles: 5 }) // 20MB, 5 files
+```
+
 ## ActionError
 
 Throw typed errors from action handlers:
@@ -109,6 +196,8 @@ outputSchema:
 | `prop: string`            | Required string           |
 | `prop?: number`           | Optional number           |
 | `prop: boolean`           | Required boolean          |
+| `prop: file`              | File upload (`JayFile`)   |
+| `prop: file[]`            | Multiple file uploads     |
 | `prop: enum(a \| b \| c)` | Required enum             |
 | `prop:` + nested block    | Nested object             |
 | `prop:` + `- child: type` | Array of objects          |
@@ -167,6 +256,34 @@ outputSchema:
   - slug: string
 ```
 
+### .jay-action for file uploads
+
+Use `file` type for upload fields. The generated TypeScript uses `JayFile`:
+
+```yaml
+name: uploadPhoto
+description: Upload a product photo with caption
+inputSchema:
+  caption: string
+  photo: file
+  attachments?: file[]
+outputSchema:
+  fileId: string
+  message: string
+```
+
+For dynamic file fields, use `record(file)`:
+
+```yaml
+name: submitTask
+description: Submit task with named file attachments
+inputSchema:
+  notes: string
+  files: record(file)
+```
+
+This generates `files: Record<string, JayFile>`.
+
 ## Type Helpers
 
 ```typescript

package/dist/index.js

@@ -4352,15 +4352,29 @@ async function runAction(actionRef, options, projectRoot, initializeServices) {
 async function runParams(contractRef, options, projectRoot, initializeServices) {
   let viteServer;
   try {
-    const slashIndex = contractRef.indexOf("/");
-    if (slashIndex === -1) {
-      getLogger().error(
-        chalk.red("❌ Invalid contract reference. Use format: <plugin>/<contract>")
-      );
-      process.exit(1);
+    let pluginName;
+    let contractName;
+    if (contractRef.startsWith("@")) {
+      const secondSlash = contractRef.indexOf("/", contractRef.indexOf("/") + 1);
+      if (secondSlash === -1) {
+        getLogger().error(
+          chalk.red("❌ Invalid contract reference. Use format: @scope/plugin/contract")
+        );
+        process.exit(1);
+      }
+      pluginName = contractRef.substring(0, secondSlash);
+      contractName = contractRef.substring(secondSlash + 1);
+    } else {
+      const slashIndex = contractRef.indexOf("/");
+      if (slashIndex === -1) {
+        getLogger().error(
+          chalk.red("❌ Invalid contract reference. Use format: <plugin>/<contract>")
+        );
+        process.exit(1);
+      }
+      pluginName = contractRef.substring(0, slashIndex);
+      contractName = contractRef.substring(slashIndex + 1);
     }
-    const pluginName = contractRef.substring(0, slashIndex);
-    const contractName = contractRef.substring(slashIndex + 1);
     if (options.verbose) {
       getLogger().info("Starting Vite for TypeScript support...");
     }
@@ -4395,21 +4409,21 @@ async function runParams(contractRef, options, projectRoot, initializeServices)
     }
     const { resolveServices } = await import("@jay-framework/stack-server-runtime");
     const resolvedServices = resolveServices(component.services || []);
-    const allParams = [];
     const paramsGenerator = component.loadParams(resolvedServices);
+    let total = 0;
     for await (const batch of paramsGenerator) {
-      allParams.push(...batch);
-    }
-    if (options.yaml) {
-      getLogger().important(YAML.stringify(allParams));
-    } else {
-      getLogger().important(JSON.stringify(allParams, null, 2));
+      for (const params of batch) {
+        if (options.yaml) {
+          getLogger().important(YAML.stringify([params]).trimEnd());
+        } else {
+          getLogger().important(JSON.stringify(params));
+        }
+        total++;
+      }
     }
     if (!options.yaml) {
-      getLogger().important(
-        chalk.green(`
-✅ Found ${allParams.length} param combination(s)`)
-      );
+      getLogger().important(chalk.green(`
+✅ Found ${total} param combination(s)`));
     }
   } catch (error) {
     getLogger().error(chalk.red("❌ Failed to discover params:") + " " + error.message);
@@ -4784,8 +4798,8 @@ program.command("action <plugin/action>").description(
   await runAction(actionRef, options, process.cwd(), initializeServicesForCli);
 });
 program.command("params <plugin/contract>").description(
-  "Discover load param values for a contract (e.g., jay-stack params wix-stores/product-page)"
-).option("--yaml", "Output result as YAML instead of JSON").option("-v, --verbose", "Show detailed output").action(async (contractRef, options) => {
+  "Discover load param values for a contract. Streams results as NDJSON (one JSON object per line) or YAML."
+).option("--yaml", "Output as YAML instead of NDJSON").option("-v, --verbose", "Show detailed output").action(async (contractRef, options) => {
   await runParams(contractRef, options, process.cwd(), initializeServicesForCli);
 });
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/jay-stack-cli",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -24,14 +24,14 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-html": "^0.16.0",
-    "@jay-framework/compiler-shared": "^0.16.0",
-    "@jay-framework/dev-server": "^0.16.0",
-    "@jay-framework/editor-server": "^0.16.0",
-    "@jay-framework/fullstack-component": "^0.16.0",
-    "@jay-framework/logger": "^0.16.0",
-    "@jay-framework/plugin-validator": "^0.16.0",
-    "@jay-framework/stack-server-runtime": "^0.16.0",
+    "@jay-framework/compiler-jay-html": "^0.16.1",
+    "@jay-framework/compiler-shared": "^0.16.1",
+    "@jay-framework/dev-server": "^0.16.1",
+    "@jay-framework/editor-server": "^0.16.1",
+    "@jay-framework/fullstack-component": "^0.16.1",
+    "@jay-framework/logger": "^0.16.1",
+    "@jay-framework/plugin-validator": "^0.16.1",
+    "@jay-framework/stack-server-runtime": "^0.16.1",
     "chalk": "^4.1.2",
     "commander": "^14.0.0",
     "express": "^5.0.1",
@@ -42,7 +42,7 @@
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.16.0",
+    "@jay-framework/dev-environment": "^0.16.1",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",