@opencraw/studio 0.0.2

package/dist/src/index.d.ts

@@ -0,0 +1,10 @@
+export { main } from './main.js';
+export { startStudioServer } from './studio-server/index.js';
+export type { StudioServer, StudioServerOptions } from './studio-server/index.js';
+export { openWorkspace, saveRecipe } from './recipe-workspace/index.js';
+export { runSample, loadRecipePair } from './sample-run/index.js';
+export type { RecipePair, SampleRunCallbacks, SampleRunHandle, SampleRunRecord, SampleRunResult, SampleStoppedBy } from './sample-run/index.js';
+export { fetchStartPage } from './page-snapshot/index.js';
+export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, studioCommandSchema, stoppedBySchema, traceLineEventSchema, recordEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema, recipeIssueSchema, recipeListingSchema, workspaceViewSchema, sampleRunRecordSchema, sampleRunViewSchema, startPageViewSchema, } from './studio-api/index.js';
+export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, StudioCommand, StoppedBy, TraceLineEvent, RecordEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent, RecipeIssue, RecipeListing, WorkspaceView, SampleRunView, StartPageView, } from './studio-api/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/main.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Runs `opencraw-studio`: starts the server, opens `folder` (if given) as
+ * the workspace right away, and prints the URL with the token, the way
+ * `docs/research/recipe-studio.md` §2 shows it: `http://127.0.0.1:<port>/?token=…`.
+ * The process stays up (the server keeps the event loop alive) until it is
+ * interrupted (Ctrl+C).
+ *
+ * @param argv - Arguments after the program name: an optional recipe folder, `.` when omitted.
+ */
+export declare function main(argv: readonly string[]): Promise<void>;
+//# sourceMappingURL=main.d.ts.map

package/dist/src/page-snapshot/fetch-start-page.use-case.d.ts

@@ -0,0 +1,20 @@
+import type { BrowserSessionConfig, InputRecipe } from '@opencraw/core';
+/**
+ * Fetches an input recipe's start page as the engine would see it: a fresh
+ * Playwright page in web mode, core's HTTP client in api mode. Returns plain
+ * text: the page's HTML, or a readable rendering of a non-HTML api response.
+ * No rewriting, no script stripping, no node ids yet: that is phase 2's
+ * `page-snapshot` proper (studio plan, #91). Provisional for phase 0 in two
+ * ways, both worth knowing before relying on it: it opens a bare page
+ * without running the recipe's own steps first, so a start point behind a
+ * `session.bootstrap` login shows what an anonymous visitor sees; and it
+ * launches a fresh browser or HTTP context per call, one page then closes
+ * it, rather than reusing whatever the last sample run had open.
+ *
+ * @param input - The input recipe; only `mode` and the first `start` point are used.
+ * @param browser - Browser launch settings for web mode (an executable path override, headless…).
+ * @returns The page's content as plain text.
+ * @throws Error when the recipe has no start point.
+ */
+export declare function fetchStartPage(input: InputRecipe, browser?: BrowserSessionConfig): Promise<string>;
+//# sourceMappingURL=fetch-start-page.use-case.d.ts.map

package/dist/src/page-snapshot/index.d.ts

@@ -0,0 +1,2 @@
+export { fetchStartPage } from './fetch-start-page.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/recipe-workspace/index.d.ts

@@ -0,0 +1,3 @@
+export { openWorkspace } from './open-workspace.use-case.js';
+export { saveRecipe } from './save-recipe.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/recipe-workspace/open-workspace.use-case.d.ts

@@ -0,0 +1,15 @@
+import type { WorkspaceView } from '../studio-api/index.js';
+/**
+ * Opens a recipe folder: every `.json`/`.jsonl` recipe directly inside it
+ * (core's own directory reading, so relative `file:` URLs resolve the same
+ * way a real run would), parsed and, for each output recipe found, bound to
+ * the input recipes that name it. Nothing throws for a bad recipe or a
+ * recipe that does not bind: every problem is reported on its file with the
+ * JSON path core already computes, exactly as `opencraw validate` prints it.
+ *
+ * @param folder - The workspace folder.
+ * @returns Every recipe file found, each with its validation and binding issues.
+ * @throws Error when the folder does not exist or cannot be read.
+ */
+export declare function openWorkspace(folder: string): Promise<WorkspaceView>;
+//# sourceMappingURL=open-workspace.use-case.d.ts.map

package/dist/src/recipe-workspace/save-recipe.use-case.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Writes a recipe back to its file: pretty JSON, a 2-space indent, a
+ * trailing newline. Phase 0 takes the JSON tab's whole parsed object rather
+ * than a patch, so this is a full replacement, not a splice: loading a file
+ * the studio has not touched and saving it again keeps every key, value and
+ * key order (`JSON.parse` preserves insertion order, and `JSON.stringify`
+ * writes it back), but not necessarily the file's exact original formatting
+ * (alignment, how arrays wrap, a trailing comment). Byte-identical
+ * round-trip for a hand-formatted file is future work; see this file's test
+ * for what is guaranteed today.
+ *
+ * @param path - The recipe file to write.
+ * @param recipe - The whole recipe object.
+ */
+export declare function saveRecipe(path: string, recipe: unknown): Promise<void>;
+//# sourceMappingURL=save-recipe.use-case.d.ts.map

package/dist/src/sample-run/index.d.ts

@@ -0,0 +1,6 @@
+export { loadRecipePair } from './load-recipe-pair.use-case.js';
+export type { RecipePair } from './load-recipe-pair.use-case.js';
+export { runSample } from './run-sample.use-case.js';
+export type { SampleRunCallbacks, SampleRunHandle } from './run-sample.use-case.js';
+export type { SampleRunRecord, SampleRunResult, SampleStoppedBy } from './sample-run-record.contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/sample-run/load-recipe-pair.use-case.d.ts

@@ -0,0 +1,18 @@
+import type { InputRecipe, OutputRecipe } from '@opencraw/core';
+/** An input recipe and the output recipe it names, both parsed. */
+export interface RecipePair {
+    input: InputRecipe;
+    output: OutputRecipe;
+}
+/**
+ * Finds and parses one input recipe of a workspace folder, and the output
+ * recipe it names.
+ *
+ * @param folder - The workspace folder.
+ * @param recipeId - The input recipe's id.
+ * @returns The parsed pair.
+ * @throws RecipeValidationError when either recipe does not parse.
+ * @throws Error when the input or its output is not in the folder.
+ */
+export declare function loadRecipePair(folder: string, recipeId: string): Promise<RecipePair>;
+//# sourceMappingURL=load-recipe-pair.use-case.d.ts.map

package/dist/src/sample-run/run-sample.use-case.d.ts

@@ -0,0 +1,30 @@
+import type { SampleBudget } from '../studio-api/index.js';
+import type { SampleRunRecord, SampleRunResult } from './sample-run-record.contract.js';
+/** Where trace lines and records go as a sample run proceeds. */
+export interface SampleRunCallbacks {
+    onTraceLine: (line: string) => void;
+    onRecord: (record: SampleRunRecord) => void;
+}
+/** A sample run in progress. */
+export interface SampleRunHandle {
+    /** Closes the crawler; the run's `result` still resolves, typically with an error from the interrupted request. */
+    stop: () => Promise<void>;
+    result: Promise<SampleRunResult>;
+}
+/**
+ * Runs one input recipe of a workspace folder as a sample: `debug: true` (so
+ * each `record:emit` carries its data), an in-memory sink, and `budget` as
+ * the crawler's `sample` (`@opencraw/core`'s `CrawlOptions.sample`, #89).
+ * Every engine event becomes a trace line with the same `traceLine`
+ * formatter the cli's `--trace` uses; every emitted record reaches
+ * `callbacks.onRecord` as it happens, not only in the final result.
+ *
+ * @param folder - The workspace folder the recipe lives in.
+ * @param recipeId - The input recipe to run.
+ * @param budget - The sample budget; unset runs the recipe to completion (still capped by its own `limits`).
+ * @param callbacks - Where trace lines and records go as the run proceeds.
+ * @returns A handle: `stop` closes the crawler cleanly, `result` resolves when the run ends.
+ * @throws RecipeValidationError, RecipeBindingError, Error when the recipe or its output cannot be loaded or bound.
+ */
+export declare function runSample(folder: string, recipeId: string, budget: SampleBudget | undefined, callbacks: SampleRunCallbacks): Promise<SampleRunHandle>;
+//# sourceMappingURL=run-sample.use-case.d.ts.map

package/dist/src/sample-run/sample-run-record.contract.d.ts

@@ -0,0 +1,19 @@
+/** One record streamed or kept from a sample run. */
+export interface SampleRunRecord {
+    key: string | null;
+    data: Record<string, unknown>;
+}
+/** A sample run's stopping reason: mirrors `@opencraw/core`'s `RecipeReport.stoppedBy`. */
+export type SampleStoppedBy = 'sample-maxRecords' | 'sample-maxPages' | 'sample-maxMs';
+/** What a sample run finished with. */
+export interface SampleRunResult {
+    recipeId: string;
+    emitted: number;
+    rejected: number;
+    duplicates: number;
+    durationMs: number;
+    error?: string;
+    stoppedBy?: SampleStoppedBy;
+    records: SampleRunRecord[];
+}
+//# sourceMappingURL=sample-run-record.contract.d.ts.map

package/dist/src/studio-api/command.contract.d.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+/** A budget for a sample run; never authored into a recipe, only asked for by the caller. */
+export declare const sampleBudgetSchema: z.ZodObject<{
+    maxRecords: z.ZodOptional<z.ZodNumber>;
+    maxPages: z.ZodOptional<z.ZodNumber>;
+    maxMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Opens a recipe folder: the server reads it and answers with a `WorkspaceView`. */
+export declare const openWorkspaceCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"open-workspace">;
+    folder: z.ZodString;
+}, z.core.$strip>;
+/** Runs one input recipe under a budget, streaming `trace-line` and `record` events, ending in `run-finished`. */
+export declare const runSampleCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"run-sample">;
+    recipeId: z.ZodString;
+    budget: z.ZodOptional<z.ZodObject<{
+        maxRecords: z.ZodOptional<z.ZodNumber>;
+        maxPages: z.ZodOptional<z.ZodNumber>;
+        maxMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Closes the crawler of the run in progress, if any; a no-op otherwise. */
+export declare const stopRunCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"stop-run">;
+}, z.core.$strip>;
+/** Writes a recipe file: the whole object, pretty-printed by the server (see `recipe-workspace`). */
+export declare const saveRecipeCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"save-recipe">;
+    path: z.ZodString;
+    recipe: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+/** Fetches the HTML of an input recipe's start page, as the engine would see it. */
+export declare const fetchStartPageCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"fetch-start-page">;
+    recipeId: z.ZodString;
+}, z.core.$strip>;
+export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"open-workspace">;
+    folder: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"run-sample">;
+    recipeId: z.ZodString;
+    budget: z.ZodOptional<z.ZodObject<{
+        maxRecords: z.ZodOptional<z.ZodNumber>;
+        maxPages: z.ZodOptional<z.ZodNumber>;
+        maxMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"stop-run">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"save-recipe">;
+    path: z.ZodString;
+    recipe: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"fetch-start-page">;
+    recipeId: z.ZodString;
+}, z.core.$strip>], "type">;
+export type SampleBudget = z.infer<typeof sampleBudgetSchema>;
+export type OpenWorkspaceCommand = z.infer<typeof openWorkspaceCommandSchema>;
+export type RunSampleCommand = z.infer<typeof runSampleCommandSchema>;
+export type StopRunCommand = z.infer<typeof stopRunCommandSchema>;
+export type SaveRecipeCommand = z.infer<typeof saveRecipeCommandSchema>;
+export type FetchStartPageCommand = z.infer<typeof fetchStartPageCommandSchema>;
+/** Every command the UI can send the server, over HTTP POST. */
+export type StudioCommand = z.infer<typeof studioCommandSchema>;
+//# sourceMappingURL=command.contract.d.ts.map

package/dist/src/studio-api/event.contract.d.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+/** Why a sample run stopped before finishing on its own; mirrors `@opencraw/core`'s `RecipeReport.stoppedBy`. */
+export declare const stoppedBySchema: z.ZodEnum<{
+    "sample-maxRecords": "sample-maxRecords";
+    "sample-maxPages": "sample-maxPages";
+    "sample-maxMs": "sample-maxMs";
+}>;
+/** One line of the engine's own trace output (`traceLine`), streamed as a sample run proceeds. */
+export declare const traceLineEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"trace-line">;
+    line: z.ZodString;
+}, z.core.$strip>;
+/** One record a sample run emitted. */
+export declare const recordEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"record">;
+    recipeId: z.ZodString;
+    key: z.ZodNullable<z.ZodString>;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+/** A sample run ended: how many records, and why it stopped when it did not finish on its own. */
+export declare const runFinishedEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"run-finished">;
+    recipeId: z.ZodString;
+    emitted: z.ZodNumber;
+    rejected: z.ZodNumber;
+    duplicates: z.ZodNumber;
+    durationMs: z.ZodNumber;
+    error: z.ZodOptional<z.ZodString>;
+    stoppedBy: z.ZodOptional<z.ZodEnum<{
+        "sample-maxRecords": "sample-maxRecords";
+        "sample-maxPages": "sample-maxPages";
+        "sample-maxMs": "sample-maxMs";
+    }>>;
+}, z.core.$strip>;
+/** The workspace's recipes changed on disk (a save, or a future watcher) and should be re-fetched. */
+export declare const workspaceChangedEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"workspace-changed">;
+}, z.core.$strip>;
+export declare const studioEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"trace-line">;
+    line: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"record">;
+    recipeId: z.ZodString;
+    key: z.ZodNullable<z.ZodString>;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"run-finished">;
+    recipeId: z.ZodString;
+    emitted: z.ZodNumber;
+    rejected: z.ZodNumber;
+    duplicates: z.ZodNumber;
+    durationMs: z.ZodNumber;
+    error: z.ZodOptional<z.ZodString>;
+    stoppedBy: z.ZodOptional<z.ZodEnum<{
+        "sample-maxRecords": "sample-maxRecords";
+        "sample-maxPages": "sample-maxPages";
+        "sample-maxMs": "sample-maxMs";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"workspace-changed">;
+}, z.core.$strip>], "type">;
+export type StoppedBy = z.infer<typeof stoppedBySchema>;
+export type TraceLineEvent = z.infer<typeof traceLineEventSchema>;
+export type RecordEvent = z.infer<typeof recordEventSchema>;
+export type RunFinishedEvent = z.infer<typeof runFinishedEventSchema>;
+export type WorkspaceChangedEvent = z.infer<typeof workspaceChangedEventSchema>;
+/** Every event the server pushes to the UI over the WebSocket. */
+export type StudioEvent = z.infer<typeof studioEventSchema>;
+//# sourceMappingURL=event.contract.d.ts.map

package/dist/src/studio-api/index.d.ts

@@ -0,0 +1,11 @@
+export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, studioCommandSchema } from './command.contract.js';
+export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, StudioCommand } from './command.contract.js';
+export { stoppedBySchema, traceLineEventSchema, recordEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema } from './event.contract.js';
+export type { StoppedBy, TraceLineEvent, RecordEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent } from './event.contract.js';
+export { recipeIssueSchema, recipeListingSchema, workspaceViewSchema } from './workspace-view.contract.js';
+export type { RecipeIssue, RecipeListing, WorkspaceView } from './workspace-view.contract.js';
+export { sampleRunRecordSchema, sampleRunViewSchema } from './sample-run-view.contract.js';
+export type { SampleRunRecord, SampleRunView } from './sample-run-view.contract.js';
+export { startPageViewSchema } from './start-page-view.contract.js';
+export type { StartPageView } from './start-page-view.contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/studio-api/sample-run-view.contract.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+/** One record of a sample run's result, kept for the Records tab. */
+export declare const sampleRunRecordSchema: z.ZodObject<{
+    key: z.ZodNullable<z.ZodString>;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+/** The last sample run's result, for a client that opens the UI after it finished. */
+export declare const sampleRunViewSchema: z.ZodObject<{
+    recipeId: z.ZodString;
+    emitted: z.ZodNumber;
+    rejected: z.ZodNumber;
+    duplicates: z.ZodNumber;
+    durationMs: z.ZodNumber;
+    error: z.ZodOptional<z.ZodString>;
+    stoppedBy: z.ZodOptional<z.ZodEnum<{
+        "sample-maxRecords": "sample-maxRecords";
+        "sample-maxPages": "sample-maxPages";
+        "sample-maxMs": "sample-maxMs";
+    }>>;
+    records: z.ZodArray<z.ZodObject<{
+        key: z.ZodNullable<z.ZodString>;
+        data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+    trace: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type SampleRunRecord = z.infer<typeof sampleRunRecordSchema>;
+export type SampleRunView = z.infer<typeof sampleRunViewSchema>;
+//# sourceMappingURL=sample-run-view.contract.d.ts.map

package/dist/src/studio-api/start-page-view.contract.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+/** What `fetch-start-page` answers with. */
+export declare const startPageViewSchema: z.ZodObject<{
+    html: z.ZodString;
+}, z.core.$strip>;
+export type StartPageView = z.infer<typeof startPageViewSchema>;
+//# sourceMappingURL=start-page-view.contract.d.ts.map

package/dist/src/studio-api/workspace-view.contract.d.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+/** One problem found on a recipe file, with the JSON path it lives at. */
+export declare const recipeIssueSchema: z.ZodObject<{
+    path: z.ZodString;
+    message: z.ZodString;
+    kind: z.ZodEnum<{
+        validation: "validation";
+        binding: "binding";
+    }>;
+}, z.core.$strip>;
+/** One recipe file in an opened workspace. */
+export declare const recipeListingSchema: z.ZodObject<{
+    file: z.ZodString;
+    kind: z.ZodEnum<{
+        unknown: "unknown";
+        input: "input";
+        output: "output";
+    }>;
+    id: z.ZodOptional<z.ZodString>;
+    issues: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        message: z.ZodString;
+        kind: z.ZodEnum<{
+            validation: "validation";
+            binding: "binding";
+        }>;
+    }, z.core.$strip>>;
+    text: z.ZodString;
+}, z.core.$strip>;
+/** What `open-workspace` answers with: every recipe file directly inside the folder. */
+export declare const workspaceViewSchema: z.ZodObject<{
+    folder: z.ZodString;
+    recipes: z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        kind: z.ZodEnum<{
+            unknown: "unknown";
+            input: "input";
+            output: "output";
+        }>;
+        id: z.ZodOptional<z.ZodString>;
+        issues: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            message: z.ZodString;
+            kind: z.ZodEnum<{
+                validation: "validation";
+                binding: "binding";
+            }>;
+        }, z.core.$strip>>;
+        text: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RecipeIssue = z.infer<typeof recipeIssueSchema>;
+export type RecipeListing = z.infer<typeof recipeListingSchema>;
+export type WorkspaceView = z.infer<typeof workspaceViewSchema>;
+//# sourceMappingURL=workspace-view.contract.d.ts.map

package/dist/src/studio-server/access-token.policy.d.ts

@@ -0,0 +1,26 @@
+import type { IncomingMessage } from 'node:http';
+/** The cookie set on the page's own document response, so its own asset and API requests carry the token too. */
+export declare const TOKEN_COOKIE = "opencraw_token";
+/** A random token, generated once at server startup and required on every request. */
+export declare function generateToken(): string;
+/**
+ * The token a request carries, checked in this order: the `x-opencraw-token`
+ * header, the `token` query param, the studio's own cookie (set after the
+ * first authenticated document request, so a browser's own asset and API
+ * requests need not repeat the query param).
+ *
+ * @param request - The incoming request.
+ * @param query - Its URL's query string, parsed.
+ * @returns The token found, or `undefined`.
+ */
+export declare function tokenOf(request: Pick<IncomingMessage, 'headers'>, query: URLSearchParams): string | undefined;
+/**
+ * Whether a request proves it holds the server's token.
+ *
+ * @param expected - The server's token.
+ * @param request - The incoming request.
+ * @param query - Its URL's query string, parsed.
+ * @returns Whether the request is authorized.
+ */
+export declare function isAuthorized(expected: string, request: Pick<IncomingMessage, 'headers'>, query: URLSearchParams): boolean;
+//# sourceMappingURL=access-token.policy.d.ts.map

package/dist/src/studio-server/fetch-start-page.handler.d.ts

@@ -0,0 +1,14 @@
+import type { FetchStartPageCommand, StartPageView } from '../studio-api/index.js';
+import type { StudioState } from './workspace.store.js';
+/**
+ * Handles `fetch-start-page`: loads the named input recipe from the current
+ * workspace and fetches its start point (see `page-snapshot`'s own caveats:
+ * no session bootstrap, a fresh browser or HTTP context per call).
+ *
+ * @param state - The server state: `folder` must already be set.
+ * @param command - The command.
+ * @returns The page's content as plain text.
+ * @throws Error when no workspace is open, or the recipe cannot be found or loaded.
+ */
+export declare function handleFetchStartPage(state: StudioState, command: FetchStartPageCommand): Promise<StartPageView>;
+//# sourceMappingURL=fetch-start-page.handler.d.ts.map

package/dist/src/studio-server/index.d.ts

@@ -0,0 +1,3 @@
+export { startStudioServer } from './studio-http.use-case.js';
+export type { StudioServer, StudioServerOptions } from './studio-http.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/studio-server/open-workspace.handler.d.ts

@@ -0,0 +1,13 @@
+import type { OpenWorkspaceCommand, WorkspaceView } from '../studio-api/index.js';
+import type { StudioState } from './workspace.store.js';
+/**
+ * Handles `open-workspace`: reads the folder, remembers it as the server's
+ * current workspace (every later command that names a recipe resolves it
+ * against this folder), and tells every connected client the workspace changed.
+ *
+ * @param state - The server state to update.
+ * @param command - The command.
+ * @returns The workspace's recipes and their issues.
+ */
+export declare function handleOpenWorkspace(state: StudioState, command: OpenWorkspaceCommand): Promise<WorkspaceView>;
+//# sourceMappingURL=open-workspace.handler.d.ts.map

package/dist/src/studio-server/run-sample.handler.d.ts

@@ -0,0 +1,28 @@
+import type { RunSampleCommand, StopRunCommand } from '../studio-api/index.js';
+import type { StudioState } from './workspace.store.js';
+/**
+ * Handles `run-sample`: stops whatever sample was still running (one run at
+ * a time), starts the new one, and returns once it has started, not once it
+ * finishes: `trace-line` and `record` stream over the WebSocket as the run
+ * proceeds, and `run-finished` closes it out.
+ *
+ * @param state - The server state: `folder` must already be set (`open-workspace` first).
+ * @param command - The command.
+ * @returns `{ started: true }` once the run has begun.
+ * @throws Error when no workspace is open, or the recipe cannot be loaded or bound.
+ */
+export declare function handleRunSample(state: StudioState, command: RunSampleCommand): Promise<{
+    started: true;
+}>;
+/**
+ * Handles `stop-run`: closes the crawler of the run in progress, if any.
+ * `run-finished` still follows once the interrupted run's promise settles.
+ *
+ * @param state - The server state holding the active run, if any.
+ * @param _command - The command (carries nothing beyond its type).
+ * @returns Whether a run was actually in progress to stop.
+ */
+export declare function handleStopRun(state: StudioState, _command: StopRunCommand): Promise<{
+    stopped: boolean;
+}>;
+//# sourceMappingURL=run-sample.handler.d.ts.map

package/dist/src/studio-server/save-recipe.handler.d.ts

@@ -0,0 +1,15 @@
+import type { SaveRecipeCommand } from '../studio-api/index.js';
+import type { StudioState } from './workspace.store.js';
+/**
+ * Handles `save-recipe`: writes the file (see `recipe-workspace/save-recipe.use-case.ts`
+ * for the pretty-printing and its round-trip guarantee), then tells every
+ * connected client the workspace changed, so the UI can re-fetch it.
+ *
+ * @param state - The server state holding the connected sockets.
+ * @param command - The command: the file path and the whole recipe object.
+ * @returns `{ saved: true }` once the write has completed.
+ */
+export declare function handleSaveRecipe(state: StudioState, command: SaveRecipeCommand): Promise<{
+    saved: true;
+}>;
+//# sourceMappingURL=save-recipe.handler.d.ts.map

package/dist/src/studio-server/static-file.handler.d.ts

@@ -0,0 +1,14 @@
+import type { ServerResponse } from 'node:http';
+/**
+ * Serves the built UI from `root` (`packages/studio/dist/ui`, `apps/studio-ui`'s
+ * build output): the requested path if it exists as a file, `index.html`
+ * otherwise, so a client-side route (or the bare `/`) always gets the SPA's
+ * shell. `root` not existing at all (the UI has not been built) answers 404
+ * with a hint rather than a stack trace.
+ *
+ * @param root - The built UI's folder.
+ * @param pathname - The request's URL path.
+ * @param response - The response to write to.
+ */
+export declare function serveStatic(root: string, pathname: string, response: ServerResponse): void;
+//# sourceMappingURL=static-file.handler.d.ts.map

package/dist/src/studio-server/studio-http.use-case.d.ts

@@ -0,0 +1,32 @@
+export interface StudioServerOptions {
+    /** Where the built UI lives; default: `dist/ui` next to the running server code. */
+    uiRoot?: string;
+    /** A fixed port; default: an OS-assigned free port. */
+    port?: number;
+    /**
+     * The folder `opencraw-studio` was started with, if any: set as the
+     * server's current workspace right away, so `run-sample`, `save-recipe`
+     * and `fetch-start-page` work immediately, before the UI's own
+     * `open-workspace` call (which it still makes, to get the recipe listing;
+     * the folder reaches it through the URL's `folder` query param).
+     */
+    initialFolder?: string;
+}
+/** The running server: its URL (token included, ready to open), the token alone, and how to stop it. */
+export interface StudioServer {
+    url: string;
+    token: string;
+    close: () => Promise<void>;
+}
+/**
+ * Starts the studio's HTTP server: one `POST /api/command` for every
+ * command `studio-api` defines, `GET /ws` for the event stream, and the
+ * built UI for everything else. Binds `127.0.0.1` only; every request needs
+ * the token (`access-token.policy.ts`) — as a header, a query param, or the
+ * cookie the server sets once a document request proves the query param.
+ *
+ * @param options - The UI root and the port; both default sensibly.
+ * @returns The running server.
+ */
+export declare function startStudioServer(options?: StudioServerOptions): Promise<StudioServer>;
+//# sourceMappingURL=studio-http.use-case.d.ts.map

package/dist/src/studio-server/websocket.client.d.ts

@@ -0,0 +1,22 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+/** One accepted WebSocket connection: text frames only, no compression, no fragmentation. */
+export interface WsConnection {
+    send: (text: string) => void;
+    close: () => void;
+    onMessage: (handler: (text: string) => void) => void;
+    onClose: (handler: () => void) => void;
+}
+/**
+ * Accepts one WebSocket upgrade on the raw socket `node:http` hands an
+ * `upgrade` listener, implementing just enough of RFC 6455 for the studio's
+ * own one-directional event stream: the server sends small JSON text
+ * frames, the client sends none (commands go over `POST /api/command`). No
+ * `ws` dependency: this is deliberately small rather than general-purpose.
+ *
+ * @param request - The upgrade request (its `Sec-WebSocket-Key` header).
+ * @param socket - The raw, already-connected socket.
+ * @returns The connection: `send`, `close`, and where messages and the close go.
+ */
+export declare function acceptWebSocket(request: IncomingMessage, socket: Duplex): WsConnection;
+//# sourceMappingURL=websocket.client.d.ts.map

package/dist/src/studio-server/workspace.store.d.ts

@@ -0,0 +1,21 @@
+import type { SampleRunHandle } from '../sample-run/index.js';
+import type { StudioEvent } from '../studio-api/index.js';
+import type { WsConnection } from './websocket.client.js';
+/** The server's mutable state: the opened folder, the run in progress (if any), and the connected event sockets. */
+export interface StudioState {
+    folder?: string;
+    activeRun?: SampleRunHandle;
+    sockets: Set<WsConnection>;
+}
+/** @returns Fresh state for a new server instance: no workspace open, no run, no sockets. */
+export declare function createStudioState(): StudioState;
+/**
+ * Sends one event to every connected client. A socket that errors while
+ * sending (gone away without a clean close yet reaching us) is dropped
+ * rather than left to fail every later broadcast too.
+ *
+ * @param state - The server state holding the connected sockets.
+ * @param event - The event to send.
+ */
+export declare function broadcast(state: StudioState, event: StudioEvent): void;
+//# sourceMappingURL=workspace.store.d.ts.map