acrylblends 0.0.0-stage → 0.3.0

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "acrylblends",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Scaffold Cordis apps: acrylblends init.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "acrylblends": "./bin/acrylblends.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates",
+    "plugins"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "prepack": "pnpm run build && node scripts-pack.mjs copy",
+    "postpack": "node scripts-pack.mjs remove"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/acrylblends/acrylblends.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://acrylblends.github.io",
+  "keywords": [
+    "cordis",
+    "scaffold"
+  ],
+  "private": false,
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugins/acryl-inspect/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WebBoxes s.r.o.
+
+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/plugins/acryl-inspect/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "acryl-inspect",
+  "description": "Introspection: what every plugin requires, provides and registers, and what unloads with it. Vendored from ACRYL.",
+  "requires": ["acryl-router"],
+  "inject": ["router"],
+  "provides": ["inspect"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  },
+  "mount": "root.plugin(inspect); ctx.inspect.plugins(), ctx.inspect.explain('name'), ctx.inspect.render()"
+}

package/plugins/acryl-inspect/src/index.ts

@@ -0,0 +1,3 @@
+export { Inspect, apply, name } from './service.ts'
+export { explain, renderReports, reportFiber, stateName } from './report.ts'
+export type { EffectLabel, FiberStateName, FiberView, PluginReport, RouteReport } from './report.ts'

package/plugins/acryl-inspect/src/report.ts

@@ -0,0 +1,123 @@
+/**
+ * The per-plugin contract, read from the running system (spec 046, M4). Cordis already knows a plugin's name, its state, the
+ * services it requires (`inject`) and a labeled tree of everything it registered (`getEffects()`), so there is no second
+ * declaration to keep in step with the code. The only convention is the label: an effect says what it is, prefixed by its
+ * owner (`acryl-router: GET /a`). Pure functions over a structural view of a fiber, so they are testable without Cordis.
+ */
+
+/** The plugin states Cordis defines, by their numeric values (`FiberState`). */
+const STATE_NAMES = ['PENDING', 'LOADING', 'ACTIVE', 'FAILED', 'DISPOSED', 'UNLOADING'] as const
+export type FiberStateName = typeof STATE_NAMES[number]
+
+export interface EffectLabel {
+  readonly label: string
+  readonly children: readonly EffectLabel[]
+}
+
+/** The slice of a Cordis fiber this module reads. */
+export interface FiberView {
+  readonly state: number
+  readonly inject: Readonly<Record<string, unknown>>
+  readonly runtime: { readonly name?: string | undefined } | null
+  /** The context the fiber was loaded from; its own `fiber` is the owning plugin when this fiber is an inline `ctx.inject(...)` callback. */
+  readonly parent?: { readonly fiber?: FiberView | undefined } | undefined
+  getEffects(): readonly EffectLabel[]
+}
+
+export interface RouteReport {
+  readonly method: string
+  readonly path: string
+}
+
+export interface PluginReport {
+  readonly name: string
+  readonly state: FiberStateName
+  /** Services the plugin waits for before it starts. */
+  readonly requires: readonly string[]
+  /** Services it provides. */
+  readonly provides: readonly string[]
+  /** Routes it registered on the router. */
+  readonly routes: readonly RouteReport[]
+  /** Router middleware paths it registered. */
+  readonly middleware: readonly string[]
+  /** Every other labeled registration (event listeners, timers, commands, tools). */
+  readonly other: readonly string[]
+  /** How many registrations disappear when it unloads: all of them. */
+  readonly removedOnUnload: number
+}
+
+const PROVIDE = /^ctx\.provide\("(.+)"\)$/
+const ROUTE = /^acryl-router: (GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|\*) (\/\S*)$/
+const USE = /^acryl-router: use (\/\S*)$/
+
+function flatten(effects: readonly EffectLabel[]): string[] {
+  return effects.flatMap(effect => [effect.label, ...flatten(effect.children)])
+}
+
+export function stateName(state: number): FiberStateName {
+  return STATE_NAMES[state] ?? 'FAILED'
+}
+
+const isNamed = (fiber: FiberView): boolean => (fiber.runtime?.name ?? '') !== ''
+
+/** The named plugin a fiber belongs to: itself, or for an unnamed inline callback (`ctx.inject([...], inner => ...)`) the nearest named ancestor. */
+export function ownerOf(fiber: FiberView): FiberView {
+  let current = fiber
+  while (!isNamed(current)) {
+    const parent = current.parent?.fiber
+    if (parent === undefined || parent === current) return fiber
+    current = parent
+  }
+  return current
+}
+
+/** Describe one fiber, counting the registrations of the unnamed inline callbacks it owns (`adopted`) as its own. */
+export function reportFiber(fiber: FiberView, adopted: readonly FiberView[] = []): PluginReport {
+  const provides: string[] = []
+  const routes: RouteReport[] = []
+  const middleware: string[] = []
+  const other: string[] = []
+  const labels = [fiber, ...adopted].flatMap(source => flatten(source.getEffects()))
+  for (const label of labels) {
+    const provided = PROVIDE.exec(label)
+    const route = ROUTE.exec(label)
+    const used = USE.exec(label)
+    if (provided?.[1] !== undefined) provides.push(provided[1])
+    else if (route?.[1] !== undefined && route[2] !== undefined) routes.push({ method: route[1], path: route[2] })
+    else if (used?.[1] !== undefined) middleware.push(used[1])
+    else other.push(label)
+  }
+  return {
+    name: isNamed(fiber) ? fiber.runtime?.name ?? 'anonymous' : 'anonymous',
+    state: stateName(fiber.state),
+    requires: Object.keys(fiber.inject).sort(),
+    provides: provides.sort(),
+    routes,
+    middleware,
+    other,
+    removedOnUnload: labels.length,
+  }
+}
+
+const list = (items: readonly string[]): string => items.length === 0 ? 'nothing' : items.join(', ')
+
+/** A short, human explanation of one plugin: what it needs, what it adds, and what happens when it unloads. */
+export function explain(report: PluginReport): string {
+  const lines = [
+    `${report.name} (${report.state})`,
+    `  needs:     ${list(report.requires)}`,
+    `  provides:  ${list(report.provides)}`,
+    `  routes:    ${list(report.routes.map(route => `${route.method} ${route.path}`))}`,
+    `  middleware:${report.middleware.length === 0 ? ' nothing' : ` ${report.middleware.join(', ')}`}`,
+  ]
+  if (report.other.length > 0) lines.push(`  also:      ${report.other.join('; ')}`)
+  lines.push(report.state === 'PENDING'
+    ? `  waiting:   it starts when ${list(report.requires)} ${report.requires.length === 1 ? 'is' : 'are'} available`
+    : `  unloading: removes ${String(report.removedOnUnload)} registration${report.removedOnUnload === 1 ? '' : 's'} and nothing else`)
+  return lines.join('\n')
+}
+
+/** One block per plugin, in registration order. */
+export function renderReports(reports: readonly PluginReport[]): string {
+  return reports.map(explain).join('\n\n')
+}

package/plugins/acryl-inspect/src/service.ts

@@ -0,0 +1,66 @@
+/**
+ * The ACRYL inspector (`ctx.inspect`): what every running plugin requires, provides and registers, read from the live
+ * registry. It owns no state and registers nothing of its own beyond an optional read-only pair of router routes, which are
+ * reachable in process unless some plugin mounts their prefix over HTTP.
+ */
+
+import { Context, Service } from '@deepseek-ai/cordis'
+import { loopbackOnly } from '../../acryl-router/src/middleware/index.ts'
+import type {} from '../../acryl-router/src/index.ts'
+import { explain, ownerOf, renderReports, reportFiber, type FiberView, type PluginReport } from './report.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    inspect: Inspect
+  }
+}
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-inspect'
+
+export class Inspect extends Service {
+  constructor(ctx: Context) {
+    super(ctx, 'inspect')
+  }
+
+  /** A report for every live plugin instance, in registry order. */
+  plugins(): PluginReport[] {
+    const fibers = [...this.ctx.registry.values()].flatMap(runtime => [...runtime.fibers] as unknown as FiberView[])
+    // An unnamed inline callback is part of the plugin that wrote it: its routes and mounts are that plugin's.
+    const adopted = new Map<FiberView, FiberView[]>()
+    const owners: FiberView[] = []
+    for (const fiber of fibers) {
+      const owner = ownerOf(fiber)
+      if (owner === fiber) owners.push(fiber)
+      else adopted.set(owner, [...(adopted.get(owner) ?? []), fiber])
+    }
+    return owners.map(fiber => reportFiber(fiber, adopted.get(fiber) ?? []))
+  }
+
+  /** The text explanation of the plugin called `pluginName`, or `undefined` when none is registered. */
+  explain(pluginName: string): string | undefined {
+    const found = this.plugins().filter(report => report.name === pluginName)
+    return found.length === 0 ? undefined : found.map(explain).join('\n\n')
+  }
+
+  /** The whole system as text. */
+  render(): string {
+    return renderReports(this.plugins())
+  }
+}
+
+export function apply(ctx: Context): void {
+  const inspect = new Inspect(ctx)
+  // The same facts on the router, for any surface; present only where a router is. A request over a socket must come from this machine to this app;
+  // the terminal calls the router in process and is the host's own code.
+  ctx.inject(['router'], inner => {
+    const api = inner.router.group('/api/inspect', loopbackOnly({ inProcess: 'allow' }))
+    api.get('/plugins', c => c.json(inspect.plugins()))
+    api.get('/plugins/:name', c => {
+      const text = inspect.explain(c.param('name') ?? '')
+      return text === undefined ? c.json({ error: 'no such plugin' }, 404) : c.text(text)
+    })
+    // Over HTTP only where an adapter exists (Web and Desktop); the terminal needs none.
+    inner.inject(['routerHttp'], http => { http.routerHttp.mount('/api/inspect') })
+  })
+}

package/plugins/acryl-inspect/tests/report.spec.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest'
+import { explain, renderReports, reportFiber, stateName, type FiberView } from '../src/report.ts'
+
+function fiber(over: Partial<FiberView> & { effects?: FiberView['getEffects'] extends () => infer R ? R : never } = {}): FiberView {
+  const { effects = [], ...rest } = over
+  return { state: 2, inject: {}, runtime: { name: 'demo' }, getEffects: () => effects, ...rest }
+}
+
+describe('reportFiber', () => {
+  it('sorts effects into provides, routes, middleware and everything else, including nested ones', () => {
+    const report = reportFiber(fiber({
+      inject: { router: null, acrylSettings: null },
+      effects: [
+        { label: 'ctx.provide("things")', children: [] },
+        { label: 'acryl-router: GET /api/things/:id', children: [] },
+        { label: 'acryl-router: POST /api/things', children: [{ label: 'inner timer', children: [] }] },
+        { label: 'acryl-router: use /api', children: [] },
+        { label: 'ctx.on("internal/status")', children: [] },
+      ],
+    }))
+    expect(report).toEqual({
+      name: 'demo',
+      state: 'ACTIVE',
+      requires: ['acrylSettings', 'router'],
+      provides: ['things'],
+      routes: [{ method: 'GET', path: '/api/things/:id' }, { method: 'POST', path: '/api/things' }],
+      middleware: ['/api'],
+      other: ['inner timer', 'ctx.on("internal/status")'],
+      removedOnUnload: 6,
+    })
+  })
+
+  it('names the state and an anonymous plugin', () => {
+    expect(stateName(0)).toBe('PENDING')
+    expect(stateName(2)).toBe('ACTIVE')
+    expect(stateName(5)).toBe('UNLOADING')
+    expect(reportFiber(fiber({ runtime: null })).name).toBe('anonymous')
+  })
+})
+
+describe('explain', () => {
+  it('says what a plugin needs, adds and removes on unload', () => {
+    const text = explain(reportFiber(fiber({
+      inject: { router: null },
+      effects: [{ label: 'acryl-router: GET /a', children: [] }],
+    })))
+    expect(text).toContain('demo (ACTIVE)')
+    expect(text).toContain('needs:     router')
+    expect(text).toContain('routes:    GET /a')
+    expect(text).toContain('unloading: removes 1 registration and nothing else')
+  })
+
+  it('says a pending plugin is waiting for its services', () => {
+    const text = explain(reportFiber(fiber({ state: 0, inject: { router: null, webServer: null } })))
+    expect(text).toContain('demo (PENDING)')
+    expect(text).toContain('it starts when router, webServer are available')
+  })
+
+  it('renders several plugins as blocks', () => {
+    const a = reportFiber(fiber({ runtime: { name: 'a' } }))
+    const b = reportFiber(fiber({ runtime: { name: 'b' } }))
+    expect(renderReports([a, b]).split('\n\n')).toHaveLength(2)
+  })
+})

package/plugins/acryl-inspect/tests/service.spec.ts

@@ -0,0 +1,120 @@
+/**
+ * The inspector against real Cordis plugins: what it reports is what Cordis holds, so the tests build a small system and
+ * compare the report with what the plugins actually did.
+ */
+
+import { Context } from '@deepseek-ai/cordis'
+import { apply as routerApply, name as routerName } from '../../acryl-router/src/index.ts'
+import { afterEach, describe, expect, it } from 'vitest'
+import { apply, name, type PluginReport } from '../src/index.ts'
+
+const contexts: Context[] = []
+const settle = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0))
+afterEach(async () => {
+  while (contexts.length > 0) await contexts.pop()?.fiber.dispose()
+})
+
+const market = {
+  name: 'demo-market',
+  inject: ['router'],
+  apply(ctx: Context): void {
+    ctx.router.use('/api/demo', async (_c, next) => next())
+    ctx.router.get('/api/demo/state', c => c.json({ ok: true }))
+    ctx.router.post('/api/demo/sources', c => c.json({ ok: true }, 201))
+  },
+}
+
+async function system(): Promise<Context> {
+  const ctx = new Context()
+  contexts.push(ctx)
+  ctx.plugin({ name: routerName, apply: routerApply }, { trailingSlash: 'strict' })
+  ctx.plugin({ name, apply })
+  await settle()
+  return ctx
+}
+
+const byName = (reports: readonly PluginReport[], pluginName: string): PluginReport => {
+  const found = reports.find(report => report.name === pluginName)
+  if (found === undefined) throw new Error(`no report for ${pluginName}`)
+  return found
+}
+
+describe('acryl-inspect', () => {
+  it('counts what an inline ctx.inject callback registers as the owning plugin\'s', async () => {
+    const ctx = await system()
+    ctx.plugin({
+      name: 'demo-inline',
+      apply(inner: Context): void {
+        inner.inject(['router'], deeper => { deeper.router.get('/api/inline', c => c.json({ ok: true })) })
+      },
+    })
+    await settle()
+    const reports = ctx.inspect.plugins()
+    expect(byName(reports, 'demo-inline').routes).toEqual([{ method: 'GET', path: '/api/inline' }])
+    expect(reports.every(report => report.name !== 'anonymous')).toBe(true)
+  })
+
+  it('reports what a plugin requires, provides and registers, from the running system', async () => {
+    const ctx = await system()
+    ctx.plugin(market)
+    await settle()
+    const reports = ctx.inspect.plugins()
+
+    expect(byName(reports, 'acryl-router')).toMatchObject({ state: 'ACTIVE', requires: [], provides: ['router'] })
+    expect(byName(reports, 'acryl-inspect')).toMatchObject({ state: 'ACTIVE', provides: ['inspect'] })
+    const demo = byName(reports, 'demo-market')
+    expect(demo).toMatchObject({
+      state: 'ACTIVE',
+      requires: ['router'],
+      provides: [],
+      routes: [{ method: 'GET', path: '/api/demo/state' }, { method: 'POST', path: '/api/demo/sources' }],
+      middleware: ['/api/demo'],
+      removedOnUnload: 3,
+    })
+  })
+
+  it('shows a plugin whose service is missing as PENDING and says what it waits for', async () => {
+    const ctx = await system()
+    ctx.plugin({ name: 'needs-a-thing', inject: ['neverProvided'], apply() { /* never runs */ } })
+    await settle()
+    expect(byName(ctx.inspect.plugins(), 'needs-a-thing')).toMatchObject({ state: 'PENDING', requires: ['neverProvided'] })
+    expect(ctx.inspect.explain('needs-a-thing')).toContain('it starts when neverProvided is available')
+  })
+
+  it('stops listing a plugin that unloaded, and the router really lost what the report said would go', async () => {
+    const ctx = await system()
+    const baseline = ctx.router.size
+    const fiber = ctx.plugin(market)
+    await settle()
+    const promised = byName(ctx.inspect.plugins(), 'demo-market').removedOnUnload
+    expect(ctx.router.size - baseline).toBe(promised)
+
+    await fiber.dispose()
+    await settle()
+    expect(ctx.inspect.plugins().some(report => report.name === 'demo-market' && report.state === 'ACTIVE')).toBe(false)
+    expect(ctx.router.size).toBe(baseline)
+  })
+
+  it('serves the same facts on the router, in process', async () => {
+    const ctx = await system()
+    ctx.plugin(market)
+    await settle()
+    const list = await ctx.router.fetch(new Request('http://acryl.test/api/inspect/plugins'))
+    expect(list.status).toBe(200)
+    const reports = await list.json() as PluginReport[]
+    expect(byName(reports, 'demo-market').routes).toHaveLength(2)
+
+    const one = await ctx.router.fetch(new Request('http://acryl.test/api/inspect/plugins/demo-market'))
+    expect(await one.text()).toContain('removes 3 registrations and nothing else')
+    expect((await ctx.router.fetch(new Request('http://acryl.test/api/inspect/plugins/nope'))).status).toBe(404)
+  })
+
+  it('needs no router: without one it still answers in code and registers no routes', async () => {
+    const ctx = new Context()
+    contexts.push(ctx)
+    ctx.plugin({ name, apply })
+    await settle()
+    expect(byName(ctx.inspect.plugins(), 'acryl-inspect').routes).toEqual([])
+    expect(ctx.inspect.render()).toContain('acryl-inspect (ACTIVE)')
+  })
+})

package/plugins/acryl-inspect/upstream.json

@@ -0,0 +1,18 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-inspect",
+    "commit": "11fed295161c0282d144b5ac62616988b58d8189"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE"
+  ],
+  "rewrittenSpecifiers": 3,
+  "digest": "sha256:0fa799474c66b7a2a159c17ea143030b9fc6a38fcb4219f5139e78fd4508bdb7",
+  "testsNotRun": {},
+  "notice": [
+    "LICENSE"
+  ]
+}

package/plugins/acryl-node-server/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WebBoxes s.r.o.
+
+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/plugins/acryl-node-server/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "acryl-node-server",
+  "description": "The standalone HTTP server as a Cordis plugin: one node:http listener that sends every request to the router. Port, loopback host and next-free-port scan; ends open streams and frees the port when unloaded. Vendored from ACRYL.",
+  "requires": ["acryl-router", "acryl-router-http"],
+  "inject": ["router"],
+  "provides": ["nodeServer"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/schemastery": "3.18.4"
+  },
+  "mount": "root.plugin(router); root.plugin(nodeServer, { port: 3000, hostname: '127.0.0.1', scan: 20 }); ctx.nodeServer.url"
+}

package/plugins/acryl-node-server/src/index.ts

@@ -0,0 +1,94 @@
+/**
+ * The framework's standalone HTTP adapter (spec 046), the standalone counterpart of the Host adapter. It owns one
+ * `node:http` listener and hands every request to `ctx.router.fetch`, with the socket's peer address and local port as connection facts.
+ * Use it in an app that runs without the ACRYL Host; inside the Host, `acryl-router-http` mounts prefixes on the Host's own web server.
+ * One adapter per runtime: a plugin keeps asking `ctx.inject(['routerHttp'], ...)` for a mount, which simply never fires here, because this
+ * adapter serves the whole router.
+ *
+ * A configured port that is taken is followed by the next free one, at most `scan` further ports; port 0 lets the system choose. Disposal ends
+ * open streams, closes every connection and returns once the port is free.
+ */
+
+import { createServer, type Server } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { Context, Service } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { serve } from '../../acryl-router-http/src/index.ts'
+import type {} from '../../acryl-router/src/index.ts'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-node-server'
+export const inject = ['router']
+
+export interface Config {
+  hostname: string
+  port: number
+  scan: number
+}
+
+export const Config: z<Config> = z.object({
+  hostname: z.string().default('127.0.0.1').description('Address to bind. Loopback by default; binding elsewhere exposes the app to the network.'),
+  port: z.number().min(0).max(65535).default(0).description('Port to listen on; 0 lets the system choose. A taken port is followed by the next free one.'),
+  scan: z.number().min(0).default(20).description('How many further ports to try when the configured one is taken.'),
+})
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    nodeServer: NodeServer
+  }
+}
+
+export class NodeServer extends Service {
+  readonly hostname: string
+  readonly config: Config
+  private readonly server: Server
+  private bound = 0
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx, 'nodeServer')
+    this.config = config
+    this.hostname = config.hostname
+    const router = ctx.router
+    this.server = createServer((req, res) => { void serve(router, req, res) })
+    ctx.effect(() => async () => {
+      this.server.closeAllConnections()
+      if (this.server.listening) await new Promise<void>(resolve => { this.server.close(() => { resolve() }) })
+    }, 'acryl-node-server: close listener and open connections')
+  }
+
+  /** The port in use, 0 before the server listens. */
+  get port(): number {
+    return this.bound
+  }
+
+  /** The address clients use. */
+  get url(): string {
+    return `http://${this.hostname.includes(':') ? `[${this.hostname}]` : this.hostname}:${String(this.bound)}`
+  }
+
+  /** Bind, scanning past taken ports. */
+  async listen(): Promise<void> {
+    const { port, scan, hostname } = this.config
+    const last = port === 0 ? 0 : Math.min(65535, port + scan)
+    for (let candidate = port; candidate <= last; candidate += 1) {
+      try {
+        await new Promise<void>((resolve, reject) => {
+          const onError = (error: Error): void => { reject(error) }
+          this.server.once('error', onError)
+          this.server.listen(candidate, hostname, () => { this.server.off('error', onError); resolve() })
+        })
+        this.bound = (this.server.address() as AddressInfo).port
+        return
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EADDRINUSE') throw error
+      }
+    }
+    throw new Error(`acryl-node-server: no free port from ${String(port)} to ${String(last)} on ${hostname}`)
+  }
+}
+
+/** Loads once the server listens, so a plugin that injects `nodeServer` can rely on `url`. A failure to bind fails the plugin. */
+export async function apply(ctx: Context, config: Partial<Config> = {}): Promise<void> {
+  const server = new NodeServer(ctx, { hostname: '127.0.0.1', port: 0, scan: 20, ...config })
+  await server.listen()
+}