@ankhorage/doctor 0.7.3 → 0.9.0

package/src/authReadinessAnalysis.ts

@@ -0,0 +1,50 @@
+import { analyzeAuthProviderReadiness } from './authReadinessProvider.js';
+import { resolveAuthReadinessTargets } from './authReadinessTargets.js';
+import type { DoctorDiagnostic } from './diagnostics.js';
+import type { DoctorReadiness } from './readiness.js';
+
+export interface DoctorAuthReadinessAnalysis {
+  readonly diagnostics: readonly DoctorDiagnostic[];
+  readonly readiness: readonly DoctorReadiness[];
+}
+
+export function analyzeAuthReadiness(
+  manifest: unknown,
+  manifestPath = 'manifest.json',
+): DoctorAuthReadinessAnalysis {
+  if (!isRecord(manifest)) return emptyAnalysis();
+
+  const infra = isRecord(manifest.infra) ? manifest.infra : null;
+  const auth = infra !== null && isRecord(infra.auth) ? infra.auth : null;
+  const oauth = auth !== null && isRecord(auth.oauth) ? auth.oauth : null;
+  if (oauth?.enabled !== true || !Array.isArray(oauth.providers)) return emptyAnalysis();
+
+  const targetResult = resolveAuthReadinessTargets(manifest.deploy, manifestPath);
+  const diagnostics = [...targetResult.diagnostics];
+  if (targetResult.targets === null) return { diagnostics, readiness: [] };
+
+  const readiness: DoctorReadiness[] = [];
+  for (const provider of oauth.providers) {
+    if (!isRecord(provider) || provider.enabled === false) continue;
+    const result = analyzeAuthProviderReadiness({
+      authProvider: auth?.provider,
+      callbackRoute: oauth.callbackRoute,
+      enabledTargets: targetResult.enabledTargets,
+      manifestPath,
+      provider,
+      targets: targetResult.targets,
+    });
+    diagnostics.push(...result.diagnostics);
+    readiness.push(...result.readiness);
+  }
+
+  return { diagnostics, readiness };
+}
+
+function emptyAnalysis(): DoctorAuthReadinessAnalysis {
+  return { diagnostics: [], readiness: [] };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/authReadinessDiagnostic.ts

@@ -0,0 +1,18 @@
+import type { DoctorDiagnostic } from './diagnostics.js';
+
+export function createAuthReadinessDiagnostic(input: {
+  readonly code: DoctorDiagnostic['code'];
+  readonly message: string;
+  readonly path: string;
+  readonly ruleId: DoctorDiagnostic['ruleId'];
+  readonly severity: DoctorDiagnostic['severity'];
+}): DoctorDiagnostic {
+  return {
+    code: input.code,
+    message: input.message,
+    path: input.path,
+    profile: 'app-manifest',
+    ruleId: input.ruleId,
+    severity: input.severity,
+  };
+}

package/src/authReadinessEnvironment.ts

@@ -0,0 +1,51 @@
+import type { AuthOAuthSetupPlan } from '@ankhorage/contracts/auth';
+import type {
+  AppDeployEnvironmentId,
+  AppDeployTargetId,
+  AppDeployTargets,
+} from '@ankhorage/contracts/deploy';
+
+import { collectMissingAuthReadinessRequirements } from './authReadinessRequirements.js';
+import type { DoctorReadiness } from './readiness.js';
+
+export function analyzeAuthReadinessEnvironment(input: {
+  readonly callbackRoute: unknown;
+  readonly credentialsRef: unknown;
+  readonly enabledTargets: readonly AppDeployTargetId[];
+  readonly environment: AppDeployEnvironmentId;
+  readonly plan: AuthOAuthSetupPlan;
+  readonly provider: string;
+  readonly targets: AppDeployTargets;
+}): {
+  readonly missingNativeTargets: readonly AppDeployTargetId[];
+  readonly readiness: readonly DoctorReadiness[];
+} {
+  const missingNativeTargets = new Set<AppDeployTargetId>();
+  const readiness = input.enabledTargets.map((target): DoctorReadiness => {
+    const missing = collectMissingAuthReadinessRequirements({
+      callbackRoute: input.callbackRoute,
+      credentialsRef: input.credentialsRef,
+      plan: input.plan,
+      target,
+      targets: input.targets,
+    });
+    if (target !== 'web' && missing.includes(`${target} deep-link scheme`)) {
+      missingNativeTargets.add(target);
+    }
+
+    return {
+      category: 'auth-oauth',
+      environment: input.environment,
+      message:
+        missing.length === 0
+          ? 'Manifest and adapter setup requirements are satisfiable; concrete callback URLs remain Infra/runtime-owned.'
+          : `Missing ${missing.join(' and ')}.`,
+      provider: input.provider,
+      status: missing.length === 0 ? 'ready' : 'missing',
+      target,
+      transport: 'brokeredRedirect',
+    };
+  });
+
+  return { missingNativeTargets: [...missingNativeTargets], readiness };
+}

package/src/authReadinessFileAnalysis.ts

@@ -0,0 +1,14 @@
+import { promises as fs } from 'node:fs';
+
+import { analyzeAuthReadiness, type DoctorAuthReadinessAnalysis } from './authReadinessAnalysis.js';
+
+export async function analyzeAuthReadinessFile(
+  filePath: string,
+): Promise<DoctorAuthReadinessAnalysis> {
+  try {
+    const manifest = JSON.parse(await fs.readFile(filePath, 'utf8')) as unknown;
+    return analyzeAuthReadiness(manifest, filePath);
+  } catch {
+    return { diagnostics: [], readiness: [] };
+  }
+}

package/src/authReadinessNativeDiagnostic.ts

@@ -0,0 +1,17 @@
+import type { AppDeployTargetId } from '@ankhorage/contracts/deploy';
+
+import { createAuthReadinessDiagnostic } from './authReadinessDiagnostic.js';
+import type { DoctorDiagnostic } from './diagnostics.js';
+
+export function createNativeAuthCallbackDiagnostic(
+  target: AppDeployTargetId,
+  path: string,
+): DoctorDiagnostic {
+  return createAuthReadinessDiagnostic({
+    code: 'field-missing',
+    message: `Enabled ${target} brokered OAuth requires deploy.targets.${target}.scheme for the app callback.`,
+    path,
+    ruleId: 'manifest.auth.oauth.callback-target.configured',
+    severity: 'error',
+  });
+}

package/src/authReadinessProvider.ts

@@ -0,0 +1,61 @@
+import type { AppDeployTargetId, AppDeployTargets } from '@ankhorage/contracts/deploy';
+import { APP_DEPLOY_ENVIRONMENT_IDS } from '@ankhorage/contracts/deploy';
+
+import { createNativeAuthCallbackDiagnostic } from './authReadinessNativeDiagnostic.js';
+import { analyzeAuthProviderEnvironment } from './authReadinessProviderEnvironment.js';
+import { createUnsupportedAuthDiagnostic } from './authReadinessUnsupported.js';
+import { analyzeUnsupportedAuthBackend } from './authReadinessUnsupportedBackend.js';
+import type { DoctorDiagnostic } from './diagnostics.js';
+import type { DoctorReadiness } from './readiness.js';
+
+export function analyzeAuthProviderReadiness(input: {
+  readonly authProvider: unknown;
+  readonly callbackRoute: unknown;
+  readonly enabledTargets: readonly AppDeployTargetId[];
+  readonly manifestPath: string;
+  readonly provider: Record<string, unknown>;
+  readonly targets: AppDeployTargets;
+}): { readonly diagnostics: DoctorDiagnostic[]; readonly readiness: DoctorReadiness[] } {
+  const providerId = typeof input.provider.id === 'string' ? input.provider.id : '';
+  if (providerId === '') return { diagnostics: [], readiness: [] };
+  if (input.authProvider !== 'supabase') {
+    const result = analyzeUnsupportedAuthBackend({
+      enabledTargets: input.enabledTargets,
+      manifestPath: input.manifestPath,
+      provider: providerId,
+    });
+    return { diagnostics: [...result.diagnostics], readiness: [...result.readiness] };
+  }
+
+  const diagnostics: DoctorDiagnostic[] = [];
+  const readiness: DoctorReadiness[] = [];
+  const missingNativeTargets = new Set<AppDeployTargetId>();
+  let unsupported = false;
+
+  for (const environment of APP_DEPLOY_ENVIRONMENT_IDS) {
+    const result = analyzeAuthProviderEnvironment({
+      callbackRoute: input.callbackRoute,
+      credentialsRef: input.provider.credentialsRef,
+      enabledTargets: input.enabledTargets,
+      environment,
+      provider: providerId,
+      targets: input.targets,
+    });
+    readiness.push(...result.readiness);
+    unsupported ||= result.unsupported;
+    result.missingNativeTargets.forEach((target) => missingNativeTargets.add(target));
+  }
+
+  if (unsupported) {
+    diagnostics.push(
+      createUnsupportedAuthDiagnostic({
+        message: `OAuth provider "${providerId}" is not supported by the Supabase brokeredRedirect setup resolver.`,
+        path: input.manifestPath,
+      }),
+    );
+  }
+  missingNativeTargets.forEach((target) =>
+    diagnostics.push(createNativeAuthCallbackDiagnostic(target, input.manifestPath)),
+  );
+  return { diagnostics, readiness };
+}

package/src/authReadinessProviderEnvironment.ts

@@ -0,0 +1,54 @@
+import type {
+  AppDeployEnvironmentId,
+  AppDeployTargetId,
+  AppDeployTargets,
+} from '@ankhorage/contracts/deploy';
+import { resolveSupabaseOAuthSetupPlan } from '@ankhorage/supabase-auth';
+
+import { analyzeAuthReadinessEnvironment } from './authReadinessEnvironment.js';
+import { createUnsupportedAuthReadiness } from './authReadinessUnsupported.js';
+import type { DoctorReadiness } from './readiness.js';
+
+export function analyzeAuthProviderEnvironment(input: {
+  readonly callbackRoute: unknown;
+  readonly credentialsRef: unknown;
+  readonly enabledTargets: readonly AppDeployTargetId[];
+  readonly environment: AppDeployEnvironmentId;
+  readonly provider: string;
+  readonly targets: AppDeployTargets;
+}): {
+  readonly missingNativeTargets: readonly AppDeployTargetId[];
+  readonly readiness: readonly DoctorReadiness[];
+  readonly unsupported: boolean;
+} {
+  const plan = resolveSupabaseOAuthSetupPlan({
+    provider: input.provider,
+    transport: 'brokeredRedirect',
+    environment: input.environment,
+    targets: input.enabledTargets,
+  });
+  if (plan === null) {
+    return {
+      missingNativeTargets: [],
+      readiness: createUnsupportedAuthReadiness({
+        environment: input.environment,
+        provider: input.provider,
+        targets: input.enabledTargets,
+      }),
+      unsupported: true,
+    };
+  }
+
+  return {
+    ...analyzeAuthReadinessEnvironment({
+      callbackRoute: input.callbackRoute,
+      credentialsRef: input.credentialsRef,
+      enabledTargets: input.enabledTargets,
+      environment: input.environment,
+      plan,
+      provider: input.provider,
+      targets: input.targets,
+    }),
+    unsupported: false,
+  };
+}

package/src/authReadinessRequirements.ts

@@ -0,0 +1,50 @@
+import type { AuthOAuthSetupPlan } from '@ankhorage/contracts/auth';
+import type { AppDeployTargetId, AppDeployTargets } from '@ankhorage/contracts/deploy';
+import { normalizeSecretRef } from '@ankhorage/contracts/secrets';
+
+export function collectMissingAuthReadinessRequirements(input: {
+  readonly callbackRoute: unknown;
+  readonly credentialsRef: unknown;
+  readonly plan: AuthOAuthSetupPlan;
+  readonly target: AppDeployTargetId;
+  readonly targets: AppDeployTargets;
+}): readonly string[] {
+  const missing: string[] = [];
+  if (requiresTrustedCredential(input.plan) && !hasCanonicalCredentialRef(input.credentialsRef)) {
+    missing.push('credential reference');
+  }
+
+  const callbackRequired = input.plan.requirements.some(
+    (requirement) =>
+      requirement.kind === 'callback' &&
+      requirement.role === 'app' &&
+      requirement.required &&
+      requirement.target === input.target,
+  );
+  if (!callbackRequired) return missing;
+
+  if (!isAbsoluteRoute(input.callbackRoute)) missing.push('callback route');
+  if (input.target !== 'web' && input.targets[input.target]?.scheme === undefined) {
+    missing.push(`${input.target} deep-link scheme`);
+  }
+  return missing;
+}
+
+function requiresTrustedCredential(plan: AuthOAuthSetupPlan): boolean {
+  return plan.requirements.some(
+    (requirement) =>
+      requirement.kind === 'field' &&
+      requirement.required &&
+      requirement.persistence === 'trustedCredential',
+  );
+}
+
+function hasCanonicalCredentialRef(value: unknown): boolean {
+  if (typeof value !== 'string') return false;
+  const result = normalizeSecretRef(value);
+  return result.ok && result.data === value;
+}
+
+function isAbsoluteRoute(value: unknown): boolean {
+  return typeof value === 'string' && value.trim().startsWith('/') && value.trim().length > 0;
+}

package/src/authReadinessTargetFallback.ts

@@ -0,0 +1,38 @@
+import { createAuthReadinessDiagnostic } from './authReadinessDiagnostic.js';
+import type { AuthReadinessTargetResolution } from './authReadinessTargetResolution.js';
+
+export function resolveAuthReadinessTargetFallback(
+  deploy: unknown,
+  manifestPath: string,
+): AuthReadinessTargetResolution {
+  if (deploy === undefined) {
+    return {
+      diagnostics: [
+        createAuthReadinessDiagnostic({
+          code: 'field-missing',
+          message:
+            'deploy.targets is missing; Doctor evaluates legacy Web-only readiness until canonical targets are persisted.',
+          path: manifestPath,
+          ruleId: 'manifest.deploy.targets.legacy-web',
+          severity: 'warning',
+        }),
+      ],
+      enabledTargets: ['web'],
+      targets: { web: { enabled: true } },
+    };
+  }
+
+  return {
+    diagnostics: [
+      createAuthReadinessDiagnostic({
+        code: 'field-invalid',
+        message: 'manifest.deploy must match the canonical Contracts deploy target model.',
+        path: manifestPath,
+        ruleId: 'manifest.deploy.valid-shape',
+        severity: 'error',
+      }),
+    ],
+    enabledTargets: [],
+    targets: null,
+  };
+}

package/src/authReadinessTargetResolution.ts

@@ -0,0 +1,9 @@
+import type { AppDeployTargetId, AppDeployTargets } from '@ankhorage/contracts/deploy';
+
+import type { DoctorDiagnostic } from './diagnostics.js';
+
+export interface AuthReadinessTargetResolution {
+  readonly diagnostics: readonly DoctorDiagnostic[];
+  readonly enabledTargets: readonly AppDeployTargetId[];
+  readonly targets: AppDeployTargets | null;
+}

package/src/authReadinessTargets.ts

@@ -0,0 +1,35 @@
+import { APP_DEPLOY_TARGET_IDS, isAppDeployManifest } from '@ankhorage/contracts/deploy';
+
+import { createAuthReadinessDiagnostic } from './authReadinessDiagnostic.js';
+import { resolveAuthReadinessTargetFallback } from './authReadinessTargetFallback.js';
+import type { AuthReadinessTargetResolution } from './authReadinessTargetResolution.js';
+
+export function resolveAuthReadinessTargets(
+  deploy: unknown,
+  manifestPath: string,
+): AuthReadinessTargetResolution {
+  if (!isAppDeployManifest(deploy)) {
+    return resolveAuthReadinessTargetFallback(deploy, manifestPath);
+  }
+
+  const enabledTargets = APP_DEPLOY_TARGET_IDS.filter(
+    (target) => deploy.targets[target]?.enabled === true,
+  );
+  if (enabledTargets.length > 0) {
+    return { diagnostics: [], enabledTargets, targets: deploy.targets };
+  }
+
+  return {
+    diagnostics: [
+      createAuthReadinessDiagnostic({
+        code: 'field-missing',
+        message: 'manifest.deploy.targets must enable at least one application target.',
+        path: manifestPath,
+        ruleId: 'manifest.deploy.targets.enabled',
+        severity: 'error',
+      }),
+    ],
+    enabledTargets,
+    targets: deploy.targets,
+  };
+}

package/src/authReadinessUnsupported.ts

@@ -0,0 +1,34 @@
+import type { AppDeployEnvironmentId, AppDeployTargetId } from '@ankhorage/contracts/deploy';
+
+import { createAuthReadinessDiagnostic } from './authReadinessDiagnostic.js';
+import type { DoctorDiagnostic } from './diagnostics.js';
+import type { DoctorReadiness } from './readiness.js';
+
+export function createUnsupportedAuthReadiness(input: {
+  readonly environment: AppDeployEnvironmentId;
+  readonly provider: string;
+  readonly targets: readonly AppDeployTargetId[];
+}): DoctorReadiness[] {
+  return input.targets.map((target) => ({
+    category: 'auth-oauth',
+    environment: input.environment,
+    message: 'The selected backend/provider/transport combination has no setup capability.',
+    provider: input.provider,
+    status: 'unsupported',
+    target,
+    transport: 'brokeredRedirect',
+  }));
+}
+
+export function createUnsupportedAuthDiagnostic(input: {
+  readonly message: string;
+  readonly path: string;
+}): DoctorDiagnostic {
+  return createAuthReadinessDiagnostic({
+    code: 'field-invalid',
+    message: input.message,
+    path: input.path,
+    ruleId: 'manifest.auth.oauth.setup.supported',
+    severity: 'error',
+  });
+}

package/src/authReadinessUnsupportedBackend.ts

@@ -0,0 +1,34 @@
+import type { AppDeployTargetId } from '@ankhorage/contracts/deploy';
+import { APP_DEPLOY_ENVIRONMENT_IDS } from '@ankhorage/contracts/deploy';
+
+import {
+  createUnsupportedAuthDiagnostic,
+  createUnsupportedAuthReadiness,
+} from './authReadinessUnsupported.js';
+import type { DoctorDiagnostic } from './diagnostics.js';
+import type { DoctorReadiness } from './readiness.js';
+
+export function analyzeUnsupportedAuthBackend(input: {
+  readonly enabledTargets: readonly AppDeployTargetId[];
+  readonly manifestPath: string;
+  readonly provider: string;
+}): {
+  readonly diagnostics: readonly DoctorDiagnostic[];
+  readonly readiness: readonly DoctorReadiness[];
+} {
+  return {
+    diagnostics: [
+      createUnsupportedAuthDiagnostic({
+        message: 'Configured OAuth backend has no Doctor setup resolver.',
+        path: input.manifestPath,
+      }),
+    ],
+    readiness: APP_DEPLOY_ENVIRONMENT_IDS.flatMap((environment) =>
+      createUnsupportedAuthReadiness({
+        environment,
+        provider: input.provider,
+        targets: input.enabledTargets,
+      }),
+    ),
+  };
+}