@pellux/goodvibes-agent 0.1.0

package/src/cli/network-posture.ts

@@ -0,0 +1,46 @@
+import type { RuntimeEndpointBinding } from './endpoints.ts';
+
+export type BindPostureKind = 'local' | 'local-network' | 'custom-network';
+
+export interface BindPosture {
+  readonly kind: BindPostureKind;
+  readonly label: string;
+  readonly networkFacing: boolean;
+}
+
+export function isLoopbackHost(host: string): boolean {
+  const normalized = host.trim().toLowerCase();
+  return normalized === 'localhost'
+    || normalized === '::1'
+    || normalized === '0:0:0:0:0:0:0:1'
+    || normalized.startsWith('127.');
+}
+
+export function classifyBindPosture(binding: Pick<RuntimeEndpointBinding, 'hostMode' | 'host'>): BindPosture {
+  if (binding.hostMode === 'local' || isLoopbackHost(binding.host)) {
+    return {
+      kind: 'local',
+      label: 'Local only',
+      networkFacing: false,
+    };
+  }
+  if (binding.hostMode === 'network' || binding.host === '0.0.0.0' || binding.host === '::') {
+    return {
+      kind: 'local-network',
+      label: 'Local Network',
+      networkFacing: true,
+    };
+  }
+  return {
+    kind: 'custom-network',
+    label: 'Custom network',
+    networkFacing: true,
+  };
+}
+
+export function isNetworkFacing(
+  enabled: unknown,
+  binding: Pick<RuntimeEndpointBinding, 'hostMode' | 'host'>,
+): boolean {
+  return enabled === true && classifyBindPosture(binding).networkFacing;
+}

package/src/cli/package-verification.ts

@@ -0,0 +1,123 @@
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface PackageCliBinVerification {
+  readonly command: 'goodvibes-agent';
+  readonly target: string;
+  readonly exists: boolean;
+  readonly executable: boolean;
+  readonly usesBunShebang: boolean;
+  readonly hasSourceEntrypoint: boolean;
+}
+
+export interface PackageCliVerificationReport {
+  readonly packageName: string;
+  readonly version: string;
+  readonly bins: readonly PackageCliBinVerification[];
+  readonly tarball: {
+    readonly entryCount: number;
+    readonly unpackedSize: number;
+    readonly requiredPathsPresent: readonly string[];
+    readonly forbiddenPaths: readonly string[];
+  };
+  readonly issues: readonly string[];
+}
+
+const REQUIRED_BIN_COMMANDS = ['goodvibes-agent'] as const;
+const REQUIRED_TARBALL_PATHS = [
+  'README.md',
+  'CHANGELOG.md',
+  'package.json',
+  'src/main.ts',
+  'bin/goodvibes-agent.ts',
+  'scripts/check-bun.sh',
+  'tsconfig.json',
+  '.goodvibes/GOODVIBES.md',
+  'docs/README.md',
+  'docs/getting-started.md',
+  'docs/deployment-and-services.md',
+  'docs/release-and-publishing.md',
+] as const;
+const FORBIDDEN_TARBALL_PREFIXES = ['.github/', 'src/test/', 'src/.test/', '.goodvibes/memory/', 'vendor/'] as const;
+const FORBIDDEN_TARBALL_DOCS = [
+  'docs/qemu-sandbox.md',
+  'docs/cloudflare-batch.md',
+  'docs/homeassistant-surface.md',
+  'docs/wrfc/',
+] as const;
+
+function readPackageJson(root: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8')) as Record<string, unknown>;
+}
+
+function hasExecutableBit(path: string): boolean {
+  return existsSync(path) && (statSync(path).mode & 0o111) !== 0;
+}
+
+function verifyBin(root: string, command: typeof REQUIRED_BIN_COMMANDS[number], target: string | undefined): PackageCliBinVerification {
+  const binPath = target ? join(root, target) : '';
+  const source = target && existsSync(binPath) ? readFileSync(binPath, 'utf-8') : '';
+  return {
+    command,
+    target: target ?? '',
+    exists: Boolean(target) && existsSync(binPath),
+    executable: Boolean(target) && hasExecutableBit(binPath),
+    usesBunShebang: source.startsWith('#!/usr/bin/env bun'),
+    hasSourceEntrypoint: source.includes('../src/main.ts'),
+  };
+}
+
+function npmPackDryRun(root: string): { readonly files: readonly string[]; readonly entryCount: number; readonly unpackedSize: number } {
+  const raw = execSync('npm pack --json --dry-run', {
+    cwd: root,
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'inherit'],
+  });
+  const [packResult] = JSON.parse(raw) as Array<{ files?: Array<{ path?: string }>; entryCount?: number; unpackedSize?: number }>;
+  return {
+    files: Array.isArray(packResult?.files) ? packResult.files.map((entry) => String(entry.path ?? '')) : [],
+    entryCount: Number(packResult?.entryCount ?? 0),
+    unpackedSize: Number(packResult?.unpackedSize ?? 0),
+  };
+}
+
+export function verifyPackageCliInstall(root: string): PackageCliVerificationReport {
+  const pkg = readPackageJson(root);
+  const bin = pkg.bin && typeof pkg.bin === 'object' ? pkg.bin as Record<string, string | undefined> : {};
+  const bins = REQUIRED_BIN_COMMANDS.map((command) => verifyBin(root, command, bin[command]));
+  const pack = npmPackDryRun(root);
+  const requiredPathsPresent = REQUIRED_TARBALL_PATHS.filter((path) => pack.files.includes(path));
+  const forbiddenPaths = pack.files.filter((path) => {
+    if (FORBIDDEN_TARBALL_PREFIXES.some((prefix) => path.startsWith(prefix))) return true;
+    return FORBIDDEN_TARBALL_DOCS.some((docPath) => path === docPath || path.startsWith(docPath));
+  });
+  const issues: string[] = [];
+
+  for (const item of bins) {
+    if (!item.target) issues.push(`package.json bin is missing ${item.command}.`);
+    if (!item.exists) issues.push(`bin target does not exist: ${item.command} -> ${item.target}`);
+    if (!item.executable) issues.push(`bin target is not executable: ${item.command} -> ${item.target}`);
+    if (!item.usesBunShebang) issues.push(`bin target does not use Bun shebang: ${item.command} -> ${item.target}`);
+    if (!item.hasSourceEntrypoint) issues.push(`bin target does not import the Agent source entrypoint: ${item.command}`);
+  }
+  for (const path of REQUIRED_TARBALL_PATHS) {
+    if (!pack.files.includes(path)) issues.push(`npm tarball missing required path: ${path}`);
+  }
+  for (const path of forbiddenPaths) {
+    issues.push(`npm tarball includes forbidden path: ${path}`);
+  }
+
+  return {
+    packageName: String(pkg.name ?? ''),
+    version: String(pkg.version ?? ''),
+    bins,
+    tarball: {
+      entryCount: pack.entryCount,
+      unpackedSize: pack.unpackedSize,
+      requiredPathsPresent,
+      forbiddenPaths,
+    },
+    issues,
+  };
+}

package/src/cli/parser.ts

@@ -0,0 +1,369 @@
+import type {
+  GoodVibesCliCommand,
+  GoodVibesCliFlags,
+  GoodVibesCliOutputFormat,
+  GoodVibesCliParseResult,
+} from './types.ts';
+
+const COMMAND_ALIASES: Readonly<Record<string, GoodVibesCliCommand>> = {
+  tui: 'tui',
+  app: 'tui',
+  run: 'run',
+  exec: 'run',
+  e: 'run',
+  serve: 'serve',
+  daemon: 'serve',
+  server: 'serve',
+  web: 'web',
+  service: 'service',
+  services: 'service',
+  status: 'status',
+  doctor: 'doctor',
+  onboarding: 'onboarding',
+  setup: 'onboarding',
+  models: 'models',
+  model: 'models',
+  providers: 'providers',
+  provider: 'providers',
+  auth: 'auth',
+  subscription: 'subscription',
+  subscriptions: 'subscription',
+  secrets: 'secrets',
+  secret: 'secrets',
+  sessions: 'sessions',
+  session: 'sessions',
+  tasks: 'tasks',
+  task: 'tasks',
+  pair: 'pair',
+  qrcode: 'pair',
+  qr: 'pair',
+  surfaces: 'surfaces',
+  surface: 'surfaces',
+  listener: 'listener',
+  'http-listener': 'listener',
+  webhook: 'listener',
+  'control-plane': 'control-plane',
+  controlplane: 'control-plane',
+  cp: 'control-plane',
+  bundle: 'bundle',
+  bundles: 'bundle',
+  remote: 'remote',
+  bridge: 'bridge',
+  completion: 'completion',
+  completions: 'completion',
+  help: 'help',
+  version: 'version',
+};
+
+function createDefaultFlags(): GoodVibesCliFlags {
+  return {
+    provider: undefined,
+    model: undefined,
+    daemonHome: undefined,
+    workingDir: undefined,
+    help: false,
+    version: false,
+    prompt: undefined,
+    print: false,
+    outputFormat: 'text',
+    configOverrides: [],
+    enableFeatures: [],
+    disableFeatures: [],
+    noAltScreen: false,
+    port: undefined,
+    hostname: undefined,
+    open: false,
+    continueLast: false,
+    resume: undefined,
+    session: undefined,
+    fork: false,
+    rawOutput: false,
+    acceptRawOutputRisk: false,
+  };
+}
+
+function splitOption(token: string): { readonly name: string; readonly value: string | undefined } {
+  const index = token.indexOf('=');
+  if (index < 0) return { name: token, value: undefined };
+  return {
+    name: token.slice(0, index),
+    value: token.slice(index + 1),
+  };
+}
+
+function getValue(
+  argv: readonly string[],
+  index: number,
+  inlineValue: string | undefined,
+  optionName: string,
+  errors: string[],
+): { readonly value: string | undefined; readonly nextIndex: number } {
+  if (inlineValue !== undefined) return { value: inlineValue, nextIndex: index };
+  const next = argv[index + 1];
+  if (next === undefined || (next.startsWith('-') && next !== '-')) {
+    errors.push(`${optionName} requires a value.`);
+    return { value: undefined, nextIndex: index };
+  }
+  return { value: next, nextIndex: index + 1 };
+}
+
+function getOptionalValue(
+  argv: readonly string[],
+  index: number,
+  inlineValue: string | undefined,
+): { readonly value: string | undefined; readonly nextIndex: number } {
+  if (inlineValue !== undefined) return { value: inlineValue, nextIndex: index };
+  const next = argv[index + 1];
+  if (next === undefined || next.startsWith('-')) return { value: undefined, nextIndex: index };
+  return { value: next, nextIndex: index + 1 };
+}
+
+function parsePort(value: string | undefined, optionName: string, errors: string[]): number | undefined {
+  if (value === undefined) return undefined;
+  if (!/^\d+$/.test(value)) {
+    errors.push(`${optionName} must be a port number from 1 to 65535.`);
+    return undefined;
+  }
+  const port = Number.parseInt(value, 10);
+  if (port < 1 || port > 65535) {
+    errors.push(`${optionName} must be a port number from 1 to 65535.`);
+    return undefined;
+  }
+  return port;
+}
+
+function normalizeOutputFormat(value: string | undefined, errors: string[]): GoodVibesCliOutputFormat {
+  if (value === 'text' || value === 'json' || value === 'stream-json') return value;
+  errors.push('--output-format must be one of: text, json, stream-json.');
+  return 'text';
+}
+
+function inferProviderFromModel(model: string, currentProvider: string | undefined): string | undefined {
+  if (currentProvider !== undefined) return currentProvider;
+  if (model.includes(':')) return model.split(':')[0];
+  if (model.includes('/')) return model.split('/')[0];
+  return undefined;
+}
+
+function withFlag<K extends keyof GoodVibesCliFlags>(
+  flags: GoodVibesCliFlags,
+  key: K,
+  value: GoodVibesCliFlags[K],
+): GoodVibesCliFlags {
+  return { ...flags, [key]: value };
+}
+
+function appendFlagArray<K extends 'configOverrides' | 'enableFeatures' | 'disableFeatures'>(
+  flags: GoodVibesCliFlags,
+  key: K,
+  value: string,
+): GoodVibesCliFlags {
+  return {
+    ...flags,
+    [key]: [...flags[key], value],
+  };
+}
+
+export function parseGoodVibesCli(
+  argv: readonly string[],
+  binary = 'goodvibes-agent',
+): GoodVibesCliParseResult {
+  let flags = createDefaultFlags();
+  let command: GoodVibesCliCommand = 'tui';
+  let rawCommand: string | undefined;
+  const commandArgs: string[] = [];
+  const positionals: string[] = [];
+  const errors: string[] = [];
+  let sawCommand = false;
+  let passthrough = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index]!;
+
+    if (passthrough) {
+      if (sawCommand) commandArgs.push(token);
+      else positionals.push(token);
+      continue;
+    }
+
+    if (token === '--') {
+      passthrough = true;
+      continue;
+    }
+
+    if (!token.startsWith('-') || token === '-') {
+      if (!sawCommand) {
+        const normalized = COMMAND_ALIASES[token.toLowerCase()];
+        if (normalized) {
+          command = normalized;
+          rawCommand = token;
+          sawCommand = true;
+          continue;
+        }
+      }
+      positionals.push(token);
+      if (sawCommand) commandArgs.push(token);
+      continue;
+    }
+
+    const { name, value: inlineValue } = splitOption(token);
+
+    if (name === '--help' || name === '-h') {
+      flags = withFlag(flags, 'help', true);
+      continue;
+    }
+    if (name === '--version' || name === '-v') {
+      flags = withFlag(flags, 'version', true);
+      continue;
+    }
+    if (name === '--print') {
+      flags = withFlag(flags, 'print', true);
+      if (!sawCommand) command = 'run';
+      continue;
+    }
+    if (name === '--json') {
+      flags = withFlag(flags, 'outputFormat', 'json');
+      continue;
+    }
+    if (name === '--no-alt-screen') {
+      flags = withFlag(flags, 'noAltScreen', true);
+      continue;
+    }
+    if (name === '--open') {
+      flags = withFlag(flags, 'open', true);
+      continue;
+    }
+    if (name === '--continue') {
+      flags = withFlag(flags, 'continueLast', true);
+      continue;
+    }
+    if (name === '--fork') {
+      flags = withFlag(flags, 'fork', true);
+      continue;
+    }
+    if (name === '--raw-output') {
+      flags = withFlag(flags, 'rawOutput', true);
+      continue;
+    }
+    if (name === '--accept-raw-output-risk') {
+      flags = withFlag(flags, 'acceptRawOutputRisk', true);
+      continue;
+    }
+
+    if (name === '--provider') {
+      const consumed = getValue(argv, index, inlineValue, name, errors);
+      index = consumed.nextIndex;
+      if (consumed.value !== undefined) flags = withFlag(flags, 'provider', consumed.value);
+      continue;
+    }
+    if (name === '--model' || name === '-m') {
+      const consumed = getValue(argv, index, inlineValue, name, errors);
+      index = consumed.nextIndex;
+      if (consumed.value !== undefined) {
+        flags = withFlag(flags, 'model', consumed.value);
+        flags = withFlag(flags, 'provider', inferProviderFromModel(consumed.value, flags.provider));
+      }
+      continue;
+    }
+    if (name === '--daemon-home') {
+      const consumed = getValue(argv, index, inlineValue, name, errors);
+      index = consumed.nextIndex;
+      if (consumed.value !== undefined) flags = withFlag(flags, 'daemonHome', consumed.value);
+      continue;
+    }
+    if (name === '--working-dir' || name === '--cd' || name === '-C') {
+      const consumed = getValue(argv, index, inlineValue, name, errors);
+      index = consumed.nextIndex;
+      if (consumed.value !== undefined) flags = withFlag(flags, 'workingDir', consumed.value);
+      continue;
+    }
+    if (name === '--prompt' || name === '-p') {
+      const consumed = getValue(argv, index, inlineValue, name, errors);
+      index = consumed.nextIndex;
+      if (consumed.value !== undefined) {
+        flags = withFlag(flags, 'prompt', consumed.value);
+        if (!sawCommand) command = 'run';
+      }
+      continue;
+    }
+    if (name === '--output-format' || name === '--output' || name === '-o') {
+      const consumed = getValue(argv, index, inlineValue, name, errors);
+      index = consumed.nextIndex;
+      flags = withFlag(flags, 'outputFormat', normalizeOutputFormat(consumed.value, errors));
+      continue;
+    }
+    if (name === '--config') {
+      const consumed = getValue(argv, index, inlineValue, name, errors);
+      index = consumed.nextIndex;
+      if (consumed.value !== undefined) flags = appendFlagArray(flags, 'configOverrides', consumed.value);
+      continue;
+    }
+    if (name === '-c') {
+      const consumed = getValue(argv, index, inlineValue, name, errors);
+      index = consumed.nextIndex;
+      if (consumed.value !== undefined) flags = appendFlagArray(flags, 'configOverrides', consumed.value);
+      continue;
+    }
+    if (name === '--enable') {
+      const consumed = getValue(argv, index, inlineValue, name, errors);
+      index = consumed.nextIndex;
+      if (consumed.value !== undefined) flags = appendFlagArray(flags, 'enableFeatures', consumed.value);
+      continue;
+    }
+    if (name === '--disable') {
+      const consumed = getValue(argv, index, inlineValue, name, errors);
+      index = consumed.nextIndex;
+      if (consumed.value !== undefined) flags = appendFlagArray(flags, 'disableFeatures', consumed.value);
+      continue;
+    }
+    if (name === '--port') {
+      const consumed = getValue(argv, index, inlineValue, name, errors);
+      index = consumed.nextIndex;
+      flags = withFlag(flags, 'port', parsePort(consumed.value, name, errors));
+      continue;
+    }
+    if (name === '--hostname' || name === '--host') {
+      const consumed = getValue(argv, index, inlineValue, name, errors);
+      index = consumed.nextIndex;
+      if (consumed.value !== undefined) flags = withFlag(flags, 'hostname', consumed.value);
+      continue;
+    }
+    if (name === '--resume' || name === '-r') {
+      const consumed = getOptionalValue(argv, index, inlineValue);
+      index = consumed.nextIndex;
+      flags = withFlag(flags, 'resume', consumed.value ?? 'latest');
+      continue;
+    }
+    if (name === '--session' || name === '-s') {
+      const consumed = getValue(argv, index, inlineValue, name, errors);
+      index = consumed.nextIndex;
+      if (consumed.value !== undefined) flags = withFlag(flags, 'session', consumed.value);
+      continue;
+    }
+
+    if (sawCommand) {
+      commandArgs.push(token);
+      continue;
+    }
+
+    errors.push(`Unknown option: ${name}`);
+  }
+
+  if (flags.prompt === undefined && (command === 'run' || flags.print) && positionals.length > 0) {
+    flags = withFlag(flags, 'prompt', positionals.join(' '));
+  }
+
+  if (rawCommand !== undefined && command === 'unknown') {
+    errors.push(`Unknown command: ${rawCommand}`);
+  }
+
+  return {
+    binary,
+    command,
+    rawCommand,
+    commandArgs,
+    positionals,
+    flags,
+    errors,
+  };
+}

package/src/cli/provider-auth-routes.ts

@@ -0,0 +1,22 @@
+import type { ProviderAuthRouteDescriptor } from '@pellux/goodvibes-sdk/platform/providers';
+
+function routeUsable(route: ProviderAuthRouteDescriptor): boolean {
+  return route.usable ?? route.configured;
+}
+
+export function summarizeProviderAuthRoutes(routes: readonly ProviderAuthRouteDescriptor[] | undefined): string {
+  if (!routes?.length) return 'n/a';
+  const configured = routes.filter((route) => route.configured).length;
+  const usable = routes.filter(routeUsable).length;
+  return `${configured}/${routes.length} configured, ${usable}/${routes.length} usable`;
+}
+
+export function formatProviderAuthRoute(route: ProviderAuthRouteDescriptor): string {
+  const status = [
+    route.configured ? 'configured' : 'not configured',
+    routeUsable(route) ? 'usable' : 'not usable',
+    route.freshness,
+  ].filter((part): part is string => Boolean(part));
+  const detail = route.detail?.trim();
+  return `${route.label} [${route.route}; ${status.join(', ')}]${detail ? ` - ${detail}` : ''}`;
+}

package/src/cli/provider-classification.ts

@@ -0,0 +1,107 @@
+export type ProviderSetupClass =
+  | 'api-key'
+  | 'cloud-account'
+  | 'local'
+  | 'no-key-free'
+  | 'self-hosted'
+  | 'subscription'
+  | 'unknown';
+
+export interface ProviderSetupClassificationInput {
+  readonly providerId: string;
+  readonly authMode?: string;
+  readonly configured?: boolean;
+  readonly modelCount?: number;
+}
+
+export interface ProviderSetupClassification {
+  readonly setupClass: ProviderSetupClass;
+  readonly setupLabel: string;
+  readonly setupDetail: string;
+}
+
+const SUBSCRIPTION_PROVIDERS = new Set([
+  'openai-subscriber',
+]);
+
+const LOCAL_PROVIDERS = new Set([
+  'ollama',
+  'synthetic',
+]);
+
+const SELF_HOSTED_PROVIDERS = new Set([
+  'copilot-proxy',
+  'litellm',
+  'sglang',
+]);
+
+const CLOUD_ACCOUNT_PROVIDERS = new Set([
+  'amazon-bedrock',
+  'amazon-bedrock-mantle',
+  'anthropic-vertex',
+  'microsoft-foundry',
+]);
+
+function byClass(setupClass: ProviderSetupClass): ProviderSetupClassification {
+  switch (setupClass) {
+    case 'api-key':
+      return {
+        setupClass,
+        setupLabel: 'API key',
+        setupDetail: 'Requires a provider API key or equivalent secret.',
+      };
+    case 'cloud-account':
+      return {
+        setupClass,
+        setupLabel: 'Cloud account',
+        setupDetail: 'Requires cloud account credentials or workload identity.',
+      };
+    case 'local':
+      return {
+        setupClass,
+        setupLabel: 'Local/no-key',
+        setupDetail: 'Runs locally or through a built-in test/local path without a paid API key.',
+      };
+    case 'no-key-free':
+      return {
+        setupClass,
+        setupLabel: 'No-key/free',
+        setupDetail: 'Can be listed or used without a configured paid API key in this runtime.',
+      };
+    case 'self-hosted':
+      return {
+        setupClass,
+        setupLabel: 'Self-hosted',
+        setupDetail: 'Uses an operator-managed local or self-hosted gateway.',
+      };
+    case 'subscription':
+      return {
+        setupClass,
+        setupLabel: 'Subscription',
+        setupDetail: 'Uses a stored subscription/OAuth session instead of a raw API key.',
+      };
+    case 'unknown':
+      return {
+        setupClass,
+        setupLabel: 'Unknown',
+        setupDetail: 'Setup path is not available from runtime metadata.',
+      };
+  }
+}
+
+export function classifyProviderSetup(input: ProviderSetupClassificationInput): ProviderSetupClassification {
+  const providerId = input.providerId.trim().toLowerCase();
+  const authMode = input.authMode?.trim().toLowerCase() ?? '';
+  const configured = input.configured ?? false;
+  const modelCount = input.modelCount ?? 0;
+
+  if (SUBSCRIPTION_PROVIDERS.has(providerId) || authMode === 'oauth') return byClass('subscription');
+  if (LOCAL_PROVIDERS.has(providerId)) return byClass('local');
+  if (SELF_HOSTED_PROVIDERS.has(providerId)) return byClass('self-hosted');
+  if (CLOUD_ACCOUNT_PROVIDERS.has(providerId)) return byClass('cloud-account');
+  if (authMode === 'api-key' || authMode === 'bearer') return byClass('api-key');
+  if (authMode === 'anonymous' || authMode === 'none') {
+    return configured || modelCount > 0 ? byClass('no-key-free') : byClass('unknown');
+  }
+  return byClass('unknown');
+}