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

package/src/contracts.ts

@@ -0,0 +1,285 @@
+import type { AgentTool } from './contracts/agent.ts'
+import type { EnvironmentProvider, EnvironmentSpec, Executor } from './contracts/execution.ts'
+import type { NodeServiceContext, ServerContext, ServerContribution } from './contracts/server.ts'
+import { defineService } from './contracts/service.ts'
+import type { ServiceToken } from './contracts/service.ts'
+import type { DirectiveSpec, IRDocument, IRPass, Renderer, RendererContribution, RoleSpec } from './ir.ts'
+
+export * from './contracts/agent.ts'
+export * from './contracts/execution.ts'
+export * from './contracts/operations.ts'
+export * from './contracts/preview.ts'
+export * from './contracts/server.ts'
+export * from './contracts/service.ts'
+export * from './contracts/speech.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
+  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>, impl: 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
+  setup(ctx: PluginContext): void | Promise<void>
+  dispose?(): void | Promise<void>
+}
+
+export type PluginStatus = 'started' | 'degraded' | 'disabled' | 'failed'
+
+export interface PluginReport {
+  id: 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 }>
+
+export type Locale = 'zh-CN' | 'en'
+
+export const DEFAULT_LANG = 'zh-CN'
+
+export function localeOf(lang: string | null | undefined): Locale | undefined {
+  const tag = lang?.trim().toLowerCase() ?? ''
+  if (tag === 'zh' || tag.startsWith('zh-')) return 'zh-CN'
+  if (tag === 'en' || tag.startsWith('en-')) return 'en'
+  return undefined
+}
+
+export function deckLocale(lang?: string): Locale {
+  return localeOf(lang || DEFAULT_LANG) ?? 'en'
+}
+
+export interface StepRange {
+  from: number
+  to?: number
+}
+
+export interface StepState {
+  active: boolean
+  reached: boolean
+  done: boolean
+}
+
+export function stepStateAt(range: StepRange, step: number): StepState {
+  const reached = step >= range.from
+  const done = range.to !== undefined && step >= range.to
+  return { active: reached && !done, reached, done }
+}
+
+export interface Cursor {
+  slide: number
+  step: number
+}
+
+export type AnchorString = `${string}:${string}`
+
+export type ResolutionStatus = 'exact' | 'moved' | 'fuzzy' | 'lost'
+
+export interface ResolvedLocation {
+  file: string
+  startLine: number
+  endLine: number
+  text: string
+}
+
+export interface Resolution {
+  status: ResolutionStatus
+  location?: ResolvedLocation
+  fingerprint?: string
+  candidates?: ResolvedLocation[]
+  message?: string
+}
+
+export interface SourceReader {
+  read(file: string, ref?: string): Promise<string | undefined>
+}
+
+export interface RecordedAnchor {
+  fingerprint: string
+  file: string
+  startLine: number
+}
+
+export interface AnchorResolver {
+  scheme: string
+  resolve(anchor: AnchorString, src: SourceReader, recorded?: RecordedAnchor, ref?: string): Promise<Resolution>
+}
+
+export interface AnchorResolverRegistry {
+  register(resolver: AnchorResolver): Unsubscribe
+  resolve(anchor: AnchorString, src: SourceReader, recorded?: RecordedAnchor, ref?: string): Promise<Resolution>
+  schemes(): string[]
+}
+
+export interface AnchorLockFile {
+  version: 1
+  anchors: Record<string, RecordedAnchor>
+}
+
+export function isRenderable(resolution: Resolution): boolean {
+  return resolution.status === 'exact' || resolution.status === 'moved'
+}
+
+export type Severity = 'error' | 'warning' | 'info'
+
+export interface Finding {
+  checkId: string
+  severity: Severity
+  message: string
+  source?: { file: string; line?: number }
+  hint?: string
+}
+
+export interface CheckContext {
+  deckDir: string
+  workspaceRoot: string
+  headmatter: Record<string, unknown>
+  src: SourceReader
+  resolvers: AnchorResolverRegistry
+  lock: AnchorLockFile
+  ir: IRDocument
+  service?<T>(token: ServiceToken<T>): T | undefined
+}
+
+export interface Check {
+  id: string
+  run(ctx: CheckContext): Promise<Finding[]>
+}
+
+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>
+  vitePlugins?(ctx: { deckDir: string, workspaceRoot: string, config: Record<string, unknown> }): unknown[]
+  services?(ctx: NodeServiceContext): [ServiceToken<unknown>, unknown][]
+  environments?: Record<string, EnvironmentProvider>
+  server?(ctx: ServerContext): ServerContribution | Promise<ServerContribution>
+  roles?: RoleSpec[]
+  tools?: AgentTool[]
+  operator?: boolean
+}
+
+export type Role = 'presenter' | 'learner'
+
+export interface Participant {
+  id: string
+  name: string
+  role: Role
+}
+
+export type SessionStatus = 'idle' | 'active' | 'ended'
+
+export interface SessionSnapshot {
+  sessionId?: string
+  status: SessionStatus
+  me?: Participant
+  participants: Participant[]
+  presenterCursor?: Cursor
+}
+
+export interface SessionService {
+  snapshot(): SessionSnapshot
+  subscribe(listener: (snapshot: SessionSnapshot) => void): Unsubscribe
+  create(name: string): Promise<string>
+  join(sessionId: string, name: string): Promise<void>
+  end(): Promise<void>
+  leave(): void
+  archive?(): Promise<string>
+  readonly personal?: ClassroomStore
+}
+
+export const SESSION = defineService<SessionService>('presmium.session')
+
+export interface StoredItem<T> {
+  id: string
+  value: T
+}
+
+export interface ClassroomStore {
+  list<T>(collection: string): StoredItem<T>[]
+  get<T>(collection: string, id: string): T | undefined
+  put<T>(collection: string, id: string, value: T): void
+  remove(collection: string, id: string): void
+  subscribe(collection: string, listener: () => void): Unsubscribe
+}
+
+export const CLASSROOM_STORE = defineService<ClassroomStore>('presmium.classroomStore')
+
+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')

package/src/errors.ts

@@ -0,0 +1,7 @@
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}

package/src/events.ts

@@ -0,0 +1,32 @@
+import type { DomainEvent, EventBus } from './contracts.ts'
+
+type Handler = (event: DomainEvent) => void
+type ErrorHandler = (error: unknown, event: DomainEvent) => void
+
+const reportToConsole: ErrorHandler = (error, event) => {
+  console.error(`[presmium] handler for "${event.type}" threw`, error)
+}
+
+export function createEventBus(onError: ErrorHandler = reportToConsole): EventBus {
+  const handlers = new Map<string, Set<Handler>>()
+  return {
+    emit(event) {
+      for (const handler of [...(handlers.get(event.type) ?? [])]) {
+        try {
+          handler(event)
+        } catch (error) {
+          onError(error, event)
+        }
+      }
+    },
+    on(type, handler) {
+      const set = handlers.get(type) ?? new Set()
+      handlers.set(type, set)
+      const h = handler as Handler
+      set.add(h)
+      return () => {
+        set.delete(h)
+      }
+    },
+  }
+}

package/src/execution.ts

@@ -0,0 +1,21 @@
+import type { RunResult } from './contracts.ts'
+
+const ALIASES: Record<string, string> = {
+  py: 'python',
+  python3: 'python',
+  js: 'javascript',
+  mjs: 'javascript',
+  ts: 'typescript',
+}
+
+export function languageId(lang: string): string {
+  const id = lang.trim().toLowerCase()
+  if (id.startsWith('ipython')) return 'python'
+  return ALIASES[id] ?? id
+}
+
+export function failedRun(executorId: string, stderr: string, durationMs = 0): RunResult {
+  return { ok: false, stdout: '', stderr, exitCode: null, durationMs, timedOut: false, source: 'live', executorId }
+}
+
+export const CREDENTIAL_VARIABLE = /_(?:KEY|TOKEN|SECRET|PASSWORD|APPID)$/i

package/src/fingerprint.ts

@@ -0,0 +1,31 @@
+export function normalizeWhitespace(text: string): string {
+  const lines = text
+    .replace(/\r\n?/g, '\n')
+    .split('\n')
+    .map(line => line.replace(/\s+$/u, '').replace(/^[ \t]+/, lead => ' '.repeat(lead.replace(/\t/g, '    ').length)))
+    .filter(line => line.length > 0)
+  if (lines.length === 0) return ''
+  const indent = Math.min(...lines.map(line => line.length - line.trimStart().length))
+  return lines
+    .map((line) => {
+      const depth = line.length - line.trimStart().length - indent
+      const body = line.trimStart().replace(/\s+/gu, ' ').replace(/ ?([^\p{L}\p{N}_ ]) ?/gu, '$1')
+      return ' '.repeat(depth) + body
+    })
+    .join('\n')
+}
+
+const FNV_OFFSET = 0xcbf29ce484222325n
+const FNV_PRIME = 0x100000001b3n
+
+export function fnv1a64(text: string): string {
+  let hash = FNV_OFFSET
+  for (const byte of new TextEncoder().encode(text)) {
+    hash = BigInt.asUintN(64, (hash ^ BigInt(byte)) * FNV_PRIME)
+  }
+  return hash.toString(16).padStart(16, '0')
+}
+
+export function fingerprint(text: string): string {
+  return fnv1a64(normalizeWhitespace(text))
+}

package/src/follow.ts

@@ -0,0 +1,37 @@
+import type { IRBlock, IRSection } from './ir.ts'
+
+export type StepKeys = string[][]
+
+export function stepKeys(section: Pick<IRSection, 'blocks' | 'steps'>, renderer?: string): StepKeys {
+  const keys: StepKeys = Array.from({ length: section.steps + 1 }, () => [])
+  const add = (step: number, key: string) => step > 0 && keys[step]?.push(key)
+  let left = false
+  const visit = (blocks: readonly IRBlock[], prefix: string) => {
+    for (const block of blocks) {
+      if (renderer !== undefined && block.only && !block.only.includes(renderer)) {
+        left = true
+        continue
+      }
+      const id = prefix + block.id
+      if (block.role === 'visual') {
+        for (let k = 0; k <= (block.span ?? 0); k++) add(block.at + k, k === 0 ? id : `${id}+${k}`)
+        if (block.until !== undefined) add(block.until, `${id}-`)
+      }
+      if (block.node.type === 'component' && block.node.children) visit(block.node.children, `${id}/`)
+    }
+  }
+  visit(section.blocks, '')
+  return left ? keys.filter((step, i) => i === 0 || step.length > 0) : keys
+}
+
+export function stepTrail(keys: StepKeys, step: number): string[] {
+  return keys.slice(1, step + 1).flat()
+}
+
+export function trailStep(keys: StepKeys, trail: readonly string[]): number {
+  const reached = new Set(trail)
+  for (let step = keys.length - 1; step > 0; step--) {
+    if (keys[step]!.some(key => reached.has(key))) return step
+  }
+  return 0
+}

package/src/git.ts

@@ -0,0 +1,12 @@
+export const GIT_SAFE_CONFIG: readonly string[] = ['core.hooksPath=/dev/null', 'core.fsmonitor=false', 'core.quotePath=false', 'commit.gpgSign=false', 'tag.gpgSign=false']
+
+export function gitConfigArgs(): string[] {
+  return GIT_SAFE_CONFIG.flatMap(entry => ['-c', entry])
+}
+
+export function gitEnvironment(env: Record<string, string | undefined>): Record<string, string> {
+  const own: Record<string, string> = {}
+  for (const [name, value] of Object.entries(env)) if (value !== undefined && !/^GIT_/i.test(name)) own[name] = value
+  own.GIT_TERMINAL_PROMPT = '0'
+  return own
+}

package/src/html.ts

@@ -0,0 +1,41 @@
+import { parseFragment } from 'parse5'
+import type { DefaultTreeAdapterMap } from 'parse5'
+
+export function escapeHtml(text: string): string {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+}
+
+export interface HtmlAttribute {
+  name: string
+  value: string
+  start: number
+  end: number
+}
+
+export const URL_ATTRIBUTES: ReadonlySet<string> = new Set(['src', 'poster', 'href'])
+
+export function htmlAttributes(html: string, names: ReadonlySet<string>): HtmlAttribute[] {
+  const found: HtmlAttribute[] = []
+  const visit = (node: DefaultTreeAdapterMap['node']) => {
+    if ('attrs' in node) {
+      for (const { name, value } of node.attrs) {
+        const at = node.sourceCodeLocation?.attrs?.[name]
+        if (names.has(name) && at) found.push({ name, value, start: at.startOffset, end: at.endOffset })
+      }
+    }
+    if ('childNodes' in node) node.childNodes.forEach(visit)
+    if ('content' in node) visit(node.content)
+  }
+  visit(parseFragment(html, { sourceCodeLocationInfo: true }))
+  return found.sort((a, b) => a.start - b.start)
+}
+
+export function mapHtmlUrls(html: string, map: (url: string, attribute: string) => string | undefined): string {
+  let out = html
+  for (const { name, value, start, end } of htmlAttributes(html, URL_ATTRIBUTES).reverse()) {
+    const mapped = map(value, name)
+    if (mapped === undefined) continue
+    out = `${out.slice(0, start)}${html.slice(start, start + name.length)}="${escapeHtml(mapped)}"${out.slice(end)}`
+  }
+  return out
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+export * from './contracts.ts'
+export * from './ir.ts'
+export { createAnchorResolverRegistry, parseAnchor } from './anchors.ts'
+export type { ParsedAnchor } from './anchors.ts'
+export { docBlocks, irBlocks, nodeMdast, withProp } from './blocks.ts'
+export { CheckRegistry } from './checks.ts'
+export { errorMessage, isRecord } from './errors.ts'
+export { createEventBus } from './events.ts'
+export { CREDENTIAL_VARIABLE, failedRun, languageId } from './execution.ts'
+export { GIT_SAFE_CONFIG, gitConfigArgs, gitEnvironment } from './git.ts'
+export { escapeHtml, htmlAttributes, mapHtmlUrls, URL_ATTRIBUTES } from './html.ts'
+export type { HtmlAttribute } from './html.ts'
+export { hostName, localRequestRefusal } from './requests.ts'
+export type { RequestHeaders } from './requests.ts'
+export { fingerprint, fnv1a64, normalizeWhitespace } from './fingerprint.ts'
+export { stepKeys, stepTrail, trailStep } from './follow.ts'
+export type { StepKeys } from './follow.ts'
+export { Kernel } from './kernel.ts'
+export type { KernelOptions } from './kernel.ts'
+export { ANCHOR_LOCK_PATH, AnchorLock } from './lock.ts'
+export { prefixed } from './logging.ts'
+export { lowerMyst, roleMark } from './markdown.ts'
+export type { LinkedType, LoweredMarkdown, LowerOptions } from './markdown.ts'
+export { publishedUrl } from './published.ts'
+export type { PublishedUrlOptions } from './published.ts'
+export { blockState, blockText, blockVisible, chapters, isChapterTitle, mdastText, narrationAt, sectionNarration, tokenize } from './reading.ts'
+export type { Chapter } from './reading.ts'
+export { HOST_OWNER, kernelIncompatibility, ServiceRegistry } from './services.ts'
+export type { StartPlan } from './services.ts'