@theruntime/protocol 0.0.0 → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Digital Pine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "@theruntime/protocol",
-  "version": "0.0.0",
-  "description": "Placeholder. The first release replaces it.",
+  "version": "0.0.1",
   "license": "MIT",
-  "publishConfig": {
-    "access": "public"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DigitalPine/runtime.git",
+    "directory": "packages/protocol"
+  },
+  "files": [
+    "src",
+    "!**/*.test.ts",
+    "!**/*.test.tsx"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
   }
 }

package/src/error.ts

@@ -0,0 +1,54 @@
+export const ERROR_CODES = [
+  "NOT_FOUND",
+  "INVALID_INPUT",
+  "CONFLICT",
+  "FORBIDDEN",
+  "INTERNAL",
+] as const;
+
+export type ErrorCode = (typeof ERROR_CODES)[number];
+
+export interface ProtocolError {
+  readonly code: ErrorCode;
+  readonly message: string;
+  readonly details?: unknown;
+  readonly retryable: boolean;
+}
+
+export function makeProtocolError(
+  code: ErrorCode,
+  message: string,
+  options: { readonly retryable: boolean; readonly details?: unknown },
+): ProtocolError {
+  return options.details !== undefined
+    ? { code, message, details: options.details, retryable: options.retryable }
+    : { code, message, retryable: options.retryable };
+}
+
+export function parseProtocolError(value: unknown): ProtocolError {
+  if (typeof value !== "object" || value === null) {
+    throw new Error("a protocol error is an object");
+  }
+  if (!("code" in value) || typeof value.code !== "string" || !isErrorCode(value.code)) {
+    throw new Error(`a protocol error names one of: ${ERROR_CODES.join(", ")}`);
+  }
+  if (!("message" in value) || typeof value.message !== "string" || value.message.length === 0) {
+    throw new Error("a protocol error carries a message");
+  }
+  if (!("retryable" in value) || typeof value.retryable !== "boolean") {
+    throw new Error("a protocol error states whether it is retryable");
+  }
+  return makeProtocolError(value.code, value.message, {
+    retryable: value.retryable,
+    details: "details" in value ? value.details : undefined,
+  });
+}
+
+export function serializeProtocolError(error: ProtocolError): string {
+  return JSON.stringify(error);
+}
+
+function isErrorCode(value: string): value is ErrorCode {
+  const codes: readonly string[] = ERROR_CODES;
+  return codes.includes(value);
+}

package/src/events/index.ts

@@ -0,0 +1,51 @@
+/** The event surface, re-exported by the package barrel as one line. */
+export { EVENT_KINDS, isEventKind, parseEvent, serializeEvent } from "../notifications/event";
+export type { Event, EventKind } from "../notifications/event";
+
+export {
+  parseEmitEventInput,
+  serializeEmitEventInput,
+  parseEmitEventResult,
+  serializeEmitEventResult,
+} from "../operations/emit-event";
+export type { EmitEventInput, EmitEventResult } from "../operations/emit-event";
+
+export {
+  parseSubscribeInput,
+  serializeSubscribeInput,
+  parseSubscribeResult,
+  serializeSubscribeResult,
+} from "../operations/subscribe";
+export type { SubscribeInput, SubscribeResult } from "../operations/subscribe";
+
+export {
+  parseUnsubscribeInput,
+  serializeUnsubscribeInput,
+  parseUnsubscribeResult,
+  serializeUnsubscribeResult,
+} from "../operations/unsubscribe";
+export type { UnsubscribeInput, UnsubscribeResult } from "../operations/unsubscribe";
+
+export {
+  parseListSubscribersInput,
+  serializeListSubscribersInput,
+  parseListSubscribersResult,
+  serializeListSubscribersResult,
+} from "../operations/list-subscribers";
+export type {
+  ListSubscribersInput,
+  ListSubscribersResult,
+  SubscriberSummary,
+} from "../operations/list-subscribers";
+
+export {
+  parseListSubscriptionsInput,
+  serializeListSubscriptionsInput,
+  parseListSubscriptionsResult,
+  serializeListSubscriptionsResult,
+} from "../operations/list-subscriptions";
+export type {
+  ListSubscriptionsInput,
+  ListSubscriptionsResult,
+  SubscriptionSummary,
+} from "../operations/list-subscriptions";

package/src/guidance/index.ts

@@ -0,0 +1,3 @@
+/** The guidance surface, re-exported by the package barrel as one line. */
+export { parseGuidance, parseRegister, serializeGuidance } from "../operations/guidance";
+export type { Guidance, Register } from "../operations/guidance";

package/src/index.ts

@@ -0,0 +1,46 @@
+export { OPERATIONS } from "./operations";
+export type { OperationName } from "./operations";
+
+export { NOTIFICATIONS } from "./notifications";
+export type { NotificationName } from "./notifications";
+
+export { APP_ACTIONS, isAppActionName } from "./payloads";
+export type { AppActionName } from "./payloads";
+
+export { parseAppReadyPayload, serializeAppReadyPayload } from "./payloads/app-ready";
+export type { AppReadyPayload } from "./payloads/app-ready";
+
+export { CRASH_REFUSED_ACTION, parseRouteRefusal, type RouteRefusal } from "./payloads/refusal";
+export { serializeRouteRefusal } from "./payloads/refusal";
+
+export {
+  APP_READINESS_STATES,
+  APP_READY_WINDOW_MS,
+  isAppReadinessState,
+  parseAppReadiness,
+  serializeAppReadiness,
+} from "./readiness";
+export type { AppReadiness, AppReadinessState } from "./readiness";
+
+export { PROTOCOL_VERSION } from "./version";
+export type { ProtocolVersion } from "./version";
+
+export {
+  ERROR_CODES,
+  makeProtocolError,
+  parseProtocolError,
+  serializeProtocolError,
+} from "./error";
+export type { ErrorCode, ProtocolError } from "./error";
+
+export * from "./events";
+export * from "./guidance";
+export * from "./logs";
+export * from "./quick-actions";
+export * from "./records";
+export * from "./routes";
+export * from "./selection";
+export * from "./sessions";
+export * from "./snapshots";
+export * from "./templates";
+export * from "./toolchain";

package/src/logs/index.ts

@@ -0,0 +1,46 @@
+/** The log surface, re-exported by the package barrel as one line. */
+export {
+  isLogLevel,
+  isLogTag,
+  LOG_LEVELS,
+  LOG_READ_LIMIT,
+  LOG_READ_LIMIT_MAX,
+  LOG_TAGS,
+  meetsLevel,
+  parseLogLine,
+  parseLogReadResult,
+  serializeLogLine,
+  serializeLogReadResult,
+} from "../operations/log-line";
+export type {
+  LogEntry,
+  LogLevel,
+  LogLine,
+  LogReadFilter,
+  LogReadResult,
+  LogTag,
+  LogValue,
+} from "../operations/log-line";
+
+export { parseReadRouteLogInput, serializeReadRouteLogInput } from "../operations/read-route-log";
+export type { ReadRouteLogInput } from "../operations/read-route-log";
+
+export {
+  parseReadDaemonLogInput,
+  serializeReadDaemonLogInput,
+} from "../operations/read-daemon-log";
+export type { ReadDaemonLogInput } from "../operations/read-daemon-log";
+
+export {
+  parseListRouteLogsInput,
+  serializeListRouteLogsInput,
+  parseListRouteLogsResult,
+  serializeListRouteLogsResult,
+  ROUTE_LOGS_LIMIT,
+  ROUTE_LOGS_LIMIT_MAX,
+} from "../operations/list-route-logs";
+export type {
+  ListRouteLogsInput,
+  ListRouteLogsResult,
+  RouteLogSummary,
+} from "../operations/list-route-logs";

package/src/notifications/event.ts

@@ -0,0 +1,62 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import {
+  asRecord,
+  requireNotification,
+  requireProtocol,
+  requireString,
+} from "../operations/parse-helpers";
+
+const NOUN = "an event";
+
+// "app" is something the app's own code emitted. "route" is what the daemon reports about a
+// route's process. "missed" is the daemon's own signal, synthesized when a subscription's
+// cursor falls behind the retained log.
+export const EVENT_KINDS = ["app", "route", "missed"] as const;
+export type EventKind = (typeof EVENT_KINDS)[number];
+
+export function isEventKind(value: unknown): value is EventKind {
+  if (typeof value !== "string") return false;
+  const kinds: readonly string[] = EVENT_KINDS;
+  return kinds.includes(value);
+}
+
+export interface Event {
+  readonly notification: "event";
+  readonly protocol: ProtocolVersion;
+  // The log position this event occupies. For a "missed" event, the position a
+  // subscription's cursor should advance to, past the pruned gap.
+  readonly id: number;
+  readonly name: string;
+  readonly kind: EventKind;
+  readonly action: string;
+  // Payload is JSON, validated at the boundary.
+  readonly payload: unknown;
+}
+
+export function parseEvent(value: unknown): Event {
+  const record = asRecord(value, NOUN);
+  requireNotification(record, "event", NOUN);
+  requireProtocol(record, NOUN);
+  if (typeof record.id !== "number" || !Number.isInteger(record.id) || record.id < 0) {
+    throw new Error(`${NOUN} names a non-negative integer id`);
+  }
+  const name = requireString(record, "name", NOUN);
+  if (!isEventKind(record.kind)) {
+    throw new Error(`${NOUN} names a kind of: ${EVENT_KINDS.join(", ")}`);
+  }
+  const action = requireString(record, "action", NOUN);
+  if (!("payload" in record)) throw new Error(`${NOUN} carries a payload`);
+  return {
+    notification: "event",
+    protocol: PROTOCOL_VERSION,
+    id: record.id,
+    name,
+    kind: record.kind,
+    action,
+    payload: record.payload,
+  };
+}
+
+export function serializeEvent(event: Event): string {
+  return JSON.stringify(event);
+}

package/src/notifications.ts

@@ -0,0 +1,5 @@
+// Every notification the protocol defines. Each name's shape lives in its own file under
+// ./notifications.
+export const NOTIFICATIONS = ["event"] as const;
+
+export type NotificationName = (typeof NOTIFICATIONS)[number];

package/src/operations/add-component.ts

@@ -0,0 +1,121 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import {
+  asRecord,
+  optionalString,
+  requireOperation,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "an addComponent input";
+const RESULT_NOUN = "an addComponent result";
+
+/** Where a component is copied from. The runtime's own package, or the route's host project. */
+export const COMPONENT_SOURCES = ["runtime", "host"] as const;
+
+export type ComponentSource = (typeof COMPONENT_SOURCES)[number];
+
+export function isComponentSource(value: unknown): value is ComponentSource {
+  if (typeof value !== "string") return false;
+  const sources: readonly string[] = COMPONENT_SOURCES;
+  return sources.includes(value);
+}
+
+export interface AddComponentInput {
+  readonly operation: "addComponent";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+  readonly component: string;
+  readonly source: ComponentSource;
+}
+
+export function parseAddComponentInput(value: unknown): AddComponentInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "addComponent", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  const component = requireString(record, "component", NOUN);
+  const source = optionalString(record, "source", NOUN);
+  if (source !== undefined && !isComponentSource(source)) {
+    throw new Error(`${NOUN}'s source is one of ${COMPONENT_SOURCES.join(", ")}`);
+  }
+  return {
+    operation: "addComponent",
+    protocol: PROTOCOL_VERSION,
+    name,
+    component,
+    source: source ?? "runtime",
+  };
+}
+
+export function serializeAddComponentInput(input: AddComponentInput): string {
+  return JSON.stringify(input);
+}
+
+/**
+ * One components-package import an app file still names after the copy. A symbol the barrel does
+ * not re-export as a value, a component the app does not own, and a namespace, default, or
+ * re-export form all stay on the package. A namespace reads as "*" and a default as "default".
+ */
+export interface LeftImport {
+  /** The app's own file that carries it, relative to the app directory. */
+  readonly file: string;
+  /** The package specifier the import still names. */
+  readonly specifier: string;
+  readonly symbols: readonly string[];
+}
+
+export interface AddComponentResult {
+  readonly name: string;
+  readonly component: string;
+  readonly source: ComponentSource;
+  /** The files this call wrote, relative to the app directory. */
+  readonly copied: readonly string[];
+  /** The files the app already owned, left byte-identical. */
+  readonly present: readonly string[];
+  /** The app's own files whose imports this call pointed at the copy. */
+  readonly rewritten: readonly string[];
+  /** What the app still imports from the package, so a caller sees what the copy did not take. */
+  readonly left: readonly LeftImport[];
+}
+
+function stringArray(record: Record<string, unknown>, field: string): readonly string[] {
+  const value = record[field];
+  if (!Array.isArray(value) || !value.every((entry): entry is string => typeof entry === "string"))
+    throw new Error(`${RESULT_NOUN} names the ${field} files`);
+  return value;
+}
+
+function leftImports(record: Record<string, unknown>): readonly LeftImport[] {
+  const value = record.left;
+  if (!Array.isArray(value)) throw new Error(`${RESULT_NOUN} names the left imports`);
+  return value.map((entry) => {
+    const one = asRecord(entry, `${RESULT_NOUN}'s left import`);
+    return {
+      file: requireString(one, "file", RESULT_NOUN),
+      specifier: requireString(one, "specifier", RESULT_NOUN),
+      symbols: stringArray(one, "symbols"),
+    };
+  });
+}
+
+export function parseAddComponentResult(value: unknown): AddComponentResult {
+  const record = asRecord(value, RESULT_NOUN);
+  const name = requireString(record, "name", RESULT_NOUN);
+  const component = requireString(record, "component", RESULT_NOUN);
+  if (!isComponentSource(record.source))
+    throw new Error(`${RESULT_NOUN} names a known component source`);
+  return {
+    name,
+    component,
+    source: record.source,
+    copied: stringArray(record, "copied"),
+    present: stringArray(record, "present"),
+    rewritten: stringArray(record, "rewritten"),
+    left: leftImports(record),
+  };
+}
+
+export function serializeAddComponentResult(result: AddComponentResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/add-package.ts

@@ -0,0 +1,58 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import {
+  asRecord,
+  optionalString,
+  requireOperation,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "an addPackage input";
+
+export interface AddPackageInput {
+  readonly operation: "addPackage";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+  readonly id?: string;
+}
+
+export function parseAddPackageInput(value: unknown): AddPackageInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "addPackage", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  const id = optionalString(record, "id", NOUN);
+  return id !== undefined
+    ? { operation: "addPackage", protocol: PROTOCOL_VERSION, name, id }
+    : { operation: "addPackage", protocol: PROTOCOL_VERSION, name };
+}
+
+export function serializeAddPackageInput(input: AddPackageInput): string {
+  return JSON.stringify(input);
+}
+
+export interface AddPackageResult {
+  readonly name: string;
+  readonly id: string;
+  readonly installed: boolean;
+  readonly rebooted: readonly string[];
+}
+
+export function parseAddPackageResult(value: unknown): AddPackageResult {
+  const record = asRecord(value, "an addPackage result");
+  const name = requireString(record, "name", "an addPackage result");
+  const id = requireString(record, "id", "an addPackage result");
+  if (typeof record.installed !== "boolean")
+    throw new Error("an addPackage result states whether bun add actually ran");
+  if (
+    !Array.isArray(record.rebooted) ||
+    !record.rebooted.every((entry): entry is string => typeof entry === "string")
+  ) {
+    throw new Error("an addPackage result names the rebooted routes");
+  }
+  return { name, id, installed: record.installed, rebooted: record.rebooted };
+}
+
+export function serializeAddPackageResult(result: AddPackageResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/app-record.ts

@@ -0,0 +1,29 @@
+import { asRecord, optionalString, requirePositiveInteger, requireString } from "./parse-helpers";
+import { isRecordStatus, type RecordStatus } from "./record-status";
+
+export interface AppRecord {
+  readonly id: number;
+  readonly name: string;
+  readonly action: string;
+  readonly status: RecordStatus;
+  readonly note?: string;
+  readonly payload: unknown;
+}
+
+export function parseAppRecord(value: unknown): AppRecord {
+  const record = asRecord(value, "a record");
+  const id = requirePositiveInteger(record, "id", "a record");
+  const name = requireString(record, "name", "a record");
+  const action = requireString(record, "action", "a record");
+  if (!isRecordStatus(record.status)) throw new Error("a record names a known status");
+  const note = optionalString(record, "note", "a record");
+  if (!("payload" in record)) throw new Error("a record carries a payload");
+  return {
+    id,
+    name,
+    action,
+    status: record.status,
+    ...(note !== undefined ? { note } : {}),
+    payload: record.payload,
+  };
+}

package/src/operations/archive-route.ts

@@ -0,0 +1,48 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import {
+  asRecord,
+  optionalBoolean,
+  requireOperation,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "an archiveRoute input";
+
+export interface ArchiveRouteInput {
+  readonly operation: "archiveRoute";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+  // Defaults to true, as in the previous engine's archive_route tool (`args.archived !== false`).
+  readonly archived: boolean;
+}
+
+export function parseArchiveRouteInput(value: unknown): ArchiveRouteInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "archiveRoute", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  const archived = optionalBoolean(record, "archived", NOUN) ?? true;
+  return { operation: "archiveRoute", protocol: PROTOCOL_VERSION, name, archived };
+}
+
+export function serializeArchiveRouteInput(input: ArchiveRouteInput): string {
+  return JSON.stringify(input);
+}
+
+export interface ArchiveRouteResult {
+  readonly name: string;
+  readonly archived: boolean;
+}
+
+export function parseArchiveRouteResult(value: unknown): ArchiveRouteResult {
+  const record = asRecord(value, "an archiveRoute result");
+  const name = requireString(record, "name", "an archiveRoute result");
+  if (typeof record.archived !== "boolean")
+    throw new Error("an archiveRoute result states whether the route is archived");
+  return { name, archived: record.archived };
+}
+
+export function serializeArchiveRouteResult(result: ArchiveRouteResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/capture-snapshot.ts

@@ -0,0 +1,46 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import { asRecord, requireOperation, requireProtocol, requireString } from "./parse-helpers";
+
+const NOUN = "a captureSnapshot input";
+
+export interface CaptureSnapshotInput {
+  readonly operation: "captureSnapshot";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+}
+
+export function parseCaptureSnapshotInput(value: unknown): CaptureSnapshotInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "captureSnapshot", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  return { operation: "captureSnapshot", protocol: PROTOCOL_VERSION, name };
+}
+
+export function serializeCaptureSnapshotInput(input: CaptureSnapshotInput): string {
+  return JSON.stringify(input);
+}
+
+export interface CaptureSnapshotResult {
+  readonly name: string;
+  readonly dir: string;
+  readonly files: number;
+  readonly bytes: number;
+}
+
+export function parseCaptureSnapshotResult(value: unknown): CaptureSnapshotResult {
+  const record = asRecord(value, "a captureSnapshot result");
+  const name = requireString(record, "name", "a captureSnapshot result");
+  const dir = requireString(record, "dir", "a captureSnapshot result");
+  if (typeof record.files !== "number" || !Number.isInteger(record.files) || record.files < 0) {
+    throw new Error("a captureSnapshot result names how many files it captured");
+  }
+  if (typeof record.bytes !== "number" || !Number.isInteger(record.bytes) || record.bytes < 0) {
+    throw new Error("a captureSnapshot result names how many bytes it captured");
+  }
+  return { name, dir, files: record.files, bytes: record.bytes };
+}
+
+export function serializeCaptureSnapshotResult(result: CaptureSnapshotResult): string {
+  return JSON.stringify(result);
+}