@aifabrix/builder 2.55.0 → 2.56.0

package/lib/app/offer-create-from-template.js

@@ -0,0 +1,184 @@
+/**
+ * Offer to materialize a missing app from shipped application templates.
+ *
+ * @fileoverview Interactive create-from-template before deploy when the app is not on disk
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { metadata } = require('../utils/cli-test-layout-chalk');
+const { listAvailableTemplates } = require('../validation/template');
+const { findExistingAppType } = require('../utils/paths');
+const { ensureAppFromTemplate } = require('../commands/up-common');
+
+/**
+ * @param {Object} [options]
+ * @returns {boolean}
+ */
+function assumeYesCreate(options = {}) {
+  return options.yes === true || options.assumeYes === true;
+}
+
+/**
+ * @param {Object} [deps]
+ * @returns {boolean}
+ */
+function isInteractiveCreate(deps = {}) {
+  if (process.env.CI === 'true' || process.env.CI === '1') {
+    return false;
+  }
+  if (typeof deps.isTty === 'function') {
+    return Boolean(deps.isTty());
+  }
+  return Boolean(process.stdin && process.stdin.isTTY);
+}
+
+/**
+ * @param {string[]} templates
+ * @returns {string}
+ */
+function formatTemplateNames(templates) {
+  return templates.join(', ');
+}
+
+/**
+ * @param {string} appName
+ * @param {string[]} templates
+ * @returns {Error}
+ */
+function buildMissingAppError(appName, templates) {
+  const listed = templates.length > 0
+    ? `Shipped templates: ${formatTemplateNames(templates)}.`
+    : 'No shipped application templates were found.';
+  const hint = templates.includes(appName)
+    ? `Create it with: aifabrix deploy ${appName} --yes`
+    : 'Pass a matching template name, or create the app first.';
+  return new Error(
+    `App '${appName}' was not found under integration/ or builder/. ${listed} ${hint}`
+  );
+}
+
+/**
+ * @param {string} appName
+ * @param {Function} promptFn
+ * @returns {Promise<boolean>}
+ */
+async function confirmCreateMatchingTemplate(appName, promptFn) {
+  const ask = promptFn || ((qs) => require('inquirer').prompt(qs));
+  const { create } = await ask([{
+    type: 'confirm',
+    name: 'create',
+    message: `App '${appName}' is not available. Create it from the shipped '${appName}' template?`,
+    default: true
+  }]);
+  return Boolean(create);
+}
+
+/**
+ * @param {string[]} templates
+ * @param {Function} promptFn
+ * @returns {Promise<string|null>}
+ */
+async function pickShippedTemplate(templates, promptFn) {
+  const ask = promptFn || ((qs) => require('inquirer').prompt(qs));
+  const { template } = await ask([{
+    type: 'list',
+    name: 'template',
+    message: 'App was not found. Create from which shipped application template?',
+    choices: [
+      ...templates.map((name) => ({ name, value: name })),
+      { name: 'Cancel', value: null }
+    ]
+  }]);
+  return template || null;
+}
+
+/**
+ * @param {string} appName
+ * @param {Object} [deps]
+ * @returns {Promise<string>}
+ */
+async function materializeShippedTemplate(appName, deps = {}) {
+  const copy = deps.ensureAppFromTemplate || ensureAppFromTemplate;
+  await copy(appName);
+  return appName;
+}
+
+/**
+ * @param {string} appName
+ * @param {string[]} templates
+ * @param {Object} options
+ * @param {Object} deps
+ * @returns {Promise<string>}
+ */
+async function createMatchingTemplateApp(appName, templates, options, deps) {
+  if (assumeYesCreate(options)) {
+    return materializeShippedTemplate(appName, deps);
+  }
+  if (!isInteractiveCreate(deps)) {
+    throw buildMissingAppError(appName, templates);
+  }
+  const ok = await confirmCreateMatchingTemplate(appName, deps.prompt);
+  if (!ok) {
+    throw buildMissingAppError(appName, templates);
+  }
+  return materializeShippedTemplate(appName, deps);
+}
+
+/**
+ * @param {string} appName
+ * @param {string[]} templates
+ * @param {Object} options
+ * @param {Object} deps
+ * @returns {Promise<string>}
+ */
+async function createPickedTemplateApp(appName, templates, options, deps) {
+  if (assumeYesCreate(options) || !isInteractiveCreate(deps) || templates.length === 0) {
+    throw buildMissingAppError(appName, templates);
+  }
+  const chosen = await pickShippedTemplate(templates, deps.prompt);
+  if (!chosen) {
+    throw buildMissingAppError(appName, templates);
+  }
+  if (chosen !== appName) {
+    logger.log(metadata(
+      `Creating '${chosen}' from shipped template (requested '${appName}' was not found).`
+    ));
+  }
+  await materializeShippedTemplate(chosen, deps);
+  return chosen;
+}
+
+/**
+ * If the app is missing locally, offer to create it from shipped templates.
+ *
+ * @async
+ * @function offerCreateFromTemplateIfMissing
+ * @param {string} appName - Requested app or system key
+ * @param {Object} [options] - CLI options (`yes` skips the confirm when the name matches a template)
+ * @param {Object} [deps] - Test seams (prompt, isTty, listTemplates, findExisting, ensureAppFromTemplate)
+ * @returns {Promise<string>} App key to continue with (may differ if the user picked another template)
+ * @throws {Error} When the app is missing and the user declines or cannot be prompted
+ */
+async function offerCreateFromTemplateIfMissing(appName, options = {}, deps = {}) {
+  const findExisting = deps.findExisting || findExistingAppType;
+  if (findExisting(appName, options)) {
+    return appName;
+  }
+  const listTemplates = deps.listTemplates || listAvailableTemplates;
+  const templates = await listTemplates();
+  if (templates.includes(appName)) {
+    return createMatchingTemplateApp(appName, templates, options, deps);
+  }
+  return createPickedTemplateApp(appName, templates, options, deps);
+}
+
+module.exports = {
+  offerCreateFromTemplateIfMissing,
+  buildMissingAppError,
+  assumeYesCreate,
+  isInteractiveCreate
+};

package/lib/cli/setup-app.js

@@ -39,6 +39,10 @@ Examples:
   $ aifabrix deploy myapp
   $ aifabrix deploy myapp --local
 
+  # Missing local app that matches a shipped template (TTY asks to create)
+  $ aifabrix deploy dataplane
+  $ aifabrix deploy dataplane --yes
+
   # Local — external system (integration/<systemKey>/); manifest regenerated on deploy
   $ aifabrix deploy hubspot-demo
   $ aifabrix deploy hubspot-demo --local
@@ -52,23 +56,25 @@ Examples:
       --client-id "$DEV_MISO_CLIENTID" \\
       --client-secret "$DEV_MISO_CLIENTSECRET"
 
-  # CI/CD — external integration (after upload/tests; promote to controller)
+  # CI/CD — external integration (qualify once via upload, then fast promote via deploy)
   $ aifabrix validate hubspot-demo
   $ aifabrix upload hubspot-demo --probe
   $ aifabrix deploy hubspot-demo --probe -v
-  # Prove pillars in tst/CI, then promote (plain deploy seals cert on published Deploy)
-  $ aifabrix deploy ek-sales --gate full --subject-email ops@example.com
   $ aifabrix deploy ek-sales
 
 Notes:
   - Login or set MISO_CONTROLLER_URL + environment (aifabrix login / aifabrix auth).
   - CI: register once (aifabrix app register <appKey>), store DEV_MISO_CLIENTID and DEV_MISO_CLIENTSECRET in pipeline secrets.
-  - upload = dataplane publish for dev iteration; deploy = controller validate + deploy (Azure or local Docker).
-  - Prove (tst/CI): use --gate full (optional --subject-email) before promote; plain deploy promotes without live E2E gates.
-  - After a successful published Deploy, the platform seals the integration certificate (no separate certificates issue step).
+  - For Connected Systems, upload validates, publishes, and finalizes the system; optional
+    checks run only with upload --gate. Deploy promotes the completed upload — the
+    server decides this automatically, no flag needed. A system that has never been uploaded
+    falls back to the full legacy ladder at deploy time instead.
+  - --gate is a no-op on deploy (kept for compatibility; prints a notice) — gates now run once
+    during "aifabrix upload", not at deploy time.
   - Default output is a compact status card; use -v for expanded preflight and readiness detail.
   - Controller deploy always polls to a terminal status (no --poll / --no-poll on this command).
   - --repository-url overrides repo URL for pipeline validate (default: application.yaml repository.repositoryUrl).
+  - If the app is missing locally and the name matches a shipped template, TTY asks to create it (use --yes in scripts).
 `;
 
 const PUSH_HELP_AFTER = `
@@ -367,6 +373,7 @@ function setupDeployCommand(program) {
       '--subject-email <emails>',
       'Subject email(s) for governance gate (comma-separated; used with --gate governance|full)'
     )
+    .option('-y, --yes', 'Create a missing app from a matching shipped template without prompting')
     .action(async(appName, options) => {
       try {
         const probeTimeout =
@@ -381,8 +388,9 @@ function setupDeployCommand(program) {
         };
         const outcome = await app.deployApp(appName, opts);
         if (opts.local && outcome) {
+          const targetApp = outcome.appKey || appName;
           if (outcome.usedExternalDeploy) await app.restartApp('dataplane');
-          else await app.runApp(appName, opts);
+          else await app.runApp(targetApp, opts);
         }
       } catch (error) {
         handleCommandError(error, 'deploy');

package/lib/cli/setup-auth.js

@@ -17,7 +17,12 @@ const { handleAuthConfig } = require('../commands/auth-config');
 const LOGIN_HELP_AFTER = `
 Examples:
   $ aifabrix login
+  $ aifabrix login -c https://controller.example.com
   $ aifabrix login -m credentials -a myapp -e dev
+
+Notes:
+  - Public controller URLs are stored as origin + /miso (extra path segments are ignored).
+  - Localhost URLs keep the origin unless the path is already /miso.
 `;
 
 const AUTH_HELP_AFTER = `
@@ -34,12 +39,15 @@ Subcommand: auth status [--validate] for CI/scripts (exit codes 0/1/3).
 const LOGOUT_HELP_AFTER = `
 Examples:
   $ aifabrix logout
+  $ aifabrix logout --type client
+  $ aifabrix logout --type device
   $ aifabrix logout -c http://localhost:3600
   $ aifabrix logout -e dev
   $ aifabrix logout -e dev -a hubspot-e2e
 
 Notes:
   - With no flags: clears all device tokens and all client tokens in config.yaml.
+  - Use --type client or --type device to clear only that token type.
   - Device tokens are keyed by controller URL (-c).
   - Client tokens are per environment and app (-e and optional -a).
   - Run aifabrix auth status to list stored app tokens and copy-paste logout commands.
@@ -164,7 +172,7 @@ function setupLoginCommand(program) {
   program.command('login')
     .description('Sign in to Miso Controller (device or credentials flow)')
     .addHelpText('after', LOGIN_HELP_AFTER)
-    .option('-c, --controller <url>', 'Controller URL (default: from config or developer ID, e.g. http://localhost:3000)')
+    .option('-c, --controller <url>', 'Controller URL (public hosts use origin + /miso; default: config or localhost by developer ID)')
     .option('-m, --method <method>', 'Authentication method (device|credentials)', 'device')
     .option('-a, --app <app>', 'Application name (required for credentials method, reads from secrets.local.yaml)')
     .option('--client-id <id>', 'Client ID (for credentials method, overrides secrets.local.yaml)')
@@ -188,7 +196,8 @@ function setupLoginCommand(program) {
 
 function setupLogoutCommand(program) {
   program.command('logout')
-    .description('Clear stored tokens (optional filter by controller/env/app)')
+    .description('Clear stored tokens (optional filter by type/controller/env/app)')
+    .option('-t, --type <type>', 'Clear only one token type (device|client)')
     .option('-c, --controller <url>', 'Clear device tokens for specific controller')
     .option('-e, --environment <env>', 'Clear client tokens for specific environment')
     .option('-a, --app <app>', 'Clear client tokens for specific app (requires --environment)')

package/lib/cli/setup-external-system-help.js

@@ -6,11 +6,18 @@
 
 const UPLOAD_HELP_AFTER = `
 Examples:
-  # Publish integration/<systemKey>/ to the dataplane (typical lab flow after validate + resolve)
+  # Upload and wait for completion
   $ aifabrix upload hubspot-demo
   $ aifabrix upload hubspot-demo -v
   $ aifabrix upload hubspot-demo --probe
-  $ aifabrix upload hubspot-demo --timeout 600000
+  $ aifabrix upload hubspot-demo --gate operations,trust
+  $ aifabrix upload hubspot-demo --gate full --subject-email user@example.com
+
+  # Queue the upload and return immediately (script/CI-friendly)
+  $ aifabrix upload hubspot-demo --no-wait
+
+  # Resume watching an existing upload job (e.g. after Ctrl-C or a closed terminal)
+  $ aifabrix upload hubspot-demo --resume <jobId>
 
   # Build and validate payload only (no API calls)
   $ aifabrix upload hubspot-demo --dry-run
@@ -25,9 +32,14 @@ Examples:
 Notes:
   - Requires login (aifabrix auth status).
   - Reads files under integration/<systemKey>/ or role-assistant/<roleKey>/ for digital workers.
+  - Upload validates, publishes, and finalizes the system. Operations, trust, and governance
+    checks are optional and run only when selected with --gate. The upload keeps running on
+    Dataplane even if this CLI process is interrupted, closed, or times out — --resume re-attaches
+    to it later, it is never re-submitted or lost.
   - Default output is a compact readiness summary; use -v for expanded detail and server-side validate warnings.
   - --probe runs dataplane runtime checks after publish (slower).
-  - --timeout sets publish budget in ms (HTTP client and dataplane); default 300000.
+  - --timeout bounds only how long this CLI waits before printing a resume hint
+    (default 1800000ms/30min); it does not stop the upload job.
   - --env selects role-assistant.yaml section (dev|tst|pro) for digital workers; default dev.
   - Role Assistant packages under role-assistant/ do not use application.yaml; upload applies settings and Evidence only.
   - test-e2e and test-integration publish local files first by default; use --no-publish on those commands to skip.

package/lib/cli/setup-external-system.js

@@ -50,7 +50,11 @@ async function handleUploadCommandAction(systemKey, options) {
     options.probeTimeout === undefined || options.probeTimeout === null
       ? 120000
       : Number(options.probeTimeout);
-  const timeoutMs = resolvePipelineUploadTimeoutMs(options.timeout);
+  // Only resolve --timeout when the caller explicitly set it; leaving it undefined otherwise
+  // lets the qualification poll fall back to its own default (30min) instead of the legacy
+  // 300000ms HTTP/dataplane-publish budget default, which no longer applies to the async path.
+  const timeoutMs =
+    options.timeout !== undefined ? resolvePipelineUploadTimeoutMs(options.timeout) : undefined;
   await upload.uploadExternalSystem(systemKey, {
     ...options,
     probeTimeout: Number.isFinite(probeTimeout) ? probeTimeout : 120000,
@@ -101,9 +105,17 @@ function setupUploadCommand(program) {
     .option('-v, --verbose', 'Expanded upload summary and server-side pipeline validate warnings before publish')
     .option('--probe', 'After publish, run dataplane runtime checks (validation/run); slower')
     .option('--probe-timeout <ms>', 'Timeout for --probe (default: 120000)', '120000')
+    .option(
+      '--gate <gates>',
+      'Optional upload checks (comma-separated): operations, trust, governance, full'
+    )
+    .option(
+      '--subject-email <emails>',
+      'Subject email(s) for governance checks (comma-separated; used with --gate governance|full)'
+    )
     .option(
       '--timeout <ms>',
-      'Publish timeout in ms for HTTP and dataplane budget (default: 300000; min 5000, max 2700000)'
+      'How long this CLI waits for the upload job before printing a resume hint (default: 1800000/30min; min 5000, max 2700000). The job keeps running regardless.'
     )
     .option(
       '--force',
@@ -114,6 +126,12 @@ function setupUploadCommand(program) {
       'Role Assistant settings environment section: dev, tst, or pro (default: dev)',
       'dev'
     )
+    .option('--wait', 'Wait for the upload job to complete (default)', true)
+    .option('--no-wait', 'Return the upload job id immediately without waiting')
+    .option(
+      '--resume <jobId>',
+      'Wait for an existing upload job instead of submitting again'
+    )
     .action(async(systemKey, options) => {
       try {
         await handleUploadCommandAction(systemKey, options);
@@ -341,4 +359,4 @@ function setupExternalSystemCommands(program) {
   setupExternalSystemTestCommands(program);
 }
 
-module.exports = { setupExternalSystemCommands };
+module.exports = { setupExternalSystemCommands, handleUploadCommandAction };

package/lib/commands/agent-kit-help.js

@@ -5,24 +5,46 @@
 
 'use strict';
 
+const HOST_OPTION_HELP =
+  'Coding hosts to activate: all, cursor, claude, or codex (one name = that host only)';
+
+const APPROVE_ALL_OPTION_HELP =
+  'Auto-approve tools for all, claude, or codex (omit value = every selected host)';
+
 const GROUP_HELP = `
+Coding hosts (--host) are Cursor, Claude Code, and/or Codex in this workspace.
+GitHub remotes are a separate command (agent-kit remote create).
+
 Examples:
   $ aifabrix agent-kit init cust-demo --host all --approve-all --yes
-  $ aifabrix agent-kit install --host all --approve-all --yes
+  $ aifabrix agent-kit install --host claude --approve-all --yes
+  $ aifabrix agent-kit install --host all --approve-all claude --yes
   $ aifabrix agent-kit update --host all --approve-all --yes
+  $ aifabrix agent-kit remote create --org my-org --yes
+  $ aifabrix agent-kit start claude --remote-control --approve-all --yes
+  $ aifabrix agent-kit start claude --name aifabrix-docs --remote-control --approve-all --yes
+  $ aifabrix agent-kit start codex --approve-all --yes
   $ aifabrix agent-kit status
   $ aifabrix agent-kit validate
 `;
 
 const INSTALL_HELP = `
+--host chooses which coding apps this repo supports (default all).
+Use one name to activate only that host. --approve-all [claude|codex] writes
+auto-approve configs for that host's tools only.
+
 Examples:
   $ aifabrix agent-kit install
   $ aifabrix agent-kit install --host all --approve-all --yes
   $ aifabrix agent-kit install --host claude --approve-all --yes
+  $ aifabrix agent-kit install --host codex --approve-all --yes
+  $ aifabrix agent-kit install --host all --approve-all claude --yes
   $ aifabrix agent-kit install --skip-approve-all
   $ aifabrix agent-kit install --dry-run
 
-TTY asks to auto-approve Claude Code and Codex permissions (default yes). Silent: --approve-all --yes. Skip: --skip-approve-all.
+TTY asks which hosts to support (omit --host) and which tools to auto-approve.
+Silent: --host <name> --approve-all [claude|codex] --yes. Skip: --skip-approve-all.
+Start without installing skills: aifabrix agent-kit start claude
 `;
 
 const STATUS_HELP = `
@@ -36,9 +58,12 @@ Examples:
   $ aifabrix agent-kit update
   $ aifabrix agent-kit update --host all --approve-all --yes
   $ aifabrix agent-kit update --host claude --force
+  $ aifabrix agent-kit update --host all --approve-all claude --yes
   $ aifabrix agent-kit update --dry-run
 
-Omit --host to keep the coding hosts already recorded. Pass --host when you add or switch Cursor, Claude Code, or Codex.
+Omit --host to keep the coding hosts already recorded. Pass --host claude or
+--host codex to activate only that host. --approve-all claude writes Claude
+Code tool auto-approve only.
 `;
 
 const VALIDATE_HELP = `
@@ -48,18 +73,39 @@ Examples:
 `;
 
 const INIT_HELP = `
+--host chooses Cursor, Claude Code, and/or Codex for the new workspace.
+GitHub (origin + push) is --remote / agent-kit remote create — not --host.
+
 Examples:
   $ aifabrix agent-kit init cust-demo
   $ aifabrix agent-kit init cust-demo --host all --approve-all --yes
+  $ aifabrix agent-kit init cust-demo --host claude --approve-all --yes
+  $ aifabrix agent-kit init cust-demo --host all --approve-all claude --yes
   $ aifabrix agent-kit init cust-demo --host all --remote --org my-org --yes
   $ aifabrix agent-kit init ./path/to/cust-demo --dry-run --json
 
 Interactive (TTY): omit --host / --yes to be prompted.
 Silent local: --host all --approve-all --yes
+Silent one host: --host claude --approve-all --yes
 Silent remote: --host all --remote --org <owner> --yes
 `;
 
+const REMOTE_GROUP_HELP = `
+This is GitHub only: create origin and push this workspace.
+It does not choose Cursor, Claude Code, or Codex.
+
+Examples:
+  $ aifabrix agent-kit remote create
+  $ aifabrix agent-kit remote create --org my-org --yes
+  $ aifabrix agent-kit install --host claude --approve-all --yes
+  $ aifabrix agent-kit install --host codex --approve-all --yes
+  $ aifabrix agent-kit install --host all --approve-all claude --yes
+`;
+
 const REMOTE_HELP = `
+Creates a GitHub repository (origin) and pushes this workspace.
+Not coding-host selection — use --host on install/update for Claude or Codex.
+
 Examples:
   $ cd cust-demo && aifabrix agent-kit remote create
   $ aifabrix agent-kit remote create --org my-org --yes
@@ -68,12 +114,36 @@ Examples:
 Interactive (TTY): omit flags to be prompted. Silent: --org <owner> --yes
 `;
 
+const START_HELP = `
+Does not install Agent Kit skills. Starts claude or codex in tmux in this git
+workspace so closing the terminal does not kill the session. Detach: Ctrl-b then
+d. --approve-all writes that app's local permission config only. --name is the
+tmux session (default: last folder, e.g. aifabrix-docs). Claude also gets
+--name and --remote-control hostname-user-folder, e.g.
+builder01-dev03-aifabrix-docs. Claude --tmux is for worktrees, not this wrapper.
+That is not Claude --cloud (a separate cloud VM). Codex has no phone/web attach.
+
+Examples:
+  $ aifabrix agent-kit start claude --remote-control --approve-all --yes
+  $ aifabrix agent-kit start claude --name aifabrix-docs --remote-control --approve-all --yes
+  $ aifabrix agent-kit start claude --name aifabrix-miso --remote-control --approve-all --yes
+  $ aifabrix agent-kit start claude --remote-control --detach
+  $ aifabrix agent-kit start claude
+  $ aifabrix agent-kit start claude --approve-all --yes
+  $ aifabrix agent-kit start codex --approve-all --yes
+  $ aifabrix agent-kit start claude --dry-run --json
+`;
+
 module.exports = {
+  HOST_OPTION_HELP,
+  APPROVE_ALL_OPTION_HELP,
   GROUP_HELP,
   INSTALL_HELP,
   STATUS_HELP,
   UPDATE_HELP,
   VALIDATE_HELP,
   INIT_HELP,
-  REMOTE_HELP
+  REMOTE_GROUP_HELP,
+  REMOTE_HELP,
+  START_HELP
 };