@geraldmaron/construct 1.1.1 → 1.2.0

package/lib/chat/command-suggest.mjs

@@ -0,0 +1,161 @@
+/**
+ * lib/chat/command-suggest.mjs — slash-command autocomplete for construct chat.
+ *
+ * Single source of truth for the advertised commands and their one-line actions,
+ * shared by the web composer dropdown, the Ink footer (ghost completion + Tab),
+ * and tests. No I/O. `/models` is intentionally absent here — it stays a hidden
+ * alias of `/model` in the command handlers so only one model command is shown.
+ */
+
+export const SLASH_COMMAND_INFO = Object.freeze([
+  { cmd: '/help', desc: 'list every command and what it does' },
+  { cmd: '/model', desc: 'show or pick the model (opens a searchable picker)' },
+  { cmd: '/free', desc: 'switch to OpenRouter free-router mode' },
+  { cmd: '/set', desc: 'change a setting — /set <key> <on|off|value>' },
+  { cmd: '/settings', desc: 'show the current settings' },
+  { cmd: '/layers', desc: 'show transparency layers (Ctrl+1–5 to toggle)' },
+  { cmd: '/usage', desc: 'session token and cost breakdown' },
+  { cmd: '/oracle', desc: 'Oracle overseer verdict and pending approvals' },
+  { cmd: '/host', desc: 'show the active engine / host' },
+  { cmd: '/inspect', desc: 'toggle the inspector panel' },
+  { cmd: '/export', desc: 'save the answer to markdown — /export [last|session]' },
+  { cmd: '/clear', desc: 'clear the conversation' },
+  { cmd: '/exit', desc: 'quit (terminal only)' },
+]);
+
+export const SLASH_COMMANDS = Object.freeze(SLASH_COMMAND_INFO.map((c) => c.cmd));
+
+export const SETTING_KEY_INFO = Object.freeze([
+  { key: 'thinking', desc: 'show model reasoning inline' },
+  { key: 'path', desc: 'show the routing path' },
+  { key: 'specialists', desc: 'show the specialist chain' },
+  { key: 'tools', desc: 'show tool calls' },
+  { key: 'observability', desc: 'show usage + telemetry' },
+  { key: 'permission', desc: 'ask | allow_once | allow_always | reject' },
+  { key: 'sandbox', desc: 'read-only | workspace-write | danger-full-access' },
+  { key: 'model', desc: 'set the model id' },
+  { key: 'ascii', desc: 'ASCII-only glyphs (on|off)' },
+  { key: 'inspector', desc: 'inspector panel (on|off|auto)' },
+]);
+
+export const SETTING_KEYS = Object.freeze(SETTING_KEY_INFO.map((s) => s.key));
+
+const DESC_BY_CMD = new Map(SLASH_COMMAND_INFO.map((c) => [c.cmd, c.desc]));
+const DESC_BY_KEY = new Map(SETTING_KEY_INFO.map((s) => [s.key, s.desc]));
+
+export function slashCommandMatches(input) {
+  const trimmed = String(input || '').trimStart();
+  if (!trimmed.startsWith('/')) return [];
+  const token = trimmed.split(/\s+/)[0].toLowerCase();
+  if (!token || token === '/') return [...SLASH_COMMANDS];
+  return SLASH_COMMANDS.filter((cmd) => cmd.startsWith(token));
+}
+
+export function slashCommandGhost(input) {
+  const matches = slashCommandMatches(input);
+  if (!matches.length) return '';
+  const trimmed = String(input || '').trimStart();
+  const token = trimmed.split(/\s+/)[0];
+  const best = matches.find((cmd) => cmd.startsWith(token.toLowerCase())) || matches[0];
+  if (best.length <= token.length) return '';
+  return best.slice(token.length);
+}
+
+export function completeSlashCommand(input) {
+  const trimmed = String(input || '').trimStart();
+  if (!trimmed.startsWith('/')) return input;
+  const parts = trimmed.split(/\s+/);
+  const token = parts[0];
+  const matches = slashCommandMatches(token);
+  if (!matches.length) return input;
+  const lower = token.toLowerCase();
+  const exact = matches.find((cmd) => cmd === lower);
+  const best = exact || matches.find((cmd) => cmd.startsWith(lower)) || matches[0];
+  const rest = parts.slice(1).join(' ');
+  const completed = rest ? `${best} ${rest}` : `${best} `;
+  const prefix = input.startsWith(' ') ? input.slice(0, input.indexOf('/')) : '';
+  return `${prefix}${completed}`;
+}
+
+export function cycleSlashCommand(input, direction = 1) {
+  const matches = slashCommandMatches(input);
+  if (!matches.length) return input;
+  const trimmed = String(input || '').trimStart();
+  const token = trimmed.split(/\s+/)[0].toLowerCase();
+  const idx = Math.max(0, matches.findIndex((cmd) => cmd.startsWith(token)));
+  const next = matches[(idx + direction + matches.length) % matches.length];
+  const prefix = input.startsWith(' ') ? input.slice(0, input.indexOf('/')) : '';
+  return `${prefix}${next} `;
+}
+
+export function setKeyMatches(input) {
+  const trimmed = String(input || '').trimStart();
+  const m = trimmed.match(/^\/set\s+(\S*)$/i);
+  if (!m) return [];
+  const partial = (m[1] || '').toLowerCase();
+  if (!partial) return [...SETTING_KEYS];
+  return SETTING_KEYS.filter((k) => k.startsWith(partial));
+}
+
+export function completeSetKey(input) {
+  const trimmed = String(input || '').trimStart();
+  const m = trimmed.match(/^\/set\s+(\S*)$/i);
+  if (!m) return input;
+  const partial = m[1] || '';
+  const matches = setKeyMatches(input);
+  if (!matches.length) return input;
+  const best = matches.find((k) => k.startsWith(partial.toLowerCase())) || matches[0];
+  return `/set ${best} `;
+}
+
+// Rich suggestions for the composer dropdown: each entry carries the token to
+// complete plus its one-line action. Returns `/set` keys while the user is
+// typing a setting, otherwise the matching commands. Empty once an argument is
+// being typed for a non-/set command, so the dropdown gets out of the way.
+
+export function slashCommandSuggestions(input, { limit = 8 } = {}) {
+  const raw = String(input || '');
+  const trimmed = raw.trimStart();
+  if (!trimmed.startsWith('/')) return { kind: 'none', items: [] };
+
+  if (/^\/set(\s|$)/i.test(trimmed)) {
+    const keys = setKeyMatches(trimmed);
+    if (keys.length) {
+      return {
+        kind: 'set',
+        items: keys.slice(0, limit).map((key) => ({ value: key, desc: DESC_BY_KEY.get(key) || '' })),
+      };
+    }
+    return { kind: 'none', items: [] };
+  }
+
+  if (trimmed.includes(' ')) return { kind: 'none', items: [] };
+
+  const matches = slashCommandMatches(trimmed);
+  return {
+    kind: 'command',
+    items: matches.slice(0, limit).map((cmd) => ({ value: cmd, desc: DESC_BY_CMD.get(cmd) || '' })),
+  };
+}
+
+export function commandSuggestHint(input) {
+  if (!String(input || '').trimStart().startsWith('/')) return '';
+  const cmdMatches = slashCommandMatches(input);
+  if (cmdMatches.length && !input.trim().includes(' ')) {
+    return cmdMatches.slice(0, 6).join('  ');
+  }
+  const setMatches = setKeyMatches(input);
+  if (setMatches.length) return setMatches.slice(0, 8).join('  ');
+  return '';
+}
+
+export function applyTabCompletion(input) {
+  const setDone = completeSetKey(input);
+  if (setDone !== input) return setDone;
+  return completeSlashCommand(input);
+}
+
+export function isSlashOnlyInput(input) {
+  const trimmed = String(input || '').trimStart();
+  return trimmed.startsWith('/') && !trimmed.includes(' ');
+}

package/lib/chat/commands.mjs

@@ -0,0 +1,215 @@
+/**
+ * lib/chat/commands.mjs — in-session slash commands for `construct chat`.
+ *
+ * Owns the interactive control surface: changing the model, toggling transparency
+ * layers, editing and persisting settings, and inspecting token usage — without
+ * leaving the chat. Each command mutates the shared `session` object (which the
+ * renderer reads per turn) and, for settings, writes through to the project config
+ * via lib/chat/config.mjs. handle() returns false only for /exit so the REPL loop
+ * stays the single owner of the readline lifecycle. Ink passes `onClear` instead of
+ * ANSI clear-screen codes; both surfaces share `createCollectWriter` for capture.
+ *
+ * Model enumeration is delegated to the driver's optional listModels(); hosts that
+ * cannot enumerate models degrade to a clear notice rather than failing.
+ */
+
+import { saveChatConfig, LAYER_KEYS, PERMISSION_MODES, SANDBOX_LEVELS } from './config.mjs';
+import { exportTurns } from './export.mjs';
+import { formatUsagePanel } from './tui/usage.mjs';
+import { applySessionSetting } from './session-settings.mjs';
+import { commitPickerModel, promptModelPickerTerminal } from './model-picker.mjs';
+import { handleDemoCommand, registerDemoCommands } from './demo-guide.mjs';
+
+export const HELP = [
+  ['/help', 'show this help'],
+  ['/model [id]', 'show or set the model (no id opens a searchable picker)'],
+  ['/free', 'set OpenRouter free-router mode (--free equivalent)'],
+  ['/export [last|session]', 'write plain markdown answer to .cx/chat-sessions/exports/'],
+  ['/set <key> <on|off|value>', 'change a setting (thinking, tools, path, specialists, observability, permission, sandbox, model)'],
+  ['/settings', 'show current settings'],
+  ['/layers', 'show transparency layers'],
+  ['/usage', 'show session token and cost breakdown'],
+  ['/oracle', 'show Oracle overseer verdict and pending approvals'],
+  ['/host', 'show the active host'],
+  ['/clear', 'clear the screen'],
+  ['/inspect', 'toggle turn inspector panel (on/off/auto)'],
+  ['/exit', 'quit'],
+];
+
+function ask(rl, question) {
+  return new Promise((resolve) => rl.question(question, (answer) => resolve(answer)));
+}
+
+export function createCommands({ driver, host, hostId = host, version, cwd = process.cwd(), env = process.env, turnBlocksRef = null, demoGuide = null } = {}) {
+  async function handle(input, ctx) {
+    const { output, colors, layers, session, rl, onClear } = ctx;
+    const runtimeEnv = ctx.env || env;
+    const [cmd, ...rest] = input.trim().split(/\s+/);
+    const arg = rest.join(' ').trim();
+    const activeGuide = demoGuide || session?.demoGuide || null;
+
+    switch (cmd) {
+      case '/exit':
+      case '/quit':
+        return false;
+
+      case '/help':
+        output.write(`${colors.bold}commands${colors.reset}\n`);
+        for (const [name, desc] of registerDemoCommands(HELP, activeGuide)) {
+          output.write(`  ${colors.cyan}${name.padEnd(28)}${colors.reset}${colors.dim}${desc}${colors.reset}\n`);
+        }
+        break;
+
+      case '/demo':
+        handleDemoCommand(arg, { demoGuide: activeGuide, output, colors });
+        break;
+
+      case '/host': {
+        const mode = session.modelMode === 'free-router' ? 'free-router' : 'pinned';
+        output.write(`${colors.dim}engine:${colors.reset} ${host} (owned loop)${version ? ` (${version})` : ''}  ${colors.dim}model:${colors.reset} ${session.model || '(default)'}  ${colors.dim}mode:${colors.reset} ${mode}\n`);
+        output.write(`${colors.dim}construct runs the loop itself; switch models with /model${colors.reset}\n`);
+        break;
+      }
+
+      case '/models':
+      case '/model':
+        if (arg) {
+          commitPickerModel(session, { mode: 'pinned', modelId: arg }, { cwd, hostId, layers: session.layers });
+          output.write(`${colors.green}model set:${colors.reset} ${arg} ${colors.dim}(pinned, saved)${colors.reset}\n`);
+          break;
+        }
+        await promptModelPickerTerminal({
+          output,
+          colors,
+          session,
+          rl,
+          askFn: ctx.ask,
+          env: runtimeEnv,
+          cwd,
+          hostId,
+          layers: session.layers,
+        });
+        break;
+
+      case '/free': {
+        const { resolveFreeOpenRouterModel } = await import('../../apps/chat/engine/models.mjs');
+        const freeId = await resolveFreeOpenRouterModel({ env: runtimeEnv, tier: 'standard' });
+        if (!freeId) {
+          output.write(`${colors.red}OpenRouter free router needs OPENROUTER_API_KEY${colors.reset}\n`);
+          break;
+        }
+        commitPickerModel(session, { mode: 'free-router', modelId: freeId }, { cwd, hostId, layers: session.layers });
+        output.write(`${colors.green}model mode:${colors.reset} free-router → ${freeId} ${colors.dim}(saved)${colors.reset}\n`);
+        break;
+      }
+
+      case '/export': {
+        const scope = arg === 'session' ? 'session' : 'last';
+        const blocks = turnBlocksRef?.() || [];
+        const result = exportTurns(blocks, { scope, cwd });
+        if (!result.ok) output.write(`${colors.red}${result.error}${colors.reset}\n`);
+        else output.write(`${colors.green}exported${colors.reset} ${result.count} turn(s) to ${result.path}\n`);
+        break;
+      }
+
+      case '/set':
+        applySetting(output, colors, session, layers, rest);
+        break;
+
+      case '/settings':
+        showSettings(output, colors, session, layers);
+        break;
+
+      case '/layers':
+        output.write(`${colors.dim}layers:${colors.reset} ${LAYER_KEYS.map((k) => `${k}=${layers[k] ? 'on' : 'off'}`).join('  ')}\n`);
+        output.write(`${colors.dim}toggle with: /set <layer> on|off${colors.reset}\n`);
+        break;
+
+      case '/usage':
+        output.write(formatUsagePanel(session.usage, colors) + '\n');
+        break;
+
+      case '/oracle': {
+        const { readOracleDockState, formatOracleDockDetail } = await import('../intake/session-prelude.mjs');
+        const state = readOracleDockState({ cwd, env: runtimeEnv });
+        output.write(`${colors.bold}oracle${colors.reset}\n`);
+        output.write(`${formatOracleDockDetail(state)}\n`);
+        break;
+      }
+
+      case '/inspect': {
+        session.inspectorForced = session.inspectorForced === true ? false : session.inspectorForced === false ? null : true;
+        const label = session.inspectorForced === true ? 'on' : session.inspectorForced === false ? 'off' : 'auto';
+        output.write(`${colors.green}inspector:${colors.reset} ${label}\n`);
+        break;
+      }
+
+      case '/clear':
+        if (typeof onClear === 'function') onClear();
+        else output.write('\u001b[2J\u001b[H');
+        break;
+
+      default:
+        output.write(`${colors.dim}unknown command: ${cmd} \u2014 try /help${colors.reset}\n`);
+    }
+    return true;
+  }
+
+  function applySetting(output, colors, session, layers, parts) {
+    if (parts.length < 2) {
+      output.write(`${colors.dim}usage: /set <key> <value>  (keys: ${[...LAYER_KEYS, 'thinking', 'permission', 'sandbox', 'model', 'ascii', 'inspector'].join(', ')})${colors.reset}\n`);
+      output.write(`${colors.dim}or run /set alone in the Ink UI for a searchable picker${colors.reset}\n`);
+      return;
+    }
+    const [key, ...valueParts] = parts;
+    const value = valueParts.join(' ');
+    if (key === 'host') {
+      output.write(`${colors.dim}host can only be changed by relaunching: construct chat --host ${value}${colors.reset}\n`);
+      return;
+    }
+    const result = applySessionSetting(session, layers, key, value, { cwd, hostId });
+    if (!result.ok) { output.write(`${colors.red}${result.error}${colors.reset}\n`); return; }
+    output.write(`${colors.green}set:${colors.reset} ${result.key} = ${result.value} ${colors.dim}(saved)${colors.reset}\n`);
+  }
+
+  function showSettings(output, colors, session, layers) {
+    output.write(`${colors.bold}settings${colors.reset}\n`);
+    output.write(`  ${colors.cyan}host${colors.reset}        ${host}\n`);
+    output.write(`  ${colors.cyan}model${colors.reset}       ${session.model || '(host default)'} ${colors.dim}(${session.modelMode || 'pinned'})${colors.reset}\n`);
+    output.write(`  ${colors.cyan}thinking${colors.reset}    ${layers.thinking ? 'on' : 'off'}\n`);
+    output.write(`  ${colors.cyan}layers${colors.reset}      ${LAYER_KEYS.map((k) => `${k}=${layers[k] ? 'on' : 'off'}`).join('  ')}\n`);
+    const perm = session.permissionMode || 'allow_once';
+    output.write(`  ${colors.cyan}permission${colors.reset}  ${perm} ${colors.dim}(${PERMISSION_MODES.join('/')})${colors.reset}\n`);
+    output.write(`  ${colors.cyan}ascii${colors.reset}       ${session.ui?.ascii ? 'on' : 'off'} ${colors.dim}(glyph fallback for limited terminals)${colors.reset}\n`);
+    output.write(`  ${colors.cyan}inspector${colors.reset}   ${session.ui?.inspector || 'auto'} ${colors.dim}(off/auto/on — per-turn detail panel)${colors.reset}\n`);
+    output.write(`  ${colors.cyan}sandbox${colors.reset}     ${session.sandbox || '(host default)'} ${colors.dim}(${SANDBOX_LEVELS.join('/')})${colors.reset}\n`);
+    output.write(`  ${colors.dim}chat sandbox gates tools in this session; isolated project copies use \`construct sandbox create\`${colors.reset}\n`);
+  }
+
+  function persist(session, layers = session.layers) {
+    try {
+      saveChatConfig({
+        host: hostId,
+        model: session.modelMode === 'pinned' ? session.model : null,
+        modelMode: session.modelMode || 'pinned',
+        layers,
+        thinking: layers?.thinking,
+        permissionMode: session.permissionMode,
+        sandbox: session.sandbox,
+        ui: session.ui,
+      }, { cwd });
+    } catch { /* settings persistence is best-effort */ }
+  }
+
+  return { handle };
+}
+
+export function createCollectWriter() {
+  const parts = [];
+  return {
+    stream: { write(chunk) { parts.push(String(chunk)); } },
+    text() { return parts.join(''); },
+  };
+}
+
+export const PLAIN_COLORS = Object.freeze({ bold: '', dim: '', reset: '', cyan: '', green: '', red: '', yellow: '' });

package/lib/chat/config.mjs

@@ -0,0 +1,142 @@
+/**
+ * lib/chat/config.mjs — persisted settings for `construct chat`.
+ *
+ * Settings are layered: built-in DEFAULTS < global (~/.cx/chat-config.json) <
+ * project (<project>/.cx/chat-config.json). Reads merge all three; writes always go
+ * to the project file (resolveProjectScopedPath falls back to ~/.cx when there is no
+ * project root), so a user's global preferences seed every project while per-project
+ * overrides stay local. Only the known, validated keys are persisted.
+ *
+ * Exposed settings: host, model, transparency layers, thinking, permissionMode,
+ * sandbox, ui (ascii, inspector). Validation lives here so the command layer and the launcher
+ * share one source of truth for allowed values.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { resolveProjectScopedPath } from '../project-root.mjs';
+
+export const LAYER_KEYS = ['thinking', 'path', 'specialists', 'tools', 'observability'];
+export const PERMISSION_MODES = ['ask', 'allow_once', 'allow_always', 'reject'];
+export const SANDBOX_LEVELS = ['read-only', 'workspace-write', 'danger-full-access'];
+
+export const INSPECTOR_MODES = ['off', 'auto', 'on'];
+export const THEME_MODES = ['auto', 'light', 'dark'];
+export const MODEL_MODES = ['pinned', 'free-router'];
+
+export const DEFAULTS = Object.freeze({
+  host: null,
+  model: null,
+  modelMode: 'pinned',
+  layers: Object.freeze(Object.fromEntries(LAYER_KEYS.map((k) => [k, true]))),
+  thinking: true,
+  permissionMode: 'allow_once',
+  sandbox: null,
+  ui: Object.freeze({ ascii: false, inspector: 'off', theme: 'auto' }),
+});
+
+const CONFIG_BASENAME = 'chat-config.json';
+
+function readJson(file) {
+  try {
+    if (!fs.existsSync(file)) return null;
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function mergeConfig(base, override) {
+  if (!override || typeof override !== 'object') return base;
+  const out = { ...base };
+  for (const key of Object.keys(DEFAULTS)) {
+    if (override[key] == null) continue;
+    if (key === 'layers' && typeof override.layers === 'object') {
+      out.layers = { ...base.layers, ...override.layers };
+    } else if (key === 'ui' && typeof override.ui === 'object') {
+      out.ui = { ...base.ui, ...override.ui };
+    } else {
+      out[key] = override[key];
+    }
+  }
+  return out;
+}
+
+export function globalConfigPath() {
+  return path.join(os.homedir(), '.cx', CONFIG_BASENAME);
+}
+
+export function projectConfigPath({ cwd = process.cwd() } = {}) {
+  return resolveProjectScopedPath(CONFIG_BASENAME, { cwd, ensureDir: false });
+}
+
+export function loadChatConfig({ cwd = process.cwd() } = {}) {
+  let config = { ...DEFAULTS, layers: { ...DEFAULTS.layers } };
+  config = mergeConfig(config, readJson(globalConfigPath()));
+  const projectPath = projectConfigPath({ cwd });
+  config = mergeConfig(config, readJson(projectPath));
+  return { config, path: projectPath };
+}
+
+export function saveChatConfig(config, { cwd = process.cwd() } = {}) {
+  const target = resolveProjectScopedPath(CONFIG_BASENAME, { cwd, ensureDir: true });
+  const persisted = {};
+  for (const key of Object.keys(DEFAULTS)) {
+    if (config[key] == null) continue;
+    persisted[key] = key === 'layers' ? { ...config.layers } : key === 'ui' ? { ...config.ui } : config[key];
+  }
+  fs.writeFileSync(target, `${JSON.stringify(persisted, null, 2)}\n`);
+  return target;
+}
+
+// Validates and coerces a single `key value` setting change. Returns
+// { ok, value, error } so the command layer can report precisely.
+
+export function validateSetting(key, rawValue) {
+  switch (key) {
+    case 'host':
+      return { ok: true, value: String(rawValue) };
+    case 'model':
+      return { ok: true, value: String(rawValue) };
+    case 'thinking': {
+      const v = parseBool(rawValue);
+      return v == null ? { ok: false, error: 'thinking must be on/off' } : { ok: true, value: v };
+    }
+    case 'permissionMode':
+    case 'permission':
+      return PERMISSION_MODES.includes(rawValue)
+        ? { ok: true, key: 'permissionMode', value: rawValue }
+        : { ok: false, error: `permission must be one of: ${PERMISSION_MODES.join(', ')}` };
+    case 'sandbox':
+      return SANDBOX_LEVELS.includes(rawValue)
+        ? { ok: true, value: rawValue }
+        : { ok: false, error: `sandbox must be one of: ${SANDBOX_LEVELS.join(', ')}` };
+    case 'ascii': {
+      const v = parseBool(rawValue);
+      return v == null ? { ok: false, error: 'ascii must be on/off' } : { ok: true, key: 'ui.ascii', value: v };
+    }
+    case 'inspector':
+      return INSPECTOR_MODES.includes(String(rawValue).toLowerCase())
+        ? { ok: true, key: 'ui.inspector', value: String(rawValue).toLowerCase() }
+        : { ok: false, error: `inspector must be one of: ${INSPECTOR_MODES.join(', ')}` };
+    case 'theme':
+      return THEME_MODES.includes(String(rawValue).toLowerCase())
+        ? { ok: true, key: 'ui.theme', value: String(rawValue).toLowerCase() }
+        : { ok: false, error: `theme must be one of: ${THEME_MODES.join(', ')}` };
+    default:
+      if (LAYER_KEYS.includes(key)) {
+        const v = parseBool(rawValue);
+        return v == null ? { ok: false, error: `${key} must be on/off` } : { ok: true, key: `layers.${key}`, value: v };
+      }
+      return { ok: false, error: `unknown setting: ${key}` };
+  }
+}
+
+function parseBool(v) {
+  if (v === true || v === false) return v;
+  const s = String(v).toLowerCase();
+  if (['on', 'true', '1', 'yes', 'show'].includes(s)) return true;
+  if (['off', 'false', '0', 'no', 'hide'].includes(s)) return false;
+  return null;
+}