@topolo/sdk 0.7.0 → 0.8.1

package/src/application-requirements.ts

@@ -1,517 +0,0 @@
-import {
-  APPLICATIONS,
-  type ApplicationCatalogEntry,
-  type ApplicationId,
-} from './applications.generated.js';
-
-export const APPLICATION_REQUIREMENTS_VERSION = '2026-06-07.1';
-
-export type ApplicationRequirementScope =
-  | 'all'
-  | 'browser'
-  | 'api'
-  | 'tooling'
-  | 'agent_surface';
-
-export interface ApplicationRequirement {
-  id: string;
-  title: string;
-  summary: string;
-  appliesTo: readonly ApplicationRequirementScope[];
-  evidence: readonly string[];
-  implementation: readonly string[];
-}
-
-export type ApplicationRequirementStatus = 'met' | 'partial' | 'missing' | 'needs_review';
-
-export interface ApplicationRequirementFinding {
-  requirementId: string;
-  title: string;
-  status: ApplicationRequirementStatus;
-  reason: string;
-  evidence: readonly string[];
-  nextActions: readonly string[];
-}
-
-export interface ApplicationRequirementScore {
-  met: number;
-  partial: number;
-  missing: number;
-  needsReview: number;
-  total: number;
-  percent: number;
-}
-
-export interface ApplicationRequirementAudit {
-  version: string;
-  application: ApplicationCatalogEntry;
-  scopes: ApplicationRequirementScope[];
-  score: ApplicationRequirementScore;
-  findings: ApplicationRequirementFinding[];
-}
-
-export interface ApplicationRequirementMigrationItem {
-  applicationId: ApplicationId;
-  applicationName: string;
-  requirementId: string;
-  title: string;
-  status: Exclude<ApplicationRequirementStatus, 'met'>;
-  reason: string;
-  nextActions: readonly string[];
-}
-
-export interface ApplicationRequirementsAuditReport {
-  version: string;
-  applications: ApplicationRequirementAudit[];
-  migrationQueue: ApplicationRequirementMigrationItem[];
-}
-
-export const APPLICATION_REQUIREMENTS = [
-  {
-    id: 'platform-metadata',
-    title: 'Register the application in platform metadata',
-    summary:
-      'Every app must have a stable application ID, CloudControl metadata for deployed surfaces, and package metadata where code is shipped.',
-    appliesTo: ['all'],
-    evidence: [
-      'topolo.cloudcontrol.json exists for every deployed app surface',
-      'package.json names the package or app when the repo ships code',
-      'The SDK application catalog exposes the app through topolo apps and MCP discovery',
-    ],
-    implementation: [
-      'Add the app to the SDK application catalog generator before exposing it to agents',
-      'Keep production URLs, Worker names, Pages projects, routes, domains, and bindings current in CloudControl metadata',
-      'Do not leave a new Topolo* app directory without an explicit application ID',
-    ],
-  },
-  {
-    id: 'canonical-docs',
-    title: 'Update canonical docs with the code change',
-    summary:
-      'TopoloDocs is the source of truth for application behavior, ownership, deployment shape, auth boundaries, and operations.',
-    appliesTo: ['all'],
-    evidence: [
-      'Matching system registry entry exists in TopoloDocs',
-      'Internal handbook coverage exists for the system',
-      'npm run validate passes in TopoloDocs when docs are touched',
-    ],
-    implementation: [
-      'Read the matching TopoloDocs system entry before coding',
-      'Update docs in the same change when behavior, API, auth, data ownership, deployment, or operations change',
-      'Update last_verified dates on touched canonical pages',
-    ],
-  },
-  {
-    id: 'shared-auth-boundary',
-    title: 'Use the shared Topolo auth boundary',
-    summary:
-      'Applications must derive identity, organization, scopes, and app entitlement from TopoloAuth rather than inventing parallel auth state.',
-    appliesTo: ['browser', 'api', 'tooling', 'agent_surface'],
-    evidence: [
-      '@topolo/auth-client or @topolo-io/worker-runtime is used where applicable',
-      'No public command, tool, or SDK method accepts orgId',
-      'App slug and Auth app registration are documented for protected APIs',
-    ],
-    implementation: [
-      'Use shared auth/runtime packages instead of copying token parsing, gateway, or browser storage flows',
-      'Derive organization from the credential on every request',
-      'Route OAuth, refresh, logout, and SSO paths according to the shared Auth contract',
-    ],
-  },
-  {
-    id: 'shared-shell-and-launcher',
-    title: 'Use the shared shell, launcher, and account menu',
-    summary:
-      'Browser applications should feel like one platform and should not create isolated navigation or account surfaces.',
-    appliesTo: ['browser'],
-    evidence: [
-      '@topolo-io/app-shell is used for the platform shell where the app has authenticated UI',
-      '@topolo-io/app-launcher keeps the shared launcher/app switcher reachable from authenticated app chrome',
-      'Account menu and sign-out behavior use TopoloAppShell or the ui-kit TopoloAccountMenu primitive',
-      'Repeated app body surfaces use shared TopoloAppLayout primitives instead of local stat cards, empty states, or status badges',
-      'Local preview supports deterministic visual QA fixtures for overview, list, detail, settings, and empty/loading states',
-      'Authenticated app body content stays inside the viewport on mobile and desktop widths',
-    ],
-    implementation: [
-      'Use @topolo-io/app-shell TopoloAppShell for authenticated app layouts',
-      'Use the @topolo-io/ui-kit TopoloAccountMenu primitive when a partial-shell surface still needs account chrome',
-      'Pass app-specific account actions as additive menu items instead of forking dropdowns',
-      'Use shared design tokens and platform UI primitives before creating local equivalents',
-      'Use TopoloAppMetricCard, TopoloAppEmptyState, TopoloAppStatusBadge, TopoloAppGrid, and TopoloAppSection for repeated app body patterns',
-      'Keep visual QA fixtures available through visualQa=1 or __devpreview=1 so screenshot checks do not depend on live API state',
-      'Keep mobile and desktop shell behavior aligned with the platform UI kit',
-      'Constrain app-owned workspace wrappers with min-width: 0, width: auto, and viewport-aware max-width so shell padding cannot create page-level horizontal overflow',
-    ],
-  },
-  {
-    id: 'app-registration-and-scopes',
-    title: 'Register protected APIs as platform apps',
-    summary:
-      'Callable app APIs need a stable app ID, app slug, permissions, role bundles, and API-key scopes before agents or users rely on them.',
-    appliesTo: ['api'],
-    evidence: [
-      'Auth app catalog contains the app ID and slug',
-      'Permissions, role bundles, and API-key scopes exist for the app',
-      'SDK, CLI, and MCP app discovery include the callable production API',
-      'CloudControl production HTTP targets classify agent reachability with sdk_app_id or agent_callable:false',
-    ],
-    implementation: [
-      'Add production Worker api_url metadata and sdk_app_id for every agent-callable API target',
-      'Mark browser, documentation, and runtime-only Worker targets with agent_callable:false',
-      'Expose stable app IDs through generated DEFAULT_APP_URLS and live catalog discovery',
-      'Keep typed SDK/CLI/MCP surfaces in sync when an API contract stabilizes',
-    ],
-  },
-  {
-    id: 'organization-scoped-data',
-    title: 'Keep application data organization-scoped',
-    summary:
-      'Protected data access must be scoped by the authenticated organization at the backend boundary, not by client-provided hints.',
-    appliesTo: ['api'],
-    evidence: [
-      'Backend request handlers derive org membership from credential validation',
-      'Queries and Durable Object keys include the authenticated organization boundary where data is tenant-owned',
-      'MCP and CLI inputs do not include orgId overrides',
-    ],
-    implementation: [
-      'Reject or ignore organization hints supplied by clients',
-      'Bind SQL, KV, R2, queue, and Durable Object access to the authenticated organization',
-      'Document service-local exceptions explicitly in the system security assurance record',
-    ],
-  },
-  {
-    id: 'cloudflare-deployment-contract',
-    title: 'Keep Cloudflare deployment metadata complete',
-    summary:
-      'Workers, Pages, bindings, routes, env vars, queues, cron triggers, and deployment commands must be discoverable through CloudControl metadata.',
-    appliesTo: ['browser', 'api'],
-    evidence: [
-      'topolo.cloudcontrol.json lists production deploy targets and URLs',
-      'Wrangler/Pages configuration matches CloudControl metadata',
-      'Secrets and environment variables are not committed',
-    ],
-    implementation: [
-      'Update CloudControl metadata whenever deployment topology changes',
-      'Prefer Cloudflare-native runtime surfaces for new Topolo app infrastructure',
-      'Keep Worker bindings and Pages domains explicit enough for agents to inspect before deploying',
-    ],
-  },
-  {
-    id: 'agent-and-operator-surfaces',
-    title: 'Expose agent-safe operations through SDK, CLI, and MCP',
-    summary:
-      'Agent-accessible functionality should be discoverable, scope-gated, and write-confirmed instead of hidden behind ad hoc HTTP calls.',
-    appliesTo: ['api', 'tooling', 'agent_surface'],
-    evidence: [
-      'Read operations have typed SDK/CLI/MCP surfaces once their contract stabilizes',
-      'Mutating generic calls require --confirm or confirm:true',
-      'MCP tools never accept orgId and advertise only appropriate scope-gated tools',
-    ],
-    implementation: [
-      'Add SDK types first, then CLI commands and MCP tools for durable workflows',
-      'Use generic API passthrough only as a temporary escape hatch',
-      'Keep command output JSON-stable for agents and human-readable with --no-json',
-    ],
-  },
-  {
-    id: 'native-dashboard-widget',
-    title: 'Expose a native dashboard widget contract',
-    summary:
-      'Launchable first-party applications must populate TopoloOne live workspace through an app-owned /api/widget endpoint using the SDK widget response contract.',
-    appliesTo: ['api'],
-    evidence: [
-      'The app-owned API exposes GET /api/widget',
-      'The endpoint returns TopoloWidgetApiResponse from @topolo/sdk',
-      'Every returned widget includes snapshot.summary with app-owned operational prose',
-      'The endpoint derives organization/user context from the app auth boundary',
-    ],
-    implementation: [
-      'Import createTopoloWidgetResponse from @topolo/sdk in the app backend',
-      'Return native app metrics or action widgets instead of generic launch-card fallbacks',
-      'Populate snapshot.summary in the producing app for every widget instead of synthesizing summaries in TopoloOne',
-      'Add a route-level test that validates the response with validateTopoloWidgetResponse',
-    ],
-  },
-  {
-    id: 'observability-and-audit',
-    title: 'Emit platform audit and debugging signals',
-    summary:
-      'Requests, agent actions, and operational workflows need traceable IDs, client labels, and useful failure evidence.',
-    appliesTo: ['api', 'tooling', 'agent_surface'],
-    evidence: [
-      'Requests carry X-Topolo-Client and X-Topolo-Request-Id where the SDK is involved',
-      'Agent-originated calls can include X-Topolo-Agent',
-      'Failure modes are documented with request IDs or deployment/log lookup paths',
-    ],
-    implementation: [
-      'Use TopoloClient for platform API calls rather than raw fetch where practical',
-      'Keep logs free of secrets and tokens',
-      'Document live smoke commands and request-id correlation in canonical docs',
-    ],
-  },
-  {
-    id: 'verification-gates',
-    title: 'Ship with build, test, docs, and smoke verification',
-    summary:
-      'A Topolo app change is not complete until the relevant code checks and docs checks have been run or explicitly reported as blocked.',
-    appliesTo: ['all'],
-    evidence: [
-      'Relevant package build/typecheck/test commands pass',
-      'TopoloDocs validation passes when docs are touched',
-      'Live or local smoke evidence is captured for user-visible or API behavior',
-    ],
-    implementation: [
-      'Prefer existing package scripts before adding new tooling',
-      'Run app-specific checks and shared docs validation for behavior changes',
-      'Report any skipped verification with the blocker and residual risk',
-    ],
-  },
-] as const satisfies readonly ApplicationRequirement[];
-
-export function applicationRequirementScopes(
-  application: ApplicationCatalogEntry,
-): ApplicationRequirementScope[] {
-  const scopes = new Set<ApplicationRequirementScope>(['all']);
-  // id is checked by value: tooling ids (cli/mcp) are intentionally not in
-  // the deploy catalog union, so compare as string rather than assert overlap.
-  const appId: string = application.id;
-  const hasBrowserSurface =
-    Boolean(application.productionUrl) ||
-    // String() keeps this guard valid after the Pages->Worker migration narrowed
-    // the generated kind union to "worker" (no "pages" literal remains).
-    application.deployTargets.some((target) => String(target.kind) === 'pages');
-  // An API surface means an agent-callable service — keyed on a resolved
-  // appId, NOT a bare apiUrl. After the Pages->Worker migration every
-  // frontend shell carries an apiUrl (its own serving domain), so apiUrl is no
-  // longer a signal for "exposes a callable API"; appId is.
-  const hasApiSurface =
-    application.services.length > 0 ||
-    application.deployTargets.some((target) => Boolean(target.appId));
-
-  if (hasBrowserSurface) scopes.add('browser');
-  if (hasApiSurface) scopes.add('api');
-  if (appId === 'cli' || appId === 'mcp' || appId === 'cloudcontrol') {
-    scopes.add('tooling');
-  }
-  if (appId === 'cli' || appId === 'mcp' || hasApiSurface) {
-    scopes.add('agent_surface');
-  }
-
-  return Array.from(scopes);
-}
-
-export function requirementsForApplication(
-  applicationOrId: ApplicationCatalogEntry | ApplicationId,
-): ApplicationRequirement[] {
-  const application =
-    typeof applicationOrId === 'string' ? APPLICATIONS[applicationOrId] : applicationOrId;
-  const scopes = new Set(applicationRequirementScopes(application));
-  return APPLICATION_REQUIREMENTS.filter((requirement) =>
-    requirement.appliesTo.some((scope) => scopes.has(scope)),
-  );
-}
-
-export function auditApplicationRequirements(
-  applicationOrId: ApplicationCatalogEntry | ApplicationId,
-): ApplicationRequirementAudit {
-  const application =
-    typeof applicationOrId === 'string' ? APPLICATIONS[applicationOrId] : applicationOrId;
-  const scopes = applicationRequirementScopes(application);
-  const findings = requirementsForApplication(application).map((requirement) =>
-    evaluateRequirement(application, requirement),
-  );
-
-  return {
-    version: APPLICATION_REQUIREMENTS_VERSION,
-    application,
-    scopes,
-    score: scoreFindings(findings),
-    findings,
-  };
-}
-
-export function auditAllApplicationRequirements(
-  applicationIds: readonly ApplicationId[] = Object.keys(APPLICATIONS).sort() as ApplicationId[],
-): ApplicationRequirementsAuditReport {
-  const applications = applicationIds.map((applicationId) =>
-    auditApplicationRequirements(applicationId),
-  );
-  const migrationQueue = applications
-    .flatMap((audit) =>
-      audit.findings
-        .filter((finding): finding is ApplicationRequirementFinding & {
-          status: Exclude<ApplicationRequirementStatus, 'met'>;
-        } => finding.status !== 'met')
-        .map((finding) => ({
-          applicationId: audit.application.id as ApplicationId,
-          applicationName: audit.application.name,
-          requirementId: finding.requirementId,
-          title: finding.title,
-          status: finding.status,
-          reason: finding.reason,
-          nextActions: finding.nextActions,
-        })),
-    )
-    .sort((a, b) => {
-      const statusOrder = statusRank(a.status) - statusRank(b.status);
-      if (statusOrder !== 0) return statusOrder;
-      const appOrder = a.applicationId.localeCompare(b.applicationId);
-      if (appOrder !== 0) return appOrder;
-      return a.requirementId.localeCompare(b.requirementId);
-    });
-
-  return {
-    version: APPLICATION_REQUIREMENTS_VERSION,
-    applications,
-    migrationQueue,
-  };
-}
-
-function evaluateRequirement(
-  application: ApplicationCatalogEntry,
-  requirement: ApplicationRequirement,
-): ApplicationRequirementFinding {
-  const evidence: string[] = [];
-
-  switch (requirement.id) {
-    case 'platform-metadata': {
-      if (application.packageName) evidence.push(`package=${application.packageName}`);
-      if (application.productionUrl) evidence.push(`productionUrl=${application.productionUrl}`);
-      if (application.deployTargets.length > 0) {
-        evidence.push(`deployTargets=${application.deployTargets.length}`);
-      }
-      if (application.services.length > 0) {
-        evidence.push(`services=${application.services.join(',')}`);
-      }
-
-      if (evidence.length === 0) {
-        return finding(requirement, 'missing', 'No package, production URL, deploy target, or service metadata is available.', evidence);
-      }
-      return finding(requirement, 'met', 'Catalog metadata exists for this application.', evidence);
-    }
-    case 'canonical-docs':
-      return finding(
-        requirement,
-        'needs_review',
-        'Catalog metadata cannot verify matching TopoloDocs system and handbook coverage.',
-        evidence,
-      );
-    case 'shared-auth-boundary':
-      return finding(
-        requirement,
-        'needs_review',
-        'Catalog metadata cannot verify that implementation uses shared Topolo auth packages and derives org from credentials.',
-        evidence,
-      );
-    case 'shared-shell-and-launcher':
-      return finding(
-        requirement,
-        'needs_review',
-        'Catalog metadata cannot verify shared shell, launcher, and account menu adoption.',
-        evidence,
-      );
-    case 'app-registration-and-scopes': {
-      if (application.services.length > 0) {
-        evidence.push(`services=${application.services.join(',')}`);
-        return finding(
-          requirement,
-          'partial',
-          'SDK service discovery exists, but Auth catalog permissions, role bundles, and API-key scopes still need confirmation.',
-          evidence,
-        );
-      }
-      return finding(requirement, 'missing', 'No SDK app API id is registered for this callable API surface.', evidence);
-    }
-    case 'organization-scoped-data':
-      return finding(
-        requirement,
-        'needs_review',
-        'Catalog metadata cannot verify backend tenant filters, storage keys, or Durable Object boundaries.',
-        evidence,
-      );
-    case 'cloudflare-deployment-contract': {
-      // `< 1` rather than `=== 0`: every catalogued app now has >=1 deploy target,
-      // so the generated tuple-length union excludes 0 and `=== 0` fails typecheck.
-      if (application.deployTargets.length < 1) {
-        return finding(requirement, 'missing', 'No CloudControl deploy targets are registered.', evidence);
-      }
-      evidence.push(`deployTargets=${application.deployTargets.length}`);
-      if (application.productionUrl) evidence.push(`productionUrl=${application.productionUrl}`);
-      return finding(requirement, 'met', 'CloudControl deploy target metadata is present.', evidence);
-    }
-    case 'agent-and-operator-surfaces': {
-      const appId: string = application.id;
-      if (application.services.length > 0) {
-        evidence.push(`services=${application.services.join(',')}`);
-        return finding(requirement, 'partial', 'SDK service discovery exists; typed SDK/CLI/MCP workflow coverage should be checked as APIs stabilize.', evidence);
-      }
-      if (appId === 'cli' || appId === 'mcp' || appId === 'cloudcontrol') {
-        evidence.push(`tooling=${appId}`);
-        return finding(requirement, 'met', 'This application is itself an agent/operator surface.', evidence);
-      }
-      return finding(requirement, 'missing', 'No SDK service or tooling surface is registered.', evidence);
-    }
-    case 'native-dashboard-widget':
-      return finding(
-        requirement,
-        'needs_review',
-        'Catalog metadata cannot verify app-owned /api/widget implementation details.',
-        evidence,
-      );
-    case 'observability-and-audit':
-      return finding(
-        requirement,
-        'needs_review',
-        'Catalog metadata cannot verify runtime request IDs, client labels, or log redaction.',
-        evidence,
-      );
-    case 'verification-gates':
-      return finding(
-        requirement,
-        'needs_review',
-        'Catalog metadata cannot verify package checks, docs validation, or smoke evidence.',
-        evidence,
-      );
-    default:
-      return finding(requirement, 'needs_review', 'No automated evaluator exists for this requirement yet.', evidence);
-  }
-}
-
-function finding(
-  requirement: ApplicationRequirement,
-  status: ApplicationRequirementStatus,
-  reason: string,
-  evidence: readonly string[],
-): ApplicationRequirementFinding {
-  return {
-    requirementId: requirement.id,
-    title: requirement.title,
-    status,
-    reason,
-    evidence,
-    nextActions: status === 'met' ? [] : requirement.implementation,
-  };
-}
-
-function scoreFindings(findings: readonly ApplicationRequirementFinding[]): ApplicationRequirementScore {
-  const met = findings.filter((finding) => finding.status === 'met').length;
-  const partial = findings.filter((finding) => finding.status === 'partial').length;
-  const missing = findings.filter((finding) => finding.status === 'missing').length;
-  const needsReview = findings.filter((finding) => finding.status === 'needs_review').length;
-  const total = findings.length;
-  const weighted = met + partial * 0.5;
-  return {
-    met,
-    partial,
-    missing,
-    needsReview,
-    total,
-    percent: total === 0 ? 100 : Math.round((weighted / total) * 100),
-  };
-}
-
-function statusRank(status: Exclude<ApplicationRequirementStatus, 'met'>): number {
-  if (status === 'missing') return 0;
-  if (status === 'partial') return 1;
-  return 2;
-}