@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.
- package/LICENSE +21 -0
- package/README.md +12 -2
- package/docs/README.md +160 -0
- package/docs/delivery/local-live.md +113 -0
- package/docs/delivery/marketplace.md +16 -0
- package/docs/docs.json +2836 -0
- package/docs/extending/agent-preset.md +37 -0
- package/docs/extending/chat-command.md +28 -0
- package/docs/extending/client-slot.md +135 -0
- package/docs/extending/config-schema.md +7 -0
- package/docs/extending/cordis-core.md +63 -0
- package/docs/extending/desktop-app.md +53 -0
- package/docs/extending/desktop-main.md +25 -0
- package/docs/extending/event-hook.md +14 -0
- package/docs/extending/host-route.md +33 -0
- package/docs/extending/llm-adapter.md +38 -0
- package/docs/extending/packaging.md +53 -0
- package/docs/extending/prompt-contribution.md +9 -0
- package/docs/extending/service.md +13 -0
- package/docs/extending/skill-provider.md +9 -0
- package/docs/extending/state-and-persistence.md +71 -0
- package/docs/extending/three-role-capability.md +33 -0
- package/docs/extending/tool-plugin.md +24 -0
- package/docs/extending/tui-command.md +8 -0
- package/docs/extending/tui-components.md +61 -0
- package/docs/extending/ui-branding.md +43 -0
- package/docs/extending/ui-components.md +56 -0
- package/docs/extending/ui-customization.md +41 -0
- package/docs/extending/ui-library.md +66 -0
- package/docs/extending/ui-theme.md +55 -0
- package/docs/extending/workspace-tab.md +50 -0
- package/docs/maps/events.md +108 -0
- package/docs/maps/mount-points.md +154 -0
- package/docs/maps/slot-contracts.md +3376 -0
- package/docs/maps/taxonomy.md +306 -0
- package/docs/maps/theme-tokens.md +115 -0
- package/docs/maps/ui-components.md +26 -0
- package/docs/reference/cookbook/adding-a-package.md +174 -0
- package/docs/reference/cookbook/adding-a-remote-api.md +199 -0
- package/docs/reference/cookbook/adding-a-settings-card.md +74 -0
- package/docs/reference/cookbook/adding-a-tool.md +103 -0
- package/docs/reference/cookbook/adding-an-llm-adapter.md +45 -0
- package/docs/reference/cookbook/extension-cookbook.md +134 -0
- package/docs/reference/cordis-api/context.md +366 -0
- package/docs/reference/cordis-api/events.md +209 -0
- package/docs/reference/cordis-api/fiber.md +377 -0
- package/docs/reference/cordis-api/inherited.md +40 -0
- package/docs/reference/cordis-api/registry.md +154 -0
- package/docs/reference/cordis-api/service.md +104 -0
- package/docs/reference/cordis-guides/cordis-usage-cheatsheet.md +167 -0
- package/docs/reference/cordis-guides/cordis_system_guide_for_coding_agents.md +4666 -0
- package/docs/reference/cordis-guides/development-canvas-plugin.md +109 -0
- package/docs/reference/cordis-guides/hello-world-plugin-guide.md +517 -0
- package/docs/reference/harness/agent-lifecycle.md +93 -0
- package/docs/reference/harness/architecture.md +168 -0
- package/docs/reference/harness/capability-seams.md +675 -0
- package/docs/reference/harness/config-catalog.md +4523 -0
- package/docs/reference/harness/cordis-primer.md +47 -0
- package/docs/reference/harness/defensive-patterns.md +35 -0
- package/docs/reference/harness/event-producer-consumer.md +111 -0
- package/docs/reference/harness/glossary.md +47 -0
- package/docs/reference/harness/tool-catalog.md +2721 -0
- package/docs/reference/harness/tool-execution-pipeline.md +67 -0
- package/docs/reference/subsystems/README.md +75 -0
- package/docs/reference/subsystems/agent-team.md +233 -0
- package/docs/reference/subsystems/approval.md +172 -0
- package/docs/reference/subsystems/attachment.md +363 -0
- package/docs/reference/subsystems/boot.md +324 -0
- package/docs/reference/subsystems/browser-use.md +69 -0
- package/docs/reference/subsystems/client-modules.md +186 -0
- package/docs/reference/subsystems/client-resources.md +94 -0
- package/docs/reference/subsystems/commands.md +225 -0
- package/docs/reference/subsystems/compaction.md +286 -0
- package/docs/reference/subsystems/computer-use.md +58 -0
- package/docs/reference/subsystems/conversation.md +287 -0
- package/docs/reference/subsystems/core.md +1107 -0
- package/docs/reference/subsystems/credentials.md +497 -0
- package/docs/reference/subsystems/deliverables.md +180 -0
- package/docs/reference/subsystems/extensions.md +386 -0
- package/docs/reference/subsystems/feedback.md +402 -0
- package/docs/reference/subsystems/filesystem.md +532 -0
- package/docs/reference/subsystems/goal.md +315 -0
- package/docs/reference/subsystems/invariants.md +90 -0
- package/docs/reference/subsystems/jobs.md +501 -0
- package/docs/reference/subsystems/llm-streaming.md +1131 -0
- package/docs/reference/subsystems/lsp.md +204 -0
- package/docs/reference/subsystems/mcp.md +141 -0
- package/docs/reference/subsystems/office-to-pdf.md +89 -0
- package/docs/reference/subsystems/otel.md +46 -0
- package/docs/reference/subsystems/permission-presets.md +169 -0
- package/docs/reference/subsystems/persistence.md +418 -0
- package/docs/reference/subsystems/plan.md +89 -0
- package/docs/reference/subsystems/product-telemetry.md +81 -0
- package/docs/reference/subsystems/ptc-runtime.md +234 -0
- package/docs/reference/subsystems/sandbox.md +223 -0
- package/docs/reference/subsystems/schedule.md +545 -0
- package/docs/reference/subsystems/scope.md +61 -0
- package/docs/reference/subsystems/session-projection.md +358 -0
- package/docs/reference/subsystems/session-query.md +511 -0
- package/docs/reference/subsystems/session-reference.md +226 -0
- package/docs/reference/subsystems/session-telemetry.md +214 -0
- package/docs/reference/subsystems/session-title.md +206 -0
- package/docs/reference/subsystems/session.md +1300 -0
- package/docs/reference/subsystems/settings.md +157 -0
- package/docs/reference/subsystems/shell.md +316 -0
- package/docs/reference/subsystems/sidebar-right.md +160 -0
- package/docs/reference/subsystems/skills.md +354 -0
- package/docs/reference/subsystems/slots.md +201 -0
- package/docs/reference/subsystems/spill.md +126 -0
- package/docs/reference/subsystems/ssh.md +137 -0
- package/docs/reference/subsystems/storage.md +262 -0
- package/docs/reference/subsystems/subagent.md +762 -0
- package/docs/reference/subsystems/subprocess.md +323 -0
- package/docs/reference/subsystems/system-prompt.md +226 -0
- package/docs/reference/subsystems/terminal.md +186 -0
- package/docs/reference/subsystems/todo.md +34 -0
- package/docs/reference/subsystems/token-meter.md +108 -0
- package/docs/reference/subsystems/tools.md +749 -0
- package/docs/reference/subsystems/typert.md +489 -0
- package/docs/reference/subsystems/user-questions.md +309 -0
- package/docs/reference/subsystems/voice-input.md +166 -0
- package/docs/reference/subsystems/web-client.md +102 -0
- package/docs/reference/subsystems/web-server.md +228 -0
- package/docs/reference/subsystems/web.md +208 -0
- package/docs/reference/subsystems/webhook.md +72 -0
- package/docs/reference/subsystems/workflow.md +280 -0
- package/docs/reference/subsystems/workspace.md +661 -0
- package/docs/start-here/blueprints.md +33 -0
- package/docs/start-here/this-runtime.md +84 -0
- package/docs/start-here/troubleshooting.md +29 -0
- package/docs/start-here/trust-and-safety.md +39 -0
- package/docs/start-here/verify-before-done.md +46 -0
- package/example-plugins/README.md +45 -0
- package/example-plugins/packages/agent-preset-reviewer/agent.cordis.yml +18 -0
- package/example-plugins/packages/agent-preset-reviewer/preset.yml +3 -0
- package/example-plugins/packages/capability-swap-consumer/cordis.patch.yml +3 -0
- package/example-plugins/packages/capability-swap-consumer/index.js +14 -0
- package/example-plugins/packages/capability-swap-consumer/package.json +25 -0
- package/example-plugins/packages/capability-swap-provider-loud/cordis.patch.yml +3 -0
- package/example-plugins/packages/capability-swap-provider-loud/index.js +20 -0
- package/example-plugins/packages/capability-swap-provider-loud/package.json +25 -0
- package/example-plugins/packages/capability-swap-provider-quiet/cordis.patch.yml +3 -0
- package/example-plugins/packages/capability-swap-provider-quiet/index.js +20 -0
- package/example-plugins/packages/capability-swap-provider-quiet/package.json +25 -0
- package/example-plugins/packages/chat-command-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/chat-command-basic/index.js +26 -0
- package/example-plugins/packages/chat-command-basic/package.json +25 -0
- package/example-plugins/packages/client-chat-message-action/client.js +46 -0
- package/example-plugins/packages/client-chat-message-action/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-chat-message-action/index.js +9 -0
- package/example-plugins/packages/client-chat-message-action/package.json +31 -0
- package/example-plugins/packages/client-slot-header-action/client.js +57 -0
- package/example-plugins/packages/client-slot-header-action/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-slot-header-action/index.js +13 -0
- package/example-plugins/packages/client-slot-header-action/package.json +31 -0
- package/example-plugins/packages/client-slot-sidebar-tab/client.js +57 -0
- package/example-plugins/packages/client-slot-sidebar-tab/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-slot-sidebar-tab/index.js +9 -0
- package/example-plugins/packages/client-slot-sidebar-tab/package.json +32 -0
- package/example-plugins/packages/client-theme-override/client.js +52 -0
- package/example-plugins/packages/client-theme-override/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-theme-override/index.js +9 -0
- package/example-plugins/packages/client-theme-override/package.json +30 -0
- package/example-plugins/packages/client-tool-view/client.js +47 -0
- package/example-plugins/packages/client-tool-view/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-tool-view/index.js +24 -0
- package/example-plugins/packages/client-tool-view/package.json +34 -0
- package/example-plugins/packages/client-ui-components/client.js +77 -0
- package/example-plugins/packages/client-ui-components/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-ui-components/index.js +9 -0
- package/example-plugins/packages/client-ui-components/package.json +31 -0
- package/example-plugins/packages/client-ui-library/client.js +715 -0
- package/example-plugins/packages/client-ui-library/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-ui-library/index.js +9 -0
- package/example-plugins/packages/client-ui-library/package.json +37 -0
- package/example-plugins/packages/client-workspace-tab/client.js +72 -0
- package/example-plugins/packages/client-workspace-tab/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-workspace-tab/index.js +9 -0
- package/example-plugins/packages/client-workspace-tab/package.json +30 -0
- package/example-plugins/packages/config-schema-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/config-schema-basic/index.js +19 -0
- package/example-plugins/packages/config-schema-basic/package.json +25 -0
- package/example-plugins/packages/desktop-main-profile-info/cordis.patch.yml +3 -0
- package/example-plugins/packages/desktop-main-profile-info/index.js +22 -0
- package/example-plugins/packages/desktop-main-profile-info/package.json +25 -0
- package/example-plugins/packages/event-hook-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/event-hook-basic/index.js +17 -0
- package/example-plugins/packages/event-hook-basic/package.json +22 -0
- package/example-plugins/packages/generated-capability-template/cordis.patch.yml +3 -0
- package/example-plugins/packages/generated-capability-template/index.js +16 -0
- package/example-plugins/packages/generated-capability-template/package.json +42 -0
- package/example-plugins/packages/host-route-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/host-route-basic/index.js +20 -0
- package/example-plugins/packages/host-route-basic/package.json +29 -0
- package/example-plugins/packages/lifecycle-function-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/lifecycle-function-basic/index.js +12 -0
- package/example-plugins/packages/lifecycle-function-basic/package.json +15 -0
- package/example-plugins/packages/lifecycle-function-hot-shim/cordis.patch.yml +3 -0
- package/example-plugins/packages/lifecycle-function-hot-shim/impl.js +5 -0
- package/example-plugins/packages/lifecycle-function-hot-shim/index.js +18 -0
- package/example-plugins/packages/lifecycle-function-hot-shim/package.json +23 -0
- package/example-plugins/packages/lifecycle-hooks-observer/cordis.patch.yml +3 -0
- package/example-plugins/packages/lifecycle-hooks-observer/index.js +23 -0
- package/example-plugins/packages/lifecycle-hooks-observer/package.json +22 -0
- package/example-plugins/packages/llm-adapter-echo/cordis.patch.yml +3 -0
- package/example-plugins/packages/llm-adapter-echo/index.js +42 -0
- package/example-plugins/packages/llm-adapter-echo/package.json +25 -0
- package/example-plugins/packages/prompt-assemble-hook/cordis.patch.yml +3 -0
- package/example-plugins/packages/prompt-assemble-hook/index.js +22 -0
- package/example-plugins/packages/prompt-assemble-hook/package.json +22 -0
- package/example-plugins/packages/prompt-contribution-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/prompt-contribution-basic/index.js +18 -0
- package/example-plugins/packages/prompt-contribution-basic/package.json +22 -0
- package/example-plugins/packages/service-consumer-greeter/cordis.patch.yml +3 -0
- package/example-plugins/packages/service-consumer-greeter/index.js +14 -0
- package/example-plugins/packages/service-consumer-greeter/package.json +22 -0
- package/example-plugins/packages/service-provider-greeter/cordis.patch.yml +3 -0
- package/example-plugins/packages/service-provider-greeter/index.js +22 -0
- package/example-plugins/packages/service-provider-greeter/package.json +25 -0
- package/example-plugins/packages/settings-section-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/settings-section-basic/index.js +34 -0
- package/example-plugins/packages/settings-section-basic/package.json +26 -0
- package/example-plugins/packages/skill-provider-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/skill-provider-basic/index.js +31 -0
- package/example-plugins/packages/skill-provider-basic/package.json +22 -0
- package/example-plugins/packages/state-host-store/client.js +57 -0
- package/example-plugins/packages/state-host-store/cordis.patch.yml +3 -0
- package/example-plugins/packages/state-host-store/index.js +90 -0
- package/example-plugins/packages/state-host-store/package.json +31 -0
- package/example-plugins/packages/state-workspace-file/cordis.patch.yml +3 -0
- package/example-plugins/packages/state-workspace-file/index.js +52 -0
- package/example-plugins/packages/state-workspace-file/package.json +25 -0
- package/example-plugins/packages/tool-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/tool-basic/index.js +25 -0
- package/example-plugins/packages/tool-basic/package.json +25 -0
- package/example-plugins/packages/tool-policy-hook/cordis.patch.yml +3 -0
- package/example-plugins/packages/tool-policy-hook/index.js +28 -0
- package/example-plugins/packages/tool-policy-hook/package.json +25 -0
- package/example-plugins/packages/tui-command-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/tui-command-basic/index.js +24 -0
- package/example-plugins/packages/tui-command-basic/package.json +22 -0
- package/example-plugins/packages/tui-overlay-themed/cordis.patch.yml +3 -0
- package/example-plugins/packages/tui-overlay-themed/index.js +65 -0
- package/example-plugins/packages/tui-overlay-themed/package.json +25 -0
- package/example-plugins/packages/tui-ui-library/cordis.patch.yml +3 -0
- package/example-plugins/packages/tui-ui-library/index.js +73 -0
- package/example-plugins/packages/tui-ui-library/package.json +29 -0
- package/example-plugins/packages/web-page-branding/cordis.patch.yml +3 -0
- package/example-plugins/packages/web-page-branding/index.js +31 -0
- package/example-plugins/packages/web-page-branding/package.json +22 -0
- package/example-plugins/scenarios.json +11 -0
- package/index.js +384 -0
- package/lib/blend-apply.js +107 -0
- package/lib/blend-capture.js +249 -0
- package/lib/blend-ledger.js +76 -0
- package/lib/contract.js +5 -0
- package/lib/install.js +516 -0
- package/lib/lookup.js +67 -0
- package/lib/manifest.js +56 -0
- package/lib/pack-root.js +22 -0
- package/lib/provenance.js +110 -0
- package/lib/publish.js +64 -0
- package/lib/reconcile.js +83 -0
- package/lib/router.js +55 -0
- package/lib/scopes.js +82 -0
- package/lib/skills.js +54 -0
- package/lib/stage.js +157 -0
- package/lib/verify.js +77 -0
- package/package.json +58 -3
- package/scripts/lib/indexes.mjs +45 -0
- package/scripts/lib/manifest.mjs +127 -0
- package/scripts/lib/maps.mjs +482 -0
- package/skills/acryl-add-provider-or-capability/SKILL.md +12 -0
- package/skills/acryl-add-ui/SKILL.md +18 -0
- package/skills/acryl-build-plugin/SKILL.md +21 -0
- package/skills/acryl-change-plugin/SKILL.md +16 -0
- package/skills/acryl-desktop-shell/SKILL.md +12 -0
- package/skills/acryl-diagnose-plugin/SKILL.md +10 -0
- package/skills/acryl-fix-plugin/SKILL.md +12 -0
- package/skills/acryl-improve-ui/SKILL.md +10 -0
- package/skills/acryl-remove-plugin/SKILL.md +11 -0
- package/skills/acryl-restyle-ui/SKILL.md +14 -0
- package/skills/acryl-share-plugin/SKILL.md +23 -0
- package/skills/acryl-tui-ui/SKILL.md +12 -0
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,61 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@acryldev/plugin-context",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.1.1",
|
|
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
|
+
"README.md",
|
|
33
|
+
"LICENSE"
|
|
34
|
+
],
|
|
35
|
+
"engines": {
|
|
36
|
+
"node": "^22.19.0 || >=24.0.0"
|
|
37
|
+
},
|
|
38
|
+
"main": "./index.js",
|
|
39
|
+
"dependencies": {
|
|
40
|
+
"@acryldev/blends-core": "0.6.0",
|
|
41
|
+
"@acryldev/plugin-hub-core": "0.2.2",
|
|
42
|
+
"@deepseek-ai/dsh-tools": "0.2.0-rc.2",
|
|
43
|
+
"@acryldev/blends": "^1.7.3",
|
|
44
|
+
"yaml": "^2.9.0"
|
|
45
|
+
},
|
|
46
|
+
"devDependencies": {
|
|
47
|
+
"@deepseek-ai/cordis": "4.0.4",
|
|
48
|
+
"@deepseek-ai/dsh-llm": "0.2.0-rc.2",
|
|
49
|
+
"@deepseek-ai/schemastery": "~3.18.4",
|
|
50
|
+
"@earendil-works/pi-tui": "1.1.0",
|
|
51
|
+
"@types/node": "^22.20.0",
|
|
52
|
+
"@acryldev/ui-tui": "0.1.0"
|
|
53
|
+
},
|
|
54
|
+
"scripts": {
|
|
55
|
+
"sync:corpus": "node scripts/sync-corpus.mjs",
|
|
56
|
+
"build:manifest": "node scripts/build-manifest.mjs",
|
|
57
|
+
"verify:manifest": "node scripts/build-manifest.mjs --check",
|
|
58
|
+
"test": "node --test scripts/contract.test.mjs scripts/manifest.test.mjs scripts/plugin.test.mjs scripts/scopes.test.mjs scripts/app-blend.test.mjs",
|
|
59
|
+
"check": "pnpm run test && pnpm run verify:manifest"
|
|
60
|
+
}
|
|
6
61
|
}
|
|
@@ -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
|
+
}
|