@superblocksteam/gateway 2.0.0-SNAPSHOT.1d4c72c0ab174c21

package/dist/capabilities/lifecycle.d.ts

@@ -0,0 +1,93 @@
+import { type HostBrowserTools } from "../capture/browser-contract.js";
+import type { CaptureLibraryScreenshot } from "../capture/capture-library.js";
+import type { GatewayConfig } from "../config.js";
+import { type CapturePreviewScreenshot } from "../preview/capture-screenshot.js";
+import type { AppState } from "../sabs/app-state.js";
+import { type SessionPeer } from "../sabs/session-peer.js";
+import type { SuperblocksServerClient } from "../server/client.js";
+import type { ProgressStore, RecentAppStore, StepUpTurnStore } from "../stores/types.js";
+import type { CapabilityResult, CheckAppProgressInput, CheckAppProgressResult, CheckPublishProgressInput, EditAppInput, EditAppResult, AskUserInput, AskUserResult, GetAppInput, GetAppResult, PreviewAppInput, PreviewAppResult, PreviewStatusInput, PreviewStatusResult, Principal, ProgressEvent, PublishAppInput, PublishAppResult, ResolvedPrincipal, StartAppInput, StartAppResult, UploadArtifactInput, UploadArtifactResult } from "./types.js";
+export { IMPORT_ZIP_MAX_BYTES } from "./types.js";
+export type CapabilityContext = {
+    config: GatewayConfig;
+    /** Injected so turn and stall thresholds are testable without real time. */
+    now?: () => number;
+    onProgress?: (event: ProgressEvent) => void;
+    onPrincipalResolved?: (principal: ResolvedPrincipal) => void;
+    principal: Principal;
+    /** Per-application facts that outlive any one turn. */
+    appState: AppState;
+    /** When each build last spoke, and whether its silence was reported. */
+    progress?: ProgressStore;
+    recentApps: RecentAppStore;
+    /**
+     * Optional headless capture of the live library iframe (pitcherURL). Injected
+     * in tests; defaults to Playwright in the MCP transport. Distinct from
+     * {@link capturePreviewScreenshot} (deployed shell).
+     */
+    captureLibraryScreenshot?: CaptureLibraryScreenshot;
+    /**
+     * Optional headless capture used when Claude cannot openLink an https URL.
+     * Injected in tests; defaults to Playwright in the MCP transport.
+     */
+    capturePreviewScreenshot?: CapturePreviewScreenshot;
+    /**
+     * What the connected host can drive a browser with. Only a transport knows
+     * which client it is talking to; absent, the contract says "unknown".
+     */
+    hostBrowserTools?: HostBrowserTools;
+    server: SuperblocksServerClient;
+    sessionPeer: SessionPeer;
+    /** The caller gave up on this call (an MCP cancellation, a closed request). */
+    signal?: AbortSignal;
+    stepUpTurns: StepUpTurnStore;
+};
+/**
+ * Resolves the Superblocks user behind the CLI session this Gateway was
+ * started with.
+ *
+ * Identity is the already-logged-in Superblocks CLI user. A rejection here
+ * means that personal API key is bad, not that the user needs a second login,
+ * so it surfaces as an error rather than an interactive-auth elicitation.
+ */
+export declare function ensurePrincipal(ctx: CapabilityContext): Promise<CapabilityResult<ResolvedPrincipal>>;
+export declare function resolveApplicationId(ctx: CapabilityContext, principal: ResolvedPrincipal, applicationId: string | undefined): Promise<CapabilityResult<string>>;
+export declare function startApp(ctx: CapabilityContext, input: StartAppInput): Promise<CapabilityResult<StartAppResult>>;
+export declare function uploadArtifact(ctx: CapabilityContext, input: UploadArtifactInput): Promise<CapabilityResult<UploadArtifactResult>>;
+export declare function checkAppProgress(ctx: CapabilityContext, input: CheckAppProgressInput): Promise<CapabilityResult<CheckAppProgressResult>>;
+export declare function editApp(ctx: CapabilityContext, input: EditAppInput, approvedPlan?: object): Promise<CapabilityResult<EditAppResult>>;
+/**
+ * Shows the app's current work on a real URL without deploying it - the
+ * editor's Preview button, driven from here.
+ *
+ * Three steps, the same ones and in the same order as the editor: snapshot the
+ * live-edit state as a commit, make sure a build exists for that commit's
+ * content, and hand back the URL that serves it. Builds are keyed on content
+ * rather than on the commit, so previewing work that was already built (by an
+ * earlier preview, or by a publish) waits on that build instead of starting a
+ * second one.
+ */
+export declare function previewApp(ctx: CapabilityContext, input: PreviewAppInput): Promise<CapabilityResult<PreviewAppResult>>;
+/** Read the build backing an existing commit preview without creating work. */
+export declare function getPreviewStatus(ctx: CapabilityContext, input: PreviewStatusInput): Promise<CapabilityResult<PreviewStatusResult>>;
+/**
+ * Opens the decision card: what Superblocks asked, for the user to answer as a
+ * form rather than by typing an approval the host has to interpret.
+ *
+ * Its own tool because an MCP App is bound to one, and `check_app_progress`
+ * must stay text-only - a card tool reopens its card on every poll, so putting
+ * this on the poll loop would flash a blank form through a whole build.
+ */
+export declare function askUser(ctx: CapabilityContext, input: AskUserInput): Promise<CapabilityResult<AskUserResult>>;
+/**
+ * Read the app's current live editor view without committing or building it.
+ */
+export declare function getApp(ctx: CapabilityContext, input: GetAppInput): Promise<CapabilityResult<GetAppResult>>;
+export declare function publishApp(ctx: CapabilityContext, input: PublishAppInput): Promise<CapabilityResult<PublishAppResult>>;
+/**
+ * Where a publish handed back as `publishing` has got to.
+ *
+ * Each call watches for a bounded slice of the rollout, then hands back a
+ * changing clock so repeated calls remain useful without outliving the host.
+ */
+export declare function checkPublishProgress(ctx: CapabilityContext, input: CheckPublishProgressInput): Promise<CapabilityResult<PublishAppResult>>;