@acryldev/plugin-context 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (284) hide show
  1. package/LICENSE +21 -0
  2. package/docs/README.md +160 -0
  3. package/docs/delivery/local-live.md +113 -0
  4. package/docs/delivery/marketplace.md +16 -0
  5. package/docs/docs.json +2836 -0
  6. package/docs/extending/agent-preset.md +37 -0
  7. package/docs/extending/chat-command.md +28 -0
  8. package/docs/extending/client-slot.md +135 -0
  9. package/docs/extending/config-schema.md +7 -0
  10. package/docs/extending/cordis-core.md +63 -0
  11. package/docs/extending/desktop-app.md +53 -0
  12. package/docs/extending/desktop-main.md +25 -0
  13. package/docs/extending/event-hook.md +14 -0
  14. package/docs/extending/host-route.md +33 -0
  15. package/docs/extending/llm-adapter.md +38 -0
  16. package/docs/extending/packaging.md +53 -0
  17. package/docs/extending/prompt-contribution.md +9 -0
  18. package/docs/extending/service.md +13 -0
  19. package/docs/extending/skill-provider.md +9 -0
  20. package/docs/extending/state-and-persistence.md +71 -0
  21. package/docs/extending/three-role-capability.md +33 -0
  22. package/docs/extending/tool-plugin.md +24 -0
  23. package/docs/extending/tui-command.md +8 -0
  24. package/docs/extending/tui-components.md +61 -0
  25. package/docs/extending/ui-branding.md +43 -0
  26. package/docs/extending/ui-components.md +56 -0
  27. package/docs/extending/ui-customization.md +41 -0
  28. package/docs/extending/ui-library.md +66 -0
  29. package/docs/extending/ui-theme.md +55 -0
  30. package/docs/extending/workspace-tab.md +50 -0
  31. package/docs/maps/events.md +108 -0
  32. package/docs/maps/mount-points.md +154 -0
  33. package/docs/maps/slot-contracts.md +3376 -0
  34. package/docs/maps/taxonomy.md +306 -0
  35. package/docs/maps/theme-tokens.md +115 -0
  36. package/docs/maps/ui-components.md +26 -0
  37. package/docs/reference/cookbook/adding-a-package.md +174 -0
  38. package/docs/reference/cookbook/adding-a-remote-api.md +199 -0
  39. package/docs/reference/cookbook/adding-a-settings-card.md +74 -0
  40. package/docs/reference/cookbook/adding-a-tool.md +103 -0
  41. package/docs/reference/cookbook/adding-an-llm-adapter.md +45 -0
  42. package/docs/reference/cookbook/extension-cookbook.md +134 -0
  43. package/docs/reference/cordis-api/context.md +366 -0
  44. package/docs/reference/cordis-api/events.md +209 -0
  45. package/docs/reference/cordis-api/fiber.md +377 -0
  46. package/docs/reference/cordis-api/inherited.md +40 -0
  47. package/docs/reference/cordis-api/registry.md +154 -0
  48. package/docs/reference/cordis-api/service.md +104 -0
  49. package/docs/reference/cordis-guides/cordis-usage-cheatsheet.md +167 -0
  50. package/docs/reference/cordis-guides/cordis_system_guide_for_coding_agents.md +4666 -0
  51. package/docs/reference/cordis-guides/development-canvas-plugin.md +109 -0
  52. package/docs/reference/cordis-guides/hello-world-plugin-guide.md +517 -0
  53. package/docs/reference/harness/agent-lifecycle.md +93 -0
  54. package/docs/reference/harness/architecture.md +168 -0
  55. package/docs/reference/harness/capability-seams.md +675 -0
  56. package/docs/reference/harness/config-catalog.md +4523 -0
  57. package/docs/reference/harness/cordis-primer.md +47 -0
  58. package/docs/reference/harness/defensive-patterns.md +35 -0
  59. package/docs/reference/harness/event-producer-consumer.md +111 -0
  60. package/docs/reference/harness/glossary.md +47 -0
  61. package/docs/reference/harness/tool-catalog.md +2721 -0
  62. package/docs/reference/harness/tool-execution-pipeline.md +67 -0
  63. package/docs/reference/subsystems/README.md +75 -0
  64. package/docs/reference/subsystems/agent-team.md +233 -0
  65. package/docs/reference/subsystems/approval.md +172 -0
  66. package/docs/reference/subsystems/attachment.md +363 -0
  67. package/docs/reference/subsystems/boot.md +324 -0
  68. package/docs/reference/subsystems/browser-use.md +69 -0
  69. package/docs/reference/subsystems/client-modules.md +186 -0
  70. package/docs/reference/subsystems/client-resources.md +94 -0
  71. package/docs/reference/subsystems/commands.md +225 -0
  72. package/docs/reference/subsystems/compaction.md +286 -0
  73. package/docs/reference/subsystems/computer-use.md +58 -0
  74. package/docs/reference/subsystems/conversation.md +287 -0
  75. package/docs/reference/subsystems/core.md +1107 -0
  76. package/docs/reference/subsystems/credentials.md +497 -0
  77. package/docs/reference/subsystems/deliverables.md +180 -0
  78. package/docs/reference/subsystems/extensions.md +386 -0
  79. package/docs/reference/subsystems/feedback.md +402 -0
  80. package/docs/reference/subsystems/filesystem.md +532 -0
  81. package/docs/reference/subsystems/goal.md +315 -0
  82. package/docs/reference/subsystems/invariants.md +90 -0
  83. package/docs/reference/subsystems/jobs.md +501 -0
  84. package/docs/reference/subsystems/llm-streaming.md +1131 -0
  85. package/docs/reference/subsystems/lsp.md +204 -0
  86. package/docs/reference/subsystems/mcp.md +141 -0
  87. package/docs/reference/subsystems/office-to-pdf.md +89 -0
  88. package/docs/reference/subsystems/otel.md +46 -0
  89. package/docs/reference/subsystems/permission-presets.md +169 -0
  90. package/docs/reference/subsystems/persistence.md +418 -0
  91. package/docs/reference/subsystems/plan.md +89 -0
  92. package/docs/reference/subsystems/product-telemetry.md +81 -0
  93. package/docs/reference/subsystems/ptc-runtime.md +234 -0
  94. package/docs/reference/subsystems/sandbox.md +223 -0
  95. package/docs/reference/subsystems/schedule.md +545 -0
  96. package/docs/reference/subsystems/scope.md +61 -0
  97. package/docs/reference/subsystems/session-projection.md +358 -0
  98. package/docs/reference/subsystems/session-query.md +511 -0
  99. package/docs/reference/subsystems/session-reference.md +226 -0
  100. package/docs/reference/subsystems/session-telemetry.md +214 -0
  101. package/docs/reference/subsystems/session-title.md +206 -0
  102. package/docs/reference/subsystems/session.md +1300 -0
  103. package/docs/reference/subsystems/settings.md +157 -0
  104. package/docs/reference/subsystems/shell.md +316 -0
  105. package/docs/reference/subsystems/sidebar-right.md +160 -0
  106. package/docs/reference/subsystems/skills.md +354 -0
  107. package/docs/reference/subsystems/slots.md +201 -0
  108. package/docs/reference/subsystems/spill.md +126 -0
  109. package/docs/reference/subsystems/ssh.md +137 -0
  110. package/docs/reference/subsystems/storage.md +262 -0
  111. package/docs/reference/subsystems/subagent.md +762 -0
  112. package/docs/reference/subsystems/subprocess.md +323 -0
  113. package/docs/reference/subsystems/system-prompt.md +226 -0
  114. package/docs/reference/subsystems/terminal.md +186 -0
  115. package/docs/reference/subsystems/todo.md +34 -0
  116. package/docs/reference/subsystems/token-meter.md +108 -0
  117. package/docs/reference/subsystems/tools.md +749 -0
  118. package/docs/reference/subsystems/typert.md +489 -0
  119. package/docs/reference/subsystems/user-questions.md +309 -0
  120. package/docs/reference/subsystems/voice-input.md +166 -0
  121. package/docs/reference/subsystems/web-client.md +102 -0
  122. package/docs/reference/subsystems/web-server.md +228 -0
  123. package/docs/reference/subsystems/web.md +208 -0
  124. package/docs/reference/subsystems/webhook.md +72 -0
  125. package/docs/reference/subsystems/workflow.md +280 -0
  126. package/docs/reference/subsystems/workspace.md +661 -0
  127. package/docs/start-here/blueprints.md +33 -0
  128. package/docs/start-here/this-runtime.md +84 -0
  129. package/docs/start-here/troubleshooting.md +29 -0
  130. package/docs/start-here/trust-and-safety.md +39 -0
  131. package/docs/start-here/verify-before-done.md +46 -0
  132. package/example-plugins/README.md +45 -0
  133. package/example-plugins/packages/agent-preset-reviewer/agent.cordis.yml +18 -0
  134. package/example-plugins/packages/agent-preset-reviewer/preset.yml +3 -0
  135. package/example-plugins/packages/capability-swap-consumer/cordis.patch.yml +3 -0
  136. package/example-plugins/packages/capability-swap-consumer/index.js +14 -0
  137. package/example-plugins/packages/capability-swap-consumer/package.json +25 -0
  138. package/example-plugins/packages/capability-swap-provider-loud/cordis.patch.yml +3 -0
  139. package/example-plugins/packages/capability-swap-provider-loud/index.js +20 -0
  140. package/example-plugins/packages/capability-swap-provider-loud/package.json +25 -0
  141. package/example-plugins/packages/capability-swap-provider-quiet/cordis.patch.yml +3 -0
  142. package/example-plugins/packages/capability-swap-provider-quiet/index.js +20 -0
  143. package/example-plugins/packages/capability-swap-provider-quiet/package.json +25 -0
  144. package/example-plugins/packages/chat-command-basic/cordis.patch.yml +3 -0
  145. package/example-plugins/packages/chat-command-basic/index.js +26 -0
  146. package/example-plugins/packages/chat-command-basic/package.json +25 -0
  147. package/example-plugins/packages/client-chat-message-action/client.js +46 -0
  148. package/example-plugins/packages/client-chat-message-action/cordis.patch.yml +3 -0
  149. package/example-plugins/packages/client-chat-message-action/index.js +9 -0
  150. package/example-plugins/packages/client-chat-message-action/package.json +31 -0
  151. package/example-plugins/packages/client-slot-header-action/client.js +57 -0
  152. package/example-plugins/packages/client-slot-header-action/cordis.patch.yml +3 -0
  153. package/example-plugins/packages/client-slot-header-action/index.js +13 -0
  154. package/example-plugins/packages/client-slot-header-action/package.json +31 -0
  155. package/example-plugins/packages/client-slot-sidebar-tab/client.js +57 -0
  156. package/example-plugins/packages/client-slot-sidebar-tab/cordis.patch.yml +3 -0
  157. package/example-plugins/packages/client-slot-sidebar-tab/index.js +9 -0
  158. package/example-plugins/packages/client-slot-sidebar-tab/package.json +32 -0
  159. package/example-plugins/packages/client-theme-override/client.js +52 -0
  160. package/example-plugins/packages/client-theme-override/cordis.patch.yml +3 -0
  161. package/example-plugins/packages/client-theme-override/index.js +9 -0
  162. package/example-plugins/packages/client-theme-override/package.json +30 -0
  163. package/example-plugins/packages/client-tool-view/client.js +47 -0
  164. package/example-plugins/packages/client-tool-view/cordis.patch.yml +3 -0
  165. package/example-plugins/packages/client-tool-view/index.js +24 -0
  166. package/example-plugins/packages/client-tool-view/package.json +34 -0
  167. package/example-plugins/packages/client-ui-components/client.js +77 -0
  168. package/example-plugins/packages/client-ui-components/cordis.patch.yml +3 -0
  169. package/example-plugins/packages/client-ui-components/index.js +9 -0
  170. package/example-plugins/packages/client-ui-components/package.json +31 -0
  171. package/example-plugins/packages/client-ui-library/client.js +715 -0
  172. package/example-plugins/packages/client-ui-library/cordis.patch.yml +3 -0
  173. package/example-plugins/packages/client-ui-library/index.js +9 -0
  174. package/example-plugins/packages/client-ui-library/package.json +37 -0
  175. package/example-plugins/packages/client-workspace-tab/client.js +72 -0
  176. package/example-plugins/packages/client-workspace-tab/cordis.patch.yml +3 -0
  177. package/example-plugins/packages/client-workspace-tab/index.js +9 -0
  178. package/example-plugins/packages/client-workspace-tab/package.json +30 -0
  179. package/example-plugins/packages/config-schema-basic/cordis.patch.yml +3 -0
  180. package/example-plugins/packages/config-schema-basic/index.js +19 -0
  181. package/example-plugins/packages/config-schema-basic/package.json +25 -0
  182. package/example-plugins/packages/desktop-main-profile-info/cordis.patch.yml +3 -0
  183. package/example-plugins/packages/desktop-main-profile-info/index.js +22 -0
  184. package/example-plugins/packages/desktop-main-profile-info/package.json +25 -0
  185. package/example-plugins/packages/event-hook-basic/cordis.patch.yml +3 -0
  186. package/example-plugins/packages/event-hook-basic/index.js +17 -0
  187. package/example-plugins/packages/event-hook-basic/package.json +22 -0
  188. package/example-plugins/packages/generated-capability-template/cordis.patch.yml +3 -0
  189. package/example-plugins/packages/generated-capability-template/index.js +16 -0
  190. package/example-plugins/packages/generated-capability-template/package.json +42 -0
  191. package/example-plugins/packages/host-route-basic/cordis.patch.yml +3 -0
  192. package/example-plugins/packages/host-route-basic/index.js +20 -0
  193. package/example-plugins/packages/host-route-basic/package.json +29 -0
  194. package/example-plugins/packages/lifecycle-function-basic/cordis.patch.yml +3 -0
  195. package/example-plugins/packages/lifecycle-function-basic/index.js +12 -0
  196. package/example-plugins/packages/lifecycle-function-basic/package.json +15 -0
  197. package/example-plugins/packages/lifecycle-function-hot-shim/cordis.patch.yml +3 -0
  198. package/example-plugins/packages/lifecycle-function-hot-shim/impl.js +5 -0
  199. package/example-plugins/packages/lifecycle-function-hot-shim/index.js +18 -0
  200. package/example-plugins/packages/lifecycle-function-hot-shim/package.json +23 -0
  201. package/example-plugins/packages/lifecycle-hooks-observer/cordis.patch.yml +3 -0
  202. package/example-plugins/packages/lifecycle-hooks-observer/index.js +23 -0
  203. package/example-plugins/packages/lifecycle-hooks-observer/package.json +22 -0
  204. package/example-plugins/packages/llm-adapter-echo/cordis.patch.yml +3 -0
  205. package/example-plugins/packages/llm-adapter-echo/index.js +42 -0
  206. package/example-plugins/packages/llm-adapter-echo/package.json +25 -0
  207. package/example-plugins/packages/prompt-assemble-hook/cordis.patch.yml +3 -0
  208. package/example-plugins/packages/prompt-assemble-hook/index.js +22 -0
  209. package/example-plugins/packages/prompt-assemble-hook/package.json +22 -0
  210. package/example-plugins/packages/prompt-contribution-basic/cordis.patch.yml +3 -0
  211. package/example-plugins/packages/prompt-contribution-basic/index.js +18 -0
  212. package/example-plugins/packages/prompt-contribution-basic/package.json +22 -0
  213. package/example-plugins/packages/service-consumer-greeter/cordis.patch.yml +3 -0
  214. package/example-plugins/packages/service-consumer-greeter/index.js +14 -0
  215. package/example-plugins/packages/service-consumer-greeter/package.json +22 -0
  216. package/example-plugins/packages/service-provider-greeter/cordis.patch.yml +3 -0
  217. package/example-plugins/packages/service-provider-greeter/index.js +22 -0
  218. package/example-plugins/packages/service-provider-greeter/package.json +25 -0
  219. package/example-plugins/packages/settings-section-basic/cordis.patch.yml +3 -0
  220. package/example-plugins/packages/settings-section-basic/index.js +34 -0
  221. package/example-plugins/packages/settings-section-basic/package.json +26 -0
  222. package/example-plugins/packages/skill-provider-basic/cordis.patch.yml +3 -0
  223. package/example-plugins/packages/skill-provider-basic/index.js +31 -0
  224. package/example-plugins/packages/skill-provider-basic/package.json +22 -0
  225. package/example-plugins/packages/state-host-store/client.js +57 -0
  226. package/example-plugins/packages/state-host-store/cordis.patch.yml +3 -0
  227. package/example-plugins/packages/state-host-store/index.js +90 -0
  228. package/example-plugins/packages/state-host-store/package.json +31 -0
  229. package/example-plugins/packages/state-workspace-file/cordis.patch.yml +3 -0
  230. package/example-plugins/packages/state-workspace-file/index.js +52 -0
  231. package/example-plugins/packages/state-workspace-file/package.json +25 -0
  232. package/example-plugins/packages/tool-basic/cordis.patch.yml +3 -0
  233. package/example-plugins/packages/tool-basic/index.js +25 -0
  234. package/example-plugins/packages/tool-basic/package.json +25 -0
  235. package/example-plugins/packages/tool-policy-hook/cordis.patch.yml +3 -0
  236. package/example-plugins/packages/tool-policy-hook/index.js +28 -0
  237. package/example-plugins/packages/tool-policy-hook/package.json +25 -0
  238. package/example-plugins/packages/tui-command-basic/cordis.patch.yml +3 -0
  239. package/example-plugins/packages/tui-command-basic/index.js +24 -0
  240. package/example-plugins/packages/tui-command-basic/package.json +22 -0
  241. package/example-plugins/packages/tui-overlay-themed/cordis.patch.yml +3 -0
  242. package/example-plugins/packages/tui-overlay-themed/index.js +65 -0
  243. package/example-plugins/packages/tui-overlay-themed/package.json +25 -0
  244. package/example-plugins/packages/tui-ui-library/cordis.patch.yml +3 -0
  245. package/example-plugins/packages/tui-ui-library/index.js +73 -0
  246. package/example-plugins/packages/tui-ui-library/package.json +29 -0
  247. package/example-plugins/packages/web-page-branding/cordis.patch.yml +3 -0
  248. package/example-plugins/packages/web-page-branding/index.js +31 -0
  249. package/example-plugins/packages/web-page-branding/package.json +22 -0
  250. package/example-plugins/scenarios.json +11 -0
  251. package/index.js +384 -0
  252. package/lib/blend-apply.js +107 -0
  253. package/lib/blend-capture.js +249 -0
  254. package/lib/blend-ledger.js +76 -0
  255. package/lib/contract.js +5 -0
  256. package/lib/install.js +516 -0
  257. package/lib/lookup.js +67 -0
  258. package/lib/manifest.js +56 -0
  259. package/lib/pack-root.js +22 -0
  260. package/lib/provenance.js +110 -0
  261. package/lib/publish.js +64 -0
  262. package/lib/reconcile.js +83 -0
  263. package/lib/router.js +55 -0
  264. package/lib/scopes.js +82 -0
  265. package/lib/skills.js +54 -0
  266. package/lib/stage.js +157 -0
  267. package/lib/verify.js +77 -0
  268. package/package.json +56 -3
  269. package/scripts/lib/indexes.mjs +45 -0
  270. package/scripts/lib/manifest.mjs +127 -0
  271. package/scripts/lib/maps.mjs +482 -0
  272. package/skills/acryl-add-provider-or-capability/SKILL.md +12 -0
  273. package/skills/acryl-add-ui/SKILL.md +18 -0
  274. package/skills/acryl-build-plugin/SKILL.md +21 -0
  275. package/skills/acryl-change-plugin/SKILL.md +16 -0
  276. package/skills/acryl-desktop-shell/SKILL.md +12 -0
  277. package/skills/acryl-diagnose-plugin/SKILL.md +10 -0
  278. package/skills/acryl-fix-plugin/SKILL.md +12 -0
  279. package/skills/acryl-improve-ui/SKILL.md +10 -0
  280. package/skills/acryl-remove-plugin/SKILL.md +11 -0
  281. package/skills/acryl-restyle-ui/SKILL.md +14 -0
  282. package/skills/acryl-share-plugin/SKILL.md +23 -0
  283. package/skills/acryl-tui-ui/SKILL.md +12 -0
  284. package/README.md +0 -3
package/lib/install.js ADDED
@@ -0,0 +1,516 @@
1
+ import { existsSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
2
+ import { tmpdir } from 'node:os'
3
+ import { isAbsolute, join, relative, resolve, sep } from 'node:path'
4
+ import { hashPackage, pruneOldStages, pruneOldVersions, stagePackage, stagedSource } from './stage.js'
5
+ import { canonical, discoverPlugins, installState } from './reconcile.js'
6
+ import { checkManifest, readManifest } from './manifest.js'
7
+ import { listInstalledPlugins } from './provenance.js'
8
+
9
+ /**
10
+ * Static checks for the two failures measured in spec 037 research Q7 that make
11
+ * a package install but never go live, or not install at all. Cheap and
12
+ * deterministic; the full mount-level verification is a separate task.
13
+ * @returns {{ name?: string, errors: string[] }}
14
+ */
15
+ export function lintPackageDir(dir, fs = { existsSync, readFileSync }) {
16
+ const errors = []
17
+ const manifestPath = join(dir, 'package.json')
18
+ if (!fs.existsSync(manifestPath)) return { errors: [`no package.json in ${dir}`] }
19
+ let pkg
20
+ try { pkg = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) } catch (cause) { return { errors: [`package.json is not valid JSON: ${cause instanceof Error ? cause.message : cause}`] } }
21
+ if (typeof pkg.name !== 'string' || pkg.name === '') errors.push('package.json needs a "name"')
22
+ const patch = pkg.dsh?.bundle?.patch
23
+ if (typeof patch !== 'string' || patch === '') {
24
+ errors.push('package.json needs "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }; without it the package is installed as a plain dependency but never added to the profile')
25
+ } else {
26
+ if (!fs.existsSync(join(dir, patch))) errors.push(`the bundle patch ${patch} does not exist`)
27
+ if (Array.isArray(pkg.files) && !pkg.files.some(f => join(dir, f) === join(dir, patch) || patch.replace(/^\.\//u, '') === f.replace(/^\.\//u, ''))) errors.push(`the bundle patch ${patch} is not in "files"`)
28
+ }
29
+ const exp = pkg.exports
30
+ if (exp !== undefined && (typeof exp !== 'object' || exp === null || !('./package.json' in exp))) {
31
+ errors.push('"exports" must include "./package.json" (for example { ".": "./index.js", "./package.json": "./package.json" }); otherwise the package installs but live activation fails with ERR_PACKAGE_PATH_NOT_EXPORTED')
32
+ }
33
+ if (pkg.dsh?.client !== undefined) {
34
+ const clientExport = exp && typeof exp === 'object' ? exp['./client'] : undefined
35
+ if (typeof clientExport !== 'string') errors.push('a package with "dsh.client" must export its browser bundle as "./client" in "exports" (for example "./client": "./client.js")')
36
+ else if (!fs.existsSync(join(dir, clientExport))) errors.push(`the client bundle ${clientExport} does not exist`)
37
+ }
38
+ const requiresAcrylPackages = pkg.dsh?.requiresAcrylPackages
39
+ if (requiresAcrylPackages !== undefined && (!Array.isArray(requiresAcrylPackages) || !requiresAcrylPackages.every(name => typeof name === 'string'))) {
40
+ errors.push('"dsh.requiresAcrylPackages" must be a list of package name strings')
41
+ }
42
+ errors.push(...hostOwnedDependencyErrors(pkg))
43
+ errors.push(...checkManifest(pkg))
44
+ const { apiVersion, permissions } = readManifest(pkg)
45
+ return { name: pkg.name, hasClient: pkg.dsh?.client !== undefined, hotShim: usesHotShim(dir, pkg, fs), apiVersion, permissions, requiresAcrylPackages: Array.isArray(requiresAcrylPackages) ? requiresAcrylPackages : [], errors }
46
+ }
47
+
48
+ /**
49
+ * Packages the app itself provides to every plugin: the harness framework, the terminal toolkit, and the web framework (`acrylblends`, whose
50
+ * router a plugin reaches through `dsh.requiresAcrylPackages`, which links the app's own copy into the profile).
51
+ */
52
+ const HOST_OWNED_PACKAGES = /^(?:@(?:deepseek-ai|earendil-works)\/|acrylblends$)/u
53
+
54
+ /**
55
+ * A plugin must not install the app's own packages. Listed under `dependencies`, the install puts a second physical copy of the framework into the
56
+ * profile, and from the next restart the plugin's imports resolve to that copy while the app runs on its own: unique symbols and classes no longer match
57
+ * (measured: `Cannot read properties of undefined (reading 'prepare')` on every tool call after a restart). `peerDependencies` state the same range
58
+ * and install nothing.
59
+ * @returns {string[]}
60
+ */
61
+ function hostOwnedDependencyErrors(pkg) {
62
+ const errors = []
63
+ for (const field of ['dependencies', 'optionalDependencies']) {
64
+ const owned = Object.keys(pkg[field] ?? {}).filter(name => HOST_OWNED_PACKAGES.test(name))
65
+ if (owned.length > 0) {
66
+ errors.push(`"${field}" lists ${owned.map(name => `"${name}"`).join(', ')}, which the app itself provides: declare ${owned.length === 1 ? 'it' : 'them'} under "peerDependencies" instead, with the same version range. Installed as a dependency, the package brings a second copy of the framework into the profile and the app's tools stop working after the next restart.`)
67
+ }
68
+ }
69
+ return errors
70
+ }
71
+
72
+ /** True when the plugin's host entry re-imports its implementation with a cache-busting query (the hot shim). */
73
+ function usesHotShim(dir, pkg, fs) {
74
+ try {
75
+ const entry = typeof pkg.main === 'string' ? pkg.main : typeof pkg.exports?.['.'] === 'string' ? pkg.exports['.'] : './index.js'
76
+ const source = fs.readFileSync(join(dir, entry), 'utf8')
77
+ return /import\([^;]*\?t=/u.test(source)
78
+ } catch { return false }
79
+ }
80
+
81
+ async function drain(stream) {
82
+ let text = ''
83
+ if (stream) for await (const chunk of stream) text += chunk.toString()
84
+ return text
85
+ }
86
+
87
+ async function runPlugin(pnpm, args, dir) {
88
+ const handle = pnpm.runPlugin(args, dir)
89
+ const [outcome, stdout, stderr] = await Promise.all([handle.done, drain(handle.stdout), drain(handle.stderr)])
90
+ return { ok: outcome.exitCode === 0, exitCode: outcome.exitCode, output: `${stdout}${stderr}`.trim().slice(-600) }
91
+ }
92
+
93
+ /** Local plugins of the active profile: dependencies installed from a `file:` path. */
94
+ export function listLocalPlugins(profileDir, fs = { existsSync, readFileSync }) {
95
+ const manifest = join(profileDir, 'package.json')
96
+ if (!fs.existsSync(manifest)) return []
97
+ const pkg = JSON.parse(fs.readFileSync(manifest, 'utf8'))
98
+ return Object.entries(pkg.dependencies ?? {})
99
+ .filter(([, spec]) => typeof spec === 'string' && spec.startsWith('file:'))
100
+ .map(([name, spec]) => {
101
+ const installed = spec.slice('file:'.length)
102
+ // A staged install (automatic host hot reload) points at the staging copy; report and re-install from the author's source folder.
103
+ return { name, installedDir: installed, installedFrom: stagedSource(installed, fs) ?? installed }
104
+ })
105
+ }
106
+
107
+ /**
108
+ * Write the profile's recorded `publicHoistPattern` into its `pnpm-workspace.yaml`, so a newer pnpm accepts the existing
109
+ * modules directory instead of demanding a full reinstall. Returns true when the file changed.
110
+ */
111
+ export function pinPublicHoistPattern(profileDir, fs = { existsSync, readFileSync, writeFileSync }) {
112
+ const modulesFile = join(profileDir, 'node_modules', '.modules.yaml')
113
+ const workspaceFile = join(profileDir, 'pnpm-workspace.yaml')
114
+ if (!fs.existsSync(modulesFile) || !fs.existsSync(workspaceFile)) return false
115
+ const workspace = fs.readFileSync(workspaceFile, 'utf8')
116
+ if (/^publicHoistPattern:/mu.test(workspace)) return false
117
+ const recorded = /^publicHoistPattern:\n((?:[ \t]+- .*\n?)+)/mu.exec(fs.readFileSync(modulesFile, 'utf8'))
118
+ const items = recorded ? recorded[1].split('\n').map(line => line.trim()).filter(line => line.startsWith('- ')) : []
119
+ const block = items.length > 0 ? `publicHoistPattern:\n${items.map(item => ` ${item}`).join('\n')}\n` : 'publicHoistPattern: []\n'
120
+ fs.writeFileSync(workspaceFile, `${workspace.replace(/\n*$/u, '\n')}# Pinned by ACRYL: this node_modules was created by an older pnpm whose default public hoist pattern differs from the pnpm on PATH.\n${block}`)
121
+ return true
122
+ }
123
+
124
+ /**
125
+ * Add `name` to `dsh.profile.bundles` in the profile's package.json when it is missing. This is what
126
+ * `dsh plugin add` (CLI/Web) does after pnpm; Desktop's generic `run` does not, so we do it here.
127
+ */
128
+ export function ensureProfileBundle(profileDir, name, fs = { existsSync, readFileSync, writeFileSync, renameSync }) {
129
+ const path = join(profileDir, 'package.json')
130
+ if (!fs.existsSync(path)) throw new Error(`the active profile has no package.json at ${path}`)
131
+ const pkg = JSON.parse(fs.readFileSync(path, 'utf8'))
132
+ const bundles = pkg.dsh?.profile?.bundles
133
+ if (!Array.isArray(bundles)) throw new Error('the active profile package.json has no dsh.profile.bundles list')
134
+ if (bundles.includes(name)) return false
135
+ pkg.dsh.profile.bundles = [...bundles, name]
136
+ const tmp = `${path}.acryl-tmp`
137
+ fs.writeFileSync(tmp, `${JSON.stringify(pkg, null, 2)}\n`)
138
+ fs.renameSync(tmp, path)
139
+ return true
140
+ }
141
+
142
+ /**
143
+ * Make the ACRYL-owned workspace packages a local extension named in `dsh.requiresAcrylPackages` resolvable
144
+ * and live, in the same profile its own install lands in: symlink each in (`acrylFrameworkPackages`, not
145
+ * published so `pnpm add` cannot fetch it). A whole package is registered in `dsh.profile.bundles` (the same
146
+ * thing `dsh plugin add` does for an ordinary local install - `livePluginActivation.activate()` refuses any
147
+ * package name absent from that list, "cannot be activated by this host", even when it is already present in
148
+ * `node_modules`) and activated as a Loader entry (already-active packages are left alone). A module inside a
149
+ * package (`acrylblends/cordis/state`) is not a bundle: `livePluginActivation.requireModules(owner, modules)`
150
+ * mounts its row when no row of it is mounted, owned by `owner` and removed when its last owner leaves
151
+ * (spec 049 T001). A runtime whose live activation cannot do that keeps the refusal, and the module mounts at
152
+ * the next start of an app whose `plugins/` folder declares it.
153
+ * @param {{ acrylFrameworkPackages?: { materialize(profileDir: string, name: string): void, describe(name: string): { module: string, packageName: string, mounted: boolean } }, live: any, profileDir?: string }} services
154
+ * @param {readonly string[]} names
155
+ * @param {object} [fs]
156
+ * @param {string} [owner] the plugin that needs them, which owns any module row inserted for it
157
+ */
158
+ export async function materializeRequiredAcrylPackages(services, names, fs, owner) {
159
+ const errors = []
160
+ if (!services.acrylFrameworkPackages) {
161
+ return { errors: [`this runtime cannot resolve ACRYL framework packages (needed: ${names.join(', ')})`] }
162
+ }
163
+ if (!services.profileDir) return { errors: ['the active profile directory is not available to resolve ACRYL framework packages'] }
164
+ const modules = []
165
+ for (const name of names) {
166
+ try {
167
+ const required = services.acrylFrameworkPackages.describe(name)
168
+ services.acrylFrameworkPackages.materialize(services.profileDir, required.module)
169
+ if (required.module !== required.packageName) {
170
+ // A module inside a package (an acrylblends Cordis plugin) is not a bundle of its own: its row is mounted below, all of them in one call.
171
+ if (owner !== undefined && typeof services.live.requireModules === 'function') modules.push(required.module)
172
+ else if (!required.mounted) {
173
+ errors.push(`"${required.module}" is not mounted in this app and cannot be started while it runs: declare it in "dsh.requiresAcrylPackages" of a plugin in the app's plugins/ folder, and it mounts at the next start`)
174
+ }
175
+ continue
176
+ }
177
+ ensureProfileBundle(services.profileDir, required.packageName, fs)
178
+ if (services.live.statusOf(required.packageName) === undefined) await services.live.activate(required.packageName)
179
+ } catch (cause) {
180
+ errors.push(`could not make "${name}" live: ${cause instanceof Error ? cause.message : String(cause)}`)
181
+ }
182
+ }
183
+ if (errors.length === 0 && owner !== undefined && typeof services.live.requireModules === 'function') {
184
+ try { await services.live.requireModules(owner, modules) } catch (cause) {
185
+ errors.push(`could not start what ${owner} needs: ${cause instanceof Error ? cause.message : String(cause)}`)
186
+ }
187
+ }
188
+ return { errors }
189
+ }
190
+
191
+ /** Release the module rows a plugin owned (best effort: a row left behind is gone at the next start, and never fails an uninstall). */
192
+ async function releaseRequiredModules(live, owner) {
193
+ if (typeof live?.requireModules !== 'function') return
194
+ try { await live.requireModules(owner, []) } catch { /* the next start composes without it */ }
195
+ }
196
+
197
+ /**
198
+ * Add a local package to the active profile. CLI and Web: `dsh plugin add file:<dir>` through runPlugin.
199
+ * Desktop refuses `add` through runPlugin (it must use its recoverable registry-install boundary, which
200
+ * cannot take a local path), so there we run pnpm directly with `run` and register the bundle ourselves.
201
+ */
202
+ export async function addLocalPackage(services, dir, name, profileDir, fs) {
203
+ try {
204
+ let first = await runPlugin(services.pnpm, ['add', `file:${dir}`], dir)
205
+ // Measured on a real profile: node_modules created by an older pnpm records a public-hoist-pattern that the pnpm on PATH
206
+ // (a newer major) computes differently and refuses (ERR_PNPM_PUBLIC_HOIST_PATTERN_DIFF). Pin the recorded value once and retry.
207
+ if (!first.ok && profileDir && /public[-_ ]?hoist[-_ ]?pattern/iu.test(first.output) && pinPublicHoistPattern(profileDir, fs)) {
208
+ first = await runPlugin(services.pnpm, ['add', `file:${dir}`], dir)
209
+ }
210
+ return first
211
+ } catch (cause) {
212
+ const message = cause instanceof Error ? cause.message : String(cause)
213
+ if (!/recoverable install boundary/u.test(message) || typeof services.pnpm.run !== 'function') throw cause
214
+ }
215
+ const handle = services.pnpm.run(['add', '-w', `file:${dir}`])
216
+ const [outcome, stdout, stderr] = await Promise.all([handle.done, drain(handle.stdout), drain(handle.stderr)])
217
+ const result = { ok: outcome.exitCode === 0, exitCode: outcome.exitCode, output: `${stdout}${stderr}`.trim().slice(-600) }
218
+ if (!result.ok) return result
219
+ if (!profileDir) return { ok: false, exitCode: null, output: 'the active profile directory is not available to register the bundle' }
220
+ try { ensureProfileBundle(profileDir, name, fs) } catch (cause) { return { ok: false, exitCode: null, output: cause instanceof Error ? cause.message : String(cause) } }
221
+ return result
222
+ }
223
+
224
+ /**
225
+ * The staged copy that is installed now (the profile's `dependencies` entry for `name` is `file:<stage dir>`), when it is one of ours: only a copy
226
+ * under `stageRoot` is ever reinstalled, never an arbitrary path. `undefined` when the running version was not staged by us (a plugin with its own
227
+ * hot shim installs from its own folder, which is exactly what an update has just changed).
228
+ */
229
+ export function previousStagedDir(profileDir, name, stageRoot, fs = { existsSync, readFileSync }) {
230
+ if (!profileDir) return undefined
231
+ try {
232
+ const spec = JSON.parse(fs.readFileSync(join(profileDir, 'package.json'), 'utf8')).dependencies?.[name]
233
+ if (typeof spec !== 'string' || !spec.startsWith('file:')) return undefined
234
+ // pnpm records the path with forward slashes on Windows (`file:C:/Users/.../.acryl-staged/x`), so compare resolved paths, not the spelling: a plain
235
+ // `startsWith(stageRoot + sep)` never matched there, the running version was not found, and a failed update could not bring it back.
236
+ const dir = resolve(spec.slice('file:'.length))
237
+ const inside = relative(resolve(stageRoot), dir)
238
+ return inside !== '' && !inside.startsWith('..') && !isAbsolute(inside) && fs.existsSync(join(dir, 'package.json')) ? dir : undefined
239
+ } catch { return undefined }
240
+ }
241
+
242
+ /**
243
+ * Bring the version that was running before a failed update back: reinstall its staged copy and activate it. Best effort and honest: the answer
244
+ * says whether it worked, and a failure here never hides the error that caused the update to fail.
245
+ */
246
+ async function restorePrevious(services, previousDir, name, fs) {
247
+ if (previousDir === undefined) return false
248
+ try {
249
+ const added = await addLocalPackage(services, previousDir, name, services.profileDir, fs)
250
+ if (!added.ok) return false
251
+ await services.live.activate(name)
252
+ return true
253
+ } catch { return false }
254
+ }
255
+
256
+ /** The staged copy of a failed attempt is of no use to anyone (best effort). */
257
+ function discardStage(staging) {
258
+ if (staging.ok) { try { rmSync(staging.dir, { recursive: true, force: true }) } catch { /* nothing depends on it */ } }
259
+ }
260
+
261
+ const RESTORED = 'The version that was running is running again. Fix the error above, then call the tool again.'
262
+ const NOT_RESTORED = 'The install was undone. Fix the error above, then call the tool again.'
263
+
264
+ /**
265
+ * Local, in-place delivery (spec 037 FR-016): lint, `dsh plugin add file:<dir>`, an
266
+ * EXPLICIT live activation, and a compensating `remove` on any failure, because CLI
267
+ * and Web have no install recovery log (measured: a plugin whose apply() threw stayed
268
+ * in the profile until removed). Services are read at call time, never captured.
269
+ * @param {{ path: string, cwd?: string }} input
270
+ * @param {{ pnpm: any, live: any, cwd?: string }} services
271
+ */
272
+ export async function installLocalPlugin(input, services, fs) {
273
+ if (typeof input.path !== 'string' || input.path === '') return { ok: false, stage: 'check', errors: ['path is required'] }
274
+ // The runtime's working directory is not the user's workspace, so a relative path would silently point somewhere else.
275
+ if (!isAbsolute(input.path) && services.cwd === undefined) {
276
+ return { ok: false, stage: 'check', errors: [`path must be ABSOLUTE (got "${input.path}"); use the workspace directory you are working in`] }
277
+ }
278
+ const dir = isAbsolute(input.path) ? input.path : resolve(services.cwd, input.path)
279
+ const lint = lintPackageDir(dir, fs)
280
+ if (lint.errors.length > 0 || lint.name === undefined) {
281
+ return { ok: false, stage: 'check', errors: lint.errors, next: 'Fix these in the package and call the tool again. See docs/start-here/this-runtime.md (package contract).' }
282
+ }
283
+ if (!services.pnpm) return { ok: false, stage: 'services', errors: ['the plugin install service (desktopPnpm) is not available in this runtime'] }
284
+ if (!services.live) return { ok: false, stage: 'services', errors: ['live plugin activation (livePluginActivation) is not available in this runtime'] }
285
+
286
+ // UPDATE: a plugin with this name is already mounted. Deactivate removes its row; the re-add
287
+ // below copies the new files over the old ones and activate mounts a fresh entry. Changed HOST
288
+ // code is only picked up if the plugin uses the hot shim (see docs/delivery/local-live.md): Node
289
+ // caches module resolution, so a plain re-import returns the old module (measured).
290
+ const updating = services.live.statusOf(lint.name) !== undefined
291
+ const stageRoot = join(services.profileDir ?? tmpdir(), '.acryl-staged')
292
+ // Remembered before anything is taken down: a failed update must leave the version that was working still working.
293
+ const previousDir = updating ? previousStagedDir(services.profileDir, lint.name, stageRoot) : undefined
294
+ if (updating) {
295
+ try { await services.live.deactivate(lint.name) } catch (cause) {
296
+ return { ok: false, stage: 'update', errors: [`could not deactivate the running version: ${cause instanceof Error ? cause.message : cause}`] }
297
+ }
298
+ }
299
+ // Automatic host hot reload: install a staged copy whose entry re-imports the newest versioned code on every activation (lib/stage.js).
300
+ // A plugin that already carries its own hot shim, or whose entry cannot be wrapped, installs as written (and is warned about below).
301
+ let installDir = dir
302
+ let staging = { ok: false, reason: 'the plugin uses its own hot shim' }
303
+ if (!lint.hotShim) {
304
+ staging = stagePackage(dir, stageRoot)
305
+ if (staging.ok) installDir = staging.dir
306
+ }
307
+ const added = await addLocalPackage(services, installDir, lint.name, services.profileDir, fs)
308
+ if (!added.ok) {
309
+ const restored = await restorePrevious(services, previousDir, lint.name, fs)
310
+ discardStage(staging)
311
+ return { ok: false, stage: 'install', errors: [`dsh plugin add failed (exit ${added.exitCode})`], detail: added.output, ...(updating ? { restoredPrevious: restored } : {}) }
312
+ }
313
+
314
+ try {
315
+ await services.live.activate(lint.name)
316
+ } catch (cause) {
317
+ const message = cause instanceof Error ? cause.message : String(cause)
318
+ const removed = await runPlugin(services.pnpm, ['remove', lint.name], installDir)
319
+ const restored = await restorePrevious(services, previousDir, lint.name, fs)
320
+ discardStage(staging)
321
+ return { ok: false, stage: 'activate', errors: [message], rolledBack: removed.ok, ...(updating ? { restoredPrevious: restored } : {}), next: restored ? RESTORED : NOT_RESTORED }
322
+ }
323
+
324
+ // The required packages activate AFTER the plugin itself, not before: `livePluginActivation`'s dynamic
325
+ // activation locates its target Loader group by searching the live tree for an already-settled "include:"
326
+ // entry (`PluginLifecycleController`'s `bundleGroup()`), and that search is unreliable on the very first
327
+ // dynamic activation of a fresh profile - measured live, activating a framework package before anything else
328
+ // had ever been dynamically activated matched the wrong group ("dsh-client-ui-layout") and failed with
329
+ // "invalid plugin, expect function or object with an apply method, received object". Activating the plugin
330
+ // itself first settles the tree into the shape every later dynamic activation (including this one) expects.
331
+ if (lint.requiresAcrylPackages.length === 0) {
332
+ // An update that no longer names any module releases the rows the earlier version owned.
333
+ await releaseRequiredModules(services.live, lint.name)
334
+ } else {
335
+ const required = await materializeRequiredAcrylPackages(services, lint.requiresAcrylPackages, fs, lint.name)
336
+ if (required.errors.length > 0) {
337
+ // No release here: a failed `requireModules` changed nothing, so the modules an earlier version owned stay for it when it is restored.
338
+ await services.live.deactivate(lint.name).catch(() => {})
339
+ const removed = await runPlugin(services.pnpm, ['remove', lint.name], installDir)
340
+ const restored = await restorePrevious(services, previousDir, lint.name, fs)
341
+ discardStage(staging)
342
+ return { ok: false, stage: 'requires', errors: required.errors, rolledBack: removed.ok, ...(updating ? { restoredPrevious: restored } : {}), next: restored ? RESTORED : NOT_RESTORED }
343
+ }
344
+ }
345
+
346
+ const result = { ok: true, package: lint.name, status: services.live.statusOf(lint.name) ?? 'unknown', action: updating ? 'updated' : 'installed' }
347
+ if (staging.ok) {
348
+ result.hostReload = 'automatic'
349
+ if (services.profileDir) pruneOldVersions(join(services.profileDir, 'node_modules', lint.name), staging.versionDir)
350
+ pruneOldStages(stageRoot, lint.name, staging.dir)
351
+ }
352
+ else if (updating && !lint.hotShim) result.warning = `Updated, but Node caches the host module and this plugin could not be staged for automatic reload (${staging.reason}): changes to HOST code are NOT picked up until the app restarts, unless the plugin uses the hot shim (docs/delivery/local-live.md). Browser (client.js) changes only need a page reload.`
353
+ if (lint.permissions !== undefined) result.permissions = lint.permissions
354
+ // Evolution Ledger (blend-ledger.js): when the workspace tracks a Blend, this install or update becomes one line of history.
355
+ services.record?.({ kind: result.action ?? 'installed', module: lint.name, origin: 'local', version: JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version, digest: `sha256:${hashPackage(dir, 64)}` })
356
+ if (lint.hasClient) result.next = 'This package has a browser (client) part. It mounts live in open windows: the new UI appears within a second or two (a conversation header slot exists only inside an open conversation). Do not ask the user to reload. Only if they say it is missing, suggest reloading once (Web: the page; Desktop: the window, Cmd/Ctrl+R); page-level changes outside the app UI (title, favicon, pre-boot background) need that reload. The host part is already live.'
357
+ return result
358
+ }
359
+
360
+ /**
361
+ * Remove a local plugin: deactivate it live, then `dsh plugin remove`. Removing something
362
+ * that is not installed is reported, not thrown.
363
+ */
364
+ export async function removeLocalPlugin(input, services) {
365
+ const name = input.package
366
+ if (!name) return { ok: false, errors: ['a package name is required'] }
367
+ if (!services.pnpm || !services.live) return { ok: false, stage: 'services', errors: ['plugin services are not available in this runtime'] }
368
+ try { await services.live.deactivate(name) } catch { /* not active: still remove it */ }
369
+ // After the plugin itself: the rows it needed outlive their consumer by a moment, never the other way round.
370
+ await releaseRequiredModules(services.live, name)
371
+ const removed = await runPlugin(services.pnpm, ['remove', name], services.cwd ?? process.cwd())
372
+ if (!removed.ok) return { ok: false, stage: 'remove', errors: [`dsh plugin remove failed (exit ${removed.exitCode})`], detail: removed.output }
373
+ services.record?.({ kind: 'removed', module: name })
374
+ return { ok: true, package: name, removed: true, next: 'If the plugin had a browser (client) part it unmounts live from open windows; do not ask the user to reload.' }
375
+ }
376
+
377
+ /**
378
+ * `/reload`: bring the installs in line with their source folders (source is authoritative): update the ones whose source changed, skip the ones
379
+ * that did not, report the ones whose source is gone, and install any NEW plugin folder found under `<workspace>/.acryl-plugins/` or the global
380
+ * extensions directory, so edits and drops made by hand (or by another tool) go live without asking the agent
381
+ * (pi.dev: write the file, then `/reload`). Each plugin goes through the same checked install path, so a broken edit is reported
382
+ * and rolled back, never half-applied.
383
+ * @param {object} services `{ pnpm, live, profileDir }`
384
+ * @param {object} [fs]
385
+ * @param {{ workspaceDir?: string, globalDir?: string, installDiscovered?: boolean, removeStale?: boolean }} [options] `globalDir`: the global extensions directory (see reconcile.js); `installDiscovered`: install new folders instead of only listing them; `removeStale`: remove installs whose source folder no longer exists (otherwise they are only reported)
386
+ */
387
+ export async function reloadLocalPlugins(services, fs, options = {}) {
388
+ const plugins = listLocalPlugins(services.profileDir, fs)
389
+ const discovered = discoverPlugins({ workspaceDir: options.workspaceDir, globalDir: options.globalDir })
390
+ const scopeOf = new Map(discovered.map(found => [found.dir, found.scope]))
391
+ const results = []
392
+ const done = new Set()
393
+ for (const plugin of plugins) {
394
+ const dir = plugin.installedFrom
395
+ if (!dir || !isAbsolute(dir)) { results.push({ name: plugin.name, ok: false, errors: [`source directory "${dir}" is not absolute, skipped`] }); continue }
396
+ done.add(canonical(dir))
397
+ const scope = scopeOf.get(canonical(dir))
398
+ const state = installState(plugin, hashPackage, fs)
399
+ // The source folder was moved or deleted: the install still runs, but it can never be updated. Report it as stale (not a failure);
400
+ // it is removed only when the human asked for that explicitly (`/reload remove-stale`), never automatically.
401
+ if (state === 'stale') {
402
+ if (!options.removeStale) { results.push({ name: plugin.name, stale: true, ok: true, dir }); continue }
403
+ const removed = await removeLocalPlugin({ package: plugin.name }, services)
404
+ results.push({ name: plugin.name, stale: true, dir, ...removed })
405
+ continue
406
+ }
407
+ // Unchanged source: nothing to do (no package-manager run, no restart of a working plugin).
408
+ if (state === 'in-sync') { results.push({ name: plugin.name, ok: true, action: 'unchanged', scope }); continue }
409
+ const result = await installLocalPlugin({ path: dir }, services, fs)
410
+ results.push({ name: plugin.name, scope, ...result })
411
+ }
412
+ for (const found of discovered) {
413
+ if (done.has(found.dir)) continue
414
+ if (found.shadowed) { results.push({ name: found.name, discovered: true, shadowed: true, ok: true, dir: found.dir, scope: found.scope }); continue }
415
+ // Extensions run with the user's permissions, and a folder in a cloned repository is a prompt-injection surface (pi.dev has project
416
+ // trust for the same reason): a new folder is only LISTED unless the human explicitly asked to install new ones.
417
+ if (!options.installDiscovered) { results.push({ name: found.name, discovered: true, pending: true, ok: true, dir: found.dir, scope: found.scope, permissions: found.permissions }); continue }
418
+ const result = await installLocalPlugin({ path: found.dir }, services, fs)
419
+ results.push({ name: result.package ?? found.name, discovered: true, scope: found.scope, ...result })
420
+ }
421
+ return results
422
+ }
423
+
424
+ /** The install stages whose failure can come from the machine rather than the plugin (pnpm and the store, loading the module): worth one more try. */
425
+ const RETRYABLE_STAGES = new Set(['install', 'activate'])
426
+
427
+ /**
428
+ * Install one plugin at start, once more when the first attempt failed at a stage the machine can cause (a store file lock on Windows, a
429
+ * transient registry error). A plugin that failed its check, its services or its requirements fails the same way again, so it is not retried.
430
+ * @returns `{ ok: true }`, `{ ok: true, firstError }` when only the second attempt worked, or `{ ok: false, error }` naming both failures.
431
+ */
432
+ async function installAtStart(dir, services, fs) {
433
+ const attempt = async () => {
434
+ try {
435
+ const result = await installLocalPlugin({ path: dir }, services, fs)
436
+ if (result.ok) return undefined
437
+ // pnpm's own words (the tail of its output) name the cause, such as a store file locked on Windows; the stage error alone is only an exit code.
438
+ const detail = typeof result.detail === 'string' ? result.detail.replace(/\s+/gu, ' ').trim().slice(-300) : ''
439
+ const error = [(result.errors ?? []).join('; ') || 'install failed', detail].filter(Boolean).join(': ')
440
+ return { error, retryable: RETRYABLE_STAGES.has(result.stage) }
441
+ } catch (cause) { return { error: String(cause?.message ?? cause), retryable: true } }
442
+ }
443
+ const first = await attempt()
444
+ if (first === undefined) return { ok: true }
445
+ if (!first.retryable) return { ok: false, error: first.error }
446
+ const second = await attempt()
447
+ if (second === undefined) return { ok: true, firstError: first.error }
448
+ return { ok: false, error: second.error === first.error ? `${first.error} (twice)` : `${second.error} (first attempt: ${first.error})` }
449
+ }
450
+
451
+ /**
452
+ * The startup pass: bring already-installed extensions up to date with their source, without asking, ONLY where that cannot run code the user
453
+ * did not put there. pi.dev auto-loads what it finds, guarded by project trust; ACRYL's equivalent guard is:
454
+ *
455
+ * - GLOBAL scope (`<ACRYL home>/plugins/`): a directory only the user (or their agent) writes to, never arrives through `git clone` or `git pull`.
456
+ * A changed source there is re-installed at startup.
457
+ * - PROJECT scope and anything else: a `git pull` can change code that then runs with the user's permissions at the next start. A changed source
458
+ * is only REPORTED (`/reload` applies it). New folders are never installed here in either scope: that is `/reload new`.
459
+ * - A missing source is only reported; nothing is removed.
460
+ *
461
+ * Never throws: a failure in one extension is recorded and the others still run.
462
+ * A plugin whose install failed at a stage the machine can cause is tried once more; one that then works is in `retried` with its first error.
463
+ * @param {object} services `{ pnpm, live, profileDir }`
464
+ * @param {{ globalDir?: string }} [options]
465
+ * @returns {Promise<{ updated: string[], installed: string[], changed: string[], stale: string[], pending: string[], failed: Array<{ name: string, error: string }>, retried: Array<{ name: string, error: string }> }>}
466
+ */
467
+ export async function syncOnStartup(services, options = {}, fs) {
468
+ const summary = { updated: [], installed: [], changed: [], stale: [], pending: [], failed: [], retried: [] }
469
+ const plugins = listLocalPlugins(services.profileDir, fs)
470
+ const globalRoot = options.globalDir ? canonical(options.globalDir) : undefined
471
+ const inGlobal = dir => globalRoot !== undefined && canonical(dir).startsWith(`${globalRoot}${sep}`)
472
+ const installed = new Set()
473
+ for (const plugin of plugins) {
474
+ if (!plugin.installedFrom || !isAbsolute(plugin.installedFrom)) continue
475
+ installed.add(canonical(plugin.installedFrom))
476
+ let state
477
+ try { state = installState(plugin, hashPackage, fs) } catch (cause) { summary.failed.push({ name: plugin.name, error: String(cause?.message ?? cause) }); continue }
478
+ if (state === 'stale') { summary.stale.push(plugin.name); continue }
479
+ if (state === 'in-sync') continue
480
+ if (!inGlobal(plugin.installedFrom)) { summary.changed.push(plugin.name); continue }
481
+ const result = await installAtStart(plugin.installedFrom, services, fs)
482
+ if (result.firstError !== undefined) summary.retried.push({ name: plugin.name, error: result.firstError })
483
+ if (result.ok) summary.updated.push(plugin.name)
484
+ else summary.failed.push({ name: plugin.name, error: result.error })
485
+ }
486
+ for (const found of discoverPlugins({ globalDir: options.globalDir })) {
487
+ if (installed.has(found.dir) || found.shadowed) continue
488
+ // An app's own plugins (its committed `plugins/`, e.g. in a fresh clone) are the app's code: they install at start. Elsewhere a new
489
+ // global folder is only reported, because installing runs code the user has not asked for yet.
490
+ if (options.installPending !== true) { summary.pending.push(found.name); continue }
491
+ const result = await installAtStart(found.dir, services, fs)
492
+ if (result.firstError !== undefined) summary.retried.push({ name: found.name, error: result.firstError })
493
+ if (result.ok) summary.installed.push(found.name)
494
+ else summary.failed.push({ name: found.name, error: result.error })
495
+ }
496
+ return summary
497
+ }
498
+
499
+ /**
500
+ * The live view of local extensions for the agent: what is installed, where its source is and whether it is mounted. Evaluated
501
+ * at every prompt assembly, so it reflects the state after an install, update or remove without the agent calling the list tool
502
+ * (pi.dev rebuilds its prompt and tool registry after a reload).
503
+ */
504
+ export function describeInstalledExtensions(profileDir, live, fs) {
505
+ if (!profileDir) return ''
506
+ const plugins = listLocalPlugins(profileDir, fs)
507
+ // Marketplace/registry installs are managed by the market: named so the agent does not go looking for a source folder to edit.
508
+ const managed = listInstalledPlugins(profileDir, {}, fs).filter(plugin => plugin.origin === 'registry')
509
+ if (plugins.length === 0) return ''
510
+ // A source folder that is gone is the one thing worth flagging in every prompt (existence is a cheap check; a content hash is not): the agent can
511
+ // then offer `/reload remove-stale` instead of failing on the next update.
512
+ const check = fs?.existsSync ?? existsSync
513
+ const lines = plugins.map(plugin => `- ${plugin.name} (${live?.statusOf?.(plugin.name) ?? 'not mounted'}) source: ${plugin.installedFrom}${check(join(plugin.installedFrom, 'package.json')) ? '' : ' [SOURCE MISSING: /reload remove-stale removes it]'}`)
514
+ const registry = managed.length > 0 ? `\nMarketplace plugins (managed, not editable here): ${managed.map(plugin => `${plugin.name}@${plugin.version ?? plugin.spec}`).join(', ')}` : ''
515
+ return `Installed local ACRYL plugins (edit the source, then call acryl_install_plugin to update; /reload re-installs all):\n${lines.join('\n')}${registry}`
516
+ }
package/lib/lookup.js ADDED
@@ -0,0 +1,67 @@
1
+ import { join } from 'node:path'
2
+
3
+ const STOP = new Set(['the', 'and', 'for', 'with', 'how', 'what', 'that', 'this', 'from', 'into', 'add', 'make', 'want', 'need', 'can', 'use', 'using', 'build', 'create', 'write', 'change', 'new', 'not', 'are', 'you', 'have', 'has'])
4
+
5
+ const words = text => String(text ?? '').toLowerCase().split(/[^a-z0-9]+/u).filter(word => word.length >= 3 && !STOP.has(word))
6
+
7
+ function score(queryWords, weightedFields) {
8
+ let total = 0
9
+ for (const [text, weight] of weightedFields) {
10
+ const hay = ` ${words(text).join(' ')} `
11
+ for (const word of queryWords) if (hay.includes(` ${word}`) || hay.includes(word)) total += weight
12
+ }
13
+ return total
14
+ }
15
+
16
+ /**
17
+ * Deterministic retrieval over the pack manifest (pi.dev research, section 73: "fast semantic routing" beside filesystem inspection): which docs and
18
+ * verified examples answer a topic, with absolute paths the agent can read. Pure: no filesystem access.
19
+ * @param {string} topic free text, for example "sidebar tab" or "change the accent color"
20
+ * @param {object} manifest parsed docs.json
21
+ * @param {string} root pack root on disk
22
+ * @param {{ limit?: number }} [options]
23
+ */
24
+ export function lookupExtensionDocs(topic, manifest, root, options = {}) {
25
+ const limit = options.limit ?? 5
26
+ const q = words(topic)
27
+ if (q.length === 0) return { ok: false, error: 'give a topic of at least one meaningful word, for example "sidebar tab" or "tool"' }
28
+ const docs = []
29
+ const byId = new Map()
30
+ for (const group of manifest.navigation) for (const item of group.items) byId.set(item.id, item)
31
+ const routeBoost = new Map()
32
+ for (const route of manifest.routes ?? []) {
33
+ const s = score(q, [[route.when, 3]])
34
+ if (s > 0) route.docs.forEach((id, i) => routeBoost.set(id, Math.max(routeBoost.get(id) ?? 0, s * (i === 0 ? 2 : 1))))
35
+ }
36
+ for (const item of byId.values()) {
37
+ if (item.id.startsWith('reference.')) continue
38
+ const s = score(q, [[item.title, 2], [item.topic, 2], [item.when, 1], [item.id.replace(/[.-]/gu, ' '), 2]]) + (routeBoost.get(item.id) ?? 0)
39
+ if (s > 0) docs.push({ id: item.id, title: item.title, path: join(root, 'docs', item.path), score: s })
40
+ }
41
+ docs.sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : 1))
42
+ const examples = []
43
+ for (const example of manifest.examples) {
44
+ const s = score(q, [[example.teaches, 1], [example.type, 3], [example.id.replace(/[.-]/gu, ' '), 2]]) + (docs.some(d => example.docs.includes(d.id)) ? 1 : 0)
45
+ if (s > 0) examples.push({ id: example.id, type: example.type, path: join(root, 'example-plugins', 'packages', example.path), teaches: example.teaches, score: s })
46
+ }
47
+ examples.sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : 1))
48
+ const top = docs.slice(0, limit)
49
+ const result = {
50
+ ok: true,
51
+ topic,
52
+ docs: top.map(({ id, title, path }) => ({ id, title, path })),
53
+ examples: examples.slice(0, limit).map(({ id, type, path, teaches }) => ({ id, type, path, teaches })),
54
+ also: {
55
+ mountPoints: join(root, 'docs', 'maps', 'mount-points.md'),
56
+ slotContracts: join(root, 'docs', 'maps', 'slot-contracts.md'),
57
+ events: join(root, 'docs', 'maps', 'events.md'),
58
+ taxonomy: join(root, 'docs', 'maps', 'taxonomy.md'),
59
+ },
60
+ next: 'Read the first doc and the nearest example COMPLETELY, follow their cross-references, then write the package. This lookup only routes: the docs are the authority.',
61
+ }
62
+ if (top.length === 0) {
63
+ result.docs = [{ id: 'start.this-runtime', title: 'This runtime', path: join(root, 'docs', 'start-here', 'this-runtime.md') }]
64
+ result.note = 'No doc matched; start with this-runtime.md and the docs index, or try other words (a plugin type, a surface, a slot name).'
65
+ }
66
+ return result
67
+ }
@@ -0,0 +1,56 @@
1
+ /**
2
+ * The extension manifest is the `acryl` block of the extension's package.json (the same block the marketplace catalog reads), not a second
3
+ * `extension.json`: two files describing one package would drift. Pi's proposed manifest fields map onto it like this:
4
+ *
5
+ * acryl.apiVersion integer, the ACRYL extension API the code was written against; refused when the runtime provides an older one
6
+ * acryl.permissions what the extension needs from the machine, from a fixed vocabulary; shown to the human before a NEW extension is installed
7
+ * acryl.surfaces the surfaces it is written for (validated by acryl_verify_plugin against what actually mounts)
8
+ *
9
+ * Permissions are DECLARATIVE: they inform the human's trust decision and are checked for honesty by review, they are not enforced by a sandbox.
10
+ */
11
+ export const EXTENSION_API_VERSION = 1
12
+
13
+ /** The permission vocabulary. Anything else is a lint error, so a typo cannot pass as "declared". */
14
+ export const PERMISSIONS = Object.freeze({
15
+ 'fs.read': 'read files outside its own folder',
16
+ 'fs.write': 'write files outside its own folder (including the workspace)',
17
+ net: 'make network requests',
18
+ shell: 'run commands or child processes',
19
+ secrets: 'read credentials or API keys',
20
+ ui: 'add UI to the app (client code runs in the browser page)',
21
+ })
22
+
23
+ /** What the package declares, without judging it: `permissions` is undefined when the package says nothing. */
24
+ export function readManifest(pkg) {
25
+ const block = pkg?.acryl
26
+ if (block === null || typeof block !== 'object') return { apiVersion: undefined, permissions: undefined }
27
+ return {
28
+ apiVersion: block.apiVersion,
29
+ permissions: Array.isArray(block.permissions) ? block.permissions.filter(item => typeof item === 'string') : undefined,
30
+ }
31
+ }
32
+
33
+ /** Lint errors for the manifest fields this module owns (the marketplace fields are checked by publish.js). */
34
+ export function checkManifest(pkg) {
35
+ const errors = []
36
+ const block = pkg?.acryl
37
+ if (block === undefined) return errors
38
+ if (block === null || typeof block !== 'object') return ['"acryl" must be an object']
39
+ if (block.apiVersion !== undefined) {
40
+ if (!Number.isInteger(block.apiVersion) || block.apiVersion < 1) errors.push('"acryl.apiVersion" must be a positive integer')
41
+ else if (block.apiVersion > EXTENSION_API_VERSION) errors.push(`this plugin needs ACRYL plugin API version ${block.apiVersion}, this runtime provides ${EXTENSION_API_VERSION}: update ACRYL or lower "acryl.apiVersion" if the code does not need the newer API`)
42
+ }
43
+ if (block.permissions !== undefined) {
44
+ if (!Array.isArray(block.permissions)) errors.push('"acryl.permissions" must be an array')
45
+ else for (const permission of block.permissions) {
46
+ if (!(typeof permission === 'string' && Object.hasOwn(PERMISSIONS, permission))) errors.push(`unknown permission ${JSON.stringify(permission)}; use one of: ${Object.keys(PERMISSIONS).join(', ')}`)
47
+ }
48
+ }
49
+ return errors
50
+ }
51
+
52
+ /** One line for the human's trust decision, e.g. `requests: shell, net` or `declares no permissions`. */
53
+ export function describePermissions(permissions) {
54
+ if (permissions === undefined) return 'declares no permissions (unknown)'
55
+ return permissions.length === 0 ? 'requests no special permissions' : `requests: ${permissions.join(', ')}`
56
+ }