acrylblends 1.3.0 → 1.3.1

package/plugins/plugin-share/index.ts

@@ -34,10 +34,10 @@ import {
   sharePlugin,
   storeRootOf,
 } from '@webboxes/plugin-hub'
-import { packagePlugin } from '../builder/package.ts'
-import { NAME } from '../extensions/index.ts'
+import { type ExtensionInfo, NAME } from '../extensions/index.ts'
 import type {} from '../instance/index.ts'
 import { LOCK_FILE, writeLock } from '../manifest/lock.ts'
+import { packagePlugin } from './package.ts'
 import {
   type PublishOptions,
   type PublishPlan,
@@ -94,12 +94,42 @@ export type PullResult =
     }
   | PullRefused
 
+/** One plugin installed while the app runs, as a person reads the list: what it is and, for one pulled, where it came from and who released it. */
+/** What extensions says about an installed plugin (its state, the services a pending one waits for, ...), and where a pulled one came from. */
+export interface SharedPluginInfo extends ExtensionInfo {
+  /** The source it was pulled from (`github:<owner>/<repo>@<version>` or an address); absent for one made in this app or pulled from a local file. */
+  readonly pulledFrom?: string
+  /** Who released it: the account of a `github:` source or of a release address on github.com. */
+  readonly author?: string
+}
+
+/** What removing a plugin did with its folder in `plugins/`. */
+export type RemovedFolder =
+  /** It held the release as pulled, so nothing of anyone's is lost: the pull line brings it back. */
+  | 'deleted'
+  /** It is this app's own work, or a pulled plugin changed after the pull: it stays, and the app starts it again at its next start. */
+  | 'kept'
+  | 'none'
+
+export type SharedRemoveResult =
+  | {
+      readonly ok: true
+      readonly name: string
+      readonly folder: RemovedFolder
+      readonly note?: string
+    }
+  | { readonly ok: false; readonly name: string; readonly errors: readonly string[] }
+
 declare module '@deepseek-ai/cordis' {
   interface Context {
     pluginShare: PluginShare
   }
 }
 
+/** The account that released a source: the owner of a `github:<owner>/<repo>@<version>` source or of a release address on github.com. */
+const authorOf = (source: string): string | undefined =>
+  (/^github:([^/]+)\//u.exec(source) ?? /^https:\/\/github\.com\/([^/]+)\//u.exec(source))?.[1]
+
 /** The license a new public plugin is offered under; the plan shows it before the person says yes. */
 const DEFAULT_LICENSE = 'MIT'
 const LICENSE_ID = /^[A-Za-z0-9][A-Za-z0-9.+-]*$/u
@@ -149,15 +179,26 @@ export class PluginShare extends Service {
   private readonly ports: PublishPorts
   /** One at a time: two pulls of one name must not race for its folder, nor two publishes for its package. */
   private queue: Promise<unknown> = Promise.resolve()
+  /** The content digest of each plugin pulled while the app runs, a local file's too, which `blend.yaml` does not remember. */
+  private readonly live = new Map<string, string>()
+
+  /**
+   * The context the service was constructed with, in the app's realm. Inside a service method `this.ctx` is Cordis's shadow context of the caller: in the
+   * frame that is the host's door, which does not see the app's own services (`home`), so a plugin needing them was refused. As `extensions` does.
+   */
+  private readonly own: Context
 
   constructor(ctx: Context, config: PluginShareConfig) {
     super(ctx, 'pluginShare')
+    this.own = ctx
     this.dir = resolve(config.dir ?? join(ctx.appInstance.root, 'plugins'))
     this.releases = config.releases ?? githubReleasesOverHttps()
     this.ports = config.publish ?? { host: githubCli(), git: gitCli() }
     // Removing a plugin removes its record. Listened to here, not asked of each caller: every way of removing it goes through extensions.
     ctx.on('extensions/changed', (name, change) => {
-      if (change === 'removed') this.remember(name, undefined)
+      if (change !== 'removed') return
+      this.live.delete(name)
+      this.remember(name, undefined)
     })
     // Not awaited by the app's start: a person offline still gets their app, and the warning says what is missing.
     this.restored = this.inTurn(() => this.restore())
@@ -168,6 +209,37 @@ export class PluginShare extends Service {
     return this.inTurn(() => this.pullNow(source))
   }
 
+  /**
+   * The content digest of a pulled plugin as it was installed: set before its folder appears, so whoever sees the folder change can tell the release as
+   * pulled from an edit (the frame then does not load the app again for it). A pull from a local file has no record in `blend.yaml`; this knows it too.
+   */
+  pulledDigest(name: string): string | undefined {
+    return this.live.get(name) ?? this.recorded(name)?.digest
+  }
+
+  /** The plugins installed while the app runs, each pulled one with its source and author. */
+  list(): SharedPluginInfo[] {
+    const file = join(this.own.appInstance.root, 'blend.yaml')
+    const records = existsSync(file) ? pulledRecords(readFileSync(file, 'utf8')) : {}
+    return this.own.extensions.list().map((info) => {
+      const record = records[info.name]
+      const author = record === undefined ? undefined : authorOf(record.source)
+      return {
+        ...info,
+        ...(record === undefined ? {} : { pulledFrom: record.source }),
+        ...(author === undefined ? {} : { author }),
+      }
+    })
+  }
+
+  /**
+   * Take a plugin out of the running app and forget its record. A pulled plugin's folder is deleted when it still holds the release as pulled; a
+   * folder with someone's work in it (this app's own plugin, or a pulled one changed since) stays, and the answer says so.
+   */
+  remove(name: string): Promise<SharedRemoveResult> {
+    return this.inTurn(() => this.removeNow(name))
+  }
+
   private inTurn<T>(step: () => Promise<T>): Promise<T> {
     const run = this.queue.then(step)
     this.queue = run.catch(() => undefined)
@@ -199,7 +271,7 @@ export class PluginShare extends Service {
           'look at the new plan and say yes again',
         )
       }
-      const { home } = this.ctx.appInstance
+      const { home } = this.own.appInstance
       try {
         const shared = await sharePlugin(
           join(this.packages, name),
@@ -233,7 +305,7 @@ export class PluginShare extends Service {
 
   /** Write one plugin's record into `blend.yaml`, and the lock when the app has one, so the two still match. @returns whether the app holds the record. */
   private remember(name: string, record: PulledRecord | undefined): boolean {
-    const { root } = this.ctx.appInstance
+    const { root } = this.own.appInstance
     const file = join(root, 'blend.yaml')
     if (!existsSync(file)) return false
     const text = readFileSync(file, 'utf8')
@@ -246,9 +318,35 @@ export class PluginShare extends Service {
     return record === undefined || pulledRecords(next)[name] !== undefined
   }
 
+  private async removeNow(name: string): Promise<SharedRemoveResult> {
+    // Read before the removal, which forgets both the record and the live digest.
+    const pulled = this.pulledDigest(name)
+    const removed = await this.own.extensions.remove(name)
+    if (!removed.ok) return removed
+    const folder = join(this.dir, name)
+    if (!existsSync(folder)) return { ok: true, name, folder: 'none' }
+    if (pulled !== undefined && digestFolder(folder) === pulled) {
+      rmSync(folder, { recursive: true, force: true })
+      return { ok: true, name, folder: 'deleted' }
+    }
+    const why = pulled === undefined ? "is this app's own plugin" : 'was changed after the pull'
+    return {
+      ok: true,
+      name,
+      folder: 'kept',
+      note: `plugins/${name} ${why}, so it stays and the app starts it again at its next start; delete the folder to drop it for good`,
+    }
+  }
+
+  /** What `blend.yaml` remembers about one pulled plugin now. */
+  private recorded(name: string): PulledRecord | undefined {
+    const file = join(this.own.appInstance.root, 'blend.yaml')
+    return existsSync(file) ? pulledRecords(readFileSync(file, 'utf8'))[name] : undefined
+  }
+
   /** Fetch the remembered plugins whose folder is gone, exactly as recorded: other bytes are refused, and the record stays for the person to decide. */
   private async restore(): Promise<readonly RestoreOutcome[]> {
-    const file = join(this.ctx.appInstance.root, 'blend.yaml')
+    const file = join(this.own.appInstance.root, 'blend.yaml')
     if (!existsSync(file)) return []
     const outcomes: RestoreOutcome[] = []
     for (const [name, record] of Object.entries(pulledRecords(readFileSync(file, 'utf8')))) {
@@ -271,7 +369,7 @@ export class PluginShare extends Service {
   }
 
   private get packages(): string {
-    return join(this.ctx.appInstance.home, 'plugin-packages')
+    return join(this.own.appInstance.home, 'plugin-packages')
   }
 
   private async planNow(
@@ -338,7 +436,7 @@ export class PluginShare extends Service {
   }
 
   private async pullNow(input: string, expectIntegrity?: string): Promise<PullResult> {
-    const { home, root } = this.ctx.appInstance
+    const { home, root } = this.own.appInstance
     let read: ReturnType<typeof readSource>
     try {
       read = readSource(input, root)
@@ -376,7 +474,7 @@ export class PluginShare extends Service {
       const refused = pullRefusal(pulled.manifest, files, {
         digest: read.digest,
         nameFits: (name) => NAME.test(name),
-        hasService: (service) => this.ctx.get(service as never) !== undefined,
+        hasService: (service) => this.own.get(service as never) !== undefined,
       })
       if (refused !== undefined) return refused
       return await this.install(
@@ -411,20 +509,36 @@ export class PluginShare extends Service {
       const digest = digestFolder(incoming)
       // The folder may be there already: the same bytes are already pulled, anything else is someone's work.
       const wrote = !existsSync(target)
-      if (wrote) renameSync(incoming, target)
-      else if (digestFolder(target) !== digest) {
+      const before = this.recorded(name)
+      const held = wrote ? undefined : digestFolder(target)
+      if (held !== undefined && held !== digest) {
+        const holder = before === undefined ? 'made in this app' : `pulled from ${before.source}`
+        // Only an untouched pulled copy goes with `plugin remove`; anything else is someone's work, which the person moves themselves.
+        const next =
+          before !== undefined && held === before.digest
+            ? `keep it, or remove it (npm run acryl -- plugin remove ${name}) and pull again`
+            : `keep it, or move plugins/${name} out of plugins/ and pull again`
         return refuse(
           'folder-exists',
-          `plugins/${name} holds a different copy of this plugin`,
-          `keep it, or remove plugins/${name} and pull again`,
+          `plugins/${name} holds a different copy of this plugin, ${holder}`,
+          next,
         )
       }
+      const liveBefore = this.live.get(name)
+      this.live.set(name, digest)
+      if (wrote) renameSync(incoming, target)
+      // Remembered as the folder appears, before it is installed, so whoever sees the folder can tell it is these released bytes (the frame then does
+      // not load the app again for a plugin the app installs live); a pull that does not end running puts back what was remembered before.
+      const remembered = source !== undefined && this.remember(name, { source, integrity, digest })
       const undo = () => {
         if (wrote) rmSync(target, { recursive: true, force: true })
+        if (remembered) this.remember(name, before)
+        if (liveBefore === undefined) this.live.delete(name)
+        else this.live.set(name, liveBefore)
       }
       let result: Awaited<ReturnType<Context['extensions']['install']>>
       try {
-        result = await this.ctx.extensions.install(target)
+        result = await this.own.extensions.install(target)
       } catch (cause) {
         undo()
         return refuse(
@@ -438,7 +552,7 @@ export class PluginShare extends Service {
         return refuse('install', result.errors.join('; '), result.next)
       }
       if (result.state === 'pending') {
-        await this.ctx.extensions.remove(name)
+        await this.own.extensions.remove(name)
         undo()
         return missingServices(result.missing)
       }
@@ -450,7 +564,7 @@ export class PluginShare extends Service {
         digest,
         action: result.action,
         state: result.state,
-        remembered: source !== undefined && this.remember(name, { source, integrity, digest }),
+        remembered,
       }
     } finally {
       rmSync(incoming, { recursive: true, force: true })

package/plugins/plugin-share/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plugin-share",
   "description": "Share plugins between people. Pull one someone released into the running app: fetched without running anything, checked by digest and for every OS, then installed live. Publish one, only as a plan a person confirmed.",
-  "requires": ["instance", "extensions", "builder", "manifest"],
+  "requires": ["instance", "extensions", "manifest"],
   "inject": ["extensions", "appInstance"],
   "provides": ["pluginShare"],
   "dependencies": {

package/templates/agent/src/app.ts

@@ -216,6 +216,8 @@ export async function composeInto(
             ...(legacy ? [{ dir: legacyDir, trust: 'install' as const }] : []),
           ],
           rows: ownRows,
+          // Messages name a route as the plugin wrote it, not under the frame's canvas prefix.
+          ...(options.host === true ? { routePrefix: FRAME_MOUNT_PREFIX } : {}),
         },
         builder: { dir: extensionsDir },
         'plugin-share': { dir: extensionsDir },

package/templates/blank/blend.yaml

@@ -25,6 +25,9 @@ spec:
     # a row is never started twice. Read-only when NODE_ENV=production.
     - id: extensions
       name: extensions
+    # Sharing: `npm run acryl -- plugin pull github:<owner>/<repo>@<version>` installs a plugin someone released (development only).
+    - id: plugin-share
+      name: plugin-share
     - id: server
       name: acryl-node-server
       config:

package/templates/blank/src/app.ts

@@ -15,6 +15,7 @@ import {
   loadManifest,
   type ParameterValue,
 } from '../plugins/manifest/index.ts'
+import { pluginShare } from '../plugins/plugin-share/index.ts'
 import { doorEnabled } from './door.ts'
 import { FRAME_MOUNT_PREFIX, routes } from './routes.ts'
 
@@ -25,6 +26,7 @@ export const registry = {
   'acryl-door': door,
   home,
   extensions,
+  'plugin-share': pluginShare,
   routes,
 }
 
@@ -106,6 +108,8 @@ export async function composeInto(
   const leaveOut = new Set<string>(options.host === true ? HOST_ROWS : [])
   if (!own) leaveOut.add('acryl-node-server').add('acryl-door')
   if (!doorEnabled()) leaveOut.add('acryl-door')
+  // A pull runs a stranger's code and a publish leaves the machine: development only, like the door.
+  if (process.env.NODE_ENV === 'production') leaveOut.add('plugin-share')
   const manifest = without(read, ...leaveOut)
   // The rows that name one of the app's own plugin folders (a feature: plugins/<name>/ and its row) rather than a registry import. Each one that runs
   // is imported here; all of them, off or on, belong to their row, so the extensions row never starts them a second time.
@@ -129,7 +133,11 @@ export async function composeInto(
         ...(process.env.NODE_ENV === 'production' ? { readOnly: true } : {}),
         sources: [{ dir: PLUGINS_DIR, trust: 'install' }],
         rows: ownRows,
+        // Messages name a route as the plugin wrote it, not under the frame's canvas prefix.
+        ...(prefix === undefined ? {} : { routePrefix: prefix }),
       },
+      // Pulled plugins go where the extensions row installs from.
+      'plugin-share': { dir: PLUGINS_DIR },
       // Only the app's own server listens; the frame host owns the server and its port.
       ...(own ? { server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 } } : {}),
     },

package/templates/blank/template.json

@@ -7,6 +7,7 @@
     "save",
     "home",
     "extensions",
+    "plugin-share",
     "acryl-door",
     "acryl-web-server",
     "acryl-page"

package/templates/chat/blend.yaml

@@ -24,6 +24,9 @@ spec:
     # Read-only when NODE_ENV=production.
     - id: extensions
       name: extensions
+    # Sharing: `npm run acryl -- plugin pull github:<owner>/<repo>@<version>` installs a plugin someone released (development only).
+    - id: plugin-share
+      name: plugin-share
     - id: server
       name: acryl-node-server
       config:

package/templates/chat/src/app.ts

@@ -15,6 +15,7 @@ import {
   loadManifest,
   type ParameterValue,
 } from '../plugins/manifest/index.ts'
+import { pluginShare } from '../plugins/plugin-share/index.ts'
 import { doorEnabled } from './door.ts'
 import { FRAME_MOUNT_PREFIX, routes } from './routes.ts'
 
@@ -25,6 +26,7 @@ export const registry = {
   'acryl-node-server': nodeServer,
   'acryl-door': door,
   extensions,
+  'plugin-share': pluginShare,
   routes,
 }
 
@@ -106,6 +108,8 @@ export async function composeInto(
   const leaveOut = new Set<string>(options.host === true ? HOST_ROWS : [])
   if (!own) leaveOut.add('acryl-node-server').add('acryl-door')
   if (!doorEnabled()) leaveOut.add('acryl-door')
+  // A pull runs a stranger's code and a publish leaves the machine: development only, like the door.
+  if (process.env.NODE_ENV === 'production') leaveOut.add('plugin-share')
   const manifest = without(read, ...leaveOut)
   // The rows that name one of the app's own plugin folders (a feature: plugins/<name>/ and its row) rather than a registry import. Each one that runs
   // is imported here; all of them, off or on, belong to their row, so the extensions row never starts them a second time.
@@ -134,7 +138,11 @@ export async function composeInto(
         ...(process.env.NODE_ENV === 'production' ? { readOnly: true } : {}),
         sources: [{ dir: PLUGINS_DIR, trust: 'install' }],
         rows: ownRows,
+        // Messages name a route as the plugin wrote it, not under the frame's canvas prefix.
+        ...(prefix === undefined ? {} : { routePrefix: prefix }),
       },
+      // Pulled plugins go where the extensions row installs from.
+      'plugin-share': { dir: PLUGINS_DIR },
       // Only the app's own server listens; the frame host owns the server and its port.
       ...(own ? { server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 } } : {}),
     },

package/templates/chat/template.json

@@ -7,6 +7,7 @@
     "manifest",
     "save",
     "extensions",
+    "plugin-share",
     "acryl-door",
     "acryl-web-server",
     "acryl-page"

package/templates/nodejs/blend.yaml

@@ -21,6 +21,9 @@ spec:
     # Read-only when NODE_ENV=production.
     - id: extensions
       name: extensions
+    # Sharing: `npm run acryl -- plugin pull github:<owner>/<repo>@<version>` installs a plugin someone released (development only).
+    - id: plugin-share
+      name: plugin-share
     - id: server
       name: acryl-node-server
       config:

package/templates/nodejs/src/app.ts

@@ -14,6 +14,7 @@ import {
   loadManifest,
   type ParameterValue,
 } from '../plugins/manifest/index.ts'
+import { pluginShare } from '../plugins/plugin-share/index.ts'
 import { doorEnabled } from './door.ts'
 import { FRAME_MOUNT_PREFIX, routes } from './routes.ts'
 
@@ -23,6 +24,7 @@ export const registry = {
   'acryl-node-server': nodeServer,
   'acryl-door': door,
   extensions,
+  'plugin-share': pluginShare,
   routes,
 }
 
@@ -104,6 +106,8 @@ export async function composeInto(
   const leaveOut = new Set<string>(options.host === true ? HOST_ROWS : [])
   if (!own) leaveOut.add('acryl-node-server').add('acryl-door')
   if (!doorEnabled()) leaveOut.add('acryl-door')
+  // A pull runs a stranger's code and a publish leaves the machine: development only, like the door.
+  if (process.env.NODE_ENV === 'production') leaveOut.add('plugin-share')
   const manifest = without(read, ...leaveOut)
   // The rows that name one of the app's own plugin folders (a feature: plugins/<name>/ and its row) rather than a registry import. Each one that runs
   // is imported here; all of them, off or on, belong to their row, so the extensions row never starts them a second time.
@@ -127,7 +131,11 @@ export async function composeInto(
         ...(process.env.NODE_ENV === 'production' ? { readOnly: true } : {}),
         sources: [{ dir: PLUGINS_DIR, trust: 'install' }],
         rows: ownRows,
+        // Messages name a route as the plugin wrote it, not under the frame's canvas prefix.
+        ...(prefix === undefined ? {} : { routePrefix: prefix }),
       },
+      // Pulled plugins go where the extensions row installs from.
+      'plugin-share': { dir: PLUGINS_DIR },
       // Only the app's own server listens; the frame host owns the server and its port.
       ...(own ? { server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 } } : {}),
     },

package/templates/nodejs/template.json

@@ -6,6 +6,7 @@
     "manifest",
     "save",
     "extensions",
+    "plugin-share",
     "acryl-door",
     "acryl-web-server",
     "acryl-page"

package/templates/notes/blend.yaml

@@ -24,6 +24,9 @@ spec:
     # Read-only when NODE_ENV=production.
     - id: extensions
       name: extensions
+    # Sharing: `npm run acryl -- plugin pull github:<owner>/<repo>@<version>` installs a plugin someone released (development only).
+    - id: plugin-share
+      name: plugin-share
     - id: server
       name: acryl-node-server
       config:

package/templates/notes/src/app.ts

@@ -15,6 +15,7 @@ import {
   loadManifest,
   type ParameterValue,
 } from '../plugins/manifest/index.ts'
+import { pluginShare } from '../plugins/plugin-share/index.ts'
 import { doorEnabled } from './door.ts'
 import { FRAME_MOUNT_PREFIX, routes } from './routes.ts'
 
@@ -25,6 +26,7 @@ export const registry = {
   'acryl-node-server': nodeServer,
   'acryl-door': door,
   extensions,
+  'plugin-share': pluginShare,
   routes,
 }
 
@@ -106,6 +108,8 @@ export async function composeInto(
   const leaveOut = new Set<string>(options.host === true ? HOST_ROWS : [])
   if (!own) leaveOut.add('acryl-node-server').add('acryl-door')
   if (!doorEnabled()) leaveOut.add('acryl-door')
+  // A pull runs a stranger's code and a publish leaves the machine: development only, like the door.
+  if (process.env.NODE_ENV === 'production') leaveOut.add('plugin-share')
   const manifest = without(read, ...leaveOut)
   // The rows that name one of the app's own plugin folders (a feature: plugins/<name>/ and its row) rather than a registry import. Each one that runs
   // is imported here; all of them, off or on, belong to their row, so the extensions row never starts them a second time.
@@ -134,7 +138,11 @@ export async function composeInto(
         ...(process.env.NODE_ENV === 'production' ? { readOnly: true } : {}),
         sources: [{ dir: PLUGINS_DIR, trust: 'install' }],
         rows: ownRows,
+        // Messages name a route as the plugin wrote it, not under the frame's canvas prefix.
+        ...(prefix === undefined ? {} : { routePrefix: prefix }),
       },
+      // Pulled plugins go where the extensions row installs from.
+      'plugin-share': { dir: PLUGINS_DIR },
       // Only the app's own server listens; the frame host owns the server and its port.
       ...(own ? { server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 } } : {}),
     },

package/templates/notes/template.json

@@ -7,6 +7,7 @@
     "manifest",
     "save",
     "extensions",
+    "plugin-share",
     "acryl-door",
     "acryl-web-server",
     "acryl-page"