@phreshos/core 0.1.0

package/source/main.ts

@@ -0,0 +1,65 @@
+export {
+  type Message,
+  type Cleanup,
+  type Capture,
+  type Captures,
+  type EventMessage,
+  type EventName,
+  type EventObserver,
+  type EventOptions,
+  type EventSubscriber,
+  type Subscribable
+} from "./subscribable.js"
+
+export { type Publishable } from "./publishable.js"
+export { type Askable, type TimedAskable } from "./askable.js"
+export { type Outcome } from "./outcome.js"
+export { type ServedFile } from "./served-file.js"
+export {
+  type DirectoryStat,
+  type EntryStat,
+  type FileStat,
+  type OtherStat,
+  type ProgramArea,
+  type ProgramStore
+} from "./storage.js"
+export { type LogKind, type LogRecord, type LogSource, type ProgramSql } from "./sql.js"
+
+export {
+  Endpoint,
+  type AskCapture,
+  type AskMessage,
+  type AskObserver,
+  type EndpointTraffic,
+  type TrafficCapture,
+  type TrafficEvents,
+  type TrafficMessage
+} from "./endpoint.js"
+export { type Channel, type ChannelCapture, type ChannelEvents, type ChannelMessage } from "./channel.js"
+export {
+  Server,
+  type AnswerCapture,
+  type AnswerMessage,
+  type AnswerObserver,
+  type ServerTraffic
+} from "./server.js"
+export { Client, type ClientTraffic } from "./client.js"
+export { Process, type Exit, type ProcessEvents } from "./process.js"
+export {
+  Program,
+  type ClientDeclaration,
+  type EndpointDeclaration,
+  type ProgramEvents,
+  type ProgramProcessExit,
+  type ProgramServerStop
+} from "./program.js"
+export { Window, type WindowEvents, type WindowState } from "./window.js"
+export { layers, type Launch, type LaunchClient, type Layer, type Position, type Size, type Value } from "./launch.js"
+export {
+  defineConfig,
+  type ClientConfig,
+  type ClientDevelopment,
+  type Config,
+  type ServerConfig,
+  type ServerDevelopment
+} from "./config.js"

package/source/outcome.ts

@@ -0,0 +1,4 @@
+/** The transport-neutral result of an operation that may fail. */
+export type Outcome<Result = unknown> =
+  | Readonly<{ success: true, result: Result }>
+  | Readonly<{ success: false, error: string }>

package/source/process.ts

@@ -0,0 +1,77 @@
+import type { Client } from "./client.js"
+import type { Program } from "./program.js"
+import type { Server } from "./server.js"
+import type { Subscribable } from "./subscribable.js"
+
+/** How an operating-system-backed endpoint or Process finished. */
+export type Exit = Readonly<{
+  /** Whether the endpoint exited normally or was terminated by a signal. */
+  status: "exited" | "signaled"
+
+  /** Numeric exit code, or `null` when no code was reported. */
+  code: number | null
+
+  /** Signal name, or `null` when no signal ended it. */
+  signal: string | null
+}>
+
+/** Lifecycle events emitted by one Process. */
+export type ProcessEvents = {
+  /** The Server entered a new live incarnation. */
+  serverStart: undefined
+
+  /** The Server incarnation ended. */
+  serverStop: Omit<Exit, "status">
+
+  /** The authoritative Client state was created. */
+  clientStart: undefined
+
+  /** The authoritative Client state ended. */
+  clientStop: undefined
+
+  /** The complete Process ended. */
+  exit: Exit
+}
+
+/** One live execution of a Program. */
+export class Process<Events extends object = {}> {
+  public constructor() {}
+}
+
+export interface Process<Events extends object = {}> extends Subscribable<ProcessEvents & Events, never> {
+  /** Immutable runtime identity. */
+  readonly identity: string
+
+  /** Optional meaningful name unique among this Program's live Processes. */
+  readonly name: string | null
+
+  /** Instant at which this Process was created. */
+  readonly startedAt: Date
+
+  /** Permanent handle to this Process's Server. */
+  readonly server: Server
+
+  /** Permanent handle to this Process's Client. */
+  readonly client: Client
+
+  /** Returns the Program that owns this Process. */
+  program(): Program
+
+  /**
+   * Returns the Process whose `createProcess()` call created this Process.
+   *
+   * Returns `null` when this Process has no accessible parent handle. Rejects
+   * when this Process or its retained parent no longer exists. Client
+   * environments never expose a parent belonging to another Program.
+   */
+  parent(): Promise<Process | null>
+
+  /** Returns one immutable launch option. */
+  option(name: string): Promise<string | undefined>
+
+  /** Ends the complete Process and all live Endpoints. */
+  exit(): Promise<void>
+
+  /** Returns whether this Process has ended. */
+  exited(): Promise<boolean>
+}

package/source/program.ts

@@ -0,0 +1,130 @@
+import type { Launch, Layer, Position, Size } from "./launch.js"
+import type { Exit, Process } from "./process.js"
+import type { ProgramSql } from "./sql.js"
+import type { ProgramArea, ProgramStore } from "./storage.js"
+import type { Subscribable } from "./subscribable.js"
+
+/** Resolved declaration shared by Server and Client endpoint kinds. */
+export type EndpointDeclaration = Readonly<{
+  /** Whether a default Process starts this declared Endpoint. */
+  start: boolean
+}>
+
+/** Resolved Client declaration and its default Window state. */
+export type ClientDeclaration = EndpointDeclaration & Readonly<{
+  /** Default Window title, or `null` when the system supplies it. */
+  title: string | null
+
+  /** Default Window size, or `null` when the system supplies it. */
+  size: Size | null
+
+  /** Default Window position, or `null` when the system supplies it. */
+  position: Position | null
+
+  /** Default Window layer, or `null` for the system default. */
+  layer: Layer | null
+
+  /** Default minimized state, or `null` for the system default. */
+  minimize: boolean | null
+}>
+
+export type ProgramProcessExit = Exit & Readonly<{
+  /** Process that ended. */
+  process: Process
+}>
+
+export type ProgramServerStop = Omit<Exit, "status"> & Readonly<{
+  /** Process whose Server incarnation ended. */
+  process: Process
+}>
+
+/** Lifecycle events scoped to one Program. */
+export type ProgramEvents = {
+  /** One Process's Server entered a new live incarnation. */
+  serverStart: Process
+
+  /** One Process's Server incarnation ended. */
+  serverStop: ProgramServerStop
+
+  /** One Process's Client state was created. */
+  clientStart: Process
+
+  /** One Process's Client state ended. */
+  clientStop: Process
+
+  /** A Process entered this Program's runtime set. */
+  processCreate: Process
+
+  /** A Process left this Program's runtime set. */
+  processExit: ProgramProcessExit
+
+  /** This Program left the runtime registry. */
+  forget: undefined
+
+  /** This Program left the installed state. */
+  uninstall: Readonly<{ everythingRemoved: boolean }>
+}
+
+/** The stable domain root from which Processes are created. */
+export class Program<Events extends object = {}> {
+  public constructor() {}
+}
+
+export interface Program<Events extends object = {}> extends Subscribable<ProgramEvents & Events, never> {
+  /** Stable public identity. */
+  readonly identity: string
+
+  /** Human-readable name. */
+  readonly name: string
+
+  /** Declared version, or `null`. */
+  readonly version: string | null
+
+  /** Declared description, or `null`. */
+  readonly description: string | null
+
+  /** Server declaration, or `null` when this Program cannot start one. */
+  readonly server: EndpointDeclaration | null
+
+  /** Client declaration, or `null` when this Program cannot start one. */
+  readonly client: ClientDeclaration | null
+
+  /** Persistent filesystem data shared by every Process of this Program. */
+  readonly data: ProgramArea
+
+  /** Disposable filesystem data shared by every Process of this Program. */
+  readonly cache: ProgramArea
+
+  /** Persistent key-value storage shared by every Process of this Program. */
+  readonly store: ProgramStore
+
+  /** Read-only SQL access to captured Client and Server output. */
+  readonly logs: ProgramSql
+
+  /** Writable SQLite database owned by this Program. */
+  readonly database: ProgramSql
+
+  /** Returns every live Process of this Program available to this SDK. */
+  processes(): Promise<Process[]>
+
+  /** Finds a live Process by identity or Program-local name. */
+  getProcess(identityOrName: string): Promise<Process | null>
+
+  /** Creates one Process of this Program. */
+  createProcess(launch?: Launch): Promise<Process>
+
+  /** Returns the official Markdown API entry point, or `null`. */
+  apiDocs(): Promise<string | null>
+
+  /** Returns whether this Program currently has an installed form. */
+  installed(): Promise<boolean>
+
+  /** Removes this Program's installed form. */
+  uninstall(everything?: boolean): Promise<void>
+
+  /** Ends all Processes and removes this Program from the runtime registry. */
+  forget(): Promise<void>
+
+  /** Ends every live Process and returns their identities. */
+  exitAll(): Promise<string[]>
+}

package/source/publishable.ts

@@ -0,0 +1,33 @@
+import type { EventMessage, EventName } from "./subscribable.js"
+
+// Preserves declared string literals in editor completion while still
+// accepting application-defined event names.
+type OpenEvent = string & {}
+
+type AvailableEvent<Events extends object, Fallback> = EventName<Events> | ([Fallback] extends [never] ? never : OpenEvent)
+
+type CompatibleEvent<Events extends object, Fallback, Payload> = {
+  [Event in EventName<Events>]: Payload extends Events[Event] ? Event : never
+}[EventName<Events>] | ([Fallback] extends [never] ? never : Payload extends Fallback ? OpenEvent : never)
+
+interface Publish<Events extends object, Fallback> {
+  <Payload, Event extends CompatibleEvent<Events, Fallback, Payload> = CompatibleEvent<Events, Fallback, Payload>>(
+    event: Event,
+    payload: Payload
+  ): void
+  <Event extends AvailableEvent<Events, Fallback>>(
+    event: Event,
+    payload: EventMessage<Events, Fallback, Event>
+  ): void
+}
+
+/**
+ * The independent capability to publish one payload to a named event.
+ *
+ * Publishing is synchronous and fire-and-forget. An unavailable destination
+ * silently drops the publication; no delivery result is produced.
+ */
+export interface Publishable<Events extends object = {}, Fallback = unknown> {
+  /** Publishes one payload to one named event on this target. */
+  publish: Publish<Events, Fallback>
+}

package/source/served-file.ts

@@ -0,0 +1,14 @@
+/** Description of a value stored as a publicly reachable file. */
+export type ServedFile = Readonly<{
+  /** Generated filename beneath the public served-files route. */
+  file: string
+
+  /** Detected media type, or `null` when no type is known. */
+  type: string | null
+
+  /** Stored size in bytes. */
+  size: number
+
+  /** Storage time as Unix milliseconds. */
+  time: number
+}>

package/source/server.ts

@@ -0,0 +1,58 @@
+import type { Askable } from "./askable.js"
+import { Endpoint, type EndpointTraffic } from "./endpoint.js"
+import type { Outcome } from "./outcome.js"
+import type { Cleanup } from "./subscribable.js"
+
+/** One answer sent by this Server to the Endpoint that asked. */
+export type AnswerMessage<Result = unknown, To = Endpoint> = Readonly<{
+  /** Destination Endpoint, or `null` when its identity is outside this boundary. */
+  to: To
+
+  /** Transport-neutral success or failure returned by the answerer. */
+  outcome: Outcome<Result>
+}>
+
+/** One observed answer sent by this Server. */
+export type AnswerCapture<Result = unknown, To = Endpoint> = Readonly<{
+  /** Event originally addressed by the question. */
+  event: string
+
+  /** Correlation identity shared with the original question. */
+  questionId: string
+
+  /** Answer destination and outcome. */
+  message: AnswerMessage<Result, To>
+}>
+
+/** A callback that observes answers sent by this Server. */
+export type AnswerObserver<Result = unknown, To = Endpoint> = (capture: AnswerCapture<Result, To>) => unknown
+
+/** Broad communication originating from one Server, including its answers. */
+export interface ServerTraffic<
+  Events extends object = {},
+  To = Endpoint,
+  AskTo = Server
+> extends EndpointTraffic<Events, To, AskTo> {
+  /** Observes answers originating from this Server. */
+  observeAnswers<Result = unknown>(observer: AnswerObserver<Result, To>): Cleanup
+}
+
+/** The server Endpoint of a Process. */
+export class Server<Events extends object = {}> extends Endpoint<Events> {
+  public constructor() {
+    super()
+  }
+}
+
+export interface Server<Events extends object = {}> extends Askable {
+  /** Broad communication originating from this Server. */
+  readonly traffic: ServerTraffic<Events>
+
+  /**
+   * Waits until a Server incarnation is ready.
+   *
+   * Temporary absence remains waitable when the Program declares a Server.
+   * The SDK uses its ten-second deadline unless one is supplied.
+  */
+  waitReady(timeout?: number): Promise<void>
+}

package/source/sql.ts

@@ -0,0 +1,36 @@
+/** SQL access to a Program-owned database or its read-only logs. */
+export interface ProgramSql {
+  /** Executes one statement; template interpolations become bound values. */
+  query<Row = Record<string, unknown>>(
+    statement: TemplateStringsArray,
+    ...values: unknown[]
+  ): Promise<Row[]>
+
+  /** Executes one statement with optional bound values. */
+  query<Row = Record<string, unknown>>(
+    statement: string,
+    values?: unknown[]
+  ): Promise<Row[]>
+}
+
+/** One captured line from a Program endpoint. */
+export type LogRecord = Readonly<{
+  createdAt: number
+  process: string
+  source: LogSource
+  kind: LogKind
+  content: string
+}>
+
+export type LogSource = "client" | "server"
+
+export type LogKind =
+  | "debug"
+  | "log"
+  | "info"
+  | "warn"
+  | "error"
+  | "stdout"
+  | "stderr"
+  | "exit"
+  | (string & {})

package/source/storage.ts

@@ -0,0 +1,66 @@
+/** Metadata returned for an entry in Program-owned filesystem storage. */
+export type EntryStat = FileStat | DirectoryStat | OtherStat
+
+export type FileStat = Readonly<{
+  kind: "file"
+  size: number
+  modifiedAt: number
+}>
+
+export type DirectoryStat = Readonly<{
+  kind: "directory"
+  modifiedAt: number
+}>
+
+export type OtherStat = Readonly<{
+  kind: "other"
+  modifiedAt: number
+}>
+
+/** Filesystem-like storage owned by one Program. */
+export interface ProgramArea {
+  /** Reads one file as bytes. */
+  bytes(...path: string[]): Promise<Uint8Array>
+
+  /** Reads one UTF-8 text file. */
+  text(...path: string[]): Promise<string>
+
+  /** Reads and parses one JSON file. */
+  json<Value = unknown>(...path: string[]): Promise<Value>
+
+  /** Opens one file as a byte stream. */
+  stream(...path: string[]): Promise<ReadableStream<Uint8Array>>
+
+  /** Atomically writes one supported value, including a byte stream. */
+  write(...arguments_: [...path: string[], value: unknown]): Promise<void>
+
+  /** Returns entry metadata, or `null` when the entry does not exist. */
+  stat(...path: string[]): Promise<EntryStat | null>
+
+  /** Lists the sorted names immediately inside one directory. */
+  list(...path: string[]): Promise<string[]>
+
+  /** Recursively removes an entry. A missing entry is accepted. */
+  delete(...path: string[]): Promise<void>
+
+  /** Removes every entry while preserving the area itself. */
+  clear(): Promise<void>
+}
+
+/** Persistent key-value storage owned by one Program. */
+export interface ProgramStore {
+  /** Returns a value, or `undefined` when its key is absent or expired. */
+  get<Value = unknown>(key: string): Promise<Value | undefined>
+
+  /** Stores a value and optionally expires it after `ttl` milliseconds. */
+  set<Value>(key: string, value: Value, ttl?: number): Promise<boolean>
+
+  /** Deletes one key or several keys and reports whether anything changed. */
+  delete(key: string | string[]): Promise<boolean>
+
+  /** Returns whether a non-expired value exists for one key. */
+  has(key: string): Promise<boolean>
+
+  /** Deletes every value in this Program's store. */
+  clear(): Promise<void>
+}

package/source/subscribable.ts

@@ -0,0 +1,94 @@
+/** The unconstrained message received by a general Subscribable. */
+export type Message = unknown
+
+/** The message observed for one event on a Subscribable. */
+export type Capture<Event extends string = string, Received = Message> = Readonly<{
+  /** Name under which the message was published. */
+  event: Event
+
+  /** Message delivered by the observed target. */
+  message: Received
+}>
+
+/** The string event names declared by an event map. */
+export type EventName<Events extends object> = Extract<keyof Events, string>
+
+/** The message declared for one event name. */
+export type EventMessage<Events extends object, Fallback, Event extends string> = Event extends EventName<Events> ? Events[Event] : Fallback
+
+/** The correlated union observed across every event declared by a target. */
+export type Captures<Events extends object, Fallback = never> = {
+  [Event in EventName<Events>]: Capture<Event, Events[Event]>
+}[EventName<Events>] | ([Fallback] extends [never] ? never : Capture<string, Fallback>)
+
+/** A callback for one subscribed message. Its return value is not communication. */
+export type EventSubscriber<Message> = (message: Message) => unknown
+
+/** A callback for an observed event and its message. */
+export type EventObserver<Events extends object, Fallback = never> = (capture: Captures<Events, Fallback>) => unknown
+
+/** Removes exactly one persistent registration. Safe to call more than once. */
+export type Cleanup = () => void
+
+/** Options controlling one asynchronous event iterator. */
+export type EventOptions = Readonly<{
+  /** Maximum queued messages. Defaults to `64`; `Infinity` removes the bound. */
+  capacity?: number
+
+  /** Aborts iteration and removes its temporary boundary registration. */
+  signal?: AbortSignal
+}>
+
+// Preserves declared string literals in editor completion while still
+// accepting application-defined event names.
+type OpenEvent = string & {}
+
+type AvailableEvent<Events extends object, Fallback> = EventName<Events> | ([Fallback] extends [never] ? never : OpenEvent)
+
+type CompatibleEvent<Events extends object, Fallback, Narrowed> = {
+  [Event in EventName<Events>]: Narrowed extends Events[Event] ? Event : never
+}[EventName<Events>] | ([Fallback] extends [never] ? never : Narrowed extends Fallback ? OpenEvent : never)
+
+interface Subscribe<Events extends object, Fallback> {
+  <Narrowed>(event: CompatibleEvent<Events, Fallback, Narrowed>, subscriber: EventSubscriber<Narrowed>): Cleanup
+  <Event extends AvailableEvent<Events, Fallback>>(event: Event, subscriber: EventSubscriber<EventMessage<Events, Fallback, Event>>): Cleanup
+}
+
+interface WaitFor<Events extends object, Fallback> {
+  <Narrowed>(event: CompatibleEvent<Events, Fallback, Narrowed>, timeout?: number): Promise<Narrowed>
+  <Event extends AvailableEvent<Events, Fallback>>(event: Event, timeout?: number): Promise<EventMessage<Events, Fallback, Event>>
+}
+
+interface EventStream<Events extends object, Fallback> {
+  <Narrowed>(event: CompatibleEvent<Events, Fallback, Narrowed>, options?: EventOptions): AsyncIterableIterator<Narrowed>
+  <Event extends AvailableEvent<Events, Fallback>>(event: Event, options?: EventOptions): AsyncIterableIterator<EventMessage<Events, Fallback, Event>>
+}
+
+interface Observe<Events extends object, Fallback> {
+  (observer: EventObserver<Events, Fallback>): Cleanup
+}
+
+/**
+ * The common receiving capability supplied by environment SDKs.
+ *
+ * Persistent registrations return their sole cleanup function. A registration
+ * may remain active across temporary endpoint absence and is removed only by
+ * that cleanup or by destruction of its owning boundary.
+ *
+ * `waitFor()` uses the SDK's ten-second deadline unless one is supplied.
+ * `events()` is long-lived instead: it ends when iteration is closed, its
+ * signal aborts, or the boundary proves that future delivery is impossible.
+ */
+export interface Subscribable<Events extends object = {}, Fallback = unknown> {
+  /** Registers one persistent named-event subscription. */
+  subscribe: Subscribe<Events, Fallback>
+
+  /** Waits for the next matching message. */
+  waitFor: WaitFor<Events, Fallback>
+
+  /** Iterates matching messages until closed, aborted, or impossible. */
+  events: EventStream<Events, Fallback>
+
+  /** Registers one persistent observer across every event on this target. */
+  observe: Observe<Events, Fallback>
+}

package/source/window.ts

@@ -0,0 +1,82 @@
+import type { Client } from "./client.js"
+import type { Layer, Position, Size } from "./launch.js"
+import type { Subscribable } from "./subscribable.js"
+
+/** Events emitted when authoritative Window state changes. */
+export type WindowEvents = {
+  move: Position
+  resize: Size
+  minimize: boolean
+  changeTitle: string
+  front: boolean
+}
+
+/** Current authoritative Window state. */
+export type WindowState = Readonly<{
+  /** Current title. */
+  title: string
+
+  /** Current top-left position. */
+  position: Position
+
+  /** Current width and height. */
+  size: Size
+
+  /** Whether the Window is minimized. */
+  minimized: boolean
+
+  /** Whether the Window is frontmost in its layer. */
+  front: boolean
+
+  /** Structurally isolated desktop layer containing the Window. */
+  layer: Layer
+
+  /** Current page beneath the declared Client location. */
+  location: string
+}>
+
+/** The Window owned by one live Client. */
+export class Window<Events extends object = {}> {
+  public constructor() {}
+}
+
+export interface Window<Events extends object = {}> extends Subscribable<WindowEvents & Events, never> {
+  /** Returns the Client that owns this Window. */
+  client(): Client
+
+  /** Returns the current title. */
+  title(): Promise<string>
+
+  /** Returns the current top-left position. */
+  position(): Promise<Position>
+
+  /** Returns the current width and height. */
+  size(): Promise<Size>
+
+  /** Returns whether the Window is minimized. */
+  minimized(): Promise<boolean>
+
+  /** Returns whether the Window is frontmost in its layer. */
+  front(): Promise<boolean>
+
+  /** Returns the structurally isolated desktop layer containing the Window. */
+  layer(): Promise<Layer>
+
+  /** Returns the current page rooted beneath the declared Client location. */
+  location(): Promise<string>
+
+  /** Moves the authoritative Window. */
+  move(position: Position): Promise<void>
+
+  /** Resizes the authoritative Window. */
+  resize(size: Size): Promise<void>
+
+  /** Changes whether the Window is minimized. */
+  minimize(minimized?: boolean): Promise<void>
+
+  /** Changes the Window title. */
+  changeTitle(title: string): Promise<void>
+
+  /** Brings the Window to the front of its own layer. */
+  raise(): Promise<void>
+}