@lincyaw/kernel 0.0.0-stage → 1.0.0-rc.1

package/src/contracts/execution.ts

@@ -0,0 +1,118 @@
+import type { Logger, Unsubscribe } from './plugin.ts'
+import { defineService } from './service.ts'
+
+export interface RunRequest {
+  lang: string
+  code: string
+  args?: Record<string, string>
+  stdin?: string
+  timeoutMs?: number
+  files?: Record<string, string>
+  executor?: string
+  session?: string
+  place?: { section: string, block: string }
+}
+
+export type RunOutput =
+  | { output_type: 'stream', name: 'stdout' | 'stderr', text: string }
+  | { output_type: 'display_data' | 'execute_result', data: Record<string, unknown>, metadata?: Record<string, unknown> }
+  | { output_type: 'error', ename: string, evalue: string, traceback: string[] }
+
+export interface RunResult {
+  ok: boolean
+  stdout: string
+  stderr: string
+  exitCode: number | null
+  durationMs: number
+  timedOut: boolean
+  source: 'live' | 'recorded'
+  executorId: string
+  outputs?: RunOutput[]
+}
+
+export interface RunContext {
+  env: Readonly<Record<string, string>>
+  sandbox?: ProcessSandbox
+  lang?: string
+}
+
+export interface SandboxRun {
+  argv: string[]
+  files: Record<string, string | Uint8Array>
+  collect: string[]
+  env: Readonly<Record<string, string>>
+  read: string[]
+  timeoutMs: number
+  signal?: AbortSignal
+}
+
+export interface SandboxResult {
+  exitCode: number | null
+  stdout: string
+  stderr: string
+  files: Record<string, Uint8Array>
+}
+
+export interface ProcessSandbox {
+  readonly kind: string
+  run(request: SandboxRun): Promise<SandboxResult>
+}
+
+export const PROCESS_SANDBOX = defineService<ProcessSandbox>('presmium.processSandbox')
+
+export interface Executor {
+  readonly id: string
+  readonly runsIn?: 'browser' | 'machine'
+  supports(lang: string): boolean
+  run(request: RunRequest, signal?: AbortSignal, ctx?: RunContext): Promise<RunResult>
+  fingerprint?(lang: string): string | Promise<string>
+  revision?(lang: string): string | Promise<string>
+  endSession?(session: string): Promise<void>
+  params?(lang: string): ParamsDisplay | undefined
+}
+
+export interface ParamsDisplay {
+  labels: Record<string, string>
+  fields?: string[]
+  summary?(args: Record<string, string>): string
+}
+
+export interface ExecutorRouter extends Executor {
+  register(executor: Executor, priority?: number): Unsubscribe
+  list(): Executor[]
+}
+
+export const EXECUTOR = defineService<ExecutorRouter>('presmium.executor')
+
+export type EnvironmentAuth = 'none' | 'env' | 'proxy' | 'prompt' | 'hub'
+
+export interface EnvironmentSpec {
+  kind: string
+  url?: string
+  kernel?: string
+  languages?: string[]
+  auth?: EnvironmentAuth
+  /** Operator-defined JupyterHub environment profile; images and resource limits stay on the Hub. */
+  profile?: string
+  image?: string
+  path?: string
+  [option: string]: unknown
+}
+
+export interface ExecuteConfig {
+  env?: string
+  environments?: Record<string, EnvironmentSpec>
+  rerun?: 'environment'
+}
+
+export interface EnvironmentContext {
+  deckDir: string
+  workspaceRoot: string
+  secret(name: string): string | undefined
+  log: Logger
+}
+
+export interface EnvironmentProvider {
+  create(name: string, spec: EnvironmentSpec, ctx: EnvironmentContext): Executor | Promise<Executor>
+  probe?(name: string, spec: EnvironmentSpec, ctx: EnvironmentContext): Promise<string | undefined>
+}

package/src/contracts/locale.ts

@@ -0,0 +1,3 @@
+export type Locale = 'zh-CN' | 'en'
+
+export const DEFAULT_LANG = 'zh-CN'

package/src/contracts/offline.ts

@@ -0,0 +1,2 @@
+/** The requests a page sends the web form's service worker, with a MessageChannel port for the answer. */
+export const OFFLINE_REQUESTS = { runtimes: 'presmium:offline-runtimes', save: 'presmium:save-offline' } as const

package/src/contracts/operations.ts

@@ -0,0 +1,8 @@
+export interface Operation {
+  type: string
+  data: Record<string, unknown>
+}
+
+export type TrackEvent = [t: number, type: string, data: Record<string, unknown>]
+
+export type UtteranceAnchor = [utterance: string, offset: number]

package/src/contracts/plugin.ts

@@ -0,0 +1,183 @@
+import type { CanonicalSource, DirectiveSpec, IRDocument, IRPass, Renderer, RendererContribution, RoleSpec } from '../ir.ts'
+import type { AgentTool } from './agent.ts'
+import type { AnchorResolver, AnchorString } from './anchors.ts'
+import type { Check, CheckContext } from './checks.ts'
+import type { EnvironmentProvider, EnvironmentSpec, Executor } from './execution.ts'
+import type { NodeServiceContext, ServerContext, ServerContribution } from './server.ts'
+import type { Locale } from './locale.ts'
+import type { ServiceToken } from './service.ts'
+
+export const KERNEL_VERSION = '1.0.0'
+
+export type Capability = 'fs' | 'network' | 'exec' | 'git'
+
+export interface ServiceRequirement {
+  token: ServiceToken<unknown>
+  optional?: boolean
+}
+
+export interface PluginManifest {
+  id: string
+  /** The name readers and authors see (the startup report), in both interface languages; the id is never shown. */
+  name?: Record<Locale, string>
+  version: string
+  kernel: string
+  provides?: ServiceToken<unknown>[]
+  requires?: ServiceRequirement[]
+  capabilities?: Capability[]
+}
+
+export type PresentationMode = 'slides' | 'document'
+
+export interface Logger {
+  debug(...args: unknown[]): void
+  info(...args: unknown[]): void
+  warn(...args: unknown[]): void
+  error(...args: unknown[]): void
+}
+
+export type Unsubscribe = () => void
+
+export interface DomainEvent<Type extends string = string, Payload = unknown> {
+  type: Type
+  payload: Payload
+}
+
+export interface EventBus {
+  emit(event: DomainEvent): void
+  on<E extends DomainEvent>(type: E['type'], handler: (event: E) => void): Unsubscribe
+}
+
+export interface PluginContext {
+  config: Record<string, unknown>
+  mode: PresentationMode
+  provide<T>(token: ServiceToken<T>, implementation: T): void
+  get<T>(token: ServiceToken<T>): T
+  tryGet<T>(token: ServiceToken<T>): T | undefined
+  events: EventBus
+  log: Logger
+  environments?: Readonly<Record<string, EnvironmentSpec>>
+}
+
+export interface PluginDefinition {
+  manifest: PluginManifest
+  /** Opt in only when dispose stops every resource and this definition can run setup again. */
+  restartable?: boolean
+  setup(ctx: PluginContext): void | Promise<void>
+  /** Also called after setup fails; releases resources acquired during partial initialization. */
+  dispose?(): void | Promise<void>
+}
+
+export type PluginStatus = 'started' | 'degraded' | 'disabled' | 'failed'
+
+export interface PluginReport {
+  id: string
+  name?: Record<Locale, string>
+  status: PluginStatus
+  reason?: string
+  missing?: string[]
+}
+
+export interface StartReport {
+  order: string[]
+  plugins: PluginReport[]
+  cycles: string[][]
+}
+
+export type KernelEvent =
+  | DomainEvent<'kernel.plugin.started', { id: string }>
+  | DomainEvent<'kernel.plugin.degraded', { id: string; missing: string[] }>
+  | DomainEvent<'kernel.plugin.disabled', { id: string; reason: string }>
+  | DomainEvent<'kernel.plugin.failed', { id: string; error: string }>
+
+/**
+ * A heavy output of a document that the plugin makes on request, as a job of the workspace service (the slides as a PDF,
+ * the lecture as a video): the job shows its progress and log, and keeps the files for the author and the AI.
+ */
+export interface Exporter {
+  /** Unique among the outputs of a document, renderers' ids included (e.g. `pdf`, `video`). */
+  id: string
+  /** What the author sees, by language (`zh-CN`, `en`). */
+  label: Record<string, string>
+  /** Whether the document can be exported so (e.g. it has the slides form); every document when left out. */
+  available?(doc: IRDocument, config: Record<string, unknown>): boolean
+  run(ctx: ExportContext): Promise<ExportOutput>
+}
+
+export interface ExportContext {
+  deckDir: string
+  workspaceRoot: string
+  /** The exact canonical source from which the requested compilation was derived. */
+  source?: CanonicalSource
+  /** The plugin's configuration in the document (`presmium.<plugin id>`). */
+  config: Record<string, unknown>
+  /** An empty directory, the job's own, for the files. */
+  outDir: string
+  /** Aborted when the author cancels the job: the exporter stops its processes and rejects. */
+  signal: AbortSignal
+  /** Where the job is: a phase, and how far through it. */
+  progress(phase: string, done?: number, total?: number): void
+  /** A line of the job's log (a tool's output, a step). */
+  log(line: string): void
+  /** What the one who asked for the export chose, as the exporter documents it (`presmium-export`'s `--with-clicks`). */
+  options: Record<string, unknown>
+  /**
+   * Builds the document with renderer `renderer` (at the root path, with `config` over the document's configuration of
+   * the renderer) and gives the directory of its output, the job's own: an exporter of the slides prints them from it.
+   */
+  build(renderer: string, config?: Record<string, unknown>): Promise<string>
+}
+
+export interface ExportOutput {
+  /** The files made, below `outDir`, the one to show first. */
+  files: string[]
+  /** The WebVTT captions of the first file (a video), by language, among `files`. */
+  captions?: Record<string, string>
+  warnings?: string[]
+}
+
+/**
+ * Files of an installed package that a plugin's browser code loads while it runs (Pyodide, the WASI runtimes): served
+ * below the document's site path at `<base><prefix><file>` and copied there into a built site.
+ */
+export interface RuntimeAssets {
+  name: string
+  /** The directory below the document's site path, e.g. `pyodide/`. */
+  prefix: string
+  /** The files that are served, with their content types. */
+  types: Readonly<Record<string, string>>
+  /** The files a build copies; default: all that are served. */
+  emitted?: readonly string[]
+  /** The path of a file on disk. */
+  source(file: string): string
+}
+
+export interface PresmiumNodePlugin {
+  id: string
+  version?: string
+  kernel?: string
+  resolvers?: AnchorResolver[]
+  checks?: Check[]
+  anchors?(ctx: CheckContext): AnchorString[] | Promise<AnchorString[]>
+  directives?: DirectiveSpec[]
+  passes?: IRPass[]
+  executors?: Executor[]
+  renderer?: Renderer
+  rendererExtensions?: Record<string, RendererContribution>
+  /** The files the plugin's browser code loads while it runs (a language runtime), for the document's configuration of the plugin. */
+  assets?(ctx: { deckDir: string, workspaceRoot: string, config: Record<string, unknown> }): RuntimeAssets[]
+  /**
+   * The virtual modules of the plugin's browser code whose content depends on the document (e.g. the list of its scene
+   * files), by id, with their source. The viewer app, prebuilt once for all documents, gets them from the document's own
+   * bundle, built with this source. Only their default export is read there.
+   */
+  documentModules?(ctx: { deckDir: string, workspaceRoot: string, config: Record<string, unknown> }): Record<string, string>
+  /** The heavy outputs the plugin makes on request, as jobs of the workspace service. */
+  exporters?: Exporter[]
+  services?(ctx: NodeServiceContext): [ServiceToken<unknown>, unknown][]
+  environments?: Record<string, EnvironmentProvider>
+  server?(ctx: ServerContext): ServerContribution | Promise<ServerContribution>
+  roles?: RoleSpec[]
+  tools?: AgentTool[]
+  operator?: boolean
+}

package/src/contracts/presenter-panels.ts

@@ -0,0 +1,17 @@
+import type { Unsubscribe } from './plugin.ts'
+import { defineService } from './service.ts'
+
+export interface PresenterPanel {
+  id: string
+  title: string
+  component: unknown
+  order?: number
+}
+
+export interface PresenterPanels {
+  register(panel: PresenterPanel): Unsubscribe
+  list(): PresenterPanel[]
+  subscribe(listener: () => void): Unsubscribe
+}
+
+export const PRESENTER_PANELS = defineService<PresenterPanels>('presmium.presenterPanels')