acrylblends 0.0.0-stage → 0.2.0

package/plugins/extensions/ledger.ts

@@ -0,0 +1,39 @@
+/**
+ * The ledger: one JSON line per change to the installed extensions, appended, never rewritten. Extracted from ACRYL's evolution ledger
+ * (`blend-ledger.js`): what was installed, updated, removed or refused, when, and the content digest of the version involved.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+export type LedgerKind =
+  | 'installed'
+  | 'updated'
+  | 'removed'
+  | 'refused'
+  | 'restored'
+  | 'requested'
+  | 'approved'
+  | 'denied'
+
+export interface LedgerEntry {
+  readonly at: string
+  readonly kind: LedgerKind
+  readonly name: string
+  readonly version?: string
+  readonly error?: string
+}
+
+export function appendLedger(file: string, entry: Omit<LedgerEntry, 'at'>): LedgerEntry {
+  const line: LedgerEntry = { at: new Date().toISOString(), ...entry }
+  mkdirSync(dirname(file), { recursive: true })
+  appendFileSync(file, `${JSON.stringify(line)}\n`)
+  return line
+}
+
+export function readLedger(file: string): LedgerEntry[] {
+  if (!existsSync(file)) return []
+  return readFileSync(file, 'utf8')
+    .split('\n')
+    .filter((line) => line.trim() !== '')
+    .map((line) => JSON.parse(line) as LedgerEntry)
+}

package/plugins/extensions/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "extensions",
+  "description": "Install, update, remove and reload plugins while the app runs; a failed update brings the previous version back; a ledger of every change.",
+  "requires": ["instance", "sandbox"],
+  "inject": ["appInstance"],
+  "provides": ["extensions"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@webboxes/blends-core": "0.4.0"
+  },
+  "mount": "mount it after instance: root.plugin(extensions, { sources: [{ dir: join(root, 'extensions'), trust: 'install' }] })"
+}

package/plugins/extensions/resolve.ts

@@ -0,0 +1,30 @@
+/**
+ * A staged extension lives in the app's home, which may be anywhere (a pinned home in a temporary folder), so a bare import such as
+ * `@deepseek-ai/cordis` would not find the app's `node_modules`. This resolve hook leaves resolution alone, and only when it fails for a
+ * module inside the staging folder, resolves the same name from the app's project folder. Uses Node's public `module.registerHooks`
+ * (ACRYL needed the same fallback on Deno); the returned function removes the hook.
+ */
+import { mkdirSync, realpathSync } from 'node:fs'
+import { registerHooks } from 'node:module'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const isBare = (specifier: string) => !/^[./]/.test(specifier) && !specifier.includes(':')
+
+export function resolveFromApp(stageRoot: string, appRoot: string): () => void {
+  mkdirSync(stageRoot, { recursive: true })
+  const staged = pathToFileURL(`${realpathSync(stageRoot)}/`).href
+  const parentURL = pathToFileURL(join(realpathSync(appRoot), 'package.json')).href
+  const hook = registerHooks({
+    resolve(specifier, context, nextResolve) {
+      try {
+        return nextResolve(specifier, context)
+      } catch (error) {
+        if (isBare(specifier) && context.parentURL?.startsWith(staged))
+          return nextResolve(specifier, { ...context, parentURL })
+        throw error
+      }
+    },
+  })
+  return () => hook.deregister()
+}

package/plugins/extensions/stage.ts

@@ -0,0 +1,44 @@
+/**
+ * Staging: every installed version of an extension is a complete copy under `<home>/extensions-staged/<name>/<stamp>-<hash>/`.
+ *
+ * Extracted from ACRYL (`acryl-extension-context/lib/stage.js`). Node caches an ES module by URL, so a re-imported file keeps its old
+ * code; a copy at a new path has fresh URLs for the entry and everything it imports, so it is evaluated anew. The author's source folder
+ * is never modified. The hash makes an unchanged source recognisable; the stamp makes "newest" well defined.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { digestFolder, FOLDER_DIGEST_SKIPPED } from '@webboxes/blends-core'
+
+/** A short content digest of a folder, so an unchanged source keeps its version. */
+export const hashFolder = (dir: string, length = 12): string => digestFolder(dir, length)
+
+/** Copy `source` into a new version folder under `stageRoot/<name>/` and return its path and version. */
+export function stage(
+  source: string,
+  stageRoot: string,
+  name: string,
+): { dir: string; version: string } {
+  const version = hashFolder(source)
+  const stamp = String(Date.now()).padStart(15, '0')
+  const dir = join(stageRoot, name, `${stamp}-${version}`)
+  mkdirSync(dir, { recursive: true })
+  cpSync(source, dir, {
+    recursive: true,
+    filter: (path) => !FOLDER_DIGEST_SKIPPED.has(basename(path)),
+  })
+  return { dir, version }
+}
+
+/** Delete staged versions of `name` except the ones to keep (best effort). Modules already loaded stay in memory until the app restarts. */
+export function prune(stageRoot: string, name: string, keep: readonly string[]): void {
+  const folder = join(stageRoot, name)
+  if (!existsSync(folder)) return
+  if (keep.length === 0) {
+    rmSync(folder, { recursive: true, force: true })
+    return
+  }
+  for (const entry of readdirSync(folder)) {
+    const path = join(folder, entry)
+    if (!keep.includes(path)) rmSync(path, { recursive: true, force: true })
+  }
+}

package/plugins/http/index.ts

@@ -0,0 +1,64 @@
+import type { Context } from '@deepseek-ai/cordis'
+
+/** A request as routes see it: the method, the path and the parsed JSON body, if any. */
+export interface RouteRequest {
+  readonly method: string
+  readonly path: string
+  readonly body: unknown
+}
+
+/** What a route answers. The status defaults to 200; the body is sent as JSON. */
+/** Sends one server-sent event: `topic` is the event name, `data` is sent as JSON. */
+export type Send = (topic: string, data: unknown) => void
+
+/** A live stream: called when a client connects, it returns what to run when the client leaves. */
+export type Stream = (send: Send) => () => void
+
+export interface Reply {
+  readonly status?: number
+  readonly body: unknown
+  /** Answer with a stream of server-sent events instead of a JSON body. */
+  readonly stream?: Stream
+}
+
+export type Handler = (request: RouteRequest) => Reply | Promise<Reply>
+
+/** The router service. Plugins add routes; the server asks it to answer requests. */
+export interface Http {
+  /** Add a route. Returns the function that removes it, so it can be the disposer of a `ctx.effect`. */
+  route(method: string, path: string, handler: Handler): () => void
+  /** Answer a request from the registered routes, 404 when none matches. */
+  handle(request: RouteRequest): Promise<{ status: number; body: unknown; stream?: Stream }>
+  /** The registered routes, as `METHOD /path`. */
+  list(): string[]
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    http: Http
+  }
+}
+
+/** Provides the `http` router. Nothing listens here: see the `server` plugin. */
+export function http(ctx: Context) {
+  const routes = new Map<string, Handler>()
+  ctx.provide('http', {
+    route(method, path, handler) {
+      const key = `${method.toUpperCase()} ${path}`
+      if (routes.has(key)) throw new Error(`route ${key} is already registered`)
+      routes.set(key, handler)
+      return () => void routes.delete(key)
+    },
+    async handle(request) {
+      const handler = routes.get(`${request.method.toUpperCase()} ${request.path}`)
+      if (!handler) return { status: 404, body: { error: 'not found' } }
+      const reply = await handler(request)
+      return {
+        status: reply.status ?? 200,
+        body: reply.body,
+        ...(reply.stream ? { stream: reply.stream } : {}),
+      }
+    },
+    list: () => [...routes.keys()].sort(),
+  } satisfies Http)
+}

package/plugins/http/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "http",
+  "description": "The router service: plugins add routes inside ctx.effect, so a route disappears with the plugin that added it.",
+  "requires": [],
+  "inject": [],
+  "provides": ["http"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  }
+}

package/plugins/instance/index.ts

@@ -0,0 +1,167 @@
+/**
+ * App instance: everything one running app owns on this machine, decided in one place and chosen once.
+ *
+ * Extracted from ACRYL (`runtime/acryl-harness-runtime/src/instance/`): a sealed compartment per app (Release It!'s bulkhead), built by
+ * factories that always produce a consistent family (home, port, run lock), chosen once in `main.ts`. `selectInstance` is the only code
+ * that reads the environment; every plugin reads the `appInstance` service instead.
+ *
+ * Pure apart from `selectInstance`, which reads the given environment object. Paths are built, never checked.
+ */
+import { createHash } from 'node:crypto'
+import { basename, join, resolve } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+
+/** How the instance was chosen: from the project folder, or a home the caller pinned. */
+export type AppInstanceKind = 'project' | 'pinned'
+
+/** Where the app listens first, and whether it moves to the next free port when that one is taken. Port 0 means any free port. */
+export interface PortPreference {
+  readonly start: number
+  readonly scan: boolean
+}
+
+export interface AppInstance {
+  readonly kind: AppInstanceKind
+  /** Unique on this machine: seeds the port. */
+  readonly id: string
+  /** Human name: the project folder's name. */
+  readonly name: string
+  /** The project folder: its code and its `node_modules`. */
+  readonly root: string
+  /** The app's own data: settings, installed extensions, the extension ledger. Never shared with another app. */
+  readonly home: string
+  readonly port: PortPreference
+  /** The interface to listen on. Absent means loopback only; a container sets `0.0.0.0` so its published port reaches the app. */
+  readonly host?: string
+  /** Records the one live process of this instance. */
+  readonly runLockFile: string
+}
+
+export const HOME_DIR_NAME = '.acrylblends'
+export const RUN_LOCK_FILE = 'instance.json'
+export const PORT_BASE = 3100
+export const PORT_SPAN = 900
+export const HOME_ENV = 'ACRYLBLENDS_HOME'
+export const PORT_ENV = 'ACRYLBLENDS_PORT'
+export const HOST_ENV = 'ACRYLBLENDS_HOST'
+
+export class AppInstanceError extends Error {
+  override name = 'AppInstanceError'
+}
+
+/** FNV-1a over the id: stable across runs and platforms, spread over the app port range, so two apps rarely start on the same port. */
+export function stablePort(id: string): number {
+  let hash = 0x811c9dc5
+  for (const character of id) {
+    hash ^= character.codePointAt(0) ?? 0
+    hash = Math.imul(hash, 0x01000193) >>> 0
+  }
+  return PORT_BASE + (hash % PORT_SPAN)
+}
+
+const digest = (text: string, length: number) =>
+  createHash('sha1').update(text).digest('hex').slice(0, length)
+const plainName = (folder: string) =>
+  basename(folder)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'app'
+
+function family(input: {
+  kind: AppInstanceKind
+  id: string
+  name: string
+  root: string
+  home: string
+  port: PortPreference
+}): AppInstance {
+  return Object.freeze({
+    kind: input.kind,
+    id: input.id,
+    name: input.name,
+    root: input.root,
+    home: input.home,
+    port: Object.freeze({ ...input.port }),
+    runLockFile: join(input.home, RUN_LOCK_FILE),
+  })
+}
+
+/** The default: the project folder owns its data in `<project>/.acrylblends`. Two folders with one name get different ids. */
+export function projectInstance(projectRoot: string): AppInstance {
+  const root = resolve(projectRoot)
+  const name = plainName(root)
+  const id = `${name}-${digest(root, 4)}`
+  return family({
+    kind: 'project',
+    id,
+    name,
+    root,
+    home: join(root, HOME_DIR_NAME),
+    port: { start: stablePort(id), scan: true },
+  })
+}
+
+/**
+ * A home the caller pinned (ACRYLBLENDS_HOME): honoured as given. Tests and second copies of an app use it to stay apart. `root` is the
+ * project folder (where its packages are installed); it defaults to the current directory.
+ */
+export function pinnedInstance(
+  home: string,
+  options: { name?: string; root?: string } = {},
+): AppInstance {
+  const absolute = resolve(home)
+  const root = resolve(options.root ?? process.cwd())
+  const id = `pinned-${digest(absolute, 6)}`
+  return family({
+    kind: 'pinned',
+    id,
+    name: options.name ?? plainName(root),
+    root,
+    home: absolute,
+    port: { start: stablePort(id), scan: true },
+  })
+}
+
+/** The same family with an explicit start port. Port 0 asks the system for any free port. */
+export function withPort(instance: AppInstance, start: number): AppInstance {
+  if (!Number.isInteger(start) || start < 0 || start > 65_535) {
+    throw new AppInstanceError(
+      `the port must be 0 (any free port) or 1 to 65535, got ${String(start)}`,
+    )
+  }
+  return Object.freeze({ ...instance, port: Object.freeze({ start, scan: start !== 0 }) })
+}
+
+/**
+ * Choose the instance. The only place that reads the environment: `ACRYLBLENDS_HOME` pins the home, `ACRYLBLENDS_PORT` sets the start port, `ACRYLBLENDS_HOST` the interface;
+ * otherwise the project folder decides.
+ */
+export function selectInstance(options: {
+  projectRoot: string
+  env?: Record<string, string | undefined>
+}): AppInstance {
+  const env = options.env ?? {}
+  const pinned = env[HOME_ENV]?.trim()
+  let instance = pinned
+    ? pinnedInstance(pinned, { name: plainName(options.projectRoot), root: options.projectRoot })
+    : projectInstance(options.projectRoot)
+  const port = env[PORT_ENV]?.trim()
+  if (port) instance = withPort(instance, Number(port))
+  const host = env[HOST_ENV]?.trim()
+  if (host) instance = Object.freeze({ ...instance, host })
+  return instance
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    appInstance: AppInstance
+  }
+}
+
+/** Provides the chosen instance as the `appInstance` service. Mount it first, with the instance as its config. */
+export const instance = {
+  name: 'instance',
+  apply(ctx: Context, chosen: AppInstance) {
+    ctx.provide('appInstance', chosen)
+  },
+}

package/plugins/instance/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "instance",
+  "description": "Where the app keeps things (home, port, run lock), chosen once from the environment or the project folder.",
+  "requires": [],
+  "inject": [],
+  "provides": ["appInstance"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  }
+}