@onlook/capsule 0.1.0

package/src/types.ts

@@ -0,0 +1,268 @@
+import { z } from 'zod';
+
+// === Route Discovery ===
+
+/** A react-router parent route that wraps child routes via <Outlet /> */
+export type LayoutRoute = {
+  /** Route path segment, e.g. "/sign-in" */
+  path: string;
+  /** Relative path to the layout component */
+  component: string;
+  /** Named export (if omitted, assumes default export) */
+  exportName?: string;
+};
+
+/** A component that wraps <Routes> in the router (e.g. LocationManager, AuthGuard) */
+export type AppWrapper = {
+  /** Component name, e.g. "LocationManager" */
+  componentName: string;
+  /** Relative path to component file */
+  component: string;
+  /** Named export (if omitted, assumes default export) */
+  exportName?: string;
+};
+
+export type RouteEntry = {
+  /** URL path, e.g. "/dashboard/settings" */
+  path: string;
+  /** Relative path to the page component, e.g. "app/dashboard/settings/page.tsx" */
+  pageComponent: string;
+  /** Layout files from outermost to innermost (Next.js) */
+  layouts: string[];
+  /** Parent route components that wrap this route via Outlet (react-router) */
+  layoutRoutes?: LayoutRoute[];
+  /** Mock values for dynamic segments, e.g. { id: "mock-123" } */
+  params?: Record<string, string>;
+  /** Named export to use (if omitted, assumes default export) */
+  exportName?: string;
+};
+
+export type RouteManifest = {
+  framework: 'nextjs-app' | 'vite-react-router';
+  routes: RouteEntry[];
+  /** Components that wrap <Routes> in the router file (react-router only) */
+  appWrappers?: AppWrapper[];
+};
+
+// === Boundary Analysis ===
+
+export type ComponentBoundary = {
+  /** Import source strings, e.g. ["@/contexts/AuthContext", "@tanstack/react-query"] */
+  imports: string[];
+  /** Hook call names, e.g. ["useAuth", "useQuery", "useFeatureFlags"] */
+  hooks: string[];
+  /** Context names from useContext calls, e.g. ["AuthContext", "ThemeContext"] */
+  contexts: string[];
+};
+
+// === Component Profile (enriched analysis for LLM context) ===
+
+export type PropInfo = {
+  /** Property name */
+  name: string;
+  /** TypeScript type text, e.g. "string", "User | null" */
+  type: string;
+  /** Whether the prop is optional (question token or `| undefined`) */
+  optional: boolean;
+};
+
+export type StateInfo = {
+  /** Variable name, e.g. "count" */
+  name: string;
+  /** Inferred type from generic or initial value */
+  type: string;
+  /** Setter name, e.g. "setCount" */
+  setter: string;
+};
+
+export type HookCallInfo = {
+  /** Hook name, e.g. "useAuth" */
+  name: string;
+  /** Import source module, e.g. "@/hooks/useAuth"; empty string if locally defined */
+  module: string;
+};
+
+export type ComponentProfile = {
+  props: PropInfo[];
+  state: StateInfo[];
+  hookCalls: HookCallInfo[];
+};
+
+// === JSON-safe value type ===
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+// === Capsule Manifest (the decoupled patch) ===
+
+export type ProviderSpec = {
+  /** Identifier for this provider, e.g. "auth" */
+  id: string;
+  /** Import path, e.g. "@/contexts/AuthContext" */
+  import: string;
+  /** Context variable name, e.g. "AuthContext" */
+  contextName: string;
+  /** Mock value to provide via Context.Provider */
+  mockValue: Record<string, unknown>;
+};
+
+export type HookStubSpec = {
+  /** Module path to intercept, e.g. "@/hooks/useFeatureFlags" */
+  module: string;
+  /** Named export to stub, e.g. "useFeatureFlags" */
+  export: string;
+  /** Value the stub returns */
+  returns: unknown;
+  /** If true, export as a value instead of a function */
+  isValue?: boolean;
+};
+
+export type NetworkMockSpec = {
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  /** URL path pattern, e.g. "/api/settings" */
+  path: string;
+  /** HTTP status code, defaults to 200 */
+  status?: number;
+  /** Response body */
+  response: unknown;
+};
+
+export type CapsuleManifest = {
+  providers: ProviderSpec[];
+  hookStubs: HookStubSpec[];
+  networkMocks: NetworkMockSpec[];
+  /** Global assignments, e.g. { "window.ENV": { API_URL: "..." } } */
+  globals: Record<string, JsonValue>;
+};
+
+// === Render Results ===
+
+export type CapsuleResult =
+  | {
+      status: 'sealed';
+      html: string;
+      manifest: CapsuleManifest;
+      attempts: number;
+    }
+  | {
+      status: 'breached';
+      error: string;
+      componentStack: string;
+      manifest: CapsuleManifest;
+    };
+
+// === Viewer ===
+
+export type CapsuleStatus = {
+  route: RouteEntry;
+  status: 'sealed' | 'breached' | 'pending';
+  attempts: number;
+  error?: string;
+};
+
+// === Config ===
+
+export type CapsuleConfig = {
+  /** Absolute path to the project root */
+  projectRoot: string;
+  /** Override route discovery glob */
+  routes?: string;
+  /** Max seal loop retries per route (default: 3) */
+  maxRetries: number;
+  /** Parallel seal operations (default: 4) */
+  concurrency: number;
+  /** Start viewer after sealing */
+  serve: boolean;
+  /** Viewer port (default: 5123) */
+  port: number;
+  /** Cache directory (default: .capsules/cache) */
+  cacheDir: string;
+  /** Show seal loop details */
+  verbose: boolean;
+  /** Run LLM fixes immediately on failure instead of after all routes render (default: false) */
+  eager: boolean;
+  /** Max parallel LLM calls in lazy mode (default: 1) */
+  llmConcurrency: number;
+  /** Path to the router file for Vite projects (auto-detected if not set) */
+  routerFile?: string;
+  /** Additional esbuild externals beyond the defaults */
+  external?: string[];
+  /** Workspace modules to allow through (bypass auto-proxy). Matched as prefixes. */
+  allowedModules?: string[];
+};
+
+// === Zod Schemas (runtime validation for LLM output, cache, API) ===
+
+export const providerSpecSchema = z.object({
+  id: z.string(),
+  import: z.string(),
+  contextName: z.string(),
+  mockValue: z.record(z.string(), z.unknown()),
+});
+
+export const hookStubSchema = z.object({
+  module: z.string(),
+  export: z.string(),
+  returns: z.unknown().default(null),
+  isValue: z.boolean().optional(),
+});
+
+export const networkMockSchema = z.object({
+  method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
+  path: z.string(),
+  status: z.number().optional(),
+  response: z.unknown(),
+});
+
+export const capsuleManifestSchema = z.object({
+  providers: z.array(providerSpecSchema),
+  hookStubs: z.array(hookStubSchema),
+  networkMocks: z.array(networkMockSchema),
+  globals: z.record(z.string(), z.unknown()),
+});
+
+// === Default values ===
+
+export const DEFAULTS = {
+  MAX_RETRIES: 3,
+  CONCURRENCY: 4,
+  VIEWER_PORT: 5123,
+  LLM_CONCURRENCY: 1,
+  CACHE_HASH_LENGTH: 16,
+} as const;
+
+/**
+ * Hooks covered by hardcoded framework stubs in the Vite plugin.
+ * These don't appear in the manifest's hookStubs but ARE stubbed at runtime.
+ */
+export const FRAMEWORK_STUBBED_HOOKS = new Set([
+  // react-router
+  'useParams',
+  'useSearchParams',
+  'useNavigate',
+  'useLocation',
+  'useMatch',
+  'useRoutes',
+  'useOutletContext',
+  'useHref',
+  'useInRouterContext',
+  'useNavigationType',
+  'useResolvedPath',
+  'useRouteError',
+  'useLoaderData',
+  'useActionData',
+  // react-i18next
+  'useTranslation',
+  // apollo/graphql
+  'useQuery',
+  'useLazyQuery',
+  'useMutation',
+  'useSubscription',
+  'useApolloClient',
+  'useClient',
+]);