@pellux/goodvibes-tui 0.19.24 → 0.19.25

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to GoodVibes TUI.
 
 ---
 
+## [0.19.25] — 2026-04-24
+
+### Changes
+- 705a19b feat: add onboarding wizard and CLI management
+
 ## [0.19.24] — 2026-04-22
 
 Four correctness and honesty fixes from an external architecture review. No SDK change (pinned at 0.23.2).

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/mgd34msu/goodvibes-tui/actions/workflows/ci.yml/badge.svg)](https://github.com/mgd34msu/goodvibes-tui/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-0.19.24-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
+[![Version](https://img.shields.io/badge/version-0.19.25-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
 
 A terminal-native AI coding, operations, automation, knowledge, and integration console with a typed runtime, omnichannel surfaces, structured memory/knowledge, and a raw ANSI renderer.
 
@@ -380,10 +380,10 @@ Alternatively, store keys encrypted using the `/secrets` command. Environment va
 For self-hosted or external secret managers, link a GoodVibes key to a provider-backed SecretRef:
 
 ```sh
-/secrets link OPENAI_API_KEY bw://GoodVibes%20OpenAI/password?sessionEnv=BW_SESSION
-/secrets link SLACK_BOT_TOKEN vaultwarden://GoodVibes%20Slack/password?server=https%3A%2F%2Fvault.example.test
-/secrets link STRIPE_TOKEN bws://00000000-0000-0000-0000-000000000000/value?accessTokenEnv=BWS_ACCESS_TOKEN
-/secrets link OPENAI_API_KEY op://Private/GoodVibes%20OpenAI/API%20Key
+/secrets link OPENAI_API_KEY goodvibes://secrets/bitwarden?item=GoodVibes%20OpenAI&field=password&sessionEnv=BW_SESSION
+/secrets link SLACK_BOT_TOKEN goodvibes://secrets/vaultwarden?item=GoodVibes%20Slack&field=password&server=https%3A%2F%2Fvault.example.test
+/secrets link STRIPE_TOKEN goodvibes://secrets/bws/00000000-0000-0000-0000-000000000000?field=value&accessTokenEnv=BWS_ACCESS_TOKEN
+/secrets link OPENAI_API_KEY goodvibes://secrets/1password?vault=Private&item=GoodVibes%20OpenAI&field=API%20Key
 ```
 
 Use `/secrets providers` for supported provider shapes and `/secrets test <secret-ref>` to validate a ref without printing its value.

package/bin/goodvibes

@@ -39,8 +39,13 @@ function run(command, args) {
 }
 
 const artifactName = resolveArtifactName(process.platform, process.arch);
+const localBuild = join(packageRoot, 'dist', 'goodvibes');
 const vendoredBinary = artifactName ? join(packageRoot, 'vendor', artifactName) : null;
 
+if (isExecutable(localBuild)) {
+  run(localBuild, process.argv.slice(2));
+}
+
 if (vendoredBinary && isExecutable(vendoredBinary)) {
   run(vendoredBinary, process.argv.slice(2));
 }

package/bin/goodvibes-daemon

@@ -39,8 +39,13 @@ function run(command, args) {
 }
 
 const artifactName = resolveArtifactName(process.platform, process.arch);
+const localBuild = join(packageRoot, 'dist', 'goodvibes-daemon');
 const vendoredBinary = artifactName ? join(packageRoot, 'vendor', artifactName) : null;
 
+if (isExecutable(localBuild)) {
+  run(localBuild, process.argv.slice(2));
+}
+
 if (vendoredBinary && isExecutable(vendoredBinary)) {
   run(vendoredBinary, process.argv.slice(2));
 }

package/docs/foundation-artifacts/operator-contract.json

@@ -3,7 +3,7 @@
   "product": {
     "id": "goodvibes",
     "surface": "operator",
-    "version": "0.23.2"
+    "version": "0.25.0"
   },
   "auth": {
     "modes": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "0.19.24",
+  "version": "0.19.25",
   "description": "Terminal-native GoodVibes product for coding, operations, automation, knowledge, channels, and daemon-backed control-plane workflows.",
   "type": "module",
   "main": "src/main.ts",
@@ -90,7 +90,7 @@
     "@anthropic-ai/vertex-sdk": "^0.16.0",
     "@ast-grep/napi": "^0.42.0",
     "@aws/bedrock-token-generator": "^1.1.0",
-    "@pellux/goodvibes-sdk": "0.23.2",
+    "@pellux/goodvibes-sdk": "^0.25.0",
     "bash-language-server": "^5.6.0",
     "fuse.js": "^7.1.0",
     "graphql": "^16.13.2",

package/src/cli/completion.ts

@@ -0,0 +1,89 @@
+const COMMANDS = [
+  'tui',
+  'run',
+  'exec',
+  'serve',
+  'web',
+  'onboarding',
+  'setup',
+  'doctor',
+  'status',
+  'models',
+  'providers',
+  'auth',
+  'subscription',
+  'secrets',
+  'sessions',
+  'tasks',
+  'pair',
+  'qrcode',
+  'surfaces',
+  'listener',
+  'control-plane',
+  'bundle',
+  'remote',
+  'bridge',
+  'completion',
+  'version',
+  'help',
+] as const;
+
+const OPTIONS = [
+  '--help',
+  '--version',
+  '--model',
+  '--provider',
+  '--cd',
+  '--working-dir',
+  '--daemon-home',
+  '--config',
+  '--enable',
+  '--disable',
+  '--prompt',
+  '--print',
+  '--output',
+  '--output-format',
+  '--json',
+  '--no-alt-screen',
+  '--port',
+  '--hostname',
+  '--open',
+  '--resume',
+  '--session',
+  '--continue',
+  '--fork',
+  '--password',
+  '--password-stdin',
+  '--role',
+  '--manual',
+] as const;
+
+export function renderCompletion(shell: string | undefined, binary = 'goodvibes'): string {
+  const normalized = (shell ?? 'bash').toLowerCase();
+  const words = [...COMMANDS, ...OPTIONS].join(' ');
+
+  if (normalized === 'zsh') {
+    return [
+      `#compdef ${binary}`,
+      `_${binary}() {`,
+      `  compadd -- ${words}`,
+      '}',
+      `_${binary} "$@"`,
+    ].join('\n');
+  }
+
+  if (normalized === 'fish') {
+    return [...COMMANDS, ...OPTIONS]
+      .map((word) => `complete -c ${binary} -a ${JSON.stringify(word)}`)
+      .join('\n');
+  }
+
+  return [
+    `_${binary}() {`,
+    '  local cur',
+    '  cur="${COMP_WORDS[COMP_CWORD]}"',
+    `  COMPREPLY=( $(compgen -W "${words}" -- "$cur") )`,
+    '}',
+    `complete -F _${binary} ${binary}`,
+  ].join('\n');
+}

package/src/cli/config-overrides.ts

@@ -0,0 +1,159 @@
+import type { ConfigKey, ConfigManager, ConfigSetting, GoodVibesConfig, PersistedFlagState } from '../config/index.ts';
+import { CONFIG_SCHEMA, ConfigError } from '../config/index.ts';
+import type { GoodVibesCliCommand, GoodVibesCliFlags } from './types.ts';
+import { RUNTIME_ENDPOINT_CONFIG_KEYS, hostModeForHostname } from './endpoints.ts';
+import type { RuntimeEndpointId } from './endpoints.ts';
+
+const CONFIG_SCHEMA_BY_KEY = new Map<string, ConfigSetting>(
+  CONFIG_SCHEMA.map((setting) => [setting.key, setting]),
+);
+
+function parseConfigOverrideValue(value: string): unknown {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return '';
+  try {
+    return JSON.parse(trimmed) as unknown;
+  } catch {
+    if (trimmed === 'true') return true;
+    if (trimmed === 'false') return false;
+    if (/^-?\d+(?:\.\d+)?$/.test(trimmed)) return Number(trimmed);
+    return value;
+  }
+}
+
+function getRuntimeConfig(configManager: ConfigManager): GoodVibesConfig {
+  const mutable = configManager as unknown as { config?: GoodVibesConfig };
+  if (!mutable.config || typeof mutable.config !== 'object') {
+    throw new ConfigError('ConfigManager runtime config is not available for CLI overrides.');
+  }
+  return mutable.config;
+}
+
+function validateConfigValue(setting: ConfigSetting, value: unknown): void {
+  if (setting.type === 'boolean' && typeof value !== 'boolean') {
+    throw new ConfigError(`Invalid value for ${setting.key}: expected boolean.`);
+  }
+  if (setting.type === 'number' && (typeof value !== 'number' || !Number.isFinite(value))) {
+    throw new ConfigError(`Invalid value for ${setting.key}: expected number.`);
+  }
+  if (setting.type === 'string' && typeof value !== 'string') {
+    throw new ConfigError(`Invalid value for ${setting.key}: expected string.`);
+  }
+  if (setting.type === 'enum' && setting.enumValues && !setting.enumValues.includes(String(value))) {
+    throw new ConfigError(`Invalid value for ${setting.key}: "${String(value)}". Allowed: ${setting.enumValues.join(', ')}`);
+  }
+  if (setting.validate && !setting.validate(value)) {
+    throw new ConfigError(`Invalid value for ${setting.key}: ${String(value)}`);
+  }
+}
+
+function setNestedConfigValue(config: GoodVibesConfig, key: ConfigKey, value: unknown): void {
+  const parts = key.split('.');
+  let cursor: unknown = config;
+  for (const part of parts.slice(0, -1)) {
+    if (cursor == null || typeof cursor !== 'object' || !(part in cursor)) {
+      throw new ConfigError(`Invalid config path: section '${part}' does not exist`);
+    }
+    cursor = (cursor as Record<string, unknown>)[part];
+  }
+  if (cursor == null || typeof cursor !== 'object') {
+    throw new ConfigError(`Invalid config path: section '${parts.slice(0, -1).join('.')}' does not exist`);
+  }
+  (cursor as Record<string, unknown>)[parts[parts.length - 1]!] = value;
+}
+
+export function applyRuntimeConfigValue(configManager: ConfigManager, key: ConfigKey, value: unknown): void {
+  const setting = CONFIG_SCHEMA_BY_KEY.get(key);
+  if (!setting) {
+    throw new ConfigError(`Unknown config key: ${key}`);
+  }
+  validateConfigValue(setting, value);
+  setNestedConfigValue(getRuntimeConfig(configManager), key, value);
+}
+
+export function applyRuntimeConfigOverrides(
+  configManager: ConfigManager,
+  overrides: readonly string[],
+): readonly string[] {
+  const errors: string[] = [];
+  for (const override of overrides) {
+    const index = override.indexOf('=');
+    if (index <= 0) {
+      errors.push(`Invalid --config override "${override}". Expected key=value.`);
+      continue;
+    }
+    const key = override.slice(0, index) as ConfigKey;
+    const rawValue = override.slice(index + 1);
+    try {
+      applyRuntimeConfigValue(configManager, key, parseConfigOverrideValue(rawValue));
+    } catch (error) {
+      errors.push(error instanceof Error ? `Invalid --config ${override}: ${error.message}` : `Invalid --config ${override}`);
+    }
+  }
+  return errors;
+}
+
+export function applyRuntimeFeatureFlagOverrides(
+  configManager: ConfigManager,
+  options: {
+    readonly enableFeatures: readonly string[];
+    readonly disableFeatures: readonly string[];
+  },
+): void {
+  if (options.enableFeatures.length === 0 && options.disableFeatures.length === 0) return;
+  const config = getRuntimeConfig(configManager);
+  const flags = { ...config.featureFlags };
+  for (const feature of options.enableFeatures) {
+    flags[feature] = 'enabled' satisfies PersistedFlagState;
+  }
+  for (const feature of options.disableFeatures) {
+    flags[feature] = 'disabled' satisfies PersistedFlagState;
+  }
+  config.featureFlags = flags;
+}
+
+export function applyRuntimeEndpointFlagOverrides(
+  configManager: ConfigManager,
+  endpoint: RuntimeEndpointId,
+  flags: Pick<GoodVibesCliFlags, 'hostname' | 'port'>,
+): readonly string[] {
+  const keys = RUNTIME_ENDPOINT_CONFIG_KEYS[endpoint];
+  const errors: string[] = [];
+
+  if (flags.hostname !== undefined) {
+    try {
+      applyRuntimeConfigValue(configManager, keys.hostMode, hostModeForHostname(flags.hostname));
+      applyRuntimeConfigValue(configManager, keys.host, flags.hostname);
+    } catch (error) {
+      errors.push(error instanceof Error
+        ? `Invalid --hostname ${flags.hostname}: ${error.message}`
+        : `Invalid --hostname ${flags.hostname}`);
+    }
+  }
+
+  if (flags.port !== undefined) {
+    try {
+      applyRuntimeConfigValue(configManager, keys.port, flags.port);
+    } catch (error) {
+      errors.push(error instanceof Error
+        ? `Invalid --port ${flags.port}: ${error.message}`
+        : `Invalid --port ${flags.port}`);
+    }
+  }
+
+  return errors;
+}
+
+export function applyRuntimeCommandEndpointFlagOverrides(
+  configManager: ConfigManager,
+  command: GoodVibesCliCommand,
+  flags: Pick<GoodVibesCliFlags, 'hostname' | 'port'>,
+): readonly string[] {
+  if (flags.hostname === undefined && flags.port === undefined) return [];
+  if (command === 'web') return applyRuntimeEndpointFlagOverrides(configManager, 'web', flags);
+  if (command === 'listener') return applyRuntimeEndpointFlagOverrides(configManager, 'httpListener', flags);
+  if (command === 'control-plane' || command === 'pair' || command === 'serve') {
+    return applyRuntimeEndpointFlagOverrides(configManager, 'controlPlane', flags);
+  }
+  return [];
+}

package/src/cli/endpoints.ts

@@ -0,0 +1,63 @@
+import type { ConfigKey, ConfigManager } from '../config/index.ts';
+
+export type RuntimeEndpointId = 'controlPlane' | 'httpListener' | 'web';
+export type RuntimeHostMode = 'local' | 'network' | 'custom';
+
+export const RUNTIME_ENDPOINT_DEFAULT_PORTS: Record<RuntimeEndpointId, number> = {
+  controlPlane: 3421,
+  httpListener: 3422,
+  web: 3423,
+};
+
+export const RUNTIME_ENDPOINT_CONFIG_KEYS: Record<RuntimeEndpointId, {
+  readonly hostMode: ConfigKey;
+  readonly host: ConfigKey;
+  readonly port: ConfigKey;
+}> = {
+  controlPlane: {
+    hostMode: 'controlPlane.hostMode',
+    host: 'controlPlane.host',
+    port: 'controlPlane.port',
+  },
+  httpListener: {
+    hostMode: 'httpListener.hostMode',
+    host: 'httpListener.host',
+    port: 'httpListener.port',
+  },
+  web: {
+    hostMode: 'web.hostMode',
+    host: 'web.host',
+    port: 'web.port',
+  },
+};
+
+export interface RuntimeEndpointBinding {
+  readonly hostMode: string;
+  readonly configuredHost: string;
+  readonly host: string;
+  readonly port: number;
+}
+
+export function hostModeForHostname(hostname: string): RuntimeHostMode {
+  const normalized = hostname.toLowerCase();
+  if (normalized === '0.0.0.0' || normalized === '::') return 'network';
+  if (normalized === '127.0.0.1' || normalized === 'localhost' || normalized === '::1') return 'local';
+  return 'custom';
+}
+
+export function resolveRuntimeEndpointBinding(
+  config: Pick<ConfigManager, 'get'>,
+  endpoint: RuntimeEndpointId,
+): RuntimeEndpointBinding {
+  const keys = RUNTIME_ENDPOINT_CONFIG_KEYS[endpoint];
+  const hostMode = String(config.get(keys.hostMode) ?? 'local');
+  const configuredHost = String(config.get(keys.host) ?? '127.0.0.1');
+  const port = Number(config.get(keys.port) || RUNTIME_ENDPOINT_DEFAULT_PORTS[endpoint]);
+  if (hostMode === 'network') {
+    return { hostMode, configuredHost, host: '0.0.0.0', port };
+  }
+  if (hostMode === 'custom') {
+    return { hostMode, configuredHost, host: configuredHost || '127.0.0.1', port };
+  }
+  return { hostMode, configuredHost, host: '127.0.0.1', port };
+}

package/src/cli/entrypoint.ts

@@ -0,0 +1,155 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { ConfigManager } from '../config/index.ts';
+import { readOnboardingCompletionMarkers } from '../runtime/onboarding/index.ts';
+import { GlobalNetworkTransportInstaller } from '@pellux/goodvibes-sdk/platform/runtime/network/index';
+import { createShellPathService } from '@pellux/goodvibes-sdk/platform/runtime/shell-paths';
+import { configureActivityLogger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import {
+  applyRuntimeCommandEndpointFlagOverrides,
+  applyRuntimeConfigOverrides,
+  applyRuntimeConfigValue,
+  applyRuntimeFeatureFlagOverrides,
+  handleGoodVibesCliCommand,
+  parseGoodVibesCli,
+  renderCliStatus,
+  renderCompletion,
+  renderGoodVibesHelp,
+  renderGoodVibesVersion,
+  renderOnboardingCliStatus,
+} from './index.ts';
+
+type ShellEntrypointOwnership = {
+  readonly workingDirectory: string;
+  readonly homeDirectory: string;
+};
+
+export type ShellEntrypointRoots = {
+  readonly defaultWorkingDirectory: string;
+  readonly homeDirectory: string;
+};
+
+export type PreparedShellCliRuntime = {
+  readonly cli: ReturnType<typeof parseGoodVibesCli>;
+  readonly configManager: ConfigManager;
+  readonly bootstrapWorkingDir: string;
+  readonly bootstrapHomeDirectory: string;
+};
+
+function resolveShellEntrypointOwnership(roots: ShellEntrypointRoots, workingDirOverride?: string): ShellEntrypointOwnership {
+  return {
+    workingDirectory: workingDirOverride ?? roots.defaultWorkingDirectory,
+    homeDirectory: roots.homeDirectory,
+  };
+}
+
+export async function prepareShellCliRuntime(
+  argv: readonly string[],
+  roots: ShellEntrypointRoots,
+  binary = 'goodvibes',
+): Promise<PreparedShellCliRuntime> {
+  const cli = parseGoodVibesCli(argv, binary);
+
+  if (cli.errors.length > 0) {
+    console.error(cli.errors.join('\n'));
+    console.error('');
+    console.error(renderGoodVibesHelp(binary));
+    process.exit(2);
+  }
+
+  if (cli.flags.help || cli.command === 'help') {
+    console.log(renderGoodVibesHelp(binary));
+    process.exit(0);
+  }
+
+  if (cli.flags.version || cli.command === 'version') {
+    console.log(renderGoodVibesVersion(binary));
+    process.exit(0);
+  }
+
+  if (cli.command === 'completion') {
+    console.log(renderCompletion(cli.commandArgs[0], binary));
+    process.exit(0);
+  }
+
+  if (cli.command === 'serve') {
+    await import('../daemon/cli.ts');
+    return new Promise<PreparedShellCliRuntime>(() => {});
+  }
+
+  const {
+    workingDirectory: bootstrapWorkingDir,
+    homeDirectory: bootstrapHomeDirectory,
+  } = resolveShellEntrypointOwnership(roots, cli.flags.workingDir ?? (cli.command === 'tui' ? cli.commandArgs[0] : undefined));
+  configureActivityLogger(join(bootstrapWorkingDir, '.goodvibes', 'logs'));
+  const configManager = new ConfigManager({
+    workingDir: bootstrapWorkingDir,
+    homeDir: bootstrapHomeDirectory,
+    surfaceRoot: 'tui',
+  });
+  new GlobalNetworkTransportInstaller().install(configManager);
+
+  const overrideErrors = applyRuntimeConfigOverrides(configManager, cli.flags.configOverrides);
+  if (overrideErrors.length > 0) {
+    console.error(overrideErrors.join('\n'));
+    process.exit(2);
+  }
+  applyRuntimeFeatureFlagOverrides(configManager, {
+    enableFeatures: cli.flags.enableFeatures,
+    disableFeatures: cli.flags.disableFeatures,
+  });
+
+  if (cli.flags.provider !== undefined) {
+    applyRuntimeConfigValue(configManager, 'provider.provider', cli.flags.provider);
+  }
+  if (cli.flags.model !== undefined) {
+    applyRuntimeConfigValue(configManager, 'provider.model', cli.flags.model);
+  }
+  const endpointOverrideErrors = applyRuntimeCommandEndpointFlagOverrides(configManager, cli.command, cli.flags);
+  if (endpointOverrideErrors.length > 0) {
+    console.error(endpointOverrideErrors.join('\n'));
+    process.exit(2);
+  }
+
+  if (cli.command === 'status' || cli.command === 'doctor' || (cli.command === 'onboarding' && cli.commandArgs[0] === 'status')) {
+    const shellPaths = createShellPathService({
+      workingDirectory: bootstrapWorkingDir,
+      homeDirectory: bootstrapHomeDirectory,
+    });
+    const userStorePath = shellPaths.resolveUserPath('tui', 'auth-users.json');
+    const bootstrapCredentialPath = shellPaths.resolveUserPath('tui', 'auth-bootstrap.txt');
+    const operatorTokenPath = join(bootstrapHomeDirectory, '.goodvibes', 'daemon', 'operator-tokens.json');
+    const onboardingMarkers = readOnboardingCompletionMarkers(shellPaths);
+    const statusOptions = {
+      configManager,
+      workingDirectory: bootstrapWorkingDir,
+      homeDirectory: bootstrapHomeDirectory,
+      onboardingMarkers,
+      auth: {
+        userStorePath,
+        userStorePresent: existsSync(userStorePath),
+        bootstrapCredentialPath,
+        bootstrapCredentialPresent: existsSync(bootstrapCredentialPath),
+        operatorTokenPath,
+        operatorTokenPresent: existsSync(operatorTokenPath),
+      },
+      doctor: cli.command === 'doctor',
+    };
+    console.log(cli.command === 'onboarding'
+      ? renderOnboardingCliStatus(statusOptions)
+      : renderCliStatus(statusOptions));
+    process.exit(0);
+  }
+
+  const cliCommandResult = await handleGoodVibesCliCommand({
+    cli,
+    configManager,
+    workingDirectory: bootstrapWorkingDir,
+    homeDirectory: bootstrapHomeDirectory,
+  });
+  if (cliCommandResult.handled) {
+    process.exit(cliCommandResult.exitCode);
+  }
+
+  return { cli, configManager, bootstrapWorkingDir, bootstrapHomeDirectory };
+}