@poetic-ai/poetic 1.42.0

package/integrations/bb-plugin-poetic/src/setup-config-service.ts

@@ -0,0 +1,590 @@
+/**
+ * Single-shot reader for Poetic-owned setup and configuration status.
+ *
+ * The injected runner receives only fixed read-only commands. This module has
+ * no setup, reinstall, auth, config mutation, cache, timer, polling, or
+ * executable-discovery path. Every command runs at most once with fixed argv,
+ * the selected repository cwd, shell: false, bounded stdout, and no retry.
+ */
+
+import type { z } from 'zod';
+import { repositorySchema } from './repository-schema.js';
+import {
+  SETUP_CONFIG_GUIDANCE,
+  SETUP_CONFIG_MAX_STDOUT_BYTES,
+  type SetupConfigAttributedValue,
+  type SetupConfigResult,
+  type SetupConfigSnapshot,
+  type SetupConfigSource,
+  type SetupConfigUnavailableReason,
+  type SetupProviderReadiness,
+  setupConfigSourceSchema,
+} from './setup-config-schema.js';
+
+export const SETUP_CONFIG_TIMEOUT_MS = 15_000;
+
+type Repository = z.infer<typeof repositorySchema>;
+
+const VERSION_ARGS = ['--version'] as const;
+const RESOLVED_ARGS = ['config', 'resolved', '--json'] as const;
+const VALIDATE_ARGS = ['config', 'validate', '--json'] as const;
+const PROVIDERS_ARGS = ['provider', 'list', '--json'] as const;
+
+export type SetupConfigCommand =
+  | {
+      file: 'poetic';
+      args: typeof VERSION_ARGS;
+      cwd: string;
+      timeoutMs: typeof SETUP_CONFIG_TIMEOUT_MS;
+      shell: false;
+    }
+  | {
+      file: 'poetic';
+      args: typeof RESOLVED_ARGS;
+      cwd: string;
+      timeoutMs: typeof SETUP_CONFIG_TIMEOUT_MS;
+      shell: false;
+    }
+  | {
+      file: 'poetic';
+      args: typeof VALIDATE_ARGS;
+      cwd: string;
+      timeoutMs: typeof SETUP_CONFIG_TIMEOUT_MS;
+      shell: false;
+    }
+  | {
+      file: 'poetic';
+      args: typeof PROVIDERS_ARGS;
+      cwd: string;
+      timeoutMs: typeof SETUP_CONFIG_TIMEOUT_MS;
+      shell: false;
+    };
+
+export interface SetupConfigCommandResult {
+  stdout: string;
+  stderr: string;
+}
+
+export type SetupConfigRunner = (command: SetupConfigCommand) => Promise<SetupConfigCommandResult>;
+
+const EMPTY_ROLE = {
+  provider: null as SetupConfigAttributedValue | null,
+  model: null as SetupConfigAttributedValue | null,
+};
+
+function guidance() {
+  return SETUP_CONFIG_GUIDANCE.map((entry) => ({ ...entry }));
+}
+
+function unavailable(
+  reason: SetupConfigUnavailableReason,
+  message: string,
+  compatibility?: SetupConfigSnapshot['compatibility']
+): SetupConfigResult {
+  return {
+    state: 'unavailable',
+    reason,
+    message,
+    ...(compatibility ? { compatibility } : {}),
+    guidance: guidance(),
+  };
+}
+
+function timeoutError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const value = error as { code?: unknown; name?: unknown };
+  return value.code === 'ETIMEDOUT' || value.name === 'TimeoutError';
+}
+
+function missingCliError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const value = error as { code?: unknown; message?: unknown };
+  if (value.code === 'ENOENT') return true;
+  if (typeof value.message === 'string') {
+    const message = value.message.toLowerCase();
+    return (
+      message.includes('enoent') ||
+      message.includes('not found') ||
+      message.includes('executable not found') ||
+      message.includes('spawn poetic')
+    );
+  }
+  return false;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function parseJsonBounded(
+  stdout: string
+):
+  | { state: 'ok'; value: unknown }
+  | { state: 'empty' }
+  | { state: 'overflow' }
+  | { state: 'malformed' } {
+  if (stdout.trim().length === 0) return { state: 'empty' };
+  if (Buffer.byteLength(stdout, 'utf8') > SETUP_CONFIG_MAX_STDOUT_BYTES) {
+    return { state: 'overflow' };
+  }
+  try {
+    return { state: 'ok', value: JSON.parse(stdout) };
+  } catch {
+    return { state: 'malformed' };
+  }
+}
+
+function parseVersion(stdout: string, stderr: string): string | null {
+  const combined = `${stdout}\n${stderr}`;
+  return combined.match(/\b(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\b/)?.[1] ?? null;
+}
+
+function asSource(value: unknown): SetupConfigSource | null {
+  const parsed = setupConfigSourceSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}
+
+/**
+ * Accept only `{ value, source }` and drop every other property (including
+ * `sourcePath`, which may carry absolute config paths).
+ */
+function attributed(value: unknown): SetupConfigAttributedValue | null {
+  if (!isRecord(value)) return null;
+  if (typeof value.value !== 'string' && typeof value.value !== 'number') return null;
+  const text = String(value.value).trim();
+  if (text.length === 0 || text.length > 500) return null;
+  const source = asSource(value.source);
+  if (!source) return null;
+  return { value: text, source };
+}
+
+function repositoryUninitialized(repository: Repository): boolean {
+  return repository.messages.some((message) =>
+    message.toLowerCase().includes('not an initialized poetic project')
+  );
+}
+
+function mapProviderReadiness(entry: {
+  installed: boolean | null;
+  ready: boolean;
+  authenticated: 'yes' | 'no' | 'unknown';
+  readinessStatus: string | null;
+}): SetupProviderReadiness {
+  if (entry.installed === false) return 'missing-cli';
+  if (entry.readinessStatus === 'broken') return 'broken';
+  // Fresh cached / reported authentication failure stays distinct from unknown.
+  if (
+    entry.authenticated === 'no' ||
+    entry.readinessStatus === 'normal-auth-needed' ||
+    entry.readinessStatus === 'contained-auth-needed'
+  ) {
+    return 'auth-failure';
+  }
+  if (entry.ready === true) {
+    return 'ready';
+  }
+  // Unobserved and deferred auth are normal unknown — never a failure or gate.
+  if (
+    entry.authenticated === 'unknown' ||
+    entry.readinessStatus === 'installed-but-unverified' ||
+    entry.installed === null
+  ) {
+    return 'unknown';
+  }
+  return 'not-ready';
+}
+
+function emptyCompetition(): SetupConfigSnapshot['competition'] {
+  return {
+    state: 'unavailable',
+    variants: [],
+    judge: null,
+    judgeRun: null,
+    judgePrimary: null,
+    completionMode: null,
+    synthesisStrategy: null,
+    timeoutMinutes: null,
+    requireMinVariants: null,
+    sources: {},
+  };
+}
+
+function emptyDefaults(): SetupConfigSnapshot['defaults'] {
+  return {
+    state: 'unavailable',
+    provider: null,
+    model: null,
+    strategy: null,
+    judgeType: null,
+    judgeProvider: null,
+    judgeModel: null,
+    synthesisModel: null,
+  };
+}
+
+function emptyRoles(): SetupConfigSnapshot['roles'] {
+  return {
+    state: 'unavailable',
+    orchestrator: { ...EMPTY_ROLE },
+    executor: { ...EMPTY_ROLE },
+    reviewer: { ...EMPTY_ROLE },
+  };
+}
+
+function emptyProviders(): SetupConfigSnapshot['providers'] {
+  return { state: 'unavailable', readyCount: 0, items: [] };
+}
+
+function parseDefaultsAndRoles(value: unknown): {
+  defaults: SetupConfigSnapshot['defaults'];
+  competition: SetupConfigSnapshot['competition'];
+  roles: SetupConfigSnapshot['roles'];
+} {
+  if (!isRecord(value)) {
+    return {
+      defaults: emptyDefaults(),
+      competition: emptyCompetition(),
+      roles: emptyRoles(),
+    };
+  }
+
+  const judge = isRecord(value.judge) ? value.judge : null;
+  const defaults: SetupConfigSnapshot['defaults'] = {
+    state: 'available',
+    provider: attributed(value.defaultProvider),
+    model: attributed(value.defaultModel),
+    strategy: attributed(value.defaultStrategy),
+    judgeType: judge ? attributed(judge.type) : null,
+    judgeProvider: judge ? attributed(judge.provider) : null,
+    judgeModel: judge ? attributed(judge.model) : null,
+    synthesisModel: attributed(value.synthesisModel),
+  };
+
+  const rolesRoot = isRecord(value.roles) ? value.roles : null;
+  const roleSlot = (slot: unknown) => {
+    if (!isRecord(slot)) return { ...EMPTY_ROLE };
+    return {
+      provider: attributed(slot.provider),
+      model: attributed(slot.model),
+    };
+  };
+  const roles: SetupConfigSnapshot['roles'] = rolesRoot
+    ? {
+        state: 'available',
+        orchestrator: roleSlot(rolesRoot.orchestrator),
+        executor: roleSlot(rolesRoot.executor),
+        reviewer: roleSlot(rolesRoot.reviewer),
+      }
+    : emptyRoles();
+
+  const preview = isRecord(value.executionPreview) ? value.executionPreview : null;
+  const compete = preview && isRecord(preview.compete) ? preview.compete : null;
+  let competition = emptyCompetition();
+  if (compete && !('error' in compete)) {
+    const sourcesRaw = isRecord(compete.sources) ? compete.sources : {};
+    const pickSource = (key: string): SetupConfigSource | undefined => {
+      const source = asSource(sourcesRaw[key]);
+      return source ?? undefined;
+    };
+    const variants = Array.isArray(compete.variants)
+      ? compete.variants
+          .filter((entry): entry is string => typeof entry === 'string' && entry.length > 0)
+          .slice(0, 100)
+      : [];
+    competition = {
+      state: 'available',
+      variants,
+      judge: typeof compete.judge === 'string' ? compete.judge : null,
+      judgeRun: typeof compete.judgeRun === 'string' ? compete.judgeRun : null,
+      judgePrimary: typeof compete.judgePrimary === 'string' ? compete.judgePrimary : null,
+      completionMode: typeof compete.completionMode === 'string' ? compete.completionMode : null,
+      synthesisStrategy:
+        typeof compete.synthesisStrategy === 'string' ? compete.synthesisStrategy : null,
+      timeoutMinutes:
+        typeof compete.timeout === 'number' && Number.isFinite(compete.timeout)
+          ? Math.trunc(compete.timeout)
+          : null,
+      requireMinVariants:
+        typeof compete.requireMinVariants === 'number' &&
+        Number.isFinite(compete.requireMinVariants)
+          ? Math.trunc(compete.requireMinVariants)
+          : null,
+      sources: {
+        ...(pickSource('variants') ? { variants: pickSource('variants') } : {}),
+        ...(pickSource('judge') ? { judge: pickSource('judge') } : {}),
+        ...(pickSource('judgeRun') ? { judgeRun: pickSource('judgeRun') } : {}),
+        ...(pickSource('judgePrimary') ? { judgePrimary: pickSource('judgePrimary') } : {}),
+        ...(pickSource('completionMode') ? { completionMode: pickSource('completionMode') } : {}),
+        ...(pickSource('synthesisStrategy')
+          ? { synthesisStrategy: pickSource('synthesisStrategy') }
+          : {}),
+        ...(pickSource('timeout') ? { timeout: pickSource('timeout') } : {}),
+        ...(pickSource('requireMinVariants')
+          ? { requireMinVariants: pickSource('requireMinVariants') }
+          : {}),
+      },
+    };
+  }
+
+  return { defaults, competition, roles };
+}
+
+function parseValidity(value: unknown, repository: Repository): SetupConfigSnapshot['validity'] {
+  if (repositoryUninitialized(repository)) {
+    return {
+      state: 'missing',
+      message: 'This repository is not an initialized Poetic project.',
+      errorCount: 0,
+      warningCount: 0,
+    };
+  }
+  if (!isRecord(value)) {
+    return {
+      state: 'unavailable',
+      message: 'Configuration validity could not be determined.',
+      errorCount: 0,
+      warningCount: 0,
+    };
+  }
+
+  const validation = isRecord(value.validation) ? value.validation : value;
+  const isValid = value.isValid === true || validation.isValid === true;
+  const errors = Array.isArray(validation.errors) ? validation.errors : [];
+  const warnings = Array.isArray(validation.warnings) ? validation.warnings : [];
+  const providerRegistryError =
+    typeof value.providerRegistryError === 'string' ? value.providerRegistryError : null;
+
+  if (isValid && !providerRegistryError) {
+    return {
+      state: 'valid',
+      message: 'Configuration is valid.',
+      errorCount: 0,
+      warningCount: warnings.length,
+    };
+  }
+
+  return {
+    state: 'invalid',
+    message: providerRegistryError
+      ? 'Configuration validation reported registry issues.'
+      : 'Configuration validation reported errors.',
+    errorCount: errors.length + (providerRegistryError ? 1 : 0),
+    warningCount: warnings.length,
+  };
+}
+
+function parseProviders(value: unknown): SetupConfigSnapshot['providers'] {
+  const list = Array.isArray(value)
+    ? value
+    : isRecord(value) && Array.isArray(value.providers)
+      ? value.providers
+      : null;
+  if (!list) return emptyProviders();
+
+  const items: SetupConfigSnapshot['providers']['items'] = [];
+  for (const entry of list.slice(0, 50)) {
+    if (!isRecord(entry)) continue;
+    const id =
+      typeof entry.provider === 'string'
+        ? entry.provider
+        : typeof entry.id === 'string'
+          ? entry.id
+          : null;
+    if (!id) continue;
+    const displayName =
+      typeof entry.displayName === 'string'
+        ? entry.displayName
+        : typeof entry.name === 'string'
+          ? entry.name
+          : id;
+    const installed = typeof entry.installed === 'boolean' ? entry.installed : null;
+    const ready = entry.ready === true;
+    const authRaw = entry.authenticated;
+    const auth: 'yes' | 'no' | 'unknown' =
+      authRaw === 'yes' || authRaw === 'no' ? authRaw : 'unknown';
+    const readinessStatus =
+      typeof entry.readinessStatus === 'string' ? entry.readinessStatus : null;
+    const readiness = mapProviderReadiness({
+      installed,
+      ready,
+      authenticated: auth,
+      readinessStatus,
+    });
+    const installation =
+      installed === true ? 'installed' : installed === false ? 'missing' : 'unknown';
+    const installGuidance =
+      typeof entry.installCommand === 'string' && entry.installCommand.length <= 500
+        ? entry.installCommand
+        : null;
+
+    items.push({
+      id,
+      displayName,
+      installation,
+      readiness,
+      auth,
+      installGuidance: installation === 'missing' ? installGuidance : null,
+    });
+  }
+
+  return {
+    state: 'available',
+    readyCount: items.filter((item) => item.readiness === 'ready').length,
+    items,
+  };
+}
+
+export class SetupConfigService {
+  constructor(private readonly run: SetupConfigRunner) {}
+
+  async read(repositoryValue: unknown): Promise<SetupConfigResult> {
+    const repository: Repository = repositorySchema.parse(repositoryValue);
+    const compatibility: SetupConfigSnapshot['compatibility'] = {
+      poeticVersion: repository.poeticVersion,
+      compatibility: repository.compatibility,
+      repositoryState: repository.state,
+    };
+
+    const runOnce = async (
+      command: SetupConfigCommand
+    ): Promise<
+      | { state: 'ok'; result: SetupConfigCommandResult }
+      | { state: 'timeout' }
+      | { state: 'missing-cli' }
+      | { state: 'command-failed' }
+    > => {
+      try {
+        const result = await this.run(command);
+        return { state: 'ok', result };
+      } catch (error) {
+        if (timeoutError(error)) return { state: 'timeout' };
+        if (missingCliError(error)) return { state: 'missing-cli' };
+        return { state: 'command-failed' };
+      }
+    };
+
+    const commandFor = (args: SetupConfigCommand['args']): SetupConfigCommand =>
+      ({
+        file: 'poetic',
+        args,
+        cwd: repository.path,
+        timeoutMs: SETUP_CONFIG_TIMEOUT_MS,
+        shell: false,
+      }) as SetupConfigCommand;
+
+    // Probe `--version` with the section reads so Settings stays fail-closed
+    // and current without a sequential wait. Inspect's memo is not evidence
+    // that the executable is still present or compatible.
+    const [versionRun, resolvedRun, validateRun, providersRun] = await Promise.all([
+      runOnce(commandFor(VERSION_ARGS)),
+      runOnce(commandFor(RESOLVED_ARGS)),
+      runOnce(commandFor(VALIDATE_ARGS)),
+      runOnce(commandFor(PROVIDERS_ARGS)),
+    ]);
+
+    if (
+      versionRun.state === 'missing-cli' ||
+      resolvedRun.state === 'missing-cli' ||
+      validateRun.state === 'missing-cli' ||
+      providersRun.state === 'missing-cli'
+    ) {
+      return unavailable(
+        'missing-cli',
+        'Poetic CLI is not available for this repository.',
+        compatibility
+      );
+    }
+    if (versionRun.state === 'timeout') {
+      return unavailable('timeout', 'Poetic version read timed out.', compatibility);
+    }
+    if (versionRun.state === 'command-failed') {
+      return unavailable('command-failed', 'Poetic version could not be read.', compatibility);
+    }
+
+    const versionFromCli = parseVersion(versionRun.result.stdout, versionRun.result.stderr);
+    const effectiveCompatibility: SetupConfigSnapshot['compatibility'] = {
+      ...compatibility,
+      poeticVersion: versionFromCli ?? compatibility.poeticVersion,
+    };
+
+    // One failed section read leaves that section unavailable; it does not
+    // blank the others or override a successful version probe.
+    let defaults = emptyDefaults();
+    let competition = emptyCompetition();
+    let roles = emptyRoles();
+    if (resolvedRun.state === 'ok') {
+      const parsed = parseJsonBounded(resolvedRun.result.stdout);
+      if (parsed.state === 'ok') {
+        const projected = parseDefaultsAndRoles(parsed.value);
+        defaults = projected.defaults;
+        competition = projected.competition;
+        roles = projected.roles;
+      }
+    }
+
+    let validity: SetupConfigSnapshot['validity'] = {
+      state: 'unavailable',
+      message: 'Configuration validity could not be determined.',
+      errorCount: 0,
+      warningCount: 0,
+    };
+    if (validateRun.state === 'ok') {
+      const parsed = parseJsonBounded(validateRun.result.stdout);
+      if (parsed.state === 'ok') {
+        validity = parseValidity(parsed.value, repository);
+      } else if (parsed.state === 'empty') {
+        validity = repositoryUninitialized(repository)
+          ? {
+              state: 'missing',
+              message: 'This repository is not an initialized Poetic project.',
+              errorCount: 0,
+              warningCount: 0,
+            }
+          : validity;
+      }
+    } else if (repositoryUninitialized(repository)) {
+      validity = {
+        state: 'missing',
+        message: 'This repository is not an initialized Poetic project.',
+        errorCount: 0,
+        warningCount: 0,
+      };
+    }
+
+    let providers = emptyProviders();
+    if (providersRun.state === 'ok') {
+      const parsed = parseJsonBounded(providersRun.result.stdout);
+      if (parsed.state === 'ok') {
+        providers = parseProviders(parsed.value);
+      }
+    }
+
+    // Overall unavailable only for hard blockers that prevent a useful workspace.
+    if (validity.state === 'missing' && defaults.state === 'unavailable') {
+      return unavailable(
+        'missing-config',
+        'Poetic configuration is missing for this repository.',
+        effectiveCompatibility
+      );
+    }
+    if (validity.state === 'invalid' && defaults.state === 'unavailable') {
+      return unavailable(
+        'invalid-config',
+        'Poetic configuration is invalid.',
+        effectiveCompatibility
+      );
+    }
+
+    const snapshot: SetupConfigSnapshot = {
+      compatibility: effectiveCompatibility,
+      validity,
+      defaults,
+      competition,
+      roles,
+      providers,
+      guidance: guidance(),
+    };
+
+    return { state: 'available', snapshot };
+  }
+}