@acryldev/plugin-context 0.0.0-stage → 0.1.1

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/README.md +12 -2
  3. package/docs/README.md +160 -0
  4. package/docs/delivery/local-live.md +113 -0
  5. package/docs/delivery/marketplace.md +16 -0
  6. package/docs/docs.json +2836 -0
  7. package/docs/extending/agent-preset.md +37 -0
  8. package/docs/extending/chat-command.md +28 -0
  9. package/docs/extending/client-slot.md +135 -0
  10. package/docs/extending/config-schema.md +7 -0
  11. package/docs/extending/cordis-core.md +63 -0
  12. package/docs/extending/desktop-app.md +53 -0
  13. package/docs/extending/desktop-main.md +25 -0
  14. package/docs/extending/event-hook.md +14 -0
  15. package/docs/extending/host-route.md +33 -0
  16. package/docs/extending/llm-adapter.md +38 -0
  17. package/docs/extending/packaging.md +53 -0
  18. package/docs/extending/prompt-contribution.md +9 -0
  19. package/docs/extending/service.md +13 -0
  20. package/docs/extending/skill-provider.md +9 -0
  21. package/docs/extending/state-and-persistence.md +71 -0
  22. package/docs/extending/three-role-capability.md +33 -0
  23. package/docs/extending/tool-plugin.md +24 -0
  24. package/docs/extending/tui-command.md +8 -0
  25. package/docs/extending/tui-components.md +61 -0
  26. package/docs/extending/ui-branding.md +43 -0
  27. package/docs/extending/ui-components.md +56 -0
  28. package/docs/extending/ui-customization.md +41 -0
  29. package/docs/extending/ui-library.md +66 -0
  30. package/docs/extending/ui-theme.md +55 -0
  31. package/docs/extending/workspace-tab.md +50 -0
  32. package/docs/maps/events.md +108 -0
  33. package/docs/maps/mount-points.md +154 -0
  34. package/docs/maps/slot-contracts.md +3376 -0
  35. package/docs/maps/taxonomy.md +306 -0
  36. package/docs/maps/theme-tokens.md +115 -0
  37. package/docs/maps/ui-components.md +26 -0
  38. package/docs/reference/cookbook/adding-a-package.md +174 -0
  39. package/docs/reference/cookbook/adding-a-remote-api.md +199 -0
  40. package/docs/reference/cookbook/adding-a-settings-card.md +74 -0
  41. package/docs/reference/cookbook/adding-a-tool.md +103 -0
  42. package/docs/reference/cookbook/adding-an-llm-adapter.md +45 -0
  43. package/docs/reference/cookbook/extension-cookbook.md +134 -0
  44. package/docs/reference/cordis-api/context.md +366 -0
  45. package/docs/reference/cordis-api/events.md +209 -0
  46. package/docs/reference/cordis-api/fiber.md +377 -0
  47. package/docs/reference/cordis-api/inherited.md +40 -0
  48. package/docs/reference/cordis-api/registry.md +154 -0
  49. package/docs/reference/cordis-api/service.md +104 -0
  50. package/docs/reference/cordis-guides/cordis-usage-cheatsheet.md +167 -0
  51. package/docs/reference/cordis-guides/cordis_system_guide_for_coding_agents.md +4666 -0
  52. package/docs/reference/cordis-guides/development-canvas-plugin.md +109 -0
  53. package/docs/reference/cordis-guides/hello-world-plugin-guide.md +517 -0
  54. package/docs/reference/harness/agent-lifecycle.md +93 -0
  55. package/docs/reference/harness/architecture.md +168 -0
  56. package/docs/reference/harness/capability-seams.md +675 -0
  57. package/docs/reference/harness/config-catalog.md +4523 -0
  58. package/docs/reference/harness/cordis-primer.md +47 -0
  59. package/docs/reference/harness/defensive-patterns.md +35 -0
  60. package/docs/reference/harness/event-producer-consumer.md +111 -0
  61. package/docs/reference/harness/glossary.md +47 -0
  62. package/docs/reference/harness/tool-catalog.md +2721 -0
  63. package/docs/reference/harness/tool-execution-pipeline.md +67 -0
  64. package/docs/reference/subsystems/README.md +75 -0
  65. package/docs/reference/subsystems/agent-team.md +233 -0
  66. package/docs/reference/subsystems/approval.md +172 -0
  67. package/docs/reference/subsystems/attachment.md +363 -0
  68. package/docs/reference/subsystems/boot.md +324 -0
  69. package/docs/reference/subsystems/browser-use.md +69 -0
  70. package/docs/reference/subsystems/client-modules.md +186 -0
  71. package/docs/reference/subsystems/client-resources.md +94 -0
  72. package/docs/reference/subsystems/commands.md +225 -0
  73. package/docs/reference/subsystems/compaction.md +286 -0
  74. package/docs/reference/subsystems/computer-use.md +58 -0
  75. package/docs/reference/subsystems/conversation.md +287 -0
  76. package/docs/reference/subsystems/core.md +1107 -0
  77. package/docs/reference/subsystems/credentials.md +497 -0
  78. package/docs/reference/subsystems/deliverables.md +180 -0
  79. package/docs/reference/subsystems/extensions.md +386 -0
  80. package/docs/reference/subsystems/feedback.md +402 -0
  81. package/docs/reference/subsystems/filesystem.md +532 -0
  82. package/docs/reference/subsystems/goal.md +315 -0
  83. package/docs/reference/subsystems/invariants.md +90 -0
  84. package/docs/reference/subsystems/jobs.md +501 -0
  85. package/docs/reference/subsystems/llm-streaming.md +1131 -0
  86. package/docs/reference/subsystems/lsp.md +204 -0
  87. package/docs/reference/subsystems/mcp.md +141 -0
  88. package/docs/reference/subsystems/office-to-pdf.md +89 -0
  89. package/docs/reference/subsystems/otel.md +46 -0
  90. package/docs/reference/subsystems/permission-presets.md +169 -0
  91. package/docs/reference/subsystems/persistence.md +418 -0
  92. package/docs/reference/subsystems/plan.md +89 -0
  93. package/docs/reference/subsystems/product-telemetry.md +81 -0
  94. package/docs/reference/subsystems/ptc-runtime.md +234 -0
  95. package/docs/reference/subsystems/sandbox.md +223 -0
  96. package/docs/reference/subsystems/schedule.md +545 -0
  97. package/docs/reference/subsystems/scope.md +61 -0
  98. package/docs/reference/subsystems/session-projection.md +358 -0
  99. package/docs/reference/subsystems/session-query.md +511 -0
  100. package/docs/reference/subsystems/session-reference.md +226 -0
  101. package/docs/reference/subsystems/session-telemetry.md +214 -0
  102. package/docs/reference/subsystems/session-title.md +206 -0
  103. package/docs/reference/subsystems/session.md +1300 -0
  104. package/docs/reference/subsystems/settings.md +157 -0
  105. package/docs/reference/subsystems/shell.md +316 -0
  106. package/docs/reference/subsystems/sidebar-right.md +160 -0
  107. package/docs/reference/subsystems/skills.md +354 -0
  108. package/docs/reference/subsystems/slots.md +201 -0
  109. package/docs/reference/subsystems/spill.md +126 -0
  110. package/docs/reference/subsystems/ssh.md +137 -0
  111. package/docs/reference/subsystems/storage.md +262 -0
  112. package/docs/reference/subsystems/subagent.md +762 -0
  113. package/docs/reference/subsystems/subprocess.md +323 -0
  114. package/docs/reference/subsystems/system-prompt.md +226 -0
  115. package/docs/reference/subsystems/terminal.md +186 -0
  116. package/docs/reference/subsystems/todo.md +34 -0
  117. package/docs/reference/subsystems/token-meter.md +108 -0
  118. package/docs/reference/subsystems/tools.md +749 -0
  119. package/docs/reference/subsystems/typert.md +489 -0
  120. package/docs/reference/subsystems/user-questions.md +309 -0
  121. package/docs/reference/subsystems/voice-input.md +166 -0
  122. package/docs/reference/subsystems/web-client.md +102 -0
  123. package/docs/reference/subsystems/web-server.md +228 -0
  124. package/docs/reference/subsystems/web.md +208 -0
  125. package/docs/reference/subsystems/webhook.md +72 -0
  126. package/docs/reference/subsystems/workflow.md +280 -0
  127. package/docs/reference/subsystems/workspace.md +661 -0
  128. package/docs/start-here/blueprints.md +33 -0
  129. package/docs/start-here/this-runtime.md +84 -0
  130. package/docs/start-here/troubleshooting.md +29 -0
  131. package/docs/start-here/trust-and-safety.md +39 -0
  132. package/docs/start-here/verify-before-done.md +46 -0
  133. package/example-plugins/README.md +45 -0
  134. package/example-plugins/packages/agent-preset-reviewer/agent.cordis.yml +18 -0
  135. package/example-plugins/packages/agent-preset-reviewer/preset.yml +3 -0
  136. package/example-plugins/packages/capability-swap-consumer/cordis.patch.yml +3 -0
  137. package/example-plugins/packages/capability-swap-consumer/index.js +14 -0
  138. package/example-plugins/packages/capability-swap-consumer/package.json +25 -0
  139. package/example-plugins/packages/capability-swap-provider-loud/cordis.patch.yml +3 -0
  140. package/example-plugins/packages/capability-swap-provider-loud/index.js +20 -0
  141. package/example-plugins/packages/capability-swap-provider-loud/package.json +25 -0
  142. package/example-plugins/packages/capability-swap-provider-quiet/cordis.patch.yml +3 -0
  143. package/example-plugins/packages/capability-swap-provider-quiet/index.js +20 -0
  144. package/example-plugins/packages/capability-swap-provider-quiet/package.json +25 -0
  145. package/example-plugins/packages/chat-command-basic/cordis.patch.yml +3 -0
  146. package/example-plugins/packages/chat-command-basic/index.js +26 -0
  147. package/example-plugins/packages/chat-command-basic/package.json +25 -0
  148. package/example-plugins/packages/client-chat-message-action/client.js +46 -0
  149. package/example-plugins/packages/client-chat-message-action/cordis.patch.yml +3 -0
  150. package/example-plugins/packages/client-chat-message-action/index.js +9 -0
  151. package/example-plugins/packages/client-chat-message-action/package.json +31 -0
  152. package/example-plugins/packages/client-slot-header-action/client.js +57 -0
  153. package/example-plugins/packages/client-slot-header-action/cordis.patch.yml +3 -0
  154. package/example-plugins/packages/client-slot-header-action/index.js +13 -0
  155. package/example-plugins/packages/client-slot-header-action/package.json +31 -0
  156. package/example-plugins/packages/client-slot-sidebar-tab/client.js +57 -0
  157. package/example-plugins/packages/client-slot-sidebar-tab/cordis.patch.yml +3 -0
  158. package/example-plugins/packages/client-slot-sidebar-tab/index.js +9 -0
  159. package/example-plugins/packages/client-slot-sidebar-tab/package.json +32 -0
  160. package/example-plugins/packages/client-theme-override/client.js +52 -0
  161. package/example-plugins/packages/client-theme-override/cordis.patch.yml +3 -0
  162. package/example-plugins/packages/client-theme-override/index.js +9 -0
  163. package/example-plugins/packages/client-theme-override/package.json +30 -0
  164. package/example-plugins/packages/client-tool-view/client.js +47 -0
  165. package/example-plugins/packages/client-tool-view/cordis.patch.yml +3 -0
  166. package/example-plugins/packages/client-tool-view/index.js +24 -0
  167. package/example-plugins/packages/client-tool-view/package.json +34 -0
  168. package/example-plugins/packages/client-ui-components/client.js +77 -0
  169. package/example-plugins/packages/client-ui-components/cordis.patch.yml +3 -0
  170. package/example-plugins/packages/client-ui-components/index.js +9 -0
  171. package/example-plugins/packages/client-ui-components/package.json +31 -0
  172. package/example-plugins/packages/client-ui-library/client.js +715 -0
  173. package/example-plugins/packages/client-ui-library/cordis.patch.yml +3 -0
  174. package/example-plugins/packages/client-ui-library/index.js +9 -0
  175. package/example-plugins/packages/client-ui-library/package.json +37 -0
  176. package/example-plugins/packages/client-workspace-tab/client.js +72 -0
  177. package/example-plugins/packages/client-workspace-tab/cordis.patch.yml +3 -0
  178. package/example-plugins/packages/client-workspace-tab/index.js +9 -0
  179. package/example-plugins/packages/client-workspace-tab/package.json +30 -0
  180. package/example-plugins/packages/config-schema-basic/cordis.patch.yml +3 -0
  181. package/example-plugins/packages/config-schema-basic/index.js +19 -0
  182. package/example-plugins/packages/config-schema-basic/package.json +25 -0
  183. package/example-plugins/packages/desktop-main-profile-info/cordis.patch.yml +3 -0
  184. package/example-plugins/packages/desktop-main-profile-info/index.js +22 -0
  185. package/example-plugins/packages/desktop-main-profile-info/package.json +25 -0
  186. package/example-plugins/packages/event-hook-basic/cordis.patch.yml +3 -0
  187. package/example-plugins/packages/event-hook-basic/index.js +17 -0
  188. package/example-plugins/packages/event-hook-basic/package.json +22 -0
  189. package/example-plugins/packages/generated-capability-template/cordis.patch.yml +3 -0
  190. package/example-plugins/packages/generated-capability-template/index.js +16 -0
  191. package/example-plugins/packages/generated-capability-template/package.json +42 -0
  192. package/example-plugins/packages/host-route-basic/cordis.patch.yml +3 -0
  193. package/example-plugins/packages/host-route-basic/index.js +20 -0
  194. package/example-plugins/packages/host-route-basic/package.json +29 -0
  195. package/example-plugins/packages/lifecycle-function-basic/cordis.patch.yml +3 -0
  196. package/example-plugins/packages/lifecycle-function-basic/index.js +12 -0
  197. package/example-plugins/packages/lifecycle-function-basic/package.json +15 -0
  198. package/example-plugins/packages/lifecycle-function-hot-shim/cordis.patch.yml +3 -0
  199. package/example-plugins/packages/lifecycle-function-hot-shim/impl.js +5 -0
  200. package/example-plugins/packages/lifecycle-function-hot-shim/index.js +18 -0
  201. package/example-plugins/packages/lifecycle-function-hot-shim/package.json +23 -0
  202. package/example-plugins/packages/lifecycle-hooks-observer/cordis.patch.yml +3 -0
  203. package/example-plugins/packages/lifecycle-hooks-observer/index.js +23 -0
  204. package/example-plugins/packages/lifecycle-hooks-observer/package.json +22 -0
  205. package/example-plugins/packages/llm-adapter-echo/cordis.patch.yml +3 -0
  206. package/example-plugins/packages/llm-adapter-echo/index.js +42 -0
  207. package/example-plugins/packages/llm-adapter-echo/package.json +25 -0
  208. package/example-plugins/packages/prompt-assemble-hook/cordis.patch.yml +3 -0
  209. package/example-plugins/packages/prompt-assemble-hook/index.js +22 -0
  210. package/example-plugins/packages/prompt-assemble-hook/package.json +22 -0
  211. package/example-plugins/packages/prompt-contribution-basic/cordis.patch.yml +3 -0
  212. package/example-plugins/packages/prompt-contribution-basic/index.js +18 -0
  213. package/example-plugins/packages/prompt-contribution-basic/package.json +22 -0
  214. package/example-plugins/packages/service-consumer-greeter/cordis.patch.yml +3 -0
  215. package/example-plugins/packages/service-consumer-greeter/index.js +14 -0
  216. package/example-plugins/packages/service-consumer-greeter/package.json +22 -0
  217. package/example-plugins/packages/service-provider-greeter/cordis.patch.yml +3 -0
  218. package/example-plugins/packages/service-provider-greeter/index.js +22 -0
  219. package/example-plugins/packages/service-provider-greeter/package.json +25 -0
  220. package/example-plugins/packages/settings-section-basic/cordis.patch.yml +3 -0
  221. package/example-plugins/packages/settings-section-basic/index.js +34 -0
  222. package/example-plugins/packages/settings-section-basic/package.json +26 -0
  223. package/example-plugins/packages/skill-provider-basic/cordis.patch.yml +3 -0
  224. package/example-plugins/packages/skill-provider-basic/index.js +31 -0
  225. package/example-plugins/packages/skill-provider-basic/package.json +22 -0
  226. package/example-plugins/packages/state-host-store/client.js +57 -0
  227. package/example-plugins/packages/state-host-store/cordis.patch.yml +3 -0
  228. package/example-plugins/packages/state-host-store/index.js +90 -0
  229. package/example-plugins/packages/state-host-store/package.json +31 -0
  230. package/example-plugins/packages/state-workspace-file/cordis.patch.yml +3 -0
  231. package/example-plugins/packages/state-workspace-file/index.js +52 -0
  232. package/example-plugins/packages/state-workspace-file/package.json +25 -0
  233. package/example-plugins/packages/tool-basic/cordis.patch.yml +3 -0
  234. package/example-plugins/packages/tool-basic/index.js +25 -0
  235. package/example-plugins/packages/tool-basic/package.json +25 -0
  236. package/example-plugins/packages/tool-policy-hook/cordis.patch.yml +3 -0
  237. package/example-plugins/packages/tool-policy-hook/index.js +28 -0
  238. package/example-plugins/packages/tool-policy-hook/package.json +25 -0
  239. package/example-plugins/packages/tui-command-basic/cordis.patch.yml +3 -0
  240. package/example-plugins/packages/tui-command-basic/index.js +24 -0
  241. package/example-plugins/packages/tui-command-basic/package.json +22 -0
  242. package/example-plugins/packages/tui-overlay-themed/cordis.patch.yml +3 -0
  243. package/example-plugins/packages/tui-overlay-themed/index.js +65 -0
  244. package/example-plugins/packages/tui-overlay-themed/package.json +25 -0
  245. package/example-plugins/packages/tui-ui-library/cordis.patch.yml +3 -0
  246. package/example-plugins/packages/tui-ui-library/index.js +73 -0
  247. package/example-plugins/packages/tui-ui-library/package.json +29 -0
  248. package/example-plugins/packages/web-page-branding/cordis.patch.yml +3 -0
  249. package/example-plugins/packages/web-page-branding/index.js +31 -0
  250. package/example-plugins/packages/web-page-branding/package.json +22 -0
  251. package/example-plugins/scenarios.json +11 -0
  252. package/index.js +384 -0
  253. package/lib/blend-apply.js +107 -0
  254. package/lib/blend-capture.js +249 -0
  255. package/lib/blend-ledger.js +76 -0
  256. package/lib/contract.js +5 -0
  257. package/lib/install.js +516 -0
  258. package/lib/lookup.js +67 -0
  259. package/lib/manifest.js +56 -0
  260. package/lib/pack-root.js +22 -0
  261. package/lib/provenance.js +110 -0
  262. package/lib/publish.js +64 -0
  263. package/lib/reconcile.js +83 -0
  264. package/lib/router.js +55 -0
  265. package/lib/scopes.js +82 -0
  266. package/lib/skills.js +54 -0
  267. package/lib/stage.js +157 -0
  268. package/lib/verify.js +77 -0
  269. package/package.json +58 -3
  270. package/scripts/lib/indexes.mjs +45 -0
  271. package/scripts/lib/manifest.mjs +127 -0
  272. package/scripts/lib/maps.mjs +482 -0
  273. package/skills/acryl-add-provider-or-capability/SKILL.md +12 -0
  274. package/skills/acryl-add-ui/SKILL.md +18 -0
  275. package/skills/acryl-build-plugin/SKILL.md +21 -0
  276. package/skills/acryl-change-plugin/SKILL.md +16 -0
  277. package/skills/acryl-desktop-shell/SKILL.md +12 -0
  278. package/skills/acryl-diagnose-plugin/SKILL.md +10 -0
  279. package/skills/acryl-fix-plugin/SKILL.md +12 -0
  280. package/skills/acryl-improve-ui/SKILL.md +10 -0
  281. package/skills/acryl-remove-plugin/SKILL.md +11 -0
  282. package/skills/acryl-restyle-ui/SKILL.md +14 -0
  283. package/skills/acryl-share-plugin/SKILL.md +23 -0
  284. package/skills/acryl-tui-ui/SKILL.md +12 -0
@@ -0,0 +1,249 @@
1
+ import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
2
+ import { basename, dirname, join, relative, sep } from 'node:path'
3
+ import { manifestDigest } from '@acryldev/blends-core'
4
+ import { isMap, isSeq, parse, parseDocument, stringify } from 'yaml'
5
+ import { canonical } from './reconcile.js'
6
+ import { hashPackage } from './stage.js'
7
+ import { listInstalledPlugins } from './provenance.js'
8
+
9
+ /**
10
+ * Capture the current state of a profile as a BLEND instance: the plugins installed (marketplace) AND the extensions built here (local), so the
11
+ * whole running composition can be persisted, versioned in git, and reproduced elsewhere.
12
+ *
13
+ * Output, written to `<outDir>` (default `<workspace>/.acryl/blend/`):
14
+ *
15
+ * blend.yaml the human-facing intent: a manifest (`Blend` with lineage, else `Blueprint`) that validates against blends-core's v1alpha1 schema (rows by id and package
16
+ * name, overrides). Same vocabulary the Loader consumes; nothing invented.
17
+ * blend.lock.json the machine state, `formatVersion: 3` (blends-core's one lock): generator, origin digest of blend.yaml, the Blueprint
18
+ * `lineage` when there is one, `parameters`, rows, and `modules`, one entry per installed package: registry -> version +
19
+ * integrity digest (reproduce from name and version); pulled -> version + the source it was pulled from + the tarball's sha512
20
+ * (reproduce by pulling it again); local -> version + sha256 of the source tree + the vendored copy (reproduce from the copy,
21
+ * verify by digest). Deterministic: no timestamps, sorted keys.
22
+ * plugins/<name>/ the source of every local plugin, copied so the Blend is self-contained (a global plugin outside the project is
23
+ * vendored here; the project's own `.acryl-plugins/` folders are copied verbatim).
24
+ *
25
+ * What is deliberately NOT captured: the ACRYL runtime's own plugins (pack, system prompt, brand, market: engine-owned, versioned with ACRYL), the
26
+ * data plugins keep (see state-and-persistence.md), and secrets.
27
+ */
28
+
29
+ const BASE_BUNDLES = new Set(['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-sdk-minimal'])
30
+ // How a lock names its manifest is the format's rule (@acryldev/blends-core), shared with every other reader and writer of a lock.
31
+ const sha256 = manifestDigest
32
+ const slug = text => String(text).toLowerCase().replace(/[^a-z0-9]+/gu, '-').replace(/^-+|-+$/gu, '') || 'blend'
33
+
34
+ /** The rows a package inserts (`- insert: [{ id, name, config? }]` in its bundle patch). */
35
+ export function readBundleRows(profileDir, packageName, fs = { existsSync, readFileSync }) {
36
+ const pkgFile = join(profileDir, 'node_modules', packageName, 'package.json')
37
+ if (!fs.existsSync(pkgFile)) return { rows: [], note: `${packageName}: not installed in node_modules, its rows could not be read` }
38
+ let patchPath
39
+ try { patchPath = JSON.parse(fs.readFileSync(pkgFile, 'utf8')).dsh?.bundle?.patch } catch { return { rows: [], note: `${packageName}: package.json is unreadable` } }
40
+ if (typeof patchPath !== 'string') return { rows: [], note: `${packageName}: declares no bundle patch` }
41
+ const file = join(dirname(pkgFile), patchPath)
42
+ if (!fs.existsSync(file)) return { rows: [], note: `${packageName}: bundle patch ${patchPath} is missing` }
43
+ let patch
44
+ try { patch = parse(fs.readFileSync(file, 'utf8')) } catch (cause) { return { rows: [], note: `${packageName}: bundle patch is not valid YAML (${String(cause?.message ?? cause).split('\n')[0]})` } }
45
+ const rows = []
46
+ for (const op of Array.isArray(patch) ? patch : []) {
47
+ for (const row of Array.isArray(op?.insert) ? op.insert : []) {
48
+ if (typeof row?.id === 'string' && typeof row?.name === 'string') {
49
+ rows.push({ id: row.id, name: row.name, ...(row.config && typeof row.config === 'object' ? { config: row.config } : {}), ...(row.disabled === true ? { disabled: true } : {}) })
50
+ }
51
+ }
52
+ }
53
+ return { rows }
54
+ }
55
+
56
+ /** The profile's own patch layer as manifest overrides (id-targeted config and disabled). Anything richer (`!!js`) is reported, not captured. */
57
+ export function readProfileOverrides(profileDir, fs = { existsSync, readFileSync }) {
58
+ const file = join(profileDir, 'cordis.patch.yml')
59
+ if (!fs.existsSync(file)) return { overrides: [] }
60
+ let patch
61
+ try { patch = parse(fs.readFileSync(file, 'utf8')) } catch { return { overrides: [], note: 'the profile patch layer could not be parsed (an expression?): its overrides were not captured' } }
62
+ const overrides = []
63
+ for (const op of Array.isArray(patch) ? patch : []) {
64
+ if (typeof op?.id === 'string' && (op.config !== undefined || op.disabled !== undefined) && !op.insert) {
65
+ overrides.push({ id: op.id, ...(op.config && typeof op.config === 'object' ? { config: op.config } : {}), ...(typeof op.disabled === 'boolean' ? { disabled: op.disabled } : {}) })
66
+ }
67
+ }
68
+ return { overrides }
69
+ }
70
+
71
+ /**
72
+ * @param {{ profileDir: string, workspaceDir?: string, globalDir?: string, id?: string, name?: string, version?: string, description?: string, lineage?: { blueprint: string, blueprintVersion: string } }} options
73
+ * @returns the manifest, its YAML text, the lock, its JSON text, the local extension sources to vendor, and notes about anything not captured
74
+ */
75
+ export function captureBlend(options, fs = { existsSync, readFileSync }) {
76
+ const { profileDir, workspaceDir, globalDir } = options
77
+ const profile = JSON.parse(fs.readFileSync(join(profileDir, 'package.json'), 'utf8'))
78
+ const bundles = (profile.dsh?.profile?.bundles ?? []).filter(name => !BASE_BUNDLES.has(name))
79
+ const installed = new Map(listInstalledPlugins(profileDir, { globalDir }, fs).map(plugin => [plugin.name, plugin]))
80
+ const notes = []
81
+ const rows = []
82
+ const modules = []
83
+ const vendored = []
84
+ const workspaceName = workspaceDir ? basename(workspaceDir) : 'blend'
85
+
86
+ for (const name of bundles) {
87
+ const plugin = installed.get(name)
88
+ if (plugin === undefined) { notes.push(`${name}: listed as a bundle but not installed as a dependency, skipped`); continue }
89
+ const { rows: pluginRows, note } = readBundleRows(profileDir, name, fs)
90
+ if (note) notes.push(note)
91
+ rows.push(...pluginRows)
92
+ if (plugin.origin === 'pulled') {
93
+ modules.push({ name, origin: 'pulled', version: plugin.version, spec: plugin.from, digest: plugin.integrity })
94
+ } else if (plugin.origin === 'registry') {
95
+ modules.push({ name, origin: 'registry', version: plugin.version ?? plugin.spec, ...(plugin.integrity ? { digest: plugin.integrity } : {}) })
96
+ if (!plugin.integrity) notes.push(`${name}: no integrity digest in the lockfile, reproducing it will not be verified`)
97
+ } else if (plugin.origin === 'local') {
98
+ let version = '0.0.0'
99
+ try { version = JSON.parse(fs.readFileSync(join(plugin.source, 'package.json'), 'utf8')).version ?? version } catch { notes.push(`${name}: its source folder is gone (${plugin.source}), it cannot be vendored`); continue }
100
+ const dir = `plugins/${name.replace(/^@/u, '').replace(/\//gu, '__')}`
101
+ modules.push({ name, origin: 'local', version, digest: `sha256:${hashPackage(plugin.source, 64)}`, source: dir })
102
+ vendored.push({ name, from: plugin.source, to: dir })
103
+ } else {
104
+ modules.push({ name, origin: plugin.origin, spec: plugin.spec })
105
+ notes.push(`${name}: origin "${plugin.origin}" is recorded by spec only, reproducing it needs that spec to stay reachable`)
106
+ }
107
+ }
108
+ const { overrides, note: overrideNote } = readProfileOverrides(profileDir, fs)
109
+ if (overrideNote) notes.push(overrideNote)
110
+
111
+ const manifest = {
112
+ apiVersion: 'blends.acryl.dev/v1alpha1',
113
+ // blends-core requires a Blend to name its origin. A capture that grew from nothing has none, and a definition without an origin is a Blueprint
114
+ // (shareable as a starting point); pass `lineage` when the state grew from a known Blueprint and it is a Blend.
115
+ kind: options.lineage ? 'Blend' : 'Blueprint',
116
+ metadata: {
117
+ id: options.id ?? `local.${slug(workspaceName)}`,
118
+ name: options.name ?? workspaceName,
119
+ version: options.version ?? '0.1.0',
120
+ ...(options.description ? { description: options.description } : {}),
121
+ },
122
+ spec: { runtime: 'cordis', ...(options.lineage ? { lineage: options.lineage } : {}), ...(rows.length > 0 ? { rows } : {}), ...(overrides.length > 0 ? { overrides } : {}) },
123
+ }
124
+ const manifestText = `# ACRYL ${manifest.kind} captured from a live profile. Edit the intent here; blend.lock.json is machine-generated.\n${stringify(manifest)}`
125
+ modules.sort((a, b) => (a.name < b.name ? -1 : 1))
126
+ // The v3 shape and key order of blends-core's generateBlendLock. A capture has no parameters: it records a live profile, not a template.
127
+ const lock = {
128
+ formatVersion: 3,
129
+ generator: { name: '@acryldev/plugin-context', version: '0.1.0' },
130
+ origin: { id: manifest.metadata.id, kind: manifest.kind, version: manifest.metadata.version, digest: sha256(manifestText) },
131
+ ...(options.lineage ? { lineage: options.lineage } : {}),
132
+ parameters: {},
133
+ rows,
134
+ modules,
135
+ }
136
+ return { manifest, manifestText, lock, lockText: `${JSON.stringify(lock, null, 2)}\n`, vendored, notes }
137
+ }
138
+
139
+ /** Write a capture to `outDir` (atomic per file); local sources are copied without node_modules or .git. Returns the files written. */
140
+ export function writeBlend(capture, outDir) {
141
+ mkdirSync(outDir, { recursive: true })
142
+ const write = (name, text) => { const temp = join(outDir, `${name}.tmp`); writeFileSync(temp, text); renameSync(temp, join(outDir, name)) }
143
+ write('blend.yaml', capture.manifestText)
144
+ write('blend.lock.json', capture.lockText)
145
+ const files = ['blend.yaml', 'blend.lock.json']
146
+ for (const { from, to } of capture.vendored) {
147
+ const target = join(outDir, to)
148
+ rmSync(target, { recursive: true, force: true }) // a re-capture replaces its own vendored copy, never anything else
149
+ mkdirSync(dirname(target), { recursive: true })
150
+ cpSync(from, target, { recursive: true, filter: source => !['node_modules', '.git'].includes(basename(source)) })
151
+ files.push(`${to}/`)
152
+ }
153
+ return files
154
+ }
155
+
156
+ /**
157
+ * Check a written Blend against its own lock, offline: the manifest still matches the digest the lock recorded, and every vendored local
158
+ * extension still hashes to the digest recorded for it. Registry and pulled modules are verified when they are installed (against the lockfile's integrity and the tarball's sha512).
159
+ * @returns {{ ok: boolean, problems: string[], checked: number }}
160
+ */
161
+ export function verifyBlend(outDir, fs = { existsSync, readFileSync }) {
162
+ const problems = []
163
+ let checked = 0
164
+ const manifestPath = join(outDir, 'blend.yaml')
165
+ const lockPath = join(outDir, 'blend.lock.json')
166
+ if (!fs.existsSync(manifestPath) || !fs.existsSync(lockPath)) return { ok: false, problems: [`no blend.yaml and blend.lock.json in ${outDir}`], checked }
167
+ let lock
168
+ try { lock = JSON.parse(fs.readFileSync(lockPath, 'utf8')) } catch { return { ok: false, problems: ['blend.lock.json is not valid JSON'], checked } }
169
+ if (lock.formatVersion !== 2 && lock.formatVersion !== 3) problems.push(`blend.lock.json formatVersion ${lock.formatVersion} is not one this build reads (2 or 3)`)
170
+ checked += 1
171
+ if (lock.origin?.digest !== sha256(fs.readFileSync(manifestPath, 'utf8'))) problems.push('blend.yaml changed since the lock was generated (its digest no longer matches): re-capture, or regenerate the lock')
172
+ for (const module of Array.isArray(lock.modules) ? lock.modules : []) {
173
+ if (module.origin !== 'local') continue
174
+ checked += 1
175
+ const dir = join(outDir, module.source ?? '')
176
+ if (!module.source || !fs.existsSync(join(dir, 'package.json'))) { problems.push(`${module.name}: the vendored source ${module.source} is missing`); continue }
177
+ if (`sha256:${hashPackage(dir, 64)}` !== module.digest) problems.push(`${module.name}: the vendored source differs from the locked digest (edited after capture)`)
178
+ }
179
+ return { ok: problems.length === 0, problems, checked }
180
+ }
181
+
182
+ /**
183
+ * Capture inside an app (`acryl new`): the app folder is the Blend, so nothing is written elsewhere and nothing the user wrote is regenerated.
184
+ *
185
+ * blend.yaml the user's own definition is kept, comments and all; a row is appended only for an installed plugin it does not name yet
186
+ * blend.lock.json regenerated from that definition: digest, rows, and every module; a plugin already in the app's `plugins/` is recorded in
187
+ * place (source `plugins/<folder>`), one installed from anywhere else is vendored into `plugins/`
188
+ *
189
+ * @param {{ profileDir: string, appHome: string, globalDir?: string }} options
190
+ */
191
+ export function captureApp(options, fs = { existsSync, readFileSync }) {
192
+ const base = captureBlend({ profileDir: options.profileDir, globalDir: options.globalDir }, fs)
193
+ const appReal = canonical(options.appHome)
194
+ const inApp = path => { const real = canonical(path); return real === appReal || real.startsWith(`${appReal}${sep}`) }
195
+ const vendored = []
196
+ const modules = base.lock.modules.map(module => {
197
+ if (module.origin !== 'local') return module
198
+ const copy = base.vendored.find(entry => entry.name === module.name)
199
+ if (copy !== undefined && inApp(copy.from)) return { ...module, source: relative(appReal, canonical(copy.from)).split(sep).join('/') }
200
+ if (copy !== undefined) vendored.push(copy)
201
+ return module
202
+ })
203
+ const manifestPath = join(options.appHome, 'blend.yaml')
204
+ const original = fs.readFileSync(manifestPath, 'utf8')
205
+ const document = parseDocument(original)
206
+ const notes = [...base.notes]
207
+ if (!isMap(document.get('spec'))) throw new Error(`${manifestPath} has no spec map; it is not an app definition`)
208
+ if (!isSeq(document.getIn(['spec', 'rows']))) document.setIn(['spec', 'rows'], document.createNode([]))
209
+ const named = new Set((document.toJS().spec.rows ?? []).map(row => row.id))
210
+ const added = []
211
+ for (const row of base.lock.rows) {
212
+ if (named.has(row.id)) continue
213
+ document.addIn(['spec', 'rows'], document.createNode(row))
214
+ named.add(row.id)
215
+ added.push(row.id)
216
+ }
217
+ const manifestText = added.length === 0 ? original : String(document)
218
+ const manifest = document.toJS()
219
+ // v3 key order; an app grown from a Blueprint records that lineage (the app's own blend.yaml names it).
220
+ const lineage = manifest.spec?.lineage
221
+ const lock = {
222
+ formatVersion: base.lock.formatVersion,
223
+ generator: base.lock.generator,
224
+ origin: { id: manifest.metadata?.id, kind: manifest.kind, version: manifest.metadata?.version, digest: sha256(manifestText) },
225
+ ...(lineage?.blueprint && lineage?.blueprintVersion ? { lineage: { blueprint: lineage.blueprint, blueprintVersion: lineage.blueprintVersion } } : {}),
226
+ parameters: base.lock.parameters,
227
+ rows: manifest.spec.rows ?? [],
228
+ modules,
229
+ }
230
+ return { manifest, manifestText, manifestChanged: added.length > 0, addedRows: added, lock, lockText: `${JSON.stringify(lock, null, 2)}\n`, vendored, notes }
231
+ }
232
+
233
+ /** Write an app capture into the app folder (atomic per file). Vendoring never replaces a folder that is already the app's own extension. */
234
+ export function writeAppBlend(capture, appHome) {
235
+ const write = (name, text) => { const temp = join(appHome, `${name}.tmp`); writeFileSync(temp, text); renameSync(temp, join(appHome, name)) }
236
+ const files = []
237
+ if (capture.manifestChanged) { write('blend.yaml', capture.manifestText); files.push('blend.yaml') }
238
+ write('blend.lock.json', capture.lockText)
239
+ files.push('blend.lock.json')
240
+ for (const { from, to } of capture.vendored) {
241
+ const target = join(appHome, to)
242
+ if (existsSync(join(target, 'package.json')) && canonical(target) !== canonical(from)) { capture.notes.push(`${to} already exists in the app; ${from} was not vendored over it`); continue }
243
+ rmSync(target, { recursive: true, force: true })
244
+ mkdirSync(dirname(target), { recursive: true })
245
+ cpSync(from, target, { recursive: true, filter: source => !['node_modules', '.git'].includes(basename(source)) })
246
+ files.push(`${to}/`)
247
+ }
248
+ return files
249
+ }
@@ -0,0 +1,76 @@
1
+ import { createHash } from 'node:crypto'
2
+ import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
3
+ import { join } from 'node:path'
4
+ import { blendDir } from './scopes.js'
5
+
6
+ /**
7
+ * The Evolution Ledger of a Blend (governing Blends spec section 16, spec 036 blend-instance-design.md): an append-only record of what changed in a tracked composition,
8
+ * by whom, and when. It exists only once a Blend has been captured (`<workspace>/.acryl/blend/blend.yaml`): from then on every install, update and removal of a plugin
9
+ * in that workspace appends one line to `ledger.jsonl`. It is a log, not a store: the Blend files are the state, the ledger is the history.
10
+ *
11
+ * Each line is one JSON object `{ at, kind, actor, prev, ... }`. `prev` is the sha256 of the previous line's exact text (null for the first), so a line that is edited
12
+ * or removed afterwards breaks the chain and `verifyLedger` names it. Lines are never rewritten; a correction is a new line. Appends use O_APPEND.
13
+ */
14
+ const LEDGER = 'ledger.jsonl'
15
+ const sha256 = text => createHash('sha256').update(text).digest('hex')
16
+
17
+ /** The directory of a tracked Blend for a workspace, or undefined when the workspace has none. */
18
+ export function trackedBlendDir(workspaceDir, fs = { existsSync }) {
19
+ if (typeof workspaceDir !== 'string' || workspaceDir === '') return undefined
20
+ const dir = blendDir(workspaceDir)
21
+ return fs.existsSync(join(dir, 'blend.yaml')) ? dir : undefined
22
+ }
23
+
24
+ function lastLine(file, fs) {
25
+ if (!fs.existsSync(file)) return undefined
26
+ const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean)
27
+ return lines.at(-1)
28
+ }
29
+
30
+ /**
31
+ * Append one entry. `kind` is one of captured, applied, installed, updated, removed; `actor` is human (a command the user typed) or agent (a tool the model called).
32
+ * @returns the entry as written
33
+ */
34
+ export function appendLedger(blendDir, entry, fs = { existsSync, readFileSync }) {
35
+ mkdirSync(blendDir, { recursive: true })
36
+ const file = join(blendDir, LEDGER)
37
+ const previous = lastLine(file, fs)
38
+ const line = { at: new Date().toISOString(), ...entry, prev: previous === undefined ? null : sha256(previous) }
39
+ appendFileSync(file, `${JSON.stringify(line)}\n`, { flag: 'a' })
40
+ return line
41
+ }
42
+
43
+ /** The entries in order; a line that is not JSON is returned as `{ invalid: <text> }` so it can be reported rather than hidden. */
44
+ export function readLedger(blendDir, fs = { existsSync, readFileSync }) {
45
+ const file = join(blendDir, LEDGER)
46
+ if (!fs.existsSync(file)) return []
47
+ return fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map(text => { try { return JSON.parse(text) } catch { return { invalid: text } } })
48
+ }
49
+
50
+ /** Check the hash chain. @returns `{ ok, problems, entries }` */
51
+ export function verifyLedger(blendDir, fs = { existsSync, readFileSync }) {
52
+ const file = join(blendDir, LEDGER)
53
+ if (!fs.existsSync(file)) return { ok: true, problems: [], entries: 0 }
54
+ const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean)
55
+ const problems = []
56
+ lines.forEach((text, index) => {
57
+ let entry
58
+ try { entry = JSON.parse(text) } catch { problems.push(`ledger line ${index + 1} is not valid JSON`); return }
59
+ const expected = index === 0 ? null : sha256(lines[index - 1])
60
+ if (entry.prev !== expected) problems.push(`ledger line ${index + 1} does not follow line ${index}: an earlier line was edited or removed`)
61
+ })
62
+ return { ok: problems.length === 0, problems, entries: lines.length }
63
+ }
64
+
65
+ /**
66
+ * A recorder for install/remove services: appends to the tracked Blend of `workspaceDir` when there is one, and does nothing otherwise. Never throws (a ledger
67
+ * failure must not undo an install).
68
+ */
69
+ export function ledgerRecorder(workspaceDir, actor, fs = { existsSync, readFileSync }) {
70
+ return entry => {
71
+ try {
72
+ const dir = trackedBlendDir(workspaceDir, fs)
73
+ if (dir !== undefined) appendLedger(dir, { actor, ...entry }, fs)
74
+ } catch { /* the ledger is history, not a gate */ }
75
+ }
76
+ }
@@ -0,0 +1,5 @@
1
+ /**
2
+ * A plugin's service contract and UI slots, generated from its code into its package.json (spec 044). The implementation is
3
+ * `@acryldev/plugin-hub-core`'s (`contract.ts`), shared with the plugin hub's share and pull; this module keeps the pack's import path.
4
+ */
5
+ export { checkContractShape, clientInjectFromSource, hostEntryOf, providedServices, readServiceContract, slotsInSource, syncServiceContract } from '@acryldev/plugin-hub-core'