@jay-framework/jay-stack-cli 0.22.0 → 0.22.2

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

@@ -1,28 +1,26 @@
 # CLI Commands Reference
 
-## jay-stack setup
+## jay-stack-cli setup
 
-Run plugin setup. Plugins can create configuration files, generate reference data, and validate their prerequisites.
+Run plugin setup. Plugins create configuration files, prompt for credentials, and validate services.
 
 ```bash
-# Run setup for all installed plugins
-jay-stack setup
+# Run setup for all installed plugins (interactive — may prompt for input)
+jay-stack-cli setup
 
 # Run setup for a specific plugin
-jay-stack setup wix-stores
+jay-stack-cli setup wix-stores
 
 # Re-run setup (e.g., after config change)
-jay-stack setup wix-data --force
-```
-
-Plugins declare their setup handler in `plugin.yaml`. Setup does two things:
+jay-stack-cli setup --force
 
-1. **Config templates**: Creates `config/<plugin>.yaml` with placeholder credentials if missing
-2. **Credential validation**: Attempts to initialize services, reports success or failure
+# Non-interactive mode (creates config templates without prompting)
+jay-stack-cli setup --no-interactive
+```
 
-Reference data (product catalogs, collection schemas) is generated by `jay-stack agent-kit`, not by setup.
+Setup is **interactive by default** — plugins may prompt for API keys and credentials. Use `--no-interactive` in CI/scripts.
 
-Run this after installing new plugins, before `jay-stack agent-kit`.
+Run this after installing new plugins, before `jay-stack-cli agent-kit`.
 
 ## jay-stack agent-kit
 

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

@@ -1,28 +1,34 @@
 # CLI Commands Reference
 
-## jay-stack setup
+## jay-stack-cli setup
 
-Run plugin setup. Plugins can create configuration files, generate reference data, and validate their prerequisites.
+Run plugin setup. Plugins can create configuration files, prompt for credentials, and validate their prerequisites.
 
 ```bash
-# Run setup for all installed plugins
-jay-stack setup
+# Run setup for all installed plugins (interactive — may prompt for input)
+jay-stack-cli setup
 
 # Run setup for a specific plugin
-jay-stack setup wix-stores
+jay-stack-cli setup wix-stores
 
 # Re-run setup (e.g., after config change)
-jay-stack setup wix-data --force
+jay-stack-cli setup wix-data --force
+
+# Non-interactive mode (CI/scripts — creates config templates without prompting)
+jay-stack-cli setup --no-interactive
 ```
 
-Plugins declare their setup handler in `plugin.yaml`. Setup does two things:
+Setup is **interactive by default** — plugins can prompt for API keys, credentials, and configuration choices. In non-interactive mode (`--no-interactive`), prompts are skipped and plugins create config templates with placeholders instead.
+
+Plugins declare their setup handler in `plugin.yaml`. Setup does three things:
 
-1. **Config templates**: Creates `config/<plugin>.yaml` with placeholder credentials if missing
-2. **Credential validation**: Attempts to initialize services, reports success or failure
+1. **Config templates**: Creates `config/<plugin>.yaml` with credentials (interactive) or placeholders (non-interactive)
+2. **Credential prompts**: Asks for API keys and configuration when running interactively
+3. **Service validation**: Attempts to initialize services, reports success or failure
 
-Reference data (product catalogs, collection schemas) is generated by `jay-stack agent-kit`, not by setup.
+Reference data (product catalogs, collection schemas) is generated by `jay-stack-cli agent-kit`, not by setup.
 
-Run this after installing new plugins, before `jay-stack agent-kit`.
+Run this after installing new plugins, before `jay-stack-cli agent-kit`.
 
 ## jay-stack agent-kit
 

package/agent-kit-template/devops/INSTRUCTIONS.md

@@ -14,6 +14,56 @@ The devops role handles the production lifecycle: building artifacts, configurin
 4. **Invalidate** — rebuild specific pages when data changes
 5. **Admin** — run plugin CLI commands via `jay-stack run <plugin>/<command>` (media upload, data sync, cache purge)
 
+## Plugin Setup
+
+Plugins may need credentials or configuration before they can run. The setup command handles this.
+
+```bash
+# Default (non-interactive) — exits with structured output if input is needed
+jay-stack-cli setup
+
+# Interactive — prompts for credentials via terminal
+jay-stack-cli setup --interactive
+
+# With pre-provided answers (for automation)
+jay-stack-cli setup --answers answers.yaml
+```
+
+### Automated setup (CI / agents)
+
+When running `jay-stack-cli setup` without `--interactive`, plugins that need user input will exit with structured YAML output:
+
+```yaml
+setup-needs-answer:
+  plugin: wix-server-client
+  key: api-key
+  type: input
+  message: 'Enter your API key'
+```
+
+To provide the answer, create a YAML file and re-run:
+
+```yaml
+# answers.yaml
+api-key: 'IST.abc123...'
+```
+
+```bash
+jay-stack-cli setup --answers answers.yaml
+```
+
+Repeat until all plugins report `configured`. The flow is iterative — each run may reveal the next question.
+
+### Setup order
+
+Run setup **before** agent-kit and build:
+
+```bash
+jay-stack-cli setup              # 1. Configure plugins
+jay-stack-cli agent-kit          # 2. Generate contracts and discovery data
+jay-stack-cli build              # 3. Production build
+```
+
 ## Guides
 
 | File                                       | Topic                                                      |

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

@@ -30,10 +30,12 @@ description: Validate credentials and install config # optional, top-level
 
 ## Writing a Setup Handler
 
-The setup handler creates config files and validates services. It receives a `PluginSetupContext` and returns a `PluginSetupResult`.
+The setup handler creates config files, validates services, and can prompt the user for credentials. It receives a `PluginSetupContext` and returns a `PluginSetupResult`.
 
 **Do not** write add-menu catalogs in setup — use the agent-kit handler.
 
+### Basic setup (non-interactive)
+
 ```typescript
 import type { PluginSetupContext, PluginSetupResult } from '@jay-framework/stack-server-runtime';
 import fs from 'node:fs';
@@ -49,7 +51,7 @@ export async function setupMyPlugin(ctx: PluginSetupContext): Promise<PluginSetu
 
   if (!fs.existsSync(configPath) || ctx.force) {
     fs.mkdirSync(ctx.configDir, { recursive: true });
-    fs.writeFileSync(configPath, '# My Plugin config\n', 'utf-8');
+    fs.writeFileSync(configPath, '# My Plugin config\napiKey: "<your-api-key>"\n', 'utf-8');
     configCreated.push('config/.my-plugin.yaml');
   }
 
@@ -64,16 +66,124 @@ export async function setupMyPlugin(ctx: PluginSetupContext): Promise<PluginSetu
 }
 ```
 
+### Interactive setup (with prompts)
+
+When the setup handler needs user input (API keys, credentials, configuration choices), use `ctx.prompt`:
+
+```typescript
+export async function setupMyPlugin(ctx: PluginSetupContext): Promise<PluginSetupResult> {
+  const configPath = path.join(ctx.configDir, '.my-plugin.yaml');
+
+  // Already configured — skip unless --force
+  if (fs.existsSync(configPath) && !ctx.force) {
+    return { status: 'configured', message: 'Already configured' };
+  }
+
+  // In non-interactive mode, create a template and ask the user to fill it in later
+  if (!ctx.interactive) {
+    fs.mkdirSync(ctx.configDir, { recursive: true });
+    fs.writeFileSync(configPath, 'apiKey: "<your-api-key>"\n', 'utf-8');
+    return {
+      status: 'needs-config',
+      configCreated: ['config/.my-plugin.yaml'],
+      message: 'Run `jay-stack-cli setup` interactively to enter your API key',
+    };
+  }
+
+  // Interactive mode — prompt the user
+  const apiKey = await ctx.prompt.input({
+    message: 'Enter your API key (create one at https://example.com/api-keys):',
+    validate: (v) => (v.trim() ? true : 'API key is required'),
+  });
+
+  const region = await ctx.prompt.select({
+    message: 'Select your region:',
+    choices: [
+      { name: 'US East', value: 'us-east' },
+      { name: 'EU West', value: 'eu-west' },
+    ],
+  });
+
+  fs.mkdirSync(ctx.configDir, { recursive: true });
+  fs.writeFileSync(configPath, `apiKey: "${apiKey.trim()}"\nregion: ${region}\n`, 'utf-8');
+
+  return {
+    status: 'configured',
+    configCreated: ['config/.my-plugin.yaml'],
+    message: 'Credentials configured successfully',
+  };
+}
+```
+
+### Setup modes
+
+Setup runs in three modes:
+
+| Mode                          | Command                                   | `ctx.interactive` | `ctx.prompt` behavior                                 |
+| ----------------------------- | ----------------------------------------- | ----------------- | ----------------------------------------------------- |
+| **Default** (agents, CI)      | `jay-stack-cli setup`                     | `false`           | Throws `SetupNeedsAnswerError` with structured output |
+| **Interactive** (humans)      | `jay-stack-cli setup --interactive`       | `true`            | Prompts via terminal                                  |
+| **Answers file** (automation) | `jay-stack-cli setup --answers file.yaml` | `false`           | Reads from file, throws if missing                    |
+
+In default mode, when a prompt has no answer, the CLI exits with structured YAML telling the caller what's needed. Agents can then provide the answer via `--answers` and re-run.
+
+### Idempotency requirement
+
+Setup handlers **must be idempotent** — re-running with the same answers must produce the same result without side effects. This is critical because:
+
+- Agents re-run setup iteratively as they provide answers one at a time
+- Users re-run setup after fixing credentials
+- CI pipelines may run setup on every deploy
+
+**Rules:**
+
+1. Check if config already exists before creating it — skip if present (unless `ctx.force`)
+2. Check if credentials are already valid before prompting — skip if configured
+3. Never append to files — write the complete content each time
+4. Use `ctx.force` to allow explicit re-creation when the user asks for it
+
+```typescript
+export async function setupMyPlugin(ctx: PluginSetupContext): Promise<PluginSetupResult> {
+  const configPath = path.join(ctx.configDir, '.my-plugin.yaml');
+
+  // Idempotent: skip if already configured (unless --force)
+  if (fs.existsSync(configPath) && !ctx.force) {
+    // Optionally validate the existing config
+    return { status: 'configured', message: 'Already configured' };
+  }
+
+  // Prompt only when needed
+  const apiKey = await ctx.prompt.input({
+    key: 'api-key',
+    message: 'Enter your API key:',
+  });
+
+  // Write complete config (not append)
+  fs.writeFileSync(configPath, `apiKey: "${apiKey}"\n`);
+  return { status: 'configured', configCreated: ['config/.my-plugin.yaml'] };
+}
+```
+
 ### PluginSetupContext
 
-| Field         | Type      | Description                                                       |
-| ------------- | --------- | ----------------------------------------------------------------- |
-| `pluginName`  | `string`  | Plugin name from plugin.yaml                                      |
-| `projectRoot` | `string`  | Absolute project root path                                        |
-| `configDir`   | `string`  | Config directory (from `.jay` configBase, defaults to `./config`) |
-| `services`    | `Map`     | Registered services (may be empty if init failed)                 |
-| `initError`   | `Error?`  | Present if plugin init failed — check this before using services  |
-| `force`       | `boolean` | Whether `--force` flag was passed                                 |
+| Field         | Type                | Description                                                       |
+| ------------- | ------------------- | ----------------------------------------------------------------- |
+| `pluginName`  | `string`            | Plugin name from plugin.yaml                                      |
+| `projectRoot` | `string`            | Absolute project root path                                        |
+| `configDir`   | `string`            | Config directory (from `.jay` configBase, defaults to `./config`) |
+| `services`    | `Map`               | Registered services (may be empty if init failed)                 |
+| `initError`   | `Error?`            | Present if plugin init failed — check this before using services  |
+| `force`       | `boolean`           | Whether `--force` flag was passed                                 |
+| `interactive` | `boolean`           | Whether running in interactive mode (can prompt user)             |
+| `prompt`      | `PluginSetupPrompt` | Prompt functions for user input (see below)                       |
+
+### PluginSetupPrompt
+
+| Method    | Signature                                          | Description                                                |
+| --------- | -------------------------------------------------- | ---------------------------------------------------------- |
+| `input`   | `(opts: { message, validate? }) → Promise<string>` | Text input. Non-interactive: returns `""`                  |
+| `confirm` | `(opts: { message, default? }) → Promise<boolean>` | Yes/no. Non-interactive: returns `default` or `false`      |
+| `select`  | `(opts: { message, choices }) → Promise<string>`   | Single choice. Non-interactive: returns first choice value |
 
 ### PluginSetupResult
 

package/dist/index.js

@@ -10,7 +10,7 @@ import YAML from "yaml";
 import { getLogger, setDevLogger, createDevLogger } from "@jay-framework/logger";
 import { parseJayFile, JAY_IMPORT_RESOLVER, generateElementDefinitionFile, ContractTagType, parseContract, generateElementFile, generateServerElementFile, htmlElementTagNameMap, loadLinkedContract, getLinkedContractDir } from "@jay-framework/compiler-jay-html";
 import { JAY_CONTRACT_EXTENSION, JAY_EXTENSION, resolvePluginManifest, LOCAL_PLUGIN_PATH, JayAtomicType, JayEnumType, loadPluginManifest, RuntimeMode, GenerateTarget, findDynamicContract } from "@jay-framework/compiler-shared";
-import { scanPlugins as scanPlugins$1, listContracts, materializeContracts } from "@jay-framework/stack-server-runtime";
+import { scanPlugins as scanPlugins$1, listContracts, materializeContracts, SetupNeedsAnswerError } from "@jay-framework/stack-server-runtime";
 import { listContracts as listContracts2, materializeContracts as materializeContracts2 } from "@jay-framework/stack-server-runtime";
 import { Command } from "commander";
 import chalk from "chalk";
@@ -20,6 +20,7 @@ import { createRequire } from "module";
 import { glob } from "glob";
 import fsSync from "node:fs";
 import { fileURLToPath } from "node:url";
+import { input, confirm, select } from "@inquirer/prompts";
 const DEFAULT_CONFIG = {
   devServer: {
     portRange: [3e3, 3100],
@@ -5958,7 +5959,7 @@ async function runAction(actionRef, options, projectRoot, initializeServices) {
       process.exit(1);
     }
     const actionExport = actionRef.substring(slashIndex + 1);
-    const input = options.input ? JSON.parse(options.input) : {};
+    const input2 = options.input ? JSON.parse(options.input) : {};
     if (options.verbose) {
       getLogger().info("Starting Vite for TypeScript support...");
     }
@@ -5991,9 +5992,9 @@ async function runAction(actionRef, options, projectRoot, initializeServices) {
     }
     if (options.verbose) {
       getLogger().info(`Executing action: ${matchedName}`);
-      getLogger().info(`Input: ${JSON.stringify(input)}`);
+      getLogger().info(`Input: ${JSON.stringify(input2)}`);
     }
-    const result = await registry.execute(matchedName, input);
+    const result = await registry.execute(matchedName, input2);
     if (result.success) {
       if (options.yaml) {
         getLogger().important(YAML.stringify(result.data));
@@ -6106,6 +6107,69 @@ async function runParams(contractRef, options, projectRoot, initializeServices)
     }
   }
 }
+function createInteractivePrompt() {
+  return {
+    async input(options) {
+      return input({ message: options.message, validate: options.validate });
+    },
+    async confirm(options) {
+      return confirm({ message: options.message, default: options.default });
+    },
+    async select(options) {
+      return select({
+        message: options.message,
+        choices: options.choices.map((c) => ({ name: c.name, value: c.value }))
+      });
+    }
+  };
+}
+function createAnswersFilePrompt(answers, pluginName) {
+  return {
+    async input(options) {
+      const value = answers[options.key];
+      if (value !== void 0)
+        return value;
+      throw new SetupNeedsAnswerError(pluginName, options.key, "input", options.message);
+    },
+    async confirm(options) {
+      const value = answers[options.key];
+      if (value !== void 0)
+        return value === "true" || value === "yes";
+      throw new SetupNeedsAnswerError(pluginName, options.key, "confirm", options.message);
+    },
+    async select(options) {
+      const value = answers[options.key];
+      if (value !== void 0)
+        return value;
+      throw new SetupNeedsAnswerError(
+        pluginName,
+        options.key,
+        "select",
+        options.message,
+        options.choices
+      );
+    }
+  };
+}
+function createDefaultPrompt(pluginName) {
+  return {
+    async input(options) {
+      throw new SetupNeedsAnswerError(pluginName, options.key, "input", options.message);
+    },
+    async confirm(options) {
+      throw new SetupNeedsAnswerError(pluginName, options.key, "confirm", options.message);
+    },
+    async select(options) {
+      throw new SetupNeedsAnswerError(
+        pluginName,
+        options.key,
+        "select",
+        options.message,
+        options.choices
+      );
+    }
+  };
+}
 async function runSetup(pluginFilter, options, projectRoot, initializeServices) {
   let viteServer;
   try {
@@ -6145,6 +6209,11 @@ async function runSetup(pluginFilter, options, projectRoot, initializeServices)
         logger.info(chalk.yellow(`⚠️  ${name} init error: ${err.message}`));
       }
     }
+    const interactive = options.interactive === true;
+    let answersMap;
+    if (options.answers) {
+      answersMap = YAML.parse(fsSync.readFileSync(options.answers, "utf-8")) || {};
+    }
     let configured = 0;
     let needsConfig = 0;
     let errors = 0;
@@ -6153,11 +6222,14 @@ async function runSetup(pluginFilter, options, projectRoot, initializeServices)
       if (plugin.setupDescription && options.verbose) {
         logger.important(chalk.gray(`   ${plugin.setupDescription}`));
       }
+      const prompt = interactive ? createInteractivePrompt() : answersMap ? createAnswersFilePrompt(answersMap, plugin.name) : createDefaultPrompt(plugin.name);
       try {
         const result = await executePluginSetup(plugin, {
           projectRoot,
           configDir,
           force: options.force ?? false,
+          interactive,
+          prompt,
           initError: initErrors.get(plugin.name),
           viteServer,
           verbose: options.verbose
@@ -6200,10 +6272,34 @@ async function runSetup(pluginFilter, options, projectRoot, initializeServices)
             break;
         }
       } catch (error) {
-        errors++;
-        logger.important(chalk.red(`   ❌ Setup failed: ${error.message}`));
-        if (options.verbose) {
-          logger.error(error.stack);
+        if (error instanceof SetupNeedsAnswerError) {
+          needsConfig++;
+          logger.important("");
+          logger.important(chalk.yellow("setup-needs-answer:"));
+          logger.important(chalk.yellow(`  plugin: ${error.plugin}`));
+          logger.important(chalk.yellow(`  key: ${error.key}`));
+          logger.important(chalk.yellow(`  type: ${error.type}`));
+          logger.important(chalk.yellow(`  message: "${error.promptMessage}"`));
+          if (error.choices) {
+            logger.important(chalk.yellow("  choices:"));
+            for (const c of error.choices) {
+              logger.important(chalk.yellow(`    - ${c.value}: ${c.name}`));
+            }
+          }
+          logger.important("");
+          logger.important(chalk.gray("Provide the answer via file:"));
+          logger.important(chalk.gray(`  jay-stack-cli setup --answers answers.yaml`));
+          logger.important(chalk.gray(`  answers.yaml format:`));
+          logger.important(chalk.gray(`    ${error.key}: "your-answer"`));
+          logger.important("");
+          logger.important(chalk.gray("Or run interactively:"));
+          logger.important(chalk.gray(`  jay-stack-cli setup --interactive`));
+        } else {
+          errors++;
+          logger.important(chalk.red(`   ❌ Setup failed: ${error.message}`));
+          if (options.verbose) {
+            logger.error(error.stack);
+          }
         }
       }
       logger.important("");
@@ -6284,11 +6380,11 @@ async function runCommand(commandRef, rawArgs, options, projectRoot, initializeS
       }
       process.exit(1);
     }
-    let input = {};
+    let input2 = {};
     if (command.metadata?.inputSchema) {
       const flagDefs = commandSchemaToFlags(command.metadata.inputSchema);
       const rawOptions = parseRawFlags(rawArgs, flagDefs);
-      input = parseInputFromFlags(rawOptions, command.metadata.inputSchema);
+      input2 = parseInputFromFlags(rawOptions, command.metadata.inputSchema);
     }
     if (options.verbose) {
       getLogger().info("Starting Vite for TypeScript support...");
@@ -6319,7 +6415,7 @@ async function runCommand(commandRef, rawArgs, options, projectRoot, initializeS
     if (options.verbose) {
       getLogger().info(`Executing ${command.pluginName}/${command.commandName}...`);
     }
-    const result = await executePluginCommand(command, input, viteServer);
+    const result = await executePluginCommand(command, input2, viteServer);
     if (!result.success) {
       process.exit(1);
     }
@@ -6459,7 +6555,7 @@ program.command("validate-plugin").description("Validate a Jay Stack plugin pack
     process.exit(1);
   }
 });
-program.command("setup [plugin]").description("Run plugin setup: config templates, credential validation, reference data").option("--force", "Force re-run (overwrite config templates and regenerate references)").option("-v, --verbose", "Show detailed output").action(async (plugin, options) => {
+program.command("setup [plugin]").description("Run plugin setup: config templates, credential validation, reference data").option("--force", "Force re-run (overwrite config templates and regenerate references)").option("--interactive", "Prompt for input via terminal (for humans)").option("--answers <file>", "Read answers from YAML file (for agents)").option("-v, --verbose", "Show detailed output").action(async (plugin, options) => {
   await runSetup(plugin, options, process.cwd(), initializeServicesForCli);
 });
 program.command("agent-kit").description("Prepare agent kit: materialize contracts, generate references, write docs").option("-o, --output <dir>", "Output directory (default: agent-kit/materialized-contracts)").option("--yaml", "Output contract index as YAML to stdout").option("--list", "List contracts without writing files").option("--plugin <name>", "Filter to specific plugin").option("--dynamic-only", "Only process dynamic contracts").option("--force", "Force re-materialization").option("--no-references", "Skip reference data generation").option(

package/package.json

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