@pikku/cli 0.12.115 → 0.12.116

package/dist/src/fabric/lib/deployment.d.ts

@@ -0,0 +1,107 @@
+import type { PikkuRPC } from '../sdk/pikku-rpc.gen.js';
+import type { GetDeploymentStatusOutput } from '../sdk/rpc-map.gen.d.js';
+type MissingConfigEntry = GetDeploymentStatusOutput['missingSecrets'][number];
+export type BlockedReason = 'awaiting_approval' | 'needs_config' | 'needs_attention' | 'unknown';
+export type StatusClass = 'in_flight' | 'succeeded' | 'failed' | 'blocked';
+export declare function classifyStatus(status: string): StatusClass;
+export declare function blockedReason(statusReason: string | null): BlockedReason;
+export declare function isApprovable(reason: BlockedReason): boolean;
+export declare function stateLabel(status: string, statusReason: string | null): string;
+export declare function blockedSummary(reason: BlockedReason): string;
+export interface DeploymentStatus {
+    status: string;
+    statusReason: string | null;
+    stageId: string;
+    hostname: string | null;
+    missingSecrets: MissingConfigEntry[];
+    missingVariables: MissingConfigEntry[];
+}
+export declare function readDeploymentStatus(rpc: PikkuRPC, deploymentId: string): Promise<DeploymentStatus>;
+export declare function approveDeployment(rpc: PikkuRPC, deploymentId: string): Promise<boolean>;
+export interface MigrationRisk {
+    name: string;
+    level: 'destructive' | 'safe';
+    reasons: string[];
+}
+export declare function destructiveMigrations(changes: DeploymentChanges | null | undefined): MigrationRisk[];
+export interface DeploymentChanges {
+    unitsAdded: string[];
+    unitsRemoved: string[];
+    handlersAdded: string[];
+    handlersRemoved: string[];
+    workflowsAdded: string[];
+    workflowsRemoved: string[];
+    workflowsChanged: string[];
+    functionsAdded: string[];
+    functionsRemoved: string[];
+    secretsChanged: string[];
+    variablesChanged: string[];
+    pendingMigrations: string[];
+    migrationRisks: MigrationRisk[];
+}
+export declare function changesAreEmpty(changes: DeploymentChanges): boolean;
+export interface DeploymentDescription {
+    branch: string;
+    stageId: string;
+    gitSha: string | null;
+    status: string;
+    statusReason: string | null;
+    url: string | null;
+    changes: DeploymentChanges | null;
+}
+export declare function describeDeployment(rpc: PikkuRPC, projectId: string, deploymentId: string): Promise<DeploymentDescription | null>;
+export interface DeployedWorker {
+    name: string;
+    role: string;
+    status: string;
+}
+export declare function readWorkers(rpc: PikkuRPC, stageId: string): Promise<DeployedWorker[]>;
+export type ProgressEvent = {
+    event: 'created';
+    deploymentId: string;
+    branch: string;
+    ref: string;
+} | {
+    event: 'attached';
+    deploymentId: string;
+    status: string;
+} | {
+    event: 'status';
+    deploymentId: string;
+    status: string;
+    statusReason: string | null;
+    elapsedMs: number;
+} | {
+    event: 'blocked';
+    deploymentId: string;
+    reason: BlockedReason;
+    missingSecrets: string[];
+    missingVariables: string[];
+} | {
+    event: 'approved';
+    deploymentId: string;
+};
+export type WaitOutcome = 'succeeded' | 'failed' | 'blocked' | 'timeout';
+export interface WaitResult {
+    outcome: WaitOutcome;
+    status: string;
+    statusReason: string | null;
+    stageId: string;
+    hostname: string | null;
+    reason: BlockedReason | null;
+    missingSecrets: MissingConfigEntry[];
+    missingVariables: MissingConfigEntry[];
+    approved: boolean;
+    elapsedMs: number;
+}
+export interface WaitOptions {
+    rpc: PikkuRPC;
+    deploymentId: string;
+    timeoutMs: number;
+    approve: (status: DeploymentStatus) => Promise<boolean>;
+    onEvent: (event: ProgressEvent) => void;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+export declare function waitForDeployment({ rpc, deploymentId, timeoutMs, approve, onEvent, sleep, now, }: WaitOptions): Promise<WaitResult>;
+export {};

package/dist/src/fabric/lib/deployment.js

@@ -0,0 +1,264 @@
+const IN_FLIGHT = new Set(['queued', 'planning', 'building', 'deploying']);
+const SUCCEEDED = new Set(['active']);
+const FAILED = new Set([
+    'failed',
+    'error',
+    'timed_out',
+    'cancelled',
+    'rolled_back',
+    'stopped',
+    'archived',
+]);
+export function classifyStatus(status) {
+    if (SUCCEEDED.has(status))
+        return 'succeeded';
+    if (FAILED.has(status))
+        return 'failed';
+    if (status === 'suspended')
+        return 'blocked';
+    if (IN_FLIGHT.has(status))
+        return 'in_flight';
+    return 'in_flight';
+}
+export function blockedReason(statusReason) {
+    if (statusReason === 'awaiting_approval' ||
+        statusReason === 'needs_config' ||
+        statusReason === 'needs_attention') {
+        return statusReason;
+    }
+    return 'unknown';
+}
+export function isApprovable(reason) {
+    return reason === 'awaiting_approval';
+}
+export function stateLabel(status, statusReason) {
+    if (status === 'suspended') {
+        if (statusReason === 'needs_attention')
+            return 'needs attention';
+        if (statusReason === 'needs_config')
+            return 'config required';
+        return 'planned';
+    }
+    if (status === 'active')
+        return 'live';
+    if (status === 'rolled_back')
+        return 'rolled back';
+    if (status === 'timed_out')
+        return 'timed out';
+    return status;
+}
+export function blockedSummary(reason) {
+    switch (reason) {
+        case 'needs_attention':
+            return 'Plan needs attention before it can deploy';
+        case 'needs_config':
+            return 'Required config missing — set values before approving';
+        case 'awaiting_approval':
+            return 'Plan ready — approve to deploy';
+        default:
+            return 'Deployment is suspended';
+    }
+}
+export async function readDeploymentStatus(rpc, deploymentId) {
+    const s = await rpc.invoke('getDeploymentStatus', { deploymentId });
+    return {
+        status: s.status,
+        statusReason: s.statusReason,
+        stageId: s.stageId,
+        hostname: s.hostname,
+        missingSecrets: s.missingSecrets,
+        missingVariables: s.missingVariables,
+    };
+}
+export async function approveDeployment(rpc, deploymentId) {
+    const { resumed } = await rpc.invoke('applyDeployment', { deploymentId });
+    return resumed;
+}
+function parseMigrationRisks(plan) {
+    const raw = plan
+        ?.migrationRisks;
+    if (!Array.isArray(raw))
+        return [];
+    const risks = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const { name, level, reasons } = entry;
+        if (typeof name !== 'string')
+            continue;
+        if (level !== 'destructive' && level !== 'safe')
+            continue;
+        risks.push({
+            name,
+            level,
+            reasons: Array.isArray(reasons)
+                ? reasons.filter((r) => typeof r === 'string')
+                : [],
+        });
+    }
+    return risks;
+}
+export function destructiveMigrations(changes) {
+    return (changes?.migrationRisks ?? []).filter((r) => r.level === 'destructive');
+}
+export function changesAreEmpty(changes) {
+    return Object.values(changes).every((list) => list.length === 0);
+}
+const handlerNames = (entries) => (entries ?? []).map((h) => `${h.unit}/${h.id}`);
+export async function describeDeployment(rpc, projectId, deploymentId) {
+    const { stages } = await rpc.invoke('getProjectDeployments', {
+        projectId,
+        includeDismissed: true,
+    });
+    for (const stage of stages) {
+        for (const deployment of stage.deployments) {
+            if (deployment.deploymentId !== deploymentId)
+                continue;
+            const diff = deployment.diff;
+            const executed = new Set((deployment.migrations ?? []).map((m) => m.migrationName));
+            const planned = deployment.plan?.pendingMigrations;
+            const pendingMigrations = Array.isArray(planned)
+                ? planned
+                    .filter((m) => typeof m === 'string')
+                    .filter((m) => !executed.has(m))
+                : [];
+            const pending = new Set(pendingMigrations);
+            const migrationRisks = parseMigrationRisks(deployment.plan).filter((r) => pending.has(r.name));
+            const changes = diff
+                ? {
+                    unitsAdded: diff.units.added,
+                    unitsRemoved: diff.units.removed,
+                    handlersAdded: handlerNames(diff.handlers.added),
+                    handlersRemoved: handlerNames(diff.handlers.removed),
+                    workflowsAdded: diff.workflows.added,
+                    workflowsRemoved: diff.workflows.removed,
+                    workflowsChanged: diff.workflows.hashChanged,
+                    functionsAdded: diff.contracts.addedFunctions,
+                    functionsRemoved: diff.contracts.removedFunctions,
+                    secretsChanged: [
+                        ...diff.secrets.added,
+                        ...diff.secrets.removed,
+                        ...diff.secrets.modified,
+                    ],
+                    variablesChanged: [
+                        ...diff.variables.added,
+                        ...diff.variables.removed,
+                        ...diff.variables.modified,
+                    ],
+                    pendingMigrations,
+                    migrationRisks,
+                }
+                : pendingMigrations.length > 0
+                    ? {
+                        unitsAdded: [],
+                        unitsRemoved: [],
+                        handlersAdded: [],
+                        handlersRemoved: [],
+                        workflowsAdded: [],
+                        workflowsRemoved: [],
+                        workflowsChanged: [],
+                        functionsAdded: [],
+                        functionsRemoved: [],
+                        secretsChanged: [],
+                        variablesChanged: [],
+                        pendingMigrations,
+                        migrationRisks,
+                    }
+                    : null;
+            return {
+                branch: stage.branch,
+                stageId: stage.stageId,
+                gitSha: deployment.gitSha,
+                status: deployment.status,
+                statusReason: deployment.statusReason ?? null,
+                url: stage.url,
+                changes,
+            };
+        }
+    }
+    return null;
+}
+export async function readWorkers(rpc, stageId) {
+    const { workers } = await rpc.invoke('listDeploymentWorkers', { stageId });
+    return workers.map(({ name, role, status }) => ({ name, role, status }));
+}
+const RESUME_GRACE_MS = 30_000;
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function waitForDeployment({ rpc, deploymentId, timeoutMs, approve, onEvent, sleep = defaultSleep, now = Date.now, }) {
+    const startedAt = now();
+    const elapsed = () => now() - startedAt;
+    let delay = 2_000;
+    let lastStatus = null;
+    let approved = false;
+    let approvedAt = 0;
+    let lastBlockedReason = null;
+    const settle = (status, outcome, reason) => ({
+        outcome,
+        status: status.status,
+        statusReason: status.statusReason,
+        stageId: status.stageId,
+        hostname: status.hostname,
+        reason,
+        missingSecrets: status.missingSecrets,
+        missingVariables: status.missingVariables,
+        approved,
+        elapsedMs: elapsed(),
+    });
+    let latest = await readDeploymentStatus(rpc, deploymentId);
+    while (true) {
+        if (latest.status !== lastStatus) {
+            lastStatus = latest.status;
+            onEvent({
+                event: 'status',
+                deploymentId,
+                status: latest.status,
+                statusReason: latest.statusReason,
+                elapsedMs: elapsed(),
+            });
+        }
+        const klass = classifyStatus(latest.status);
+        if (klass === 'succeeded')
+            return settle(latest, 'succeeded', null);
+        if (klass === 'failed')
+            return settle(latest, 'failed', null);
+        if (klass === 'blocked') {
+            const reason = blockedReason(latest.statusReason);
+            if (reason !== lastBlockedReason) {
+                lastBlockedReason = reason;
+                onEvent({
+                    event: 'blocked',
+                    deploymentId,
+                    reason,
+                    missingSecrets: latest.missingSecrets.map((m) => m.name),
+                    missingVariables: latest.missingVariables.map((m) => m.name),
+                });
+            }
+            if (!isApprovable(reason)) {
+                return settle(latest, 'blocked', reason);
+            }
+            if (approved) {
+                if (elapsed() - approvedAt >= RESUME_GRACE_MS) {
+                    return settle(latest, 'blocked', reason);
+                }
+            }
+            else {
+                if (!(await approve(latest))) {
+                    return settle(latest, 'blocked', reason);
+                }
+                await approveDeployment(rpc, deploymentId);
+                approved = true;
+                approvedAt = elapsed();
+                onEvent({ event: 'approved', deploymentId });
+                delay = 2_000;
+                latest = await readDeploymentStatus(rpc, deploymentId);
+                continue;
+            }
+        }
+        const remaining = timeoutMs - elapsed();
+        if (remaining <= 0)
+            return settle(latest, 'timeout', null);
+        await sleep(Math.min(delay, remaining));
+        delay = Math.min(delay * 1.5, 10_000);
+        latest = await readDeploymentStatus(rpc, deploymentId);
+    }
+}

package/dist/src/fabric/sdk/pikku-fetch.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.21
+ * This file was generated by @pikku/cli@0.12.113
  */
 import { CorePikkuFetch } from '@pikku/fetch';
 import type { HTTPWiringsMap, HTTPWiringHandlerOf, HTTPWiringsWithMethod } from './http-map.gen.d.js';

package/dist/src/fabric/sdk/pikku-fetch.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.21
+ * This file was generated by @pikku/cli@0.12.113
  */
 import { CorePikkuFetch } from '@pikku/fetch';
 export class PikkuFetch extends CorePikkuFetch {

package/dist/src/fabric/sdk/pikku-rpc.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.21
+ * This file was generated by @pikku/cli@0.12.113
  */
 import { PikkuFetch } from "./pikku-fetch.gen.js";
 import type { RPCInvoke, TypedAgentRun, TypedStartWorkflow, TypedRunWorkflow, TypedWorkflowStatus } from './rpc-map.gen.d.js';
@@ -101,5 +101,8 @@ export declare class PikkuRPC {
          */
         approve: (agentName: string, input: Record<string, unknown>) => Promise<any>;
     };
+    subscribeToSSE<T = unknown>(path: string, handler: (event: T) => void, onError?: (err: unknown) => void): {
+        close: () => void;
+    };
 }
 export declare const pikkuRPC: PikkuRPC;

package/dist/src/fabric/sdk/pikku-rpc.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.21
+ * This file was generated by @pikku/cli@0.12.113
  */
 import { PikkuFetch } from "./pikku-fetch.gen.js";
 /**
@@ -122,5 +122,8 @@ export class PikkuRPC {
             return await this.pikkuFetch.post(`/rpc/agent/${String(agentName)}/approve`, input);
         },
     };
+    subscribeToSSE(path, handler, onError) {
+        return this.pikkuFetch.subscribeToSSE(path, handler, onError);
+    }
 }
 export const pikkuRPC = new PikkuRPC();

package/dist/src/functions/commands/deploy-apply.js

@@ -210,6 +210,7 @@ export const deployApply = pikkuSessionlessFunc({
             inspectorState,
             serverlessIncompatible: config.deploy?.serverlessIncompatible,
             defaultTarget: config.deploy?.defaultTarget,
+            globalHTTPPrefix: config.globalHTTPPrefix,
             getEntryContext,
             outDir: config.outDir,
             debugArtifacts: data?.debugArtifacts ?? false,

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

@@ -57,6 +57,7 @@ export const deployPlan = pikkuSessionlessFunc({
             inspectorState,
             serverlessIncompatible: config.deploy?.serverlessIncompatible,
             defaultTarget: config.deploy?.defaultTarget,
+            globalHTTPPrefix: config.globalHTTPPrefix,
             getEntryContext,
             outDir: config.outDir,
             debugArtifacts: data?.debugArtifacts ?? false,

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

@@ -0,0 +1,22 @@
+export declare const doc: import("#pikku/function").PikkuFunctionConfig<{
+    topics?: string[];
+    ai?: boolean;
+    addon?: boolean;
+}, {
+    text: string;
+}, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<{
+    topics?: string[];
+    ai?: boolean;
+    addon?: boolean;
+}, {
+    text: string;
+}, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<{
+    topics?: string[];
+    ai?: boolean;
+    addon?: boolean;
+}, {
+    text: string;
+}, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const renderDoc: (_services: unknown, { text }: {
+    text: string;
+}) => void;

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

@@ -0,0 +1,25 @@
+import { pikkuSessionlessFunc } from '#pikku/function';
+import { readShippedSurfaceDoc } from '../surface/shipped-surface-doc.js';
+import { renderSurfaceDoc } from '../surface/render-surface-doc.js';
+export const doc = pikkuSessionlessFunc({
+    description: 'Print the public API surface of the pikku version installed here: the doors you import from, what each exports, and how each export is called.',
+    func: async (_services, { topics, ai, addon }) => {
+        const surface = readShippedSurfaceDoc();
+        if (!surface) {
+            throw new Error('This @pikku/cli has no surface doc. It ships with the published package and is written when the CLI is built, so a source checkout needs a build first.');
+        }
+        const targets = topics?.length ? topics : [undefined];
+        return {
+            text: targets
+                .map((target) => renderSurfaceDoc(surface, {
+                target,
+                ai,
+                entryPoint: addon ? 'addon' : 'app',
+            }))
+                .join('\n\n'),
+        };
+    },
+});
+export const renderDoc = (_services, { text }) => {
+    console.log(text);
+};

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

@@ -10,17 +10,20 @@ export declare const pikkuSkillsInstall: import("#pikku/function").PikkuFunction
     only?: string;
     core?: boolean;
     fabric?: boolean;
+    client?: boolean;
     update?: boolean;
 }, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<{
     agent?: string;
     only?: string;
     core?: boolean;
     fabric?: boolean;
+    client?: boolean;
     update?: boolean;
 }, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<{
     agent?: string;
     only?: string;
     core?: boolean;
     fabric?: boolean;
+    client?: boolean;
     update?: boolean;
 }, void, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;

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

@@ -67,7 +67,7 @@ async function readSkillInstallGroups(skillName) {
         return [];
     return parseInstallGroups(match[1]);
 }
-async function getWantedSkills(allEntries, { only, core = false, fabric = false, }) {
+async function getWantedSkills(allEntries, { only, core = false, fabric = false, client = false, }) {
     const wanted = new Set();
     if (only) {
         for (const name of only
@@ -80,6 +80,7 @@ async function getWantedSkills(allEntries, { only, core = false, fabric = false,
     const requestedGroups = [
         ...(core ? ['core'] : []),
         ...(fabric ? ['fabric'] : []),
+        ...(client ? ['client'] : []),
     ];
     if (requestedGroups.length > 0) {
         for (const name of allEntries) {
@@ -117,7 +118,7 @@ export const pikkuSkillsList = pikkuSessionlessFunc({
     },
 });
 export const pikkuSkillsInstall = pikkuSessionlessFunc({
-    func: async ({ logger }, { agent = 'claude', only, core = false, fabric = false, update = false }) => {
+    func: async ({ logger }, { agent = 'claude', only, core = false, fabric = false, client = false, update = false, }) => {
         const supportedAgents = Object.keys(AGENT_SKILL_DIRS);
         if (!supportedAgents.includes(agent)) {
             logger.error(`Agent "${agent}" is not yet supported. Supported: ${supportedAgents.join(', ')}. ` +
@@ -130,6 +131,7 @@ export const pikkuSkillsInstall = pikkuSessionlessFunc({
             only,
             core,
             fabric,
+            client,
         });
         const missing = wanted.filter((n) => !allEntries.includes(n));
         if (missing.length > 0) {

package/dist/src/functions/runtimes/tanstack-start/serialize-tanstack-start-shim.d.ts

@@ -3,8 +3,9 @@
  *
  * The "server function" is a Pikku function; this shim is a typed *caller* over
  * the generated RPC map (`PikkuRPC`) for use in Start loaders, actions and
- * components. The API base URL comes from `import.meta.env.VITE_API_URL` and the
- * shim throws if it is unset — never hardcode a host.
+ * components. The base URL is derived from the page origin in the browser and
+ * from a runtime binding during SSR — never hardcoded, and never taken from a
+ * build-time variable alone, which is undefined in a deployed bundle.
  *
  * @param rpcWiringsPath - import path to the file exporting the `PikkuRPC` class
  */

package/dist/src/functions/runtimes/tanstack-start/serialize-tanstack-start-shim.js

@@ -3,8 +3,9 @@
  *
  * The "server function" is a Pikku function; this shim is a typed *caller* over
  * the generated RPC map (`PikkuRPC`) for use in Start loaders, actions and
- * components. The API base URL comes from `import.meta.env.VITE_API_URL` and the
- * shim throws if it is unset — never hardcode a host.
+ * components. The base URL is derived from the page origin in the browser and
+ * from a runtime binding during SSR — never hardcoded, and never taken from a
+ * build-time variable alone, which is undefined in a deployed bundle.
  *
  * @param rpcWiringsPath - import path to the file exporting the `PikkuRPC` class
  */
@@ -17,19 +18,41 @@ export const serializeTanStackStartShim = (rpcWiringsPath) => {
  *
  *   loader: () => makeApi().invoke('listCards', {})
  *
- * The API base URL is read from \`import.meta.env.VITE_API_URL\`.
+ * In the browser the base URL is \`import.meta.env.VITE_API_URL\` when the build
+ * inlined one, otherwise the page's own origin + /api. During SSR it comes from
+ * \`PIKKU_API_URL\` / \`VITE_API_URL\` in the environment, since there is no page
+ * to derive it from.
  */
 import { PikkuRPC } from '${rpcWiringsPath}'
 
-export function makeApi(): PikkuRPC {
-  const serverUrl = import.meta.env.VITE_API_URL
-  if (!serverUrl) {
-    throw new Error(
-      'VITE_API_URL is not set — point it at the Pikku API base URL'
-    )
+const LOCAL_HOSTNAME = /^(localhost|127\\.0\\.0\\.1)$/
+const LOCAL_BASE = /\\/\\/(localhost|127\\.0\\.0\\.1)(:|\\/)/
+
+export function apiBaseUrl(): string {
+  const configured = import.meta.env.VITE_API_URL
+
+  if (import.meta.env.SSR) {
+    const env = (globalThis as { process?: { env?: Record<string, string | undefined> } })
+      .process?.env
+    const serverUrl = env?.PIKKU_API_URL ?? env?.VITE_API_URL ?? configured
+    if (!serverUrl) {
+      throw new Error(
+        'No API base URL during SSR — set VITE_API_URL for local dev, or bind PIKKU_API_URL on the deployed server'
+      )
+    }
+    return serverUrl
+  }
+
+  const remote = !LOCAL_HOSTNAME.test(window.location.hostname)
+  if (configured && !(remote && LOCAL_BASE.test(configured))) {
+    return configured
   }
+  return window.location.origin + '/api'
+}
+
+export function makeApi(): PikkuRPC {
   const rpc = new PikkuRPC()
-  rpc.setServerUrl(serverUrl)
+  rpc.setServerUrl(apiBaseUrl())
   return rpc
 }
 `;

package/dist/src/functions/surface/build-surface-doc.d.ts

@@ -18,5 +18,12 @@ export type BuildSurfaceDocOptions = {
     version: string;
     app: SurfaceProject;
     addon: SurfaceProject;
+    /** Named regions an `@example snippet: <name>` resolves against. */
+    snippets?: Map<string, string>;
 };
-export declare const buildSurfaceDoc: ({ version, app, addon, }: BuildSurfaceDocOptions) => Promise<SurfaceDoc>;
+/**
+ * An example names a snippet rather than restating it, and both entrypoints
+ * resolve against the same map — the regions come from one running application
+ * (`examples/online-shop`), not from whichever template happened to hold them.
+ */
+export declare const buildSurfaceDoc: ({ version, app, addon, snippets, }: BuildSurfaceDocOptions) => Promise<SurfaceDoc>;