@pellux/goodvibes-tui 0.19.24 → 0.19.26

package/src/runtime/onboarding/snapshot.ts

@@ -0,0 +1,400 @@
+import type { SecretStorageReview } from '../../config/secrets.ts';
+import type { LocalAuthSnapshot } from '@pellux/goodvibes-sdk/platform/security/user-auth';
+import { readOnboardingRuntimeState } from './state.ts';
+import type {
+  OnboardingAcknowledgementSnapshot,
+  OnboardingConfigSnapshot,
+  OnboardingProviderRoutingSnapshot,
+  OnboardingRuntimeDefaultsSnapshot,
+  OnboardingServiceState,
+  OnboardingSnapshotCollectionIssue,
+  OnboardingSnapshotCollectionIssueArea,
+  OnboardingSnapshotDependencies,
+  OnboardingSnapshotState,
+  OnboardingSurfaceRecord,
+} from './types.ts';
+
+function sortUnique(values: readonly string[]): string[] {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function buildConfigSnapshot(
+  config: OnboardingSnapshotDependencies['config'],
+): OnboardingConfigSnapshot {
+  return {
+    display: config.getCategory('display'),
+    provider: config.getCategory('provider'),
+    behavior: config.getCategory('behavior'),
+    storage: config.getCategory('storage'),
+    permissions: config.getCategory('permissions'),
+    helper: config.getCategory('helper'),
+    tools: {
+      llmEnabled: config.get('tools.llmEnabled'),
+      llmProvider: config.get('tools.llmProvider'),
+      llmModel: config.get('tools.llmModel'),
+    },
+    danger: config.getCategory('danger'),
+    controlPlane: config.getCategory('controlPlane'),
+    httpListener: config.getCategory('httpListener'),
+    web: config.getCategory('web'),
+    network: config.getCategory('network'),
+    surfaces: config.getCategory('surfaces'),
+    service: config.getCategory('service'),
+  };
+}
+
+function buildProviderRoutingSnapshot(
+  config: OnboardingConfigSnapshot,
+): OnboardingProviderRoutingSnapshot {
+  return {
+    primaryProviderId: config.provider.provider,
+    primaryModelId: config.provider.model,
+    primaryReasoningEffort: config.provider.reasoningEffort,
+    embeddingProviderId: config.provider.embeddingProvider,
+    systemPromptFile: config.provider.systemPromptFile,
+    helperEnabled: config.helper.enabled,
+    helperProviderId: config.helper.globalProvider,
+    helperModelId: config.helper.globalModel,
+    toolLlmEnabled: config.tools.llmEnabled,
+    toolProviderId: config.tools.llmProvider,
+    toolModelId: config.tools.llmModel,
+  };
+}
+
+function buildRuntimeDefaultsSnapshot(
+  config: OnboardingConfigSnapshot,
+): OnboardingRuntimeDefaultsSnapshot {
+  return {
+    providerReasoningEffort: config.provider.reasoningEffort,
+    permissionsMode: config.permissions.mode,
+    behavior: config.behavior,
+    display: config.display,
+    secretStoragePolicy: config.storage.secretPolicy,
+  };
+}
+
+async function buildServicesSnapshot(
+  services: OnboardingSnapshotDependencies['services'],
+): Promise<{
+  snapshot: {
+    total: number;
+    oauthProviderIds: readonly string[];
+    services: readonly OnboardingServiceState[];
+  };
+  issues: readonly OnboardingSnapshotCollectionIssue[];
+}> {
+  let configs: ReturnType<OnboardingSnapshotDependencies['services']['getAll']>;
+  try {
+    configs = services.getAll();
+  } catch (error) {
+    return {
+      snapshot: {
+        total: 0,
+        oauthProviderIds: [],
+        services: [],
+      },
+      issues: [
+        {
+          area: 'services',
+          message: error instanceof Error ? error.message : String(error),
+        },
+      ],
+    };
+  }
+
+  const names = Object.keys(configs).sort((left, right) => left.localeCompare(right));
+  const entryResults = await Promise.all(names.map(async (name) => {
+    const config = configs[name]!;
+    try {
+      const inspection = await services.inspect(name);
+
+      return {
+        entry: {
+          name,
+          providerId: config.providerId ?? config.name,
+          baseUrl: config.baseUrl ?? null,
+          authType: config.authType,
+          tokenKey: config.tokenKey,
+          oauthConfigured: Boolean(config.oauth),
+          hasPrimaryCredential: inspection?.hasPrimaryCredential ?? false,
+          hasPasswordCredential: inspection?.hasPasswordCredential ?? false,
+          hasWebhookUrl: inspection?.hasWebhookUrl ?? false,
+          hasSigningSecret: inspection?.hasSigningSecret ?? false,
+          hasPublicKey: inspection?.hasPublicKey ?? false,
+        } satisfies OnboardingServiceState,
+        issue: null,
+      };
+    } catch (error) {
+      return {
+        entry: {
+          name,
+          providerId: config.providerId ?? config.name,
+          baseUrl: config.baseUrl ?? null,
+          authType: config.authType,
+          tokenKey: config.tokenKey,
+          oauthConfigured: Boolean(config.oauth),
+          hasPrimaryCredential: false,
+          hasPasswordCredential: false,
+          hasWebhookUrl: false,
+          hasSigningSecret: false,
+          hasPublicKey: false,
+        } satisfies OnboardingServiceState,
+        issue: {
+          area: 'services',
+          message: `${name}: ${error instanceof Error ? error.message : String(error)}`,
+        } satisfies OnboardingSnapshotCollectionIssue,
+      };
+    }
+  }));
+
+  const entries = entryResults.map((result) => result.entry);
+  const issues: OnboardingSnapshotCollectionIssue[] = [];
+  for (const result of entryResults) {
+    if (result.issue) issues.push(result.issue);
+  }
+
+  return {
+    snapshot: {
+      total: entries.length,
+      oauthProviderIds: sortUnique(entries.filter((entry) => entry.oauthConfigured).map((entry) => entry.providerId)),
+      services: entries,
+    },
+    issues,
+  };
+}
+
+function buildFallbackSecretReview(
+  config: OnboardingConfigSnapshot,
+): SecretStorageReview {
+  return {
+    policy: config.storage.secretPolicy,
+    secureAvailable: false,
+    storedKeys: 0,
+    envBackedKeys: 0,
+    secureKeys: 0,
+    plaintextKeys: 0,
+    warnings: [],
+    locations: [],
+  };
+}
+
+function buildFallbackAuthSnapshot(): LocalAuthSnapshot {
+  return {
+    userStorePath: '',
+    bootstrapCredentialPath: '',
+    persisted: false,
+    bootstrapCredentialPresent: false,
+    userCount: 0,
+    sessionCount: 0,
+    users: [],
+    sessions: [],
+  };
+}
+
+function buildConfiguredSurfaceKinds(
+  surfaces: OnboardingConfigSnapshot['surfaces'],
+): string[] {
+  const enabledKinds: string[] = [];
+
+  for (const [kind, value] of Object.entries(surfaces)) {
+    if (!value || typeof value !== 'object') continue;
+    if ('enabled' in value && value.enabled === true) enabledKinds.push(kind);
+  }
+
+  return enabledKinds.sort((left, right) => left.localeCompare(right));
+}
+
+function sortSurfaceRecords(
+  records: readonly OnboardingSurfaceRecord[],
+): OnboardingSurfaceRecord[] {
+  return [...records].sort((left, right) => {
+    const kindOrder = left.kind.localeCompare(right.kind);
+    if (kindOrder !== 0) return kindOrder;
+
+    const labelOrder = left.label.localeCompare(right.label);
+    if (labelOrder !== 0) return labelOrder;
+
+    return left.id.localeCompare(right.id);
+  });
+}
+
+async function loadOptionalSnapshot<T>(
+  area: OnboardingSnapshotCollectionIssueArea,
+  loader: (() => Promise<T>) | undefined,
+  fallback: T,
+): Promise<{
+  value: T;
+  issue: OnboardingSnapshotCollectionIssue | null;
+}> {
+  if (!loader) return { value: fallback, issue: null };
+
+  try {
+    return {
+      value: await loader(),
+      issue: null,
+    };
+  } catch (error) {
+    return {
+      value: fallback,
+      issue: {
+        area,
+        message: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+}
+
+function buildAcknowledgementSnapshot(
+  deps: OnboardingSnapshotDependencies,
+): {
+  snapshot: OnboardingAcknowledgementSnapshot;
+  issue: OnboardingSnapshotCollectionIssue | null;
+} {
+  const scope = deps.acknowledgementScope ?? 'project';
+  if (!deps.shellPaths) {
+    return {
+      snapshot: {
+        scope,
+        exists: false,
+        updatedAt: null,
+        source: null,
+        accepted: {},
+      },
+      issue: null,
+    };
+  }
+
+  const state = readOnboardingRuntimeState(deps.shellPaths, scope);
+  if (state.parseError) {
+    return {
+      snapshot: {
+        scope,
+        exists: true,
+        updatedAt: null,
+        source: null,
+        accepted: {},
+      },
+      issue: {
+        area: 'acknowledgements',
+        message: state.parseError,
+      },
+    };
+  }
+
+  return {
+    snapshot: {
+      scope,
+      exists: state.exists,
+      updatedAt: state.payload?.updatedAt ?? null,
+      source: state.payload?.source ?? null,
+      ...(state.payload?.mode ? { mode: state.payload.mode } : {}),
+      ...(state.payload?.workspaceRoot ? { workspaceRoot: state.payload.workspaceRoot } : {}),
+      accepted: state.payload?.acknowledgements ?? {},
+    },
+    issue: null,
+  };
+}
+
+export async function collectOnboardingSnapshot(
+  deps: OnboardingSnapshotDependencies,
+): Promise<OnboardingSnapshotState> {
+  const capturedAt = deps.clock?.() ?? Date.now();
+  const config = buildConfigSnapshot(deps.config);
+  const providerRouting = buildProviderRoutingSnapshot(config);
+  const runtimeDefaults = buildRuntimeDefaultsSnapshot(config);
+  const acknowledgementResult = buildAcknowledgementSnapshot(deps);
+
+  const [
+    subscriptionsActiveResult,
+    subscriptionsPendingResult,
+    authSnapshotResult,
+    servicesResult,
+    secretReviewResult,
+    secretRecordsResult,
+    surfaceResult,
+    providerAccountsResult,
+  ] = await Promise.all([
+    loadOptionalSnapshot(
+      'subscriptions-active',
+      () => Promise.resolve(deps.subscriptions.list()),
+      [] as ReturnType<OnboardingSnapshotDependencies['subscriptions']['list']>,
+    ),
+    loadOptionalSnapshot(
+      'subscriptions-pending',
+      () => Promise.resolve(deps.subscriptions.listPending()),
+      [] as ReturnType<OnboardingSnapshotDependencies['subscriptions']['listPending']>,
+    ),
+    loadOptionalSnapshot(
+      'auth',
+      () => Promise.resolve(deps.auth.inspect()),
+      buildFallbackAuthSnapshot(),
+    ),
+    buildServicesSnapshot(deps.services),
+    loadOptionalSnapshot(
+      'secrets-review',
+      () => deps.secrets.inspect(),
+      buildFallbackSecretReview(config),
+    ),
+    loadOptionalSnapshot(
+      'secrets-records',
+      () => deps.secrets.listDetailed(),
+      [] as const,
+    ),
+    loadOptionalSnapshot(
+      'surfaces',
+      deps.surfaces ? () => Promise.resolve(deps.surfaces!.list()) : undefined,
+      [] as readonly OnboardingSurfaceRecord[],
+    ),
+    loadOptionalSnapshot(
+      'provider-accounts',
+      deps.providerAccounts ? () => deps.providerAccounts!.loadSnapshot() : undefined,
+      null,
+    ),
+  ]);
+
+  const collectionIssues: OnboardingSnapshotCollectionIssue[] = [];
+  if (acknowledgementResult.issue) collectionIssues.push(acknowledgementResult.issue);
+  collectionIssues.push(...servicesResult.issues);
+  if (subscriptionsActiveResult.issue) collectionIssues.push(subscriptionsActiveResult.issue);
+  if (subscriptionsPendingResult.issue) collectionIssues.push(subscriptionsPendingResult.issue);
+  if (authSnapshotResult.issue) collectionIssues.push(authSnapshotResult.issue);
+  if (secretReviewResult.issue) collectionIssues.push(secretReviewResult.issue);
+  if (secretRecordsResult.issue) collectionIssues.push(secretRecordsResult.issue);
+  if (surfaceResult.issue) collectionIssues.push(surfaceResult.issue);
+  if (providerAccountsResult.issue) collectionIssues.push(providerAccountsResult.issue);
+
+  return {
+    capturedAt,
+    config,
+    providerRouting,
+    runtimeDefaults,
+    acknowledgements: acknowledgementResult.snapshot,
+    services: servicesResult.snapshot,
+    subscriptions: {
+      active: subscriptionsActiveResult.value,
+      pending: subscriptionsPendingResult.value,
+      activeProviderIds: sortUnique(subscriptionsActiveResult.value.map((entry) => entry.provider)),
+      pendingProviderIds: sortUnique(subscriptionsPendingResult.value.map((entry) => entry.provider)),
+    },
+    secrets: {
+      review: secretReviewResult.value,
+      records: secretRecordsResult.value,
+    },
+    auth: {
+      snapshot: authSnapshotResult.value,
+    },
+    bindSettings: {
+      daemonEnabled: Boolean(config.danger.daemon),
+      httpListenerEnabled: Boolean(config.danger.httpListener),
+      controlPlane: config.controlPlane,
+      httpListener: config.httpListener,
+      web: config.web,
+    },
+    surfaces: {
+      configuredEnabledKinds: buildConfiguredSurfaceKinds(config.surfaces),
+      records: sortSurfaceRecords(surfaceResult.value),
+    },
+    providerAccounts: providerAccountsResult.value,
+    collectionIssues,
+  };
+}

package/src/runtime/onboarding/state.ts

@@ -0,0 +1,140 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type {
+  OnboardingAcknowledgementRuntimeState,
+  OnboardingAcknowledgementTarget,
+  OnboardingCompletionMarkerScope,
+  OnboardingMode,
+  OnboardingShellPaths,
+} from './types.ts';
+
+const ONBOARDING_RUNTIME_STATE_FILE = 'onboarding-state.json';
+
+export interface OnboardingRuntimeStateRecord {
+  readonly scope: OnboardingCompletionMarkerScope;
+  readonly path: string;
+  readonly exists: boolean;
+  readonly payload: OnboardingAcknowledgementRuntimeState | null;
+  readonly parseError?: string;
+}
+
+interface WriteOnboardingAcknowledgementStateOptions {
+  readonly scope?: OnboardingCompletionMarkerScope;
+  readonly target: OnboardingAcknowledgementTarget;
+  readonly acknowledged: boolean;
+  readonly updatedAt?: number;
+  readonly source: string;
+  readonly mode?: OnboardingMode;
+  readonly workspaceRoot?: string;
+}
+
+function resolveStatePath(
+  shellPaths: OnboardingShellPaths,
+  scope: OnboardingCompletionMarkerScope,
+): string {
+  return scope === 'project'
+    ? shellPaths.resolveProjectPath('tui', ONBOARDING_RUNTIME_STATE_FILE)
+    : shellPaths.resolveUserPath('tui', ONBOARDING_RUNTIME_STATE_FILE);
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function isOnboardingMode(value: unknown): value is OnboardingAcknowledgementRuntimeState['mode'] {
+  return value === 'new' || value === 'edit' || value === 'reopen';
+}
+
+function isAcknowledgementTarget(value: string): value is OnboardingAcknowledgementTarget {
+  return value === 'providers' || value === 'subscriptions' || value === 'auth';
+}
+
+function isRuntimeStatePayload(value: unknown): value is OnboardingAcknowledgementRuntimeState {
+  if (!isObject(value)) return false;
+  if (value.version !== 1) return false;
+  if (typeof value.updatedAt !== 'number' || !Number.isFinite(value.updatedAt)) return false;
+  if (typeof value.source !== 'string') return false;
+  if (value.mode !== undefined && !isOnboardingMode(value.mode)) return false;
+  if (value.workspaceRoot !== undefined && typeof value.workspaceRoot !== 'string') return false;
+  if (!isObject(value.acknowledgements)) return false;
+
+  return Object.entries(value.acknowledgements).every(([key, entry]) => isAcknowledgementTarget(key) && typeof entry === 'boolean');
+}
+
+export function getOnboardingRuntimeStatePath(
+  shellPaths: OnboardingShellPaths,
+  scope: OnboardingCompletionMarkerScope = 'project',
+): string {
+  return resolveStatePath(shellPaths, scope);
+}
+
+export function readOnboardingRuntimeState(
+  shellPaths: OnboardingShellPaths,
+  scope: OnboardingCompletionMarkerScope = 'project',
+): OnboardingRuntimeStateRecord {
+  const path = resolveStatePath(shellPaths, scope);
+  if (!existsSync(path)) {
+    return {
+      scope,
+      path,
+      exists: false,
+      payload: null,
+    };
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown;
+    if (!isRuntimeStatePayload(parsed)) {
+      return {
+        scope,
+        path,
+        exists: true,
+        payload: null,
+        parseError: 'Invalid onboarding runtime state payload.',
+      };
+    }
+
+    return {
+      scope,
+      path,
+      exists: true,
+      payload: parsed,
+    };
+  } catch (error) {
+    return {
+      scope,
+      path,
+      exists: true,
+      payload: null,
+      parseError: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export function writeOnboardingAcknowledgementState(
+  shellPaths: OnboardingShellPaths,
+  options: WriteOnboardingAcknowledgementStateOptions,
+): OnboardingRuntimeStateRecord {
+  const scope = options.scope ?? 'project';
+  const path = resolveStatePath(shellPaths, scope);
+  const existing = readOnboardingRuntimeState(shellPaths, scope);
+  const updatedAt = options.updatedAt ?? Date.now();
+  const payload: OnboardingAcknowledgementRuntimeState = {
+    version: 1,
+    updatedAt,
+    source: options.source,
+    ...(options.mode ? { mode: options.mode } : {}),
+    ...(options.workspaceRoot ?? shellPaths.workingDirectory
+      ? { workspaceRoot: options.workspaceRoot ?? shellPaths.workingDirectory }
+      : {}),
+    acknowledgements: {
+      ...(existing.payload?.acknowledgements ?? {}),
+      [options.target]: options.acknowledged,
+    },
+  };
+
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+
+  return readOnboardingRuntimeState(shellPaths, scope);
+}