@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/verify.js ADDED
@@ -0,0 +1,77 @@
1
+ import { existsSync, readFileSync } from 'node:fs'
2
+ import { join } from 'node:path'
3
+ import { pathToFileURL } from 'node:url'
4
+ import { hostEntryOf } from './contract.js'
5
+ import { lintPackageDir } from './install.js'
6
+
7
+ let importCounter = 0
8
+ const DOCS = {
9
+ shape: ['extending.service', 'start.verify-before-done'],
10
+ packaging: ['extending.packaging'],
11
+ client: ['extending.client-slot'],
12
+ }
13
+
14
+ /**
15
+ * Verify a plugin package WITHOUT installing it: install lint, then import the host entry and check the
16
+ * Cordis plugin shape (the real underlying error text is reported, never swallowed). Every finding names the
17
+ * pack docs that explain the fix. A package that throws at import never crashes the verifier.
18
+ */
19
+ export async function verifyPackage(input, fs = { existsSync, readFileSync }) {
20
+ const dir = input.path
21
+ const findings = []
22
+ const lint = lintPackageDir(dir, fs)
23
+ for (const message of lint.errors ?? []) {
24
+ findings.push({ severity: 'error', code: /exports/u.test(message) ? 'package-json-not-exported' : /bundle patch|"dsh"/u.test(message) ? 'bundle-patch-missing' : 'invalid-package', message, docs: DOCS.packaging })
25
+ }
26
+ if (lint.name === undefined) return report(dir, findings)
27
+
28
+ const pkg = JSON.parse(fs.readFileSync(join(dir, 'package.json'), 'utf8'))
29
+ const entryRel = hostEntryOf(pkg)
30
+ const entry = join(dir, entryRel)
31
+ if (!fs.existsSync(entry)) {
32
+ findings.push({ severity: 'error', code: 'import-failed', message: `the host entry ${entryRel} does not exist`, docs: DOCS.packaging })
33
+ return report(dir, findings)
34
+ }
35
+ // A UI-only plugin ships an empty host apply; it still must import.
36
+ let mod
37
+ try { mod = await import(`${pathToFileURL(entry).href}?verify=${++importCounter}-${Date.now()}`) } catch (cause) {
38
+ // Declared dependencies are not installed in the source folder until the plugin is installed into the
39
+ // profile, so a missing declared package is expected here: the shape cannot be checked yet, not an error.
40
+ const missing = cause?.code === 'ERR_MODULE_NOT_FOUND' ? /Cannot find package '([^']+)'/u.exec(String(cause.message))?.[1] : undefined
41
+ if (missing && (pkg.dependencies?.[missing] || pkg.peerDependencies?.[missing])) {
42
+ findings.push({ severity: 'warning', code: 'dependency-not-installed-yet', message: `the entry imports "${missing}", which is declared but only resolvable after install; the plugin shape was NOT checked. Install it, then read the plugin status in the result.`, docs: DOCS.packaging })
43
+ return report(dir, findings)
44
+ }
45
+ findings.push({ severity: 'error', code: 'import-failed', message: `importing ${entryRel} failed: ${cause instanceof Error ? cause.stack ?? cause.message : cause}`, docs: DOCS.shape })
46
+ return report(dir, findings)
47
+ }
48
+ const hasDefault = 'default' in mod
49
+ const named = ['name', 'inject', 'apply', 'Config'].filter(key => key in mod)
50
+ if (hasDefault && named.length > 0) {
51
+ findings.push({ severity: 'error', code: 'default-with-named-metadata', message: `the entry has a default export AND named exports (${named.join(', ')}); the loader keeps only the default, so the named metadata (name, inject, Config) is silently dropped. Use named exports only.`, docs: DOCS.shape })
52
+ }
53
+ const plugin = hasDefault ? mod.default : mod
54
+ const apply = typeof plugin === 'function' ? plugin : plugin?.apply
55
+ if (typeof apply !== 'function') {
56
+ findings.push({ severity: 'error', code: 'invalid-plugin-shape', message: 'the entry must export an "apply(ctx)" function (named export), or a default function', docs: DOCS.shape })
57
+ }
58
+ if (plugin?.inject !== undefined && !(Array.isArray(plugin.inject) || (typeof plugin.inject === 'object' && plugin.inject !== null))) {
59
+ findings.push({ severity: 'error', code: 'invalid-plugin-shape', message: '"inject" must be an array of service names (or a map of service name to its config); every service listed is required, an optional one is read with ctx.get()', docs: DOCS.shape })
60
+ }
61
+ if (plugin?.name !== undefined && typeof plugin.name !== 'string') {
62
+ findings.push({ severity: 'error', code: 'invalid-plugin-shape', message: '"name" must be a string', docs: DOCS.shape })
63
+ }
64
+ if (lint.hasClient) {
65
+ const clientPath = typeof pkg.exports?.['./client'] === 'string' ? join(dir, pkg.exports['./client']) : undefined
66
+ const source = clientPath && fs.existsSync(clientPath) ? fs.readFileSync(clientPath, 'utf8') : ''
67
+ if (source && !/__ModuleLoader__/u.test(source)) {
68
+ findings.push({ severity: 'warning', code: 'client-loader-wrapper-missing', message: 'the client bundle does not reference window.__ModuleLoader__; it will not register in the browser unless it is wrapped as the example shows', docs: DOCS.client })
69
+ }
70
+ }
71
+ return report(dir, findings)
72
+ }
73
+
74
+ function report(dir, findings) {
75
+ const docs = [...new Set(findings.flatMap(f => f.docs ?? []))]
76
+ return { ok: findings.every(f => f.severity !== 'error'), target: dir, findings, docs }
77
+ }
package/package.json CHANGED
@@ -1,6 +1,59 @@
1
1
  {
2
2
  "name": "@acryldev/plugin-context",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0",
4
+ "description": "Extension Context Pack: routed docs, verified examples and authoring skills that let the ACRYL agent write its own plugins (spec 037)",
5
+ "license": "MIT",
6
+ "publishConfig": {
7
+ "access": "public",
8
+ "registry": "https://registry.npmjs.org"
9
+ },
10
+ "repository": {
11
+ "type": "git",
12
+ "url": "git+https://github.com/acryldev/acryl.git",
13
+ "directory": "plugins/plugin-context"
14
+ },
15
+ "homepage": "https://github.com/acryldev/acryl/tree/main/plugins/plugin-context#readme",
16
+ "bugs": {
17
+ "url": "https://github.com/acryldev/acryl/issues"
18
+ },
19
+ "type": "module",
20
+ "exports": {
21
+ ".": "./index.js",
22
+ "./package.json": "./package.json",
23
+ "./manifest": "./docs/docs.json"
24
+ },
25
+ "files": [
26
+ "index.js",
27
+ "lib/**",
28
+ "docs/**",
29
+ "example-plugins/**",
30
+ "skills/**",
31
+ "scripts/lib/**"
32
+ ],
33
+ "engines": {
34
+ "node": "^22.19.0 || >=24.0.0"
35
+ },
36
+ "main": "./index.js",
37
+ "dependencies": {
38
+ "@acryldev/blends-core": "0.6.0",
39
+ "@acryldev/plugin-hub-core": "0.2.2",
40
+ "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
41
+ "@acryldev/blends": "^1.7.1",
42
+ "yaml": "^2.9.0"
43
+ },
44
+ "devDependencies": {
45
+ "@deepseek-ai/cordis": "4.0.4",
46
+ "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
47
+ "@deepseek-ai/schemastery": "~3.18.4",
48
+ "@earendil-works/pi-tui": "1.1.0",
49
+ "@types/node": "^22.20.0",
50
+ "@acryldev/ui-tui": "0.1.0"
51
+ },
52
+ "scripts": {
53
+ "sync:corpus": "node scripts/sync-corpus.mjs",
54
+ "build:manifest": "node scripts/build-manifest.mjs",
55
+ "verify:manifest": "node scripts/build-manifest.mjs --check",
56
+ "test": "node --test scripts/contract.test.mjs scripts/manifest.test.mjs scripts/plugin.test.mjs scripts/scopes.test.mjs scripts/app-blend.test.mjs",
57
+ "check": "pnpm run test && pnpm run verify:manifest"
58
+ }
6
59
  }
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Human and agent readable indexes generated from the manifest (spec 037
3
+ * FR-001). Generated, never hand-edited, so an index cannot disagree with
4
+ * the manifest.
5
+ */
6
+
7
+ const cell = text => String(text).replaceAll('|', '\\|').replaceAll('\n', ' ')
8
+
9
+ export function renderDocsIndex(manifest) {
10
+ const lines = [
11
+ '# ACRYL plugin docs',
12
+ '',
13
+ '<!-- Generated from docs.json by scripts/build-manifest.mjs. Do not edit here. -->',
14
+ '',
15
+ 'Read the file for your topic BEFORE implementing. Read it completely, follow its',
16
+ 'cross-references and the example it names. Do not guess from memory of a similar',
17
+ 'plugin. Verified working examples: `../example-plugins/README.md`.',
18
+ '',
19
+ ]
20
+ for (const group of manifest.navigation) {
21
+ lines.push(`## ${cell(group.title)}`, '', '| Doc | Read it when | Surfaces | Applies |', '| --- | --- | --- | --- |')
22
+ for (const doc of group.items) lines.push(`| [${cell(doc.title)}](${doc.path}) | ${cell(doc.when)} | ${doc.surfaces.join(' ')} | ${doc.applies} |`)
23
+ lines.push('')
24
+ }
25
+ return lines.join('\n')
26
+ }
27
+
28
+ export function renderExamplesIndex(manifest) {
29
+ const lines = [
30
+ '# ACRYL plugin examples',
31
+ '',
32
+ '<!-- Generated from docs/docs.json by scripts/build-manifest.mjs. Do not edit here. -->',
33
+ '',
34
+ 'Every example is a real package. Each is mounted through the real Loader by the',
35
+ 'pack gate and its declared outcome observed. Find the closest, read it, then adapt it.',
36
+ '',
37
+ '| Example | Type | Teaches | Surfaces | Docs |',
38
+ '| --- | --- | --- | --- | --- |',
39
+ ]
40
+ for (const example of manifest.examples) {
41
+ lines.push(`| [${cell(example.id)}](packages/${example.path}/) | ${example.type} | ${cell(example.teaches)} | ${example.surfaces.join(' ')} | ${example.docs.join(', ')} |`)
42
+ }
43
+ lines.push('')
44
+ return lines.join('\n')
45
+ }
@@ -0,0 +1,127 @@
1
+ /**
2
+ * Extension Context Pack manifest (spec 037, data-model.md). Pure validation:
3
+ * the caller supplies the manifest and the list of files that exist, so tests
4
+ * need no filesystem. Every invariant here is what makes "a doc not in the
5
+ * manifest does not exist to the agent" true (FR-001) and keeps the index from
6
+ * rotting (FR-015).
7
+ */
8
+
9
+ export const SURFACES = ['tui', 'web', 'desktop']
10
+ export const APPLIES = ['all', 'partial', 'not-for-authors']
11
+ export const PLUGIN_TYPES = [
12
+ 'lifecycle-function', 'service-provider', 'service-consumer',
13
+ 'tool', 'event-hook', 'config-schema',
14
+ 'three-role-capability', 'prompt-contribution', 'skill-provider',
15
+ 'llm-adapter', 'agent-preset', 'host-route',
16
+ 'client-slot', 'desktop-main', 'tui-contribution',
17
+ 'packaging', 'generated-capability', 'diagnostics',
18
+ 'chat-command', 'settings-section',
19
+ 'ui-theme', 'ui-branding', 'tui-ui', 'ui-components',
20
+ ]
21
+
22
+ const ID = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u
23
+ const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u
24
+ // The release pruner deletes these under node_modules (research.md Q3), so an
25
+ // example must never depend on files inside them.
26
+ const PRUNED_DIR = /(?:^|\/)(?:test|tests)(?:\/|$)/u
27
+
28
+ const isObject = value => typeof value === 'object' && value !== null && !Array.isArray(value)
29
+ const isSafeRelative = path => typeof path === 'string' && path.length > 0 && !path.startsWith('/') && !/^[A-Za-z]:/u.test(path) && !path.split('/').includes('..')
30
+
31
+ /**
32
+ * @param {unknown} manifest parsed docs.json
33
+ * @param {{ docFiles: readonly string[], exampleFiles: readonly string[] }} files
34
+ * paths relative to docs/ and to example-plugins/ (posix separators)
35
+ * @returns {string[]} violations, empty when valid
36
+ */
37
+ export function validateManifest(manifest, files) {
38
+ const problems = []
39
+ if (!isObject(manifest)) return ['manifest is not an object']
40
+ if (manifest.schemaVersion !== 1) problems.push('schemaVersion must be 1')
41
+ if (typeof manifest.packVersion !== 'string' || !SEMVER.test(manifest.packVersion)) problems.push('packVersion must be a semver string')
42
+ if (!Array.isArray(manifest.navigation)) problems.push('navigation must be an array')
43
+ if (!Array.isArray(manifest.examples)) problems.push('examples must be an array')
44
+ if (problems.length) return problems
45
+
46
+ const docFiles = new Set(files.docFiles)
47
+ const exampleFiles = new Set(files.exampleFiles)
48
+ const docIds = new Set()
49
+ const exampleIds = new Set()
50
+ const docPaths = new Set()
51
+
52
+ const docs = []
53
+ manifest.navigation.forEach((group, gi) => {
54
+ if (!isObject(group) || typeof group.title !== 'string' || group.title === '' || !Array.isArray(group.items)) {
55
+ problems.push(`navigation[${gi}] must have a title and items`)
56
+ return
57
+ }
58
+ for (const item of group.items) docs.push(item)
59
+ })
60
+
61
+ for (const doc of docs) {
62
+ const at = isObject(doc) && typeof doc.id === 'string' ? `doc ${doc.id}` : 'doc <no id>'
63
+ if (!isObject(doc)) { problems.push(`${at}: not an object`); continue }
64
+ if (typeof doc.id !== 'string' || !ID.test(doc.id)) problems.push(`${at}: id must be lowercase kebab/dot`)
65
+ else if (docIds.has(doc.id)) problems.push(`${at}: duplicate id`)
66
+ else docIds.add(doc.id)
67
+ if (typeof doc.title !== 'string' || doc.title === '') problems.push(`${at}: title is required`)
68
+ if (typeof doc.when !== 'string' || doc.when.trim() === '') problems.push(`${at}: "when" (read this when...) is required`)
69
+ if (!isSafeRelative(doc.path)) problems.push(`${at}: path must be a safe relative path`)
70
+ else {
71
+ docPaths.add(doc.path)
72
+ if (!docFiles.has(doc.path)) problems.push(`${at}: path ${doc.path} does not exist under docs/`)
73
+ }
74
+ if (!Array.isArray(doc.surfaces) || doc.surfaces.length === 0 || doc.surfaces.some(s => !SURFACES.includes(s))) problems.push(`${at}: surfaces must be a non-empty subset of ${SURFACES.join(', ')}`)
75
+ if (!APPLIES.includes(doc.applies)) problems.push(`${at}: applies must be one of ${APPLIES.join(', ')}`)
76
+ }
77
+
78
+ // Router routes (the prompt's "when asked about X (docs)" map): every route names existing docs.
79
+ if (manifest.routes !== undefined) {
80
+ if (!Array.isArray(manifest.routes)) problems.push('routes must be an array')
81
+ else manifest.routes.forEach((route, i) => {
82
+ if (!isObject(route) || typeof route.when !== 'string' || route.when === '' || !Array.isArray(route.docs) || route.docs.length === 0) { problems.push(`routes[${i}]: needs "when" and a non-empty "docs" array`); return }
83
+ for (const id of route.docs) if (!docIds.has(id)) problems.push(`routes[${i}] (${route.when}): unknown doc id ${id}`)
84
+ })
85
+ }
86
+
87
+ for (const example of manifest.examples) {
88
+ const at = isObject(example) && typeof example.id === 'string' ? `example ${example.id}` : 'example <no id>'
89
+ if (!isObject(example)) { problems.push(`${at}: not an object`); continue }
90
+ if (typeof example.id !== 'string' || !ID.test(example.id)) problems.push(`${at}: id must be lowercase kebab/dot`)
91
+ else if (exampleIds.has(example.id)) problems.push(`${at}: duplicate id`)
92
+ else exampleIds.add(example.id)
93
+ if (!PLUGIN_TYPES.includes(example.type)) problems.push(`${at}: type must be a coverage-matrix type`)
94
+ if (typeof example.teaches !== 'string' || example.teaches.trim() === '') problems.push(`${at}: teaches is required`)
95
+ if (example.scenario !== undefined && (typeof example.scenario !== 'string' || example.scenario === '')) problems.push(`${at}: scenario, when present, must be a non-empty id`)
96
+ if (!Array.isArray(example.surfaces) || example.surfaces.length === 0 || example.surfaces.some(s => !SURFACES.includes(s))) problems.push(`${at}: surfaces must be a non-empty subset of ${SURFACES.join(', ')}`)
97
+ if (!isSafeRelative(example.path)) problems.push(`${at}: path must be a safe relative path`)
98
+ else {
99
+ const prefix = `packages/${example.path}/`
100
+ if (![...exampleFiles].some(f => f.startsWith(prefix))) problems.push(`${at}: no files under example-plugins/${prefix}`)
101
+ if (PRUNED_DIR.test(example.path)) problems.push(`${at}: path uses a test/tests directory the release pruner deletes`)
102
+ for (const f of exampleFiles) if (f.startsWith(prefix) && PRUNED_DIR.test(f.slice(prefix.length))) problems.push(`${at}: ${f} is inside a test/tests directory the release pruner deletes (use checks/)`)
103
+ }
104
+ if (!Array.isArray(example.docs)) problems.push(`${at}: docs must be an array of doc ids`)
105
+ else for (const id of example.docs) if (!docIds.has(id)) problems.push(`${at}: unknown doc id ${id}`)
106
+ }
107
+
108
+ for (const doc of docs) {
109
+ if (!isObject(doc) || typeof doc.id !== 'string') continue
110
+ for (const id of doc.seeAlso ?? []) if (!docIds.has(id)) problems.push(`doc ${doc.id}: seeAlso unknown doc id ${id}`)
111
+ for (const id of doc.examples ?? []) if (!exampleIds.has(id)) problems.push(`doc ${doc.id}: examples unknown example id ${id}`)
112
+ }
113
+
114
+ // Index completeness: nothing under docs/ or example-plugins/ may exist unlisted.
115
+ const generated = new Set(['docs.json', 'README.md'])
116
+ for (const file of docFiles) {
117
+ if (generated.has(file)) continue
118
+ if (!docPaths.has(file)) problems.push(`docs/${file} is not listed in the manifest`)
119
+ }
120
+ const exampleRoots = new Set(manifest.examples.filter(e => isObject(e) && typeof e.path === 'string').map(e => `packages/${e.path}/`))
121
+ const exampleMeta = new Set(['README.md', 'scenarios.json'])
122
+ for (const file of exampleFiles) {
123
+ if (exampleMeta.has(file)) continue
124
+ if (![...exampleRoots].some(root => file.startsWith(root))) problems.push(`example-plugins/${file} is not covered by any manifest example`)
125
+ }
126
+ return problems
127
+ }