@pikku/cli 0.12.100 → 0.12.103

package/dist/src/functions/commands/scenario-browser.d.ts

@@ -7,7 +7,7 @@
  * making the driver's optional isolation and diagnostics safe to call
  * unconditionally.
  */
-import type { ScenarioBrowserFailure, ScenarioBrowserProvider } from '@pikku/core/workflow';
+import type { ScenarioBrowserFailure, ScenarioBrowserProvider } from '@pikku/core/scenario';
 import type { ResolvedPersona } from '@pikku/core/services';
 /** The default driver, used when a project names no other. */
 export declare const DEFAULT_BROWSER_DRIVER = "@pikku/playwright";
@@ -16,6 +16,7 @@ export interface ScenarioBrowserDriverOptions {
     actors: Record<string, ResolvedPersona>;
     signInPath?: string;
     failureDir?: string;
+    capture?: ScenarioCaptureOptions;
     config: unknown;
 }
 /**
@@ -43,6 +44,21 @@ export interface ScenarioBrowserDriver {
         apiUrl: string;
     }) => unknown;
 }
+/**
+ * Artifacts a run may produce. Mirrors the driver's own CaptureOptions rather
+ * than importing it: the CLI must not depend on a driver package it resolves
+ * dynamically, and this shape is the contract between them.
+ */
+export interface ScenarioCaptureOptions {
+    /** Root directory for the run's artifacts. */
+    dir: string;
+    /** The invocation these artifacts belong to. */
+    runId: string;
+    /** Record a video per scenario. */
+    video?: boolean;
+    /** Re-encode with ffmpeg when available. Defaults on — the footage is nearly static. */
+    compress?: boolean;
+}
 export interface ResolveScenarioBrowserProviderOptions {
     /** The environment name, for error messages that tell the user what to edit. */
     environment: string;
@@ -53,6 +69,12 @@ export interface ResolveScenarioBrowserProviderOptions {
     signInPath?: string;
     /** Where failure screenshots are written. */
     failureDir: string;
+    /**
+     * Artifacts for this run — named screenshots, and optionally a video per
+     * scenario. Undefined leaves capture off, which is the default: most runs
+     * ask a pass/fail question and writing video to answer it is waste.
+     */
+    capture?: ScenarioCaptureOptions;
     /** The scenarios that declared browser steps, named in the missing-driver error. */
     browserScenarios: string[];
     /** Package to drive the browser. Defaults to `@pikku/playwright`. */
@@ -71,13 +93,14 @@ export interface ResolveScenarioBrowserProviderOptions {
  * because a run against a placeholder URL is worse than one that refuses to
  * start.
  */
-export declare const resolveScenarioBrowserProvider: ({ environment, apiUrl, appUrl, secret, actors, signInPath, failureDir, browserScenarios, driver, importDriver, }: ResolveScenarioBrowserProviderOptions) => Promise<ScenarioBrowserProvider>;
+export declare const resolveScenarioBrowserProvider: ({ environment, apiUrl, appUrl, secret, actors, signInPath, failureDir, capture, browserScenarios, driver, importDriver, }: ResolveScenarioBrowserProviderOptions) => Promise<ScenarioBrowserProvider>;
 /**
  * The three calls the run loop makes, safe against a run with no browser and
  * against a driver that implements neither optional member.
  */
 export interface ScenarioBrowserLifecycle {
     reset(): Promise<void>;
+    beginScenario(scenario: string): void;
     captureFailure(label: string): Promise<ScenarioBrowserFailure[]>;
     close(): Promise<void>;
 }

package/dist/src/functions/commands/scenario-browser.js

@@ -12,7 +12,7 @@ export const DEFAULT_BROWSER_DRIVER = '@pikku/playwright';
  * because a run against a placeholder URL is worse than one that refuses to
  * start.
  */
-export const resolveScenarioBrowserProvider = async ({ environment, apiUrl, appUrl, secret, actors, signInPath, failureDir, browserScenarios, driver = DEFAULT_BROWSER_DRIVER, importDriver = (specifier) => import(specifier), }) => {
+export const resolveScenarioBrowserProvider = async ({ environment, apiUrl, appUrl, secret, actors, signInPath, failureDir, capture, browserScenarios, driver = DEFAULT_BROWSER_DRIVER, importDriver = (specifier) => import(specifier), }) => {
     const module = await importDriver(driver).catch(() => {
         const install = driver === DEFAULT_BROWSER_DRIVER
             ? `Run 'yarn add -D ${driver} @playwright/test'`
@@ -33,6 +33,7 @@ export const resolveScenarioBrowserProvider = async ({ environment, apiUrl, appU
         actors,
         signInPath,
         failureDir,
+        capture,
         config,
     };
     if (module.createScenarioBrowserProvider) {
@@ -52,6 +53,9 @@ export const scenarioBrowserLifecycle = (provider) => ({
     reset: async () => {
         await provider?.reset?.();
     },
+    beginScenario: (scenario) => {
+        provider?.beginScenario?.(scenario);
+    },
     captureFailure: async (label) => {
         try {
             return (await provider?.captureFailure?.(label)) ?? [];

package/dist/src/functions/commands/scenario-formatter.d.ts

@@ -7,7 +7,7 @@
  * second formatter (JSON, JUnit) a matter of writing one function rather than
  * unpicking the runner.
  */
-import type { ScenarioBrowserFailure } from '@pikku/core/workflow';
+import type { ScenarioBrowserFailure } from '@pikku/core/scenario';
 /** The longest gherkin keyword ("Given"), so sentences line up under each other. */
 declare const KEYWORD_WIDTH = 5;
 /** One step of a run, already joined to the prose that declared it. */

package/dist/src/functions/commands/scenario-ladder.d.ts

@@ -1,4 +1,4 @@
-import type { ScenarioStepPhase, ScenarioSurface } from '@pikku/core/workflow';
+import type { ScenarioStepPhase, ScenarioSurface } from '@pikku/core/scenario';
 import type { WorkflowStepMeta } from '@pikku/core/workflow/types';
 import type { FunctionsMeta } from '@pikku/core';
 import type { ScenarioFailureDetail, ScenarioStepRow } from './scenario-formatter.js';

package/dist/src/functions/commands/scenario-ladder.js

@@ -8,7 +8,7 @@
  * belongs to `scenario-formatter.ts`; this module only decides what each step
  * is called.
  */
-import { composeStepProse } from '@pikku/core/workflow';
+import { composeStepProse } from '@pikku/core/scenario';
 import { KEYWORD_WIDTH } from './scenario-formatter.js';
 /**
  * Walk a workflow's steps — including the ones nested inside branches, fanouts

package/dist/src/functions/commands/scenario-plan.d.ts

@@ -1,4 +1,5 @@
-import type { CoreFeature, CoreWorkflow } from '@pikku/core/workflow';
+import type { CoreWorkflow } from '@pikku/core/workflow';
+import type { CoreFeature } from '@pikku/core/scenario';
 /** One scenario run: a scenario name and, for a feature's paired entry, its input. */
 export type ScenarioPlanEntry = {
     scenarioName: string;

package/dist/src/functions/commands/scenario-plan.js

@@ -1,4 +1,4 @@
-import { resolveFeatureScenarios } from '@pikku/core/workflow';
+import { resolveFeatureScenarios } from '@pikku/core/scenario';
 /**
  * Turn the registered scenarios and features into an ordered list of run units.
  *

package/dist/src/functions/commands/scenario.d.ts

@@ -1,4 +1,4 @@
-import type { ScenarioSurface } from '@pikku/core/workflow';
+import type { ScenarioSurface } from '@pikku/core/scenario';
 export declare const scenarioList: import("#pikku").PikkuFunctionConfig<{}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{}, void, "rpc" | "session", import("#pikku").WiredServices, unknown> | import("#pikku").PikkuFunction<{}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
 export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     environment: string;
@@ -13,6 +13,8 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;
+    screenshots?: boolean;
+    video?: boolean;
     apiUrl?: string;
     appUrl?: string;
 }, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
@@ -28,6 +30,8 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;
+    screenshots?: boolean;
+    video?: boolean;
     apiUrl?: string;
     appUrl?: string;
 }, void, "rpc" | "session", import("#pikku").WiredServices, unknown> | import("#pikku").PikkuFunction<{
@@ -43,6 +47,8 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;
+    screenshots?: boolean;
+    video?: boolean;
     apiUrl?: string;
     appUrl?: string;
 }, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/commands/scenario.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { resolve, join } from 'node:path';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { pikkuSessionlessFunc } from '#pikku';
@@ -5,10 +6,10 @@ import { InMemoryWorkflowService } from '@pikku/core/services';
 import { createHttpPersonas } from '@pikku/core/persona';
 import { PikkuScenarioService } from '@pikku/core/scenario';
 import { pikkuState, getAllPackageStates } from '@pikku/core/ecosystem';
-import { resolveFeatureScenarios } from '@pikku/core/workflow';
+import { resolveFeatureScenarios } from '@pikku/core/scenario';
 import { loadScenarioBootstrap } from './load-user-project.js';
 import { collectScenarioStepProse, scenarioBrowserSteps, scenarioFailureFromSteps, scenarioStepRows, scenarioStepsWithoutBinding, scenarioSurfaceCoverage, } from './scenario-ladder.js';
-import { SCENARIO_SURFACES } from '@pikku/core/workflow';
+import { SCENARIO_SURFACES } from '@pikku/core/scenario';
 import { formatScenarioReport } from './scenario-formatter.js';
 import { resolveScenarioBrowserProvider, scenarioBrowserLifecycle, } from './scenario-browser.js';
 import { resolvePersonas } from '../../utils/resolve-personas.js';
@@ -87,7 +88,7 @@ export const scenarioList = pikkuSessionlessFunc({
     },
 });
 export const scenarioRun = pikkuSessionlessFunc({
-    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, features, tags, excludeTags, coverage, browser = true, run: runSurface = 'default', strict = false, spawn = false, keepAlive = false, trace = false, apiUrl, appUrl, }) => {
+    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, features, tags, excludeTags, coverage, browser = true, run: runSurface = 'default', strict = false, spawn = false, keepAlive = false, trace = false, screenshots = false, video = false, apiUrl, appUrl, }) => {
         if (!SCENARIO_SURFACES.includes(runSurface)) {
             throw new Error(`Unknown --run surface '${runSurface}'. Expected one of: ${SCENARIO_SURFACES.join(', ')}.`);
         }
@@ -285,6 +286,17 @@ export const scenarioRun = pikkuSessionlessFunc({
         const needsBrowser = effectiveSurface === 'browser' &&
             groups.some((group) => group.entries.some((entry) => browserStepsByFlow.has(entry.scenarioName)));
         const failureDir = join(resolve(config.rootDir, config.outDir), 'scenario-failures');
+        // Artifacts are filed under the run, not the scenario, so one run's output
+        // is one folder to open, keep or delete. `--video` implies capture is on:
+        // recording without somewhere to put it is not a thing anyone wants.
+        const captureDir = join(resolve(config.rootDir, config.outDir), 'scenario-runs');
+        // One id for the whole invocation, distinct from a scenario's own runId:
+        // reviewing artifacts means opening what `pikku scenario run` just produced,
+        // not hunting for one scenario's folder among many.
+        const captureRunId = randomUUID();
+        const capture = screenshots || video
+            ? { dir: captureDir, runId: captureRunId, video, compress: true }
+            : undefined;
         const browserLifecycle = scenarioBrowserLifecycle(needsBrowser
             ? await (async () => {
                 const provider = await resolveScenarioBrowserProvider({
@@ -295,6 +307,7 @@ export const scenarioRun = pikkuSessionlessFunc({
                     actors: scenarioActors,
                     signInPath: env.signInPath,
                     failureDir,
+                    capture,
                     browserScenarios: [...browserStepsByFlow.keys()],
                     driver: config.scenarios?.browserDriver,
                 });
@@ -353,10 +366,9 @@ export const scenarioRun = pikkuSessionlessFunc({
          * scenario body gets, the CLI's own singletons included, and its result is
          * discarded.
          *
-         * The context is *feature*-scoped: `before` and `after` of one feature share
-         * it, so setup can hand teardown the ids it created. It is deliberately not
-         * the context the scenarios in the group see — sharing one bag across a
-         * group is the invisible coupling a Cucumber world had.
+         * Its context is *feature*-scoped — shared by that feature's `before` and
+         * `after`, and deliberately not the context the group's scenarios see:
+         * one bag across a group is the invisible coupling a Cucumber world had.
          */
         const singletonServices = pikkuState(null, 'package', 'singletonServices');
         const runFeatureHook = async (hook, context) => {
@@ -371,6 +383,9 @@ export const scenarioRun = pikkuSessionlessFunc({
             // Before the scenario, not after it: the last scenario's window is left
             // open for headed debugging, while this one still starts clean.
             await browserLifecycle.reset();
+            // After the reset, which is what closes the previous scenario's context
+            // and finalises its video.
+            browserLifecycle.beginScenario(label);
             if (coverageActive) {
                 const reset = await invokeCoverage('pikkuScenarioResetLiveCoverage');
                 if (reset && reset.enabled === false) {
@@ -495,6 +510,12 @@ export const scenarioRun = pikkuSessionlessFunc({
             }
         }
         await browserLifecycle.close();
+        // Reported after the browser has closed, because video is only finalised
+        // when its context is. A capture nobody can find is a capture nobody
+        // looks at, and looking at them is the entire point of the flags.
+        if (capture) {
+            logger.info(`Captures → ${join(capture.dir, capture.runId)}`);
+        }
         if (coverage && Object.keys(scenarioCoverage).length > 0) {
             const coverageDir = join(resolve(config.rootDir, config.outDir), 'coverage');
             mkdirSync(coverageDir, { recursive: true });

package/dist/src/functions/commands/serve.d.ts

@@ -1,10 +1,13 @@
 export declare const serve: import("#pikku").PikkuFunctionConfig<{
     port?: string;
     console?: boolean;
+    model?: string;
 }, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
     port?: string;
     console?: boolean;
+    model?: string;
 }, void, "rpc" | "session", import("#pikku").WiredServices, unknown> | import("#pikku").PikkuFunction<{
     port?: string;
     console?: boolean;
+    model?: string;
 }, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/commands/serve.js

@@ -4,19 +4,24 @@ import { ConsoleLogger, LocalEmailService, InMemoryQueueService, InMemoryWorkflo
 import { KyselyAIStorageService, KyselyAIRunStateService, KyselyAgentRunService, } from '@pikku/kysely';
 import { stopSingletonServices } from '@pikku/core';
 import { pikkuState } from '@pikku/core/ecosystem';
+import { wireAIScorerQueueWorkers } from '@pikku/core/ai-scorer';
 import { LocalMetaService } from '@pikku/core/services/local-meta';
 import { LocalContent, } from '@pikku/core/services/local-content';
 import { InMemorySchedulerService } from '@pikku/schedule';
 import { resolveDb, createKysely, parseDatabaseUrl, } from '../db/local-db.js';
 import { loadUserBootstrap, loadUserModule } from './load-user-project.js';
+import { registerScenarioInstrumentation } from '../wirings/scenarios/register-scenario-instrumentation.js';
+import { resolveScaffoldFeature } from '../../utils/resolve-scaffold-feature.js';
 import { createDevAIAgentRunner } from './dev-ai-runner.js';
 import { resolveConsoleMount } from './serve-console.js';
 import { serverReadyLine } from '../../server/server-ready.js';
 import { createEphemeralContentSigningJWT } from '../../server/content-signing-jwt.js';
+import { applyModelAliasOverride } from '../../utils/model-alias-override.js';
 export const serve = pikkuSessionlessFunc({
     remote: true,
-    func: async ({ logger, config, getInspectorState, variables, devServerRunner }, { port, console: serveConsole }) => {
+    func: async ({ logger, config, getInspectorState, variables, devServerRunner }, { port, console: serveConsole, model }) => {
         process.env.PIKKU_DEV_QUICK_LOGIN ??= 'true';
+        applyModelAliasOverride(logger, model, config.models);
         const resolvedPort = parseInt(port || '3000', 10);
         const hostname = 'localhost';
         const bindHostname = '127.0.0.1';
@@ -28,6 +33,14 @@ export const serve = pikkuSessionlessFunc({
             return;
         }
         await loadUserBootstrap(pikkuDir);
+        // Scenario instrumentation exists only on a locally served project: the
+        // runner calls it over RPC to reset and snapshot coverage and stub calls.
+        // It is registered here, after the app bootstrap, rather than generated
+        // into the project — an app bootstrap is what a deployed bundle imports,
+        // and coverage endpoints have no business in one.
+        if (config.scaffold?.scenarios) {
+            registerScenarioInstrumentation(resolveScaffoldFeature('scenarios', config.scaffold.scenarios).auth);
+        }
         const workflowService = new InMemoryWorkflowService();
         const configModule = await loadUserModule(pikkuConfigFactory.file);
         const servicesModule = await loadUserModule(singletonServicesFactory.file);
@@ -115,6 +128,7 @@ export const serve = pikkuSessionlessFunc({
         };
         pikkuState(null, 'package', 'singletonServices', resolvedServices);
         resolvedServices.workflowService?.wireQueueWorkers?.();
+        wireAIScorerQueueWorkers();
         const { serverLifecycleFactory } = inspectorState.filesAndMethods;
         const loadLifecycle = async () => {
             if (!serverLifecycleFactory)

package/dist/src/functions/commands/{workspace-validate.d.ts → validate.d.ts}

@@ -1,7 +1,12 @@
-import { renderWorkspaceValidate } from '../validate/workspace-validate.js';
-export declare const workspaceValidate: import("#pikku").PikkuFunctionConfig<Record<string, never>, {
+import { renderValidate } from '../validate/validate.js';
+export declare const validate: import("#pikku").PikkuFunctionConfig<Record<string, never>, {
     ok: boolean;
     root: string;
+    ran: {
+        checkId: string;
+        subject: string;
+        target: string;
+    }[];
     findings: {
         id: string;
         severity: "warn" | "error" | "info";
@@ -12,6 +17,11 @@ export declare const workspaceValidate: import("#pikku").PikkuFunctionConfig<Rec
 }, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<Record<string, never>, {
     ok: boolean;
     root: string;
+    ran: {
+        checkId: string;
+        subject: string;
+        target: string;
+    }[];
     findings: {
         id: string;
         severity: "warn" | "error" | "info";
@@ -22,6 +32,11 @@ export declare const workspaceValidate: import("#pikku").PikkuFunctionConfig<Rec
 }, "rpc" | "session", import("#pikku").WiredServices, unknown> | import("#pikku").PikkuFunction<Record<string, never>, {
     ok: boolean;
     root: string;
+    ran: {
+        checkId: string;
+        subject: string;
+        target: string;
+    }[];
     findings: {
         id: string;
         severity: "warn" | "error" | "info";
@@ -30,4 +45,4 @@ export declare const workspaceValidate: import("#pikku").PikkuFunctionConfig<Rec
         fixHint: string;
     }[];
 }, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
-export { renderWorkspaceValidate };
+export { renderValidate };

package/dist/src/functions/commands/validate.js

@@ -0,0 +1,9 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { ValidateInput, ValidateOutput, renderValidate, runProjectValidate, } from '../validate/validate.js';
+export const validate = pikkuSessionlessFunc({
+    description: 'Check this project against every Pikku check that applies to it — app structure, and the published file set of any addon it contains. Prints what was checked, with fix hints for anything wrong.',
+    input: ValidateInput,
+    output: ValidateOutput,
+    func: async () => runProjectValidate(),
+});
+export { renderValidate };

package/dist/src/functions/db/local-db.d.ts

@@ -40,7 +40,7 @@ export interface ResolvedPostgresDb extends ResolvedDbBase {
     devSeedFile: string;
     /**
      * Postgres extensions the embedded PGlite databases must load, as declared by
-     * `pgliteExtensions` in the project's config. See
+     * `db.pgliteExtensions` in the project's pikku.config.json. See
      * {@link loadPGliteExtensions}.
      *
      * Carried even in `url` mode: the shadow database the CLI migrates and
@@ -72,6 +72,7 @@ export declare function parseDatabaseUrl(url: string): Pick<UserConfigShape, 'sq
 export declare function resolveDb(userConfig: UserConfigShape, rootDir: string, outDir: string, runtimeDir?: string, dbConfig?: {
     schema?: string;
     defaultSchema?: string;
+    pgliteExtensions?: string[];
 } | string): ResolvedDb | null;
 /** @deprecated Use resolveDb(userConfig, ...) instead. */
 export declare function resolveLocalDb(sqliteDb: string | undefined, rootDir: string, outDir: string, runtimeDir?: string): ResolvedSqliteDb | null;

package/dist/src/functions/db/local-db.js

@@ -68,7 +68,7 @@ export function resolveDb(userConfig, rootDir, outDir, runtimeDir, dbConfig) {
     if (userConfig.postgresUrl && userConfig.sqliteDb) {
         throw new Error('Both postgresUrl and sqliteDb are set. Configure exactly one database dialect.');
     }
-    const pgliteExtensions = userConfig.pgliteExtensions ?? [];
+    const pgliteExtensions = (typeof dbConfig === 'string' ? undefined : dbConfig?.pgliteExtensions) ?? [];
     if (userConfig.postgresUrl) {
         return {
             dialect: 'postgres',
@@ -268,7 +268,7 @@ function explainMissingExtension(error, declared) {
     return new Error(`The embedded PGlite database has no '${name}' extension. ` +
         `The CLI migrates a PGlite shadow database to type and diff your schema, ` +
         `so every extension your migrations use has to be declared as ` +
-        `pgliteExtensions in createConfig — e.g. pgliteExtensions: ['${name}'] ` +
+        `db.pgliteExtensions in pikku.config.json — e.g. "db": { "pgliteExtensions": ["${name}"] } ` +
         `for a PGlite contrib extension, or the package that publishes it ` +
         `('@electric-sql/pglite-pgvector' for pgvector).` +
         (declared.length > 0

package/dist/src/functions/surface/collect-surface.d.ts

@@ -0,0 +1,14 @@
+export type SurfaceKind = 'function' | 'class' | 'interface' | 'type' | 'const' | 'enum' | 'namespace';
+export type SurfaceSymbol = {
+    name: string;
+    kind: SurfaceKind;
+    declaredAt: string;
+    deprecated: boolean;
+};
+export type SurfaceEntrypoint = {
+    subpath: string;
+    specifier: string;
+    entryFile: string;
+    symbols: SurfaceSymbol[];
+};
+export declare const collectSurface: (packageDir: string) => Promise<SurfaceEntrypoint[]>;

package/dist/src/functions/surface/collect-surface.js

@@ -0,0 +1,215 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import ts from 'typescript';
+const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts'];
+const MODULE_EXTENSIONS = [...SOURCE_EXTENSIONS, '.js', '.jsx', '.mjs', '.cjs'];
+const wildcardStem = (fileName) => {
+    if (fileName.endsWith('.map'))
+        return null;
+    if (/\.d\.(ts|mts|cts)$/.test(fileName))
+        return null;
+    const extension = MODULE_EXTENSIONS.find((each) => fileName.endsWith(each));
+    return extension ? fileName.slice(0, -extension.length) : null;
+};
+const subpathMap = (exports) => {
+    if (typeof exports === 'string')
+        return { '.': exports };
+    return Object.keys(exports).some((key) => key.startsWith('.'))
+        ? exports
+        : { '.': exports };
+};
+const publishesCode = (target) => !/\.(css|scss|json|svg|png|woff2?|txt|md)$/.test(target);
+const sourceForTarget = (packageDir, target, outDir) => {
+    const withoutPrefix = target.replace(/^\.\//, '');
+    const isDeclaration = /\.d\.(ts|mts|cts)$/.test(withoutPrefix);
+    if (!isDeclaration &&
+        SOURCE_EXTENSIONS.some((extension) => withoutPrefix.endsWith(extension))) {
+        return existsSync(join(packageDir, withoutPrefix)) ? withoutPrefix : null;
+    }
+    const stripped = withoutPrefix.startsWith(`${outDir}/`)
+        ? withoutPrefix.slice(outDir.length + 1)
+        : withoutPrefix;
+    const base = stripped
+        .replace(/\.d\.(ts|mts|cts)$/, '')
+        .replace(/\.(js|jsx|mjs|cjs)$/, '');
+    const withoutSrc = base.startsWith('src/') ? base.slice(4) : base;
+    const candidates = [];
+    for (const extension of SOURCE_EXTENSIONS) {
+        candidates.push(join('src', `${base}${extension}`), `${base}${extension}`, join('src', `${withoutSrc}${extension}`), join('src', base, `index${extension}`), join(base, `index${extension}`));
+    }
+    for (const candidate of candidates) {
+        if (existsSync(join(packageDir, candidate)))
+            return candidate;
+    }
+    return null;
+};
+const expandWildcard = (packageDir, subpath, target) => {
+    const targetDir = target.replace(/^\.\//, '').split('*')[0] ?? '';
+    const suffix = target.slice(target.indexOf('*') + 1);
+    const absolute = join(packageDir, targetDir);
+    if (!existsSync(absolute))
+        return [];
+    const expanded = [];
+    const walk = (directory, prefix) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                walk(join(directory, entry.name), `${prefix}${entry.name}/`);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (suffix && !entry.name.endsWith(suffix))
+                continue;
+            const stem = wildcardStem(entry.name);
+            if (stem === null)
+                continue;
+            expanded.push({
+                subpath: subpath.replace('*', `${prefix}${stem}`),
+                target: `${targetDir}${prefix}${entry.name}`,
+            });
+        }
+    };
+    walk(absolute, '');
+    return expanded;
+};
+const targetOf = (value) => {
+    if (typeof value === 'string')
+        return value;
+    if (!value || typeof value !== 'object')
+        return null;
+    const conditions = value;
+    for (const key of ['types', 'import', 'default', 'require']) {
+        const resolved = targetOf(conditions[key]);
+        if (resolved)
+            return resolved;
+    }
+    return null;
+};
+const readJson = async (path) => {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+};
+const readCompilerOptions = async (packageDir) => {
+    const configPath = join(packageDir, 'tsconfig.json');
+    if (!existsSync(configPath))
+        return { outDir: 'dist', paths: {} };
+    const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (configFile.error)
+        return { outDir: 'dist', paths: {} };
+    const { options } = ts.parseJsonConfigFileContent(configFile.config, ts.sys, packageDir);
+    const { baseUrl, paths, pathsBasePath } = options;
+    return {
+        outDir: options.outDir ? relative(packageDir, options.outDir) : 'dist',
+        paths: {
+            ...(baseUrl !== undefined ? { baseUrl } : {}),
+            ...(paths !== undefined ? { paths } : {}),
+            ...(pathsBasePath !== undefined ? { pathsBasePath } : {}),
+        },
+    };
+};
+const KIND_BY_FLAG = [
+    [ts.SymbolFlags.Class, 'class'],
+    [ts.SymbolFlags.Interface, 'interface'],
+    [ts.SymbolFlags.RegularEnum | ts.SymbolFlags.ConstEnum, 'enum'],
+    [ts.SymbolFlags.Function, 'function'],
+    [ts.SymbolFlags.TypeAlias, 'type'],
+    [ts.SymbolFlags.Namespace, 'namespace'],
+];
+const kindOf = (symbol, checker) => {
+    const target = symbol.flags & ts.SymbolFlags.Alias
+        ? checker.getAliasedSymbol(symbol)
+        : symbol;
+    for (const [flag, kind] of KIND_BY_FLAG) {
+        if (target.flags & flag)
+            return kind;
+    }
+    if (target.flags & ts.SymbolFlags.Variable) {
+        const declaration = target.declarations?.[0];
+        if (declaration) {
+            const type = checker.getTypeOfSymbolAtLocation(target, declaration);
+            if (type.getCallSignatures().length > 0)
+                return 'function';
+        }
+        return 'const';
+    }
+    return 'const';
+};
+const isDeprecated = (symbol) => symbol.getJsDocTags().some((tag) => tag.name === 'deprecated');
+const declarationFileOf = (symbol, checker) => {
+    const target = symbol.flags & ts.SymbolFlags.Alias
+        ? checker.getAliasedSymbol(symbol)
+        : symbol;
+    const declaration = target.declarations?.[0] ?? symbol.declarations?.[0];
+    return declaration?.getSourceFile().fileName ?? null;
+};
+export const collectSurface = async (packageDir) => {
+    const root = resolve(packageDir);
+    const packageJson = await readJson(join(root, 'package.json'));
+    if (!packageJson?.exports)
+        return [];
+    const { outDir, paths } = await readCompilerOptions(root);
+    const packageName = packageJson.name ?? '';
+    const entries = [];
+    const seenEntryFiles = new Set();
+    for (const [subpath, value] of Object.entries(subpathMap(packageJson.exports))) {
+        if (!subpath.startsWith('.'))
+            continue;
+        const target = targetOf(value);
+        if (!target || !publishesCode(target))
+            continue;
+        const declared = target.includes('*')
+            ? expandWildcard(root, subpath, target)
+            : [{ subpath, target }];
+        for (const each of declared) {
+            const entryFile = sourceForTarget(root, each.target, outDir);
+            if (!entryFile || seenEntryFiles.has(entryFile))
+                continue;
+            seenEntryFiles.add(entryFile);
+            entries.push({
+                subpath: each.subpath,
+                specifier: each.subpath === '.'
+                    ? packageName
+                    : `${packageName}${each.subpath.slice(1)}`,
+                entryFile,
+            });
+        }
+    }
+    if (entries.length === 0)
+        return [];
+    const program = ts.createProgram(entries.map((entry) => join(root, entry.entryFile)), {
+        ...paths,
+        target: ts.ScriptTarget.ESNext,
+        module: ts.ModuleKind.Node16,
+        moduleResolution: ts.ModuleResolutionKind.Node16,
+        skipLibCheck: true,
+        skipDefaultLibCheck: true,
+        types: [],
+        allowJs: false,
+        checkJs: false,
+    });
+    const checker = program.getTypeChecker();
+    return entries.map((entry) => {
+        const sourceFile = program.getSourceFile(join(root, entry.entryFile));
+        const moduleSymbol = sourceFile
+            ? checker.getSymbolAtLocation(sourceFile)
+            : undefined;
+        const symbols = [];
+        for (const symbol of moduleSymbol
+            ? checker.getExportsOfModule(moduleSymbol)
+            : []) {
+            const file = declarationFileOf(symbol, checker);
+            symbols.push({
+                name: symbol.getName(),
+                kind: kindOf(symbol, checker),
+                declaredAt: file ? relative(root, file) : entry.entryFile,
+                deprecated: isDeprecated(symbol),
+            });
+        }
+        return { ...entry, symbols };
+    });
+};