@verbatra/studio 0.1.0-next.1

package/dist/index.d.ts

@@ -0,0 +1,115 @@
+import { LoadedConfig, SdkFs, CheckDeps } from '@verbatra/sdk';
+
+/** The result of one `execFileImpl` call: captured stdout and stderr, never a raw child_process error. */
+interface ExecFileResult {
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * A bounded, argument-array process runner: `execFile(file, args, options)`, never a shell string.
+ * Mirrors `util.promisify(child_process.execFile)`. Consumed by the git-log history view, which
+ * runs `git` with an explicit `cwd` and never a `--follow` or other unbounded argument.
+ */
+type ExecFileImpl = (file: string, args: readonly string[], options: {
+    readonly cwd: string;
+}) => Promise<ExecFileResult>;
+/**
+ * A minimal change-event source for the live-refresh stream. Mirrors the shape of the sdk's own
+ * `Watcher` (see `@verbatra/sdk`'s `watch.ts`) but is studio-owned: production wraps chokidar directly
+ * (a studio dependency in its own right), tests inject a stub.
+ */
+interface StudioWatcher {
+    /** Register a listener invoked once per coalesced, debounced change event. */
+    onChange(listener: () => void): void;
+    /** Stop watching and release the underlying resources. */
+    close(): Promise<void>;
+}
+/** Builds a {@link StudioWatcher} over the given paths (the source file, target files, and the lock-file). */
+type CreateStudioWatcher = (paths: readonly string[]) => StudioWatcher;
+/**
+ * Every dependency an RPC handler or the server itself may need, across the whole dashboard, fully
+ * pre-declared up front so later handlers never widen this type. Most fields are unused until a
+ * later view lands; each doc comment names what consumes it.
+ */
+interface StudioServerDeps {
+    /**
+     * Resolves the project configuration exactly once, at server startup, before the server starts
+     * listening. Every RPC handler receives that same resolved value for the life of the process; it
+     * is never re-invoked per request, and the server holds no other project-derived cache. Consumed
+     * by every RPC handler, starting with the project configuration snapshot.
+     */
+    readonly loader: () => Promise<LoadedConfig>;
+    /** Bounded file-system seam for the status and diff drift views. */
+    readonly fs?: SdkFs;
+    /** Format-adapter registry override for the status and diff drift views; defaults to the sdk's own registry. */
+    readonly adapterRegistry?: NonNullable<CheckDeps["adapterRegistry"]>;
+    /** Bounded, argument-array process runner for the git-log history view. */
+    readonly execFileImpl?: ExecFileImpl;
+    /** Factory for the file watcher backing the live-refresh event stream. */
+    readonly createWatcher?: CreateStudioWatcher;
+    /** Interval between live-refresh heartbeat frames; injected so tests never depend on a real timer. */
+    readonly heartbeatIntervalMs?: number;
+    /** Bootstrap token the server accepts. Omit to have the server generate one from secure randomness. */
+    readonly token?: string;
+    /** Sink for the startup banner and the per-request log line. Defaults to writing to the console. */
+    readonly output?: (line: string) => void;
+    /** Overrides where static assets are served from; defaults to the built SPA next to this module. */
+    readonly assetsRoot?: URL;
+}
+/** Options accepted by {@link startStudioServer}: every {@link StudioServerDeps} field, plus the bind port and cwd. */
+interface StudioServerOptions extends StudioServerDeps {
+    /** TCP port to bind. Omit for the default Studio port, or pass 0 to let the OS assign an ephemeral port (tests only). */
+    readonly port?: number;
+    /**
+     * The project root every RPC handler resolves relative paths against: the source locale file,
+     * each target locale file, the lock file, and the git repository root for the history view.
+     * Omit to use `process.cwd()`, which is also the behavior of any existing caller that does not
+     * pass this.
+     */
+    readonly cwd?: string;
+}
+/** A running Verbatra Studio server instance. */
+interface StudioServer {
+    /** The loopback URL the server is reachable at, including the actual bound port. */
+    readonly url: string;
+    /** The actual bound TCP port (relevant when `port` was omitted or 0). */
+    readonly port: number;
+    /** Stops accepting new connections and closes the server. */
+    close(): Promise<void>;
+}
+
+/**
+ * Starts the local Verbatra Studio server: a loopback-only HTTP server that serves the prebuilt
+ * SPA and gates every request behind a Host and Origin check, a bootstrap token, and a session
+ * cookie. There is no host option and no relaxed mode; the printed loopback URL, shown once at
+ * startup, is the only supported entry point.
+ *
+ * `options.loader` is resolved exactly once here, before the server starts listening (G11): every
+ * RPC handler for the life of this process receives that same resolved config, and it is never
+ * re-invoked on a later request, whatever the request does.
+ *
+ * Every RPC handler resolves relative paths against `options.cwd` when given, or `process.cwd()`
+ * otherwise; see {@link StudioServerOptions.cwd}.
+ */
+declare function startStudioServer(options: StudioServerOptions): Promise<StudioServer>;
+
+/**
+ * The port Verbatra Studio listens on when the caller does not specify one. Chosen once so the
+ * printed URL is stable and bookmarkable; there is no fallback to another port if it is busy.
+ */
+declare const DEFAULT_STUDIO_PORT = 5849;
+
+/** Stable, machine-readable codes for a failure to start the local server. */
+type StudioServerErrorCode = "PORT_IN_USE" | "BIND_FAILED";
+/**
+ * A structured error for a failure to start the server, so a caller can branch on {@link code}
+ * instead of parsing a message. The message is always a fixed, safe string; it never embeds a
+ * filesystem path or other environment detail.
+ */
+declare class StudioServerStartError extends Error {
+    readonly code: StudioServerErrorCode;
+    readonly port: number;
+    constructor(code: StudioServerErrorCode, port: number, message: string);
+}
+
+export { type CreateStudioWatcher, DEFAULT_STUDIO_PORT, type ExecFileImpl, type ExecFileResult, type StudioServer, type StudioServerDeps, type StudioServerErrorCode, type StudioServerOptions, StudioServerStartError, type StudioWatcher, startStudioServer };