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