@aifabrix/builder 2.55.0 → 2.55.2

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
@@ -69,6 +73,7 @@ Notes:
   - 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 +372,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 +387,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/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
 };

package/lib/commands/agent-kit.js

@@ -1,6 +1,6 @@
 /**
  * `aifabrix agent-kit` command group.
- * @fileoverview Install, init, status, update, validate, remote create
+ * @fileoverview Install, init, status, update, validate, remote create, start
  */
 
 'use strict';
@@ -9,6 +9,7 @@ const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
 const { formatSuccessLine, formatBlockingError, formatWarningLine } = require('../utils/cli-layout-chalk');
 const { runInstall, runUpdate } = require('../agent-kit/run');
+const { runStart } = require('../agent-kit/start');
 const path = require('path');
 const { runInit, runRemoteCreate } = require('../agent-kit/init');
 const { enrichInitHostOptions, enrichInitRemoteOptions, enrichRemoteOptions, enrichApproveAllOptions } = require('../agent-kit/remote-prompts');
@@ -26,7 +27,11 @@ const {
   UPDATE_HELP,
   VALIDATE_HELP,
   INIT_HELP,
-  REMOTE_HELP
+  REMOTE_GROUP_HELP,
+  REMOTE_HELP,
+  START_HELP,
+  HOST_OPTION_HELP,
+  APPROVE_ALL_OPTION_HELP
 } = require('./agent-kit-help');
 
 /**
@@ -91,6 +96,34 @@ function emitRemoteReport(json, asJson) {
   logger.log(formatSuccessLine(json.dryRun ? 'Dry-run complete' : 'Done'));
 }
 
+/**
+ * @param {object} json
+ * @param {boolean} asJson
+ * @returns {void}
+ */
+function emitStartReport(json, asJson) {
+  if (asJson) {
+    logger.log(JSON.stringify(json, null, 2));
+    return;
+  }
+  logger.log(`App        ${json.app}`);
+  logger.log(`Session    ${json.session}`);
+  if (json.remoteControlName) {
+    logger.log(`Remote     ${json.remoteControlName}`);
+  }
+  logger.log(`Path       ${json.path}`);
+  logger.log(`Launch     ${json.launch.join(' ')}`);
+  if (json.executed && json.detach) {
+    logger.log(formatSuccessLine('Session started in background'));
+    return;
+  }
+  if (json.executed) {
+    logger.log(formatSuccessLine('Session ended'));
+    return;
+  }
+  logger.log(formatSuccessLine(json.dryRun ? 'Dry-run complete' : 'Ready'));
+}
+
 /**
  * @param {Function} runner
  * @param {object} options
@@ -125,6 +158,7 @@ function setupAgentKitCommands(program) {
   addUpdateCommand(group);
   addValidateCommand(group);
   addRemoteCommand(group);
+  addStartCommand(group);
 }
 
 /**
@@ -134,16 +168,16 @@ function addInitCommand(group) {
   group
     .command('init [nameOrPath]')
     .description('Create a customer workspace skeleton, git repo, and Agent Kit')
-    .option('--host <target>', 'all, cursor, codex, or claude (omit on TTY to choose)', 'all')
+    .option('--host <target>', HOST_OPTION_HELP, 'all')
     .option('--scm <kind>', 'git or none', 'git')
-    .option('--remote', 'Create private hosting remote and push (requires auth)')
+    .option('--remote', 'Create private GitHub remote and push (requires auth)')
     .option('--no-remote', 'Force local-only (skip remote prompt on TTY)')
     .option('--org <owner>', 'Hosting org or user (required with --remote when non-TTY)')
     .option('--visibility <mode>', 'private or public', 'private')
     .option('--license <kind>', 'mit or none', 'none')
     .option('--force', 'Allow non-empty target directory')
     .option('--yes', 'Silent: skip TTY confirm (pair with --host and --org); also auto-approves host permissions')
-    .option('--approve-all', 'Write Claude Code and Codex auto-approve configs')
+    .option('--approve-all [host]', APPROVE_ALL_OPTION_HELP)
     .option('--skip-approve-all', 'Do not write Claude Code or Codex auto-approve configs')
     .option('--dry-run', 'Plan writes without changing files')
     .option('--json', 'Machine-readable output')
@@ -177,10 +211,13 @@ function addInitCommand(group) {
  * @param {import('commander').Command} group
  */
 function addRemoteCommand(group) {
-  const remote = group.command('remote').description('Hosting remotes for an Agent Kit workspace');
+  const remote = group
+    .command('remote')
+    .description('Create a GitHub repository for this workspace and push')
+    .addHelpText('after', REMOTE_GROUP_HELP);
   remote
     .command('create')
-    .description('Create a private GitHub remote and push the current workspace')
+    .description('Create a private GitHub repository (origin) and push this workspace')
     .option('--org <owner>', 'Hosting org or user (required when non-TTY)')
     .option('--name <repo>', 'Remote repository name (default: directory basename)')
     .option('--visibility <mode>', 'private or public', 'private')
@@ -215,8 +252,8 @@ function addInstallCommand(group) {
   group
     .command('install')
     .description('Install the Agent Kit into the current git repository')
-    .option('--host <target>', 'all, cursor, codex, or claude', 'all')
-    .option('--approve-all', 'Write Claude Code and Codex auto-approve configs')
+    .option('--host <target>', HOST_OPTION_HELP, 'all')
+    .option('--approve-all [host]', APPROVE_ALL_OPTION_HELP)
     .option('--skip-approve-all', 'Do not write Claude Code or Codex auto-approve configs')
     .option('--yes', 'Silent: auto-approve host permission configs without asking')
     .option('--dry-run', 'Plan writes without changing files')
@@ -225,7 +262,8 @@ function addInstallCommand(group) {
     .action(async(options) => {
       try {
         const interactive = Boolean(process.stdout.isTTY) && !options.json;
-        const merged = await enrichApproveAllOptions(options, { interactive });
+        const withHost = await enrichInitHostOptions(options, { interactive });
+        const merged = await enrichApproveAllOptions(withHost, { interactive });
         await runLeaf(runInstall, merged, true);
       } catch (error) {
         handleCommandError(error, 'agent-kit install');
@@ -287,8 +325,8 @@ function addUpdateCommand(group) {
   group
     .command('update')
     .description('Update managed Agent Kit files from this Builder release')
-    .option('--host <target>', 'all, cursor, codex, or claude (omit to keep recorded hosts)')
-    .option('--approve-all', 'Write Claude Code and Codex auto-approve configs')
+    .option('--host <target>', `${HOST_OPTION_HELP} (omit to keep recorded hosts)`)
+    .option('--approve-all [host]', APPROVE_ALL_OPTION_HELP)
     .option('--skip-approve-all', 'Do not write Claude Code or Codex auto-approve configs')
     .option('--yes', 'Silent: auto-approve host permission configs without asking')
     .option('--dry-run', 'Plan writes without changing files')
@@ -343,4 +381,37 @@ async function runValidateLeaf(options) {
   }
 }
 
+/**
+ * @param {import('commander').Command} group
+ */
+function addStartCommand(group) {
+  group
+    .command('start <app>')
+    .description('Start Claude Code or Codex in tmux (does not install skills)')
+    .option('--approve-all', 'Write auto-approve config for this app only')
+    .option('--skip-approve-all', 'Do not write auto-approve configs')
+    .option('--yes', 'Same as --approve-all')
+    .option('--detach', 'Create the tmux session in the background (no attach)')
+    .option(
+      '--name <session>',
+      'tmux session name (default: last folder of this git workspace)'
+    )
+    .option(
+      '--remote-control',
+      'Claude Code only: same session on this PC, claude.ai/code, and the Claude mobile app'
+    )
+    .option('--dry-run', 'Print the launch command without starting it')
+    .option('--json', 'Machine-readable output')
+    .addHelpText('after', START_HELP)
+    .action(async(app, options) => {
+      try {
+        const json = runStart({ ...options, app });
+        emitStartReport(json, Boolean(options.json));
+      } catch (error) {
+        handleCommandError(error, 'agent-kit start');
+        process.exitCode = 1;
+      }
+    });
+}
+
 module.exports = { setupAgentKitCommands };

package/lib/commands/auth-status-user.js

@@ -0,0 +1,99 @@
+/**
+ * Resolve the signed-in username for `aifabrix auth status`.
+ *
+ * @fileoverview Unwrap controller auth/user payloads and pick a display username
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { unwrapControllerData } = require('../identity/identity-response-helpers');
+
+/**
+ * @param {...*} values
+ * @returns {string}
+ */
+function firstNonEmptyString(...values) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) {
+      return value.trim();
+    }
+  }
+  return '';
+}
+
+/**
+ * Decode a JWT payload for display only. Does not verify the signature.
+ * @param {string} token
+ * @returns {Object|null}
+ */
+function decodeJwtPayload(token) {
+  if (!token || typeof token !== 'string') {
+    return null;
+  }
+  const parts = token.split('.');
+  if (parts.length < 2) {
+    return null;
+  }
+  try {
+    const b64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+    const padded = b64.padEnd(Math.ceil(b64.length / 4) * 4, '=');
+    const payload = JSON.parse(Buffer.from(padded, 'base64').toString('utf8'));
+    return payload && typeof payload === 'object' ? payload : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {Object|null|undefined} user
+ * @param {string} [token]
+ * @returns {string}
+ */
+function resolveDisplayUsername(user, token) {
+  const fromUser = firstNonEmptyString(
+    user && user.username,
+    user && user.preferredUsername,
+    user && user.preferred_username,
+    user && user.email
+  );
+  if (fromUser) {
+    return fromUser;
+  }
+  const payload = decodeJwtPayload(token);
+  return firstNonEmptyString(
+    payload && payload.preferred_username,
+    payload && payload.preferredUsername,
+    payload && payload.email,
+    payload && payload.upn
+  );
+}
+
+/**
+ * @param {Object|null|undefined} response
+ * @param {string} [token]
+ * @returns {{ authenticated: boolean, user: Object|null, username: string }}
+ */
+function parseAuthUserResponse(response, token) {
+  const payload = unwrapControllerData(response);
+  if (!payload || typeof payload !== 'object') {
+    return { authenticated: false, user: null, username: '' };
+  }
+  const rawUser = payload.user && typeof payload.user === 'object' ? payload.user : null;
+  const username = resolveDisplayUsername(rawUser, token);
+  const user = username && (!rawUser || !rawUser.username)
+    ? { ...(rawUser || {}), username }
+    : rawUser;
+  return {
+    authenticated: payload.authenticated !== false,
+    user,
+    username
+  };
+}
+
+module.exports = {
+  decodeJwtPayload,
+  resolveDisplayUsername,
+  parseAuthUserResponse
+};