acrylblends 1.2.0 → 1.3.0

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

@@ -19,7 +19,7 @@ import { auditPath, AuditLog } from './host/audit.ts'
 import { UiChannel } from './host/channel.ts'
 import { registerChatTools } from './host/chat-tools.ts'
 import { PAGE_VERBS, VERBS } from './host/verbs.ts'
-import { Door, type ExtensionsPort, type ToolsPort } from './host/door.ts'
+import { Door, type ExtensionsPort, type PluginSharePort, type ToolsPort } from './host/door.ts'
 import { assertDoorIsFree, newSecret, removeDoorFile, stateDir, writeDoorFile } from './host/door-file.ts'
 import { DOOR_PREFIX, privateApi } from './host/http.ts'
 import { mcpRoutes } from './host/mcp-routes.ts'
@@ -182,6 +182,7 @@ export function apply(ctx: Context, rawConfig: Config = {}): void {
     app: { name: app.name, root: app.root, get url() { return address.url } },
     ...(appBase === '' ? {} : { appBase }),
     extensions: () => ctx.get('extensions') as unknown as ExtensionsPort | undefined,
+    pluginShare: () => ctx.get('pluginShare') as unknown as PluginSharePort | undefined,
     tools: () => ctx.get('tools') as unknown as ToolsPort | undefined,
     expose: config.tools?.expose ?? [],
     reloadOnChange: config.reloadOnChange !== false,

package/plugins/builder/index.ts

@@ -5,12 +5,13 @@
  * extensions folder, installs it, and gets back the real result (`active`, `pending` with what it waits for, or the error, with the
  * previous version restored). Writes are confined to that folder. The tools register in `ctx.effect`, so they leave with the builder.
  */
-import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import { scripted, type Tools } from '../agent/index.ts'
 import { NAME } from '../extensions/index.ts'
 import type {} from '../instance/index.ts'
+import { packagePlugin } from './package.ts'
 import { builderRules } from './script.ts'
 
 export interface BuilderConfig {
@@ -20,22 +21,6 @@ export interface BuilderConfig {
   packagesDir?: string
 }
 
-/** The package.json of a standalone plugin package: the host framework is a peer, never a second installed copy. */
-export function packageManifest(name: string, description: string): Record<string, unknown> {
-  return {
-    name,
-    version: '0.1.0',
-    description,
-    type: 'module',
-    exports: { '.': './index.ts', './package.json': './package.json' },
-    files: ['*.ts', '**/*.ts', 'README.md'],
-    // ACRYL measured it: a host package listed under dependencies brings a second copy of the framework, and its services stop
-    // matching after a restart. A peer names the version and installs nothing.
-    peerDependencies: { '@deepseek-ai/cordis': '4.0.4' },
-    keywords: ['cordis', 'cordis-plugin', 'acrylblends'],
-  }
-}
-
 const EXTENSIONS = new Set(['.ts', '.js', '.mjs', '.json', '.md'])
 const MAX_BYTES = 256 * 1024
 
@@ -154,8 +139,8 @@ export const builder = {
     )
     register(
       'package_plugin',
-      'Turn an extension into a standalone plugin package other apps can use: input { name, description? }. Returns its folder.',
-      (input) => {
+      'Turn an extension into a standalone plugin package other apps can pull: input { name, description? }. Writes the package folder and its release .tgz, the same bytes on every OS. Returns the folder, the file, its sha512 and its content digest.',
+      async (input) => {
         const name = pluginName(input)
         if (
           !existsSync(join(folder(name), 'index.ts')) &&
@@ -166,24 +151,17 @@ export const builder = {
         const description = String(
           (input as { description?: unknown }).description ?? `The ${name} Cordis plugin.`,
         )
-        const target = join(packagesDir, name)
-        rmSync(target, { recursive: true, force: true })
-        mkdirSync(packagesDir, { recursive: true })
-        cpSync(folder(name), target, {
-          recursive: true,
-          filter: (path) => !path.includes('node_modules'),
-        })
-        writeFileSync(
-          join(target, 'package.json'),
-          `${JSON.stringify(packageManifest(name, description), null, 2)}\n`,
-        )
-        if (!existsSync(join(target, 'README.md'))) {
-          writeFileSync(
-            join(target, 'README.md'),
-            `# ${name}\n\n${description}\n\nA Cordis plugin. In an ACRYLBLENDS app: \`acrylblends add <this folder>\`.\n`,
+        try {
+          return {
+            ok: true,
+            name,
+            ...(await packagePlugin(folder(name), packagesDir, name, description)),
+          }
+        } catch (cause) {
+          throw new BuilderError(
+            `${name}: ${cause instanceof Error ? cause.message : String(cause)}`,
           )
         }
-        return { ok: true, name, dir: target }
       },
     )
 

package/plugins/builder/package.ts

@@ -0,0 +1,186 @@
+/**
+ * Turning a plugin folder into what other people's apps can pull: a package folder and its release tarball, with the same bytes on every OS. The
+ * hub owns the tarball and the contract, blends-core what "portable" and "digest" mean; this module only decides what goes in.
+ */
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { extname, join } from 'node:path'
+import { digestFiles, pluginFiles, portabilityIssues } from '@webboxes/blends-core'
+import { packFolder, readTarball, syncServiceContract } from '@webboxes/plugin-hub'
+
+/** The package.json of a standalone plugin package: the host framework is a peer, never a second installed copy. */
+export function packageManifest(
+  name: string,
+  description: string,
+  version = '0.1.0',
+  release?: PackageRelease,
+): Record<string, unknown> {
+  return {
+    name,
+    version,
+    description,
+    ...(release === undefined
+      ? {}
+      : {
+          license: release.license,
+          repository: {
+            type: 'git',
+            url: `git+https://github.com/${release.owner}/${release.repo}.git`,
+          },
+        }),
+    type: 'module',
+    exports: { '.': './index.ts', './package.json': './package.json' },
+    // No `files` list: a plugin's plugin.json, data and .js files go with it, and the packer's own skips (node_modules, .git) apply.
+    // ACRYL measured it: a host package listed under dependencies brings a second copy of the framework, and its services stop
+    // matching after a restart. A peer names the version and installs nothing.
+    peerDependencies: { '@deepseek-ai/cordis': '4.0.4' },
+    keywords: ['cordis', 'cordis-plugin', 'acrylblends'],
+  }
+}
+
+/** Where a package is going to be released: written in now, so what is planned is byte for byte what is released. */
+export interface PackageRelease {
+  readonly owner: string
+  readonly repo: string
+  readonly license: string
+}
+
+export interface PackageOptions {
+  /** This version, instead of the one already packaged. */
+  readonly version?: string
+  readonly release?: PackageRelease
+}
+
+export interface PackagedPlugin {
+  readonly dir: string
+  readonly version: string
+  readonly files: readonly string[]
+  /** The release file, next to the package folder. */
+  readonly tarball: string
+  /** The tarball's sha512, as the registry lists it. */
+  readonly integrity: string
+  /** The sha256 of the plugin's content, which a source can name (`@sha256:<digest>`). */
+  readonly digest: string
+}
+
+/** Text whose line endings an editor or git on Windows may change: LF in the package, so those endings are not part of the plugin's identity. */
+const TEXT = new Set([
+  '.ts',
+  '.mts',
+  '.cts',
+  '.tsx',
+  '.js',
+  '.mjs',
+  '.cjs',
+  '.jsx',
+  '.json',
+  '.md',
+  '.txt',
+  '.css',
+  '.html',
+  '.yml',
+  '.yaml',
+  '.svg',
+])
+
+function withLineFeeds(dir: string): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) withLineFeeds(path)
+    else if (entry.isFile() && TEXT.has(extname(entry.name).toLowerCase())) {
+      const text = readFileSync(path, 'utf8')
+      if (text.includes('\r\n')) writeFileSync(path, text.replaceAll('\r\n', '\n'))
+    }
+  }
+}
+
+/** What the hub's share would otherwise add on the way out, changing the bytes after they were planned. */
+function markPublic(target: string): void {
+  const file = join(target, 'package.json')
+  const manifest = JSON.parse(readFileSync(file, 'utf8')) as Record<string, unknown>
+  writeFileSync(
+    file,
+    `${JSON.stringify({ ...manifest, acryl: { ...(manifest.acryl as object), visibility: 'public' } }, null, 2)}\n`,
+  )
+}
+
+function versionIn(target: string): string | undefined {
+  try {
+    const { version } = JSON.parse(readFileSync(join(target, 'package.json'), 'utf8')) as {
+      version?: unknown
+    }
+    return typeof version === 'string' ? version : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Package the plugin in `source` as `<packages>/<name>/` and `<packages>/<name>-<version>.tgz`. The person's folder is not touched. A version already
+ * packaged stays: a release is made once, and a person bumps it deliberately.
+ * @throws when the plugin would not work on every OS or its contract cannot be read; no package is left.
+ */
+export async function packagePlugin(
+  source: string,
+  packages: string,
+  name: string,
+  description: string,
+  options: PackageOptions = {},
+): Promise<PackagedPlugin> {
+  const target = join(packages, name)
+  const version = options.version ?? versionIn(target)
+  rmSync(target, { recursive: true, force: true })
+  mkdirSync(packages, { recursive: true })
+  cpSync(source, target, { recursive: true, filter: (path) => !path.includes('node_modules') })
+  try {
+    writeFileSync(
+      join(target, 'package.json'),
+      `${JSON.stringify(packageManifest(name, description, version, options.release), null, 2)}\n`,
+    )
+    if (!existsSync(join(target, 'README.md'))) {
+      writeFileSync(
+        join(target, 'README.md'),
+        `# ${name}\n\n${description}\n\nA Cordis plugin. Once it is released, pull it into an ACRYLBLENDS app while that app runs (\`npm run dev\`): \`npm run acryl -- plugin pull github:<owner>/<repo>\`.\n`,
+      )
+    }
+    withLineFeeds(target)
+    const issues = portabilityIssues(pluginFiles(target))
+    if (issues.length > 0)
+      throw new Error(
+        `it would not work on every OS: ${issues.map((issue) => `${issue.path}: ${issue.reason}`).join('; ')}`,
+      )
+    // The contract other people's apps and the registry read: what the plugin needs and provides, from its code.
+    const contract = await syncServiceContract(target)
+    if (!contract.ok)
+      throw new Error(`its service contract cannot be read: ${contract.errors.join('; ')}`)
+    if (options.release !== undefined) markPublic(target)
+    const packed = packFolder(target)
+    const tarball = join(packages, packed.fileName)
+    writeFileSync(tarball, packed.tarball)
+    const digest = digestFiles(
+      readTarball(packed.tarball).map(({ path, content }) => ({
+        path,
+        bytes: content,
+        kind: 'file' as const,
+      })),
+    )
+    return {
+      dir: target,
+      version: packed.version,
+      files: packed.files,
+      tarball,
+      integrity: packed.integrity,
+      digest,
+    }
+  } catch (cause) {
+    rmSync(target, { recursive: true, force: true })
+    throw cause
+  }
+}

package/plugins/builder/plugin.json

@@ -5,7 +5,9 @@
   "inject": ["extensions", "tools", "appInstance"],
   "provides": [],
   "dependencies": {
-    "@deepseek-ai/cordis": "4.0.4"
+    "@deepseek-ai/cordis": "4.0.4",
+    "@webboxes/blends-core": "0.5.0",
+    "@webboxes/plugin-hub": "0.2.0"
   },
   "mount": "mount it after agent and extensions: root.plugin(builder, { dir: join(root, 'plugins') }); dir must be an extensions source"
 }

package/plugins/extensions/index.ts

@@ -31,8 +31,8 @@ import { type Context, type Fiber, Service } from '@deepseek-ai/cordis'
 import type {} from '../instance/index.ts'
 import type { Sandbox } from '../sandbox/index.ts'
 import { appendLedger, type LedgerEntry, readLedger } from './ledger.ts'
-import { resolveFromApp, routerAliases } from './resolve.ts'
-import { discard, hashFolder, prune, stage } from './stage.ts'
+import { type PluginStore, pluginVersion } from './plugin-store.ts'
+import { folderPluginStore } from './stage.ts'
 
 /** A fiber's lifecycle state, by name (Cordis's own enum is a `const enum`, which does not exist at run time). */
 export type ExtensionState = 'pending' | 'loading' | 'active' | 'failed' | 'disposed' | 'unloading'
@@ -224,7 +224,6 @@ interface StateService {
 
 export class Extensions extends Service {
   readonly sources: readonly ExtensionSource[]
-  readonly stageRoot: string
   readonly stateFile: string
   readonly ledgerFile: string
   /** Settles when the startup pass is done. */
@@ -245,10 +244,12 @@ export class Extensions extends Service {
    * service's own fiber, so a plugin mounted from it would read `ctx.router` from the installer's fiber and fail. Extensions mount from this one.
    */
   private readonly owner: Context
+  private readonly store: PluginStore
 
-  constructor(ctx: Context, config: ExtensionsConfig = {}) {
+  constructor(ctx: Context, config: ExtensionsConfig, store: PluginStore) {
     super(ctx, 'extensions')
     this.owner = ctx
+    this.store = store
     this.readOnly = config.readOnly === true
     this.off = new Set(config.off ?? [])
     this.rows = new Set(config.rows ?? [])
@@ -260,14 +261,13 @@ export class Extensions extends Service {
         trust: config.approval === true && source.trust === 'install' ? 'ask' : source.trust,
       }),
     )
-    this.stageRoot = join(home, 'extensions-staged')
     this.stateFile = join(home, 'extensions.json')
     this.ledgerFile = join(home, 'extensions-ledger.jsonl')
     // Effects run their disposers newest first: settle pending operations, then dispose every mounted extension, then drop the hook.
     // Staged copies live in the app's home, outside the app: their bare imports are resolved from the app. A read-only start imports the folders where they are (inside the app).
     if (!this.readOnly)
       ctx.effect(
-        () => resolveFromApp(this.stageRoot, root, routerAliases()),
+        () => this.store.resolveImportsFrom(root),
         'extensions: resolve staged imports from the app',
       )
     ctx.effect(
@@ -317,7 +317,7 @@ export class Extensions extends Service {
           this.stale.add(entry.name)
           continue
         }
-        if (hashFolder(entry.source) !== entry.version)
+        if (pluginVersion(entry.source) !== entry.version)
           results.push(await this.installNow(entry.source))
       }
       for (const found of this.discover()) {
@@ -365,7 +365,7 @@ export class Extensions extends Service {
         }
       }
       this.requests.delete(name)
-      if (!existsSync(request.dir) || hashFolder(request.dir) !== request.version) {
+      if (!existsSync(request.dir) || pluginVersion(request.dir) !== request.version) {
         return {
           ok: false,
           stage: 'approval',
@@ -617,7 +617,7 @@ export class Extensions extends Service {
     const { name, dir, errors } = this.check(source)
     if (errors.length > 0) return { ok: false, stage: 'check', name, errors, next: NOTHING }
     const previous = this.installed.get(name)
-    const version = hashFolder(dir)
+    const version = pluginVersion(dir)
     const running =
       previous && previous.version === version && STATES[previous.fiber.state] !== 'failed'
     // A source that asks: this exact version must have been approved. Anything else waits, and the ledger says so.
@@ -648,12 +648,12 @@ export class Extensions extends Service {
     }
 
     // Import the new version while the old one keeps running: a syntax error or a missing export changes nothing.
-    const staged = stage(dir, this.stageRoot, name)
+    const staged = this.store.put(name, dir)
     let module: PluginModule
     try {
       module = await this.load(staged.dir, name)
     } catch (error) {
-      discard(staged.dir)
+      this.store.discard(staged)
       this.record({ kind: 'refused', name, version: staged.version, error: message(error) })
       return {
         ok: false,
@@ -680,7 +680,7 @@ export class Extensions extends Service {
           : undefined
     if (failure) {
       await mounted.fiber.dispose().catch(() => undefined)
-      discard(staged.dir)
+      this.store.discard(staged)
       const error = failure.error
       this.record({ kind: 'refused', name, version: staged.version, error })
       let restored = false
@@ -717,7 +717,7 @@ export class Extensions extends Service {
     })
     this.stale.delete(name)
     this.saveState()
-    prune(this.stageRoot, name, [staged.dir])
+    this.store.keepOnly(name, staged)
     this.record({ kind: action, name, version: staged.version })
     this.ctx.emit('extensions/changed', name, action)
     return {
@@ -737,7 +737,7 @@ export class Extensions extends Service {
     this.installed.delete(name)
     this.stale.delete(name)
     this.saveState()
-    prune(this.stageRoot, name, [])
+    this.store.keepOnly(name)
     this.record({ kind: 'removed', name, version: entry.version })
     this.ctx.emit('extensions/changed', name, 'removed')
     return { ok: true, name }
@@ -762,7 +762,7 @@ export class Extensions extends Service {
         this.installed.set(folder.name, {
           name: folder.name,
           source: folder.dir,
-          version: hashFolder(folder.dir),
+          version: pluginVersion(folder.dir),
           dir: folder.dir,
           module,
           fiber: mounted.fiber,
@@ -825,7 +825,7 @@ export class Extensions extends Service {
         // The source is gone: the last installed version still runs, and is reported as stale.
         summary.stale.push(name)
         this.stale.add(name)
-        if (!existsSync(record.dir)) {
+        if (!this.store.holds(record)) {
           summary.failed.push({ name, error: 'neither the source nor the staged copy exists' })
           continue
         }
@@ -869,7 +869,11 @@ export const extensions = {
   name: 'extensions',
   inject: ['appInstance'],
   async apply(ctx: Context, config: ExtensionsConfig) {
-    const service = new Extensions(ctx, config ?? {})
+    const service = new Extensions(
+      ctx,
+      config ?? {},
+      folderPluginStore(join(ctx.appInstance.home, 'extensions-staged')),
+    )
     await service.ready
   },
 }

package/plugins/extensions/plugin-store.ts

@@ -0,0 +1,27 @@
+/**
+ * Where installed versions of a plugin are kept, as the install transaction needs it. The transaction (`index.ts`) owns this port and says nothing about folders,
+ * copies or URLs; `stage.ts` is the adapter that keeps them on disk (Clean Architecture: a boundary owned by the use case; the layout is a detail).
+ */
+import { digestFolder } from '@webboxes/blends-core'
+
+/** One kept version of a plugin. `dir` is what the transaction imports it from. */
+export interface StoredPlugin {
+  readonly dir: string
+  readonly version: string
+}
+
+export interface PluginStore {
+  /** Keep this source as a version of `name` and return it. An unchanged source returns the version already kept. */
+  put(name: string, source: string): StoredPlugin
+  /** Whether this version, recorded earlier, is still here. */
+  holds(plugin: StoredPlugin): boolean
+  /** Drop a version that was refused. */
+  discard(plugin: StoredPlugin): void
+  /** Drop every version of `name` but `plugin`; all of them when none is given. */
+  keepOnly(name: string, plugin?: StoredPlugin): void
+  /** Let kept plugins import what the app at `appRoot` provides, until the returned function is called. */
+  resolveImportsFrom(appRoot: string): () => void
+}
+
+/** A short content digest of a plugin's folder: an unchanged source keeps its version. */
+export const pluginVersion = (dir: string): string => digestFolder(dir, 12)

package/plugins/extensions/plugin.json

@@ -6,7 +6,7 @@
   "provides": ["extensions"],
   "dependencies": {
     "@deepseek-ai/cordis": "4.0.4",
-    "@webboxes/blends-core": "0.4.0"
+    "@webboxes/blends-core": "0.5.0"
   },
   "mount": "mount it after instance: root.plugin(extensions, { sources: [{ dir: join(root, 'plugins'), trust: 'install' }] })"
 }

package/plugins/extensions/stage.ts

@@ -7,10 +7,9 @@
  */
 import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, 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)
+import { FOLDER_DIGEST_SKIPPED } from '@webboxes/blends-core'
+import { type PluginStore, pluginVersion } from './plugin-store.ts'
+import { resolveFromApp, routerAliases } from './resolve.ts'
 
 /**
  * Whether `node --watch` runs this process. It watches every module the process has imported, and keeps watching the paths of the runs before; a staged copy that is deleted
@@ -40,7 +39,7 @@ export function stage(
   stageRoot: string,
   name: string,
 ): { dir: string; version: string } {
-  const version = hashFolder(source)
+  const version = pluginVersion(source)
   const existing = staged(stageRoot, name, version)
   if (existing !== undefined) return { dir: existing, version }
   const stamp = String(Date.now()).padStart(15, '0')
@@ -70,3 +69,14 @@ export function prune(stageRoot: string, name: string, keep: readonly string[]):
     if (!keep.includes(path)) rmSync(path, { recursive: true, force: true })
   }
 }
+
+/** The plugin store of an app: its versions as staged copies under `stageRoot`. */
+export function folderPluginStore(stageRoot: string): PluginStore {
+  return {
+    put: (name, source) => stage(source, stageRoot, name),
+    holds: ({ dir }) => existsSync(dir),
+    discard: ({ dir }) => discard(dir),
+    keepOnly: (name, plugin) => prune(stageRoot, name, plugin ? [plugin.dir] : []),
+    resolveImportsFrom: (appRoot) => resolveFromApp(stageRoot, appRoot, routerAliases()),
+  }
+}

package/plugins/manifest/plugin.json

@@ -7,7 +7,7 @@
   "dependencies": {
     "@deepseek-ai/cordis": "4.0.4",
     "yaml": "2.9.0",
-    "@webboxes/blends-core": "0.4.0"
+    "@webboxes/blends-core": "0.5.0"
   },
   "mount": "in src/app.ts: const manifest = loadManifest(join(chosen.root, 'blend.yaml')); await compose(root, manifest, registry)"
 }

package/plugins/plugin-share/README.md

@@ -0,0 +1,51 @@
+# plugin-share
+
+Share plugins between people. Pull a plugin someone released into your running app, and publish your own as a plan a person confirms.
+
+## Pull
+
+```
+npm run acryl -- plugin pull github:<owner>/<repo>@<version>
+```
+
+The line someone gives you after publishing also carries `@sha256:<digest>`. Then a release with different bytes is refused, with exit 1, and nothing changes.
+
+The app must be running (`npm run dev`), because the pull installs into it live. A stopped app never installs offline: the line exits 3 and asks you to start the app and run the same line again.
+
+The app remembers where each pulled plugin came from, in the `plugin-share` row of `blend.yaml`. A copy of the app fetches the same bytes at its next start.
+
+## Publish
+
+```
+npm run acryl -- plugin publish <name> [--owner <account>] [--license <id>]
+```
+
+It prints the plan: account, repository, version, visibility and license. Only a person's yes at the terminal publishes. Declining sends nothing. An agent gets the plan and cannot say yes. The output ends with the pull line to give to others.
+
+## An app made by an older version
+
+Every new app has this plugin. `upgrade` does not add it to an older app, so add it and mount it by hand:
+
+```
+npx acrylblends add plugin-share
+npm install
+```
+
+In `src/app.ts`, import it, add it to the registry and give it the plugins folder:
+
+```ts
+import { pluginShare } from '../plugins/plugin-share/index.ts'
+// in the registry
+'plugin-share': pluginShare,
+// in the configuration passed to compose
+'plugin-share': { dir: extensionsDir },
+```
+
+In `blend.yaml`, add the row after `builder`:
+
+```yaml
+    - id: plugin-share
+      name: plugin-share
+```
+
+Then restart the app.