@acryldev/harness-runtime 0.0.0-stage → 0.2.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (167) hide show
  1. package/LICENSE +49 -0
  2. package/README.md +14 -2
  3. package/lib/index.mjs +5693 -0
  4. package/lib/index.mjs.map +1 -0
  5. package/lib/types/acryl-home.d.ts +81 -0
  6. package/lib/types/app/new-app.d.ts +65 -0
  7. package/lib/types/app/start-source.d.ts +47 -0
  8. package/lib/types/blueprint/blueprint.d.ts +74 -0
  9. package/lib/types/blueprint/brand-identity.d.ts +26 -0
  10. package/lib/types/blueprint/compose.d.ts +53 -0
  11. package/lib/types/blueprint/definition.d.ts +22 -0
  12. package/lib/types/blueprint/index.d.ts +7 -0
  13. package/lib/types/blueprint/manifest.d.ts +35 -0
  14. package/lib/types/blueprint/selection.d.ts +19 -0
  15. package/lib/types/cli-market-install.d.ts +97 -0
  16. package/lib/types/cli-market-plugins.d.ts +81 -0
  17. package/lib/types/coding-capabilities.d.ts +29 -0
  18. package/lib/types/durable-message.d.ts +18 -0
  19. package/lib/types/engine-dsh.d.ts +181 -0
  20. package/lib/types/engine-files.d.ts +8 -0
  21. package/lib/types/engine-host.d.ts +32 -0
  22. package/lib/types/engine-tools.d.ts +11 -0
  23. package/lib/types/index.d.ts +67 -0
  24. package/lib/types/instance/announce-self.d.ts +38 -0
  25. package/lib/types/instance/app-instance.d.ts +125 -0
  26. package/lib/types/instance/index.d.ts +6 -0
  27. package/lib/types/instance/offline-lock.d.ts +29 -0
  28. package/lib/types/instance/online-secret.d.ts +29 -0
  29. package/lib/types/instance/registry.d.ts +26 -0
  30. package/lib/types/instance/select.d.ts +43 -0
  31. package/lib/types/module-hooks.d.ts +19 -0
  32. package/lib/types/module-resolution.d.ts +31 -0
  33. package/lib/types/package-overlay.d.ts +41 -0
  34. package/lib/types/pinned-pnpm.d.ts +15 -0
  35. package/lib/types/plugin-acryl-workspace-status.d.ts +24 -0
  36. package/lib/types/plugin-doctor.d.ts +49 -0
  37. package/lib/types/plugin-lifecycle-state.d.ts +92 -0
  38. package/lib/types/plugin-lifecycle.d.ts +87 -0
  39. package/lib/types/profile-layout.d.ts +17 -0
  40. package/lib/types/profile-owner.d.ts +25 -0
  41. package/lib/types/profile-repair/backup.d.ts +37 -0
  42. package/lib/types/profile-repair/findings.d.ts +29 -0
  43. package/lib/types/profile-repair/index.d.ts +9 -0
  44. package/lib/types/profile-repair/inspector.d.ts +11 -0
  45. package/lib/types/profile-repair/repair.d.ts +38 -0
  46. package/lib/types/profile-resolution/moved-framework.d.ts +21 -0
  47. package/lib/types/profile-resolution/resolver.d.ts +41 -0
  48. package/lib/types/profile-resolution/service.d.ts +22 -0
  49. package/lib/types/prompt-budget.d.ts +44 -0
  50. package/lib/types/session-bridge.d.ts +57 -0
  51. package/lib/types/session-log-exporter.d.ts +31 -0
  52. package/lib/types/system-prompt-capture.d.ts +29 -0
  53. package/lib/types/web-favicon-data.d.ts +5 -0
  54. package/lib/types/web-favicon.d.ts +23 -0
  55. package/lib/types/web-market-install.d.ts +114 -0
  56. package/lib/types/web-market-plugins.d.ts +106 -0
  57. package/lib/types/web-port.d.ts +15 -0
  58. package/package.json +211 -3
  59. package/src/acryl-home.ts +103 -0
  60. package/src/app/new-app.ts +239 -0
  61. package/src/app/start-source.ts +110 -0
  62. package/src/blueprint/blueprint.ts +141 -0
  63. package/src/blueprint/brand-identity.ts +75 -0
  64. package/src/blueprint/compose.ts +222 -0
  65. package/src/blueprint/definition.ts +92 -0
  66. package/src/blueprint/index.ts +20 -0
  67. package/src/blueprint/manifest.ts +145 -0
  68. package/src/blueprint/selection.ts +74 -0
  69. package/src/cli-market-install.ts +181 -0
  70. package/src/cli-market-plugins.ts +176 -0
  71. package/src/coding-capabilities.ts +61 -0
  72. package/src/durable-message.ts +23 -0
  73. package/src/engine-dsh.ts +856 -0
  74. package/src/engine-files.ts +9 -0
  75. package/src/engine-host.ts +128 -0
  76. package/src/engine-tools.ts +26 -0
  77. package/src/index.ts +436 -0
  78. package/src/instance/announce-self.ts +88 -0
  79. package/src/instance/app-instance.ts +240 -0
  80. package/src/instance/index.ts +45 -0
  81. package/src/instance/offline-lock.ts +71 -0
  82. package/src/instance/online-secret.ts +55 -0
  83. package/src/instance/registry.ts +53 -0
  84. package/src/instance/select.ts +134 -0
  85. package/src/module-hooks.ts +41 -0
  86. package/src/module-resolution.ts +187 -0
  87. package/src/package-overlay.ts +160 -0
  88. package/src/pinned-pnpm.ts +67 -0
  89. package/src/plugin-acryl-workspace-status.ts +99 -0
  90. package/src/plugin-doctor.ts +141 -0
  91. package/src/plugin-lifecycle-state.ts +347 -0
  92. package/src/plugin-lifecycle.ts +223 -0
  93. package/src/profile-layout.ts +97 -0
  94. package/src/profile-owner.ts +52 -0
  95. package/src/profile-repair/backup.ts +119 -0
  96. package/src/profile-repair/findings.ts +43 -0
  97. package/src/profile-repair/index.ts +10 -0
  98. package/src/profile-repair/inspector.ts +156 -0
  99. package/src/profile-repair/repair.ts +137 -0
  100. package/src/profile-resolution/moved-framework.ts +64 -0
  101. package/src/profile-resolution/resolver.ts +876 -0
  102. package/src/profile-resolution/service.ts +99 -0
  103. package/src/prompt-budget.ts +118 -0
  104. package/src/session-bridge.ts +350 -0
  105. package/src/session-log-exporter.ts +68 -0
  106. package/src/system-prompt-capture.ts +99 -0
  107. package/src/web-favicon-data.ts +6 -0
  108. package/src/web-favicon.ts +43 -0
  109. package/src/web-market-install.ts +206 -0
  110. package/src/web-market-plugins.ts +215 -0
  111. package/src/web-port.ts +39 -0
  112. package/tests/account-callback.spec.ts +173 -0
  113. package/tests/acryl-home.spec.ts +39 -0
  114. package/tests/agent-self-hosting.spec.ts +101 -0
  115. package/tests/announce-self.spec.ts +84 -0
  116. package/tests/app-lifecycle.spec.ts +99 -0
  117. package/tests/blank-blueprint.spec.ts +110 -0
  118. package/tests/blueprint-definition.spec.ts +128 -0
  119. package/tests/blueprint.spec.ts +138 -0
  120. package/tests/bulkhead.spec.ts +187 -0
  121. package/tests/coding-vocabulary.spec.ts +15 -0
  122. package/tests/dump-system-prompt.spec.ts +65 -0
  123. package/tests/e2e-real-model.spec.ts +71 -0
  124. package/tests/e2e-restart-real-model.spec.ts +77 -0
  125. package/tests/engine-dsh.spec.ts +340 -0
  126. package/tests/engine-host-mount-root-include.spec.ts +118 -0
  127. package/tests/engine-host.spec.ts +176 -0
  128. package/tests/engine-optional.spec.ts +81 -0
  129. package/tests/extension-examples.spec.ts +261 -0
  130. package/tests/hooks-thread-stack.ts +27 -0
  131. package/tests/instance-patches.spec.ts +25 -0
  132. package/tests/instance.spec.ts +235 -0
  133. package/tests/live/community-plugins.spec.ts +83 -0
  134. package/tests/module-hooks.spec.ts +35 -0
  135. package/tests/module-resolution.spec.ts +265 -0
  136. package/tests/moved-framework.spec.ts +61 -0
  137. package/tests/new-app.spec.ts +132 -0
  138. package/tests/organizer-growth.spec.ts +117 -0
  139. package/tests/pinned-pnpm.spec.ts +34 -0
  140. package/tests/plugin-acryl-workspace-status.spec.ts +63 -0
  141. package/tests/plugin-context.spec.ts +640 -0
  142. package/tests/plugin-doctor.spec.ts +183 -0
  143. package/tests/plugin-enablement-one-store.spec.ts +130 -0
  144. package/tests/plugin-lifecycle-state.spec.ts +169 -0
  145. package/tests/profile-layout.spec.ts +58 -0
  146. package/tests/profile-owner.spec.ts +38 -0
  147. package/tests/profile-repair/profile-repair.spec.ts +231 -0
  148. package/tests/profile-resolution-port.spec.ts +30 -0
  149. package/tests/profile-resolution-service.spec.ts +273 -0
  150. package/tests/profile-resolution-swap.spec.ts +69 -0
  151. package/tests/profile-resolution.spec.ts +2535 -0
  152. package/tests/profile.spec.ts +70 -0
  153. package/tests/project-registry.spec.ts +81 -0
  154. package/tests/prompt-budget.spec.ts +58 -0
  155. package/tests/real-home-guard.spec.ts +178 -0
  156. package/tests/session-bridge.spec.ts +316 -0
  157. package/tests/start-source.spec.ts +65 -0
  158. package/tests/system-prompt-shape.spec.ts +95 -0
  159. package/tests/three-levels.spec.ts +84 -0
  160. package/tests/tool-gateway.spec.ts +116 -0
  161. package/tests/tool-schemas.spec.ts +41 -0
  162. package/tests/web-favicon.spec.ts +42 -0
  163. package/tests/web-port.spec.ts +38 -0
  164. package/tests/web-startup-hold.spec.ts +79 -0
  165. package/tsconfig.json +24 -0
  166. package/tsdown.config.ts +2 -0
  167. package/vitest.config.ts +18 -0
@@ -0,0 +1,20 @@
1
+ export { brandIdentity, identityLine, InvalidBrandIdentityError, type BrandIdentity } from './brand-identity.ts'
2
+ export {
3
+ AGENTS_BLUEPRINT,
4
+ BLANK_BLUEPRINT,
5
+ IDE_BLUEPRINT,
6
+ UnknownBlueprintError,
7
+ BLUEPRINT_ROW_IDS,
8
+ builtInCatalog,
9
+ selectBlueprint,
10
+ withBrand,
11
+ type Blueprint,
12
+ type BlueprintBrand,
13
+ type BlueprintCatalog,
14
+ type BlueprintRowId,
15
+ } from './blueprint.ts'
16
+ export { blueprintRowForModule, composeBlueprintRows, currentModule, DSH_CHAT_ROW_IDS, DSH_PLUGIN_MANAGER_ROW_ID, packageOfModule, PLUGIN_MANAGER_ROW_ID, RENAMED_MODULES, rowForBlueprintRow, type BlueprintComposition } from './compose.ts'
17
+ export { blueprintFromEnvironment } from './selection.ts'
18
+ export { InvalidBlueprintError, parseBlueprint } from './definition.ts'
19
+ export { readBlueprintFile, readStarters } from './selection.ts'
20
+ export { BLENDS_API_VERSION, BRAND_PACKAGE, appManifest, blueprintFromManifest, catalogWithStarters, isBlendsManifest } from './manifest.ts'
@@ -0,0 +1,145 @@
1
+ /**
2
+ * The app definition file (`blend.yaml`) is a Blends manifest (`blends.acryl.dev/v1alpha1`), so one file is both what the Blends tooling reads, captures
3
+ * and publishes and what this runtime boots from. The format itself (schema, structural rules, lineage) is validated by `@acryldev/blends-core`, the one
4
+ * reader of the format; this module is only the translation between the two vocabularies, pure and in both directions:
5
+ *
6
+ * manifest -> Blueprint `kind: Blend` grows from `spec.lineage.blueprint` (a known Blueprint); `kind: Blueprint` names one. Rows whose package is one of
7
+ * ACRYL's own rows turn that capability on (or off with `disabled: true`); the `@acryldev/brand` row's config is the brand. Any other
8
+ * row is an app plugin: it lives in the app's `extensions/` and loads from there, so the Blueprint does not compose it.
9
+ * Blueprint -> manifest what `acryl new` writes.
10
+ *
11
+ * @module @acryldev/harness-runtime/blueprint/manifest
12
+ */
13
+
14
+ import { validateDefinition } from '@acryldev/blends-core'
15
+ import { brandIdentity, type BrandIdentity } from './brand-identity.ts'
16
+ import { builtInCatalog, type Blueprint, type BlueprintCatalog, type BlueprintRowId } from './blueprint.ts'
17
+ import { blueprintRowForModule, rowForBlueprintRow } from './compose.ts'
18
+ import { InvalidBlueprintError } from './definition.ts'
19
+
20
+ export const BLENDS_API_VERSION = 'blends.acryl.dev/v1alpha1'
21
+ export const BRAND_PACKAGE = '@acryldev/brand'
22
+
23
+ const ID = /^[a-z][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)+$/u
24
+
25
+ interface ManifestRow {
26
+ readonly id: string
27
+ readonly name: string
28
+ readonly config?: Record<string, unknown>
29
+ readonly disabled?: boolean
30
+ }
31
+
32
+ export function isBlendsManifest(input: unknown): boolean {
33
+ return input !== null && typeof input === 'object' && (input as Record<string, unknown>).apiVersion === BLENDS_API_VERSION
34
+ }
35
+
36
+ function record(value: unknown, what: string): Record<string, unknown> {
37
+ if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new InvalidBlueprintError(`${what} must be an object`)
38
+ return value as Record<string, unknown>
39
+ }
40
+
41
+ function rowsOf(spec: Record<string, unknown>): readonly ManifestRow[] {
42
+ const rows = spec.rows
43
+ if (rows === undefined) return []
44
+ if (!Array.isArray(rows)) throw new InvalidBlueprintError('"spec.rows" must be a list')
45
+ return rows.map((row, index) => {
46
+ const entry = record(row, `spec.rows[${String(index)}]`)
47
+ if (typeof entry.id !== 'string' || typeof entry.name !== 'string') throw new InvalidBlueprintError(`spec.rows[${String(index)}] needs a string id and name`)
48
+ return entry as unknown as ManifestRow
49
+ })
50
+ }
51
+
52
+ /** Turn a parsed Blends manifest into the Blueprint this runtime boots. */
53
+ export function blueprintFromManifest(input: unknown, catalog: BlueprintCatalog = builtInCatalog()): Blueprint {
54
+ const document = record(input, 'the manifest')
55
+ if (document.apiVersion !== BLENDS_API_VERSION) throw new InvalidBlueprintError(`apiVersion must be ${BLENDS_API_VERSION}`)
56
+ // The format's own rules first (schema, row ids, lineage), from the format package; `distribution` also refuses executable `!!js` values in an app definition.
57
+ const problems = validateDefinition(input, 'distribution')
58
+ if (problems.length > 0) throw new InvalidBlueprintError(problems.map(problem => `${problem.path}: ${problem.message}`).join('; '))
59
+ const metadata = record(document.metadata, '"metadata"')
60
+ const spec = record(document.spec, '"spec"')
61
+ const id = metadata.id
62
+ if (typeof id !== 'string' || !ID.test(id)) throw new InvalidBlueprintError('"metadata.id" must be a dot-namespaced id such as acryl.blank.orbit')
63
+ const kind = document.kind
64
+ let base: Blueprint | undefined
65
+ if (kind === 'Blueprint') {
66
+ // A built-in Blueprint (the blank canvas), or a starter kit that extends one: accounting, sound stage, video editor...
67
+ // A starter resolves through its parent; only a Blueprint without `extends` is looked up by its own id (a built-in).
68
+ if (typeof spec.extends === 'string') {
69
+ base = catalog.get(spec.extends)
70
+ if (base === undefined) throw new InvalidBlueprintError(`"spec.extends" names ${JSON.stringify(spec.extends)}, which is not a known blueprint (a starter's parent must be built in or kept in the app's blueprints/ folder)`)
71
+ } else base = catalog.get(id)
72
+ } else if (kind === 'Blend') {
73
+ const lineage = record(spec.lineage, '"spec.lineage"')
74
+ if (typeof lineage.blueprint !== 'string') throw new InvalidBlueprintError('"spec.lineage.blueprint" is required for a Blend')
75
+ base = catalog.get(lineage.blueprint)
76
+ if (base === undefined) throw new InvalidBlueprintError(`"spec.lineage.blueprint" names ${JSON.stringify(lineage.blueprint)}, which is not a known blueprint (a project keeps the starter it grew from in its blueprints/ folder)`)
77
+ } else throw new InvalidBlueprintError('"kind" must be Blueprint or Blend')
78
+ if (base === undefined) throw new InvalidBlueprintError(`${JSON.stringify(id)} is not a known blueprint: a starter names its parent with spec.extends, a project names what it grew from with kind: Blend and spec.lineage`)
79
+
80
+ const rows = new Set<BlueprintRowId>(base.rows)
81
+ let brand: Blueprint['brand'] = base.brand
82
+ for (const row of rowsOf(spec)) {
83
+ if (row.name === BRAND_PACKAGE) {
84
+ brand = row.disabled === true ? { kind: 'acryl' } : { kind: 'custom', identity: brandIdentity(row.config ?? {}) }
85
+ continue
86
+ }
87
+ const known = blueprintRowForModule(row.name)
88
+ if (known === undefined) continue // an app plugin: loaded from the app's plugins/, not composed here
89
+ if (row.disabled === true) rows.delete(known)
90
+ else rows.add(known)
91
+ }
92
+ return Object.freeze({
93
+ ...base,
94
+ id,
95
+ name: typeof metadata.name === 'string' && metadata.name.trim() !== '' ? metadata.name.trim() : base.name,
96
+ description: typeof metadata.description === 'string' ? metadata.description : base.description,
97
+ rows: [...rows],
98
+ brand,
99
+ })
100
+ }
101
+
102
+ /** The manifest `acryl new` writes: a Blend grown from `blueprint`, carrying the brand as a row. */
103
+ export function appManifest(input: { id: string, name: string, blueprint: Blueprint, brand: BrandIdentity, description?: string }): Record<string, unknown> {
104
+ const brandRow = { id: 'brand', name: BRAND_PACKAGE, config: { ...input.brand } }
105
+ return {
106
+ apiVersion: BLENDS_API_VERSION,
107
+ kind: 'Blend',
108
+ // Private and proprietary until the owner says otherwise: saving refuses a public remote for a private app, and a registry refuses to list it.
109
+ metadata: { id: input.id, name: input.name, version: '0.1.0', description: input.description ?? `${input.name}, grown from ${input.blueprint.id}.`, license: 'Proprietary', visibility: 'private' },
110
+ spec: {
111
+ runtime: 'cordis',
112
+ lineage: { blueprint: input.blueprint.id, blueprintVersion: '0.1.0' },
113
+ rows: [brandRow, ...input.blueprint.rows.map(id => { const row = rowForBlueprintRow(id); return { id: row.rowId, name: row.module } })],
114
+ },
115
+ }
116
+ }
117
+
118
+ /**
119
+ * The Blueprints an app can grow from: the built-ins, plus the starter definitions it keeps in its `blueprints/` folder (`acryl new --from <starter>` copies
120
+ * the starter there, like a lock of the parent). A starter may extend another starter; each is resolved on first use, and a cycle is refused.
121
+ */
122
+ export function catalogWithStarters(starters: ReadonlyArray<{ readonly id: string, readonly document: unknown }>, base: BlueprintCatalog = builtInCatalog()): BlueprintCatalog {
123
+ const resolved = new Map<string, Blueprint>()
124
+ const resolving = new Set<string>()
125
+ const byId = new Map(starters.map(starter => [starter.id, starter.document]))
126
+ const catalog: BlueprintCatalog = {
127
+ get(id) {
128
+ const builtIn = base.get(id)
129
+ if (builtIn !== undefined) return builtIn
130
+ const cached = resolved.get(id)
131
+ if (cached !== undefined) return cached
132
+ const document = byId.get(id)
133
+ if (document === undefined) return undefined
134
+ if (resolving.has(id)) throw new InvalidBlueprintError(`the starters in blueprints/ extend each other in a cycle (${[...resolving, id].join(' -> ')})`)
135
+ resolving.add(id)
136
+ try {
137
+ const blueprint = blueprintFromManifest(document, catalog)
138
+ resolved.set(id, blueprint)
139
+ return blueprint
140
+ } finally { resolving.delete(id) }
141
+ },
142
+ list() { return [...base.list(), ...starters.map(starter => catalog.get(starter.id)).filter((entry): entry is Blueprint => entry !== undefined)] },
143
+ }
144
+ return catalog
145
+ }
@@ -0,0 +1,74 @@
1
+ /**
2
+ * The boundary that reads the environment to choose a Blueprint. Kept apart from the pure domain modules so the only
3
+ * `process.env` access in the blueprint context is in one named place.
4
+ *
5
+ * `ACRYL_BLUEPRINT` names a built-in Blueprint id (`acryl.blank`, `acryl.ide`) or a `.yaml`, `.yml` or `.json` file that defines one
6
+ * (see `definition.ts`); unset means `acryl.ide`.
7
+ * `ACRYL_BRAND_NAME` (and the other `ACRYL_BRAND_*` values) rebrand the selected Blueprint without editing any file.
8
+ *
9
+ * @module @acryldev/harness-runtime/blueprint/selection
10
+ */
11
+
12
+ import { existsSync, readFileSync, readdirSync } from 'node:fs'
13
+ import { dirname, extname, join } from 'node:path'
14
+ import { parse } from 'yaml'
15
+ import { brandIdentity } from './brand-identity.ts'
16
+ import { selectBlueprint, withBrand, type Blueprint } from './blueprint.ts'
17
+ import { InvalidBlueprintError, parseBlueprint } from './definition.ts'
18
+ import { blueprintFromManifest, catalogWithStarters, isBlendsManifest } from './manifest.ts'
19
+
20
+ const BRAND_ENV: readonly (readonly [string, string])[] = [
21
+ ['ACRYL_BRAND_NAME', 'name'],
22
+ ['ACRYL_BRAND_TAGLINE', 'tagline'],
23
+ ['ACRYL_BRAND_ACCENT', 'accent'],
24
+ ['ACRYL_BRAND_ACCENT_DARK', 'accentDark'],
25
+ ['ACRYL_BRAND_FONT', 'fontFamily'],
26
+ ['ACRYL_BRAND_MARK', 'mark'],
27
+ ]
28
+
29
+ const BLUEPRINT_FILE_EXTENSIONS = new Set(['.yaml', '.yml', '.json'])
30
+
31
+ /** Read and validate a Blueprint file. A missing or malformed file fails loudly: a silent fallback would boot the wrong product. */
32
+ export function readBlueprintFile(path: string): Blueprint {
33
+ let source: string
34
+ try {
35
+ source = readFileSync(path, 'utf8')
36
+ } catch (cause) {
37
+ throw new InvalidBlueprintError(`cannot read ${path}: ${cause instanceof Error ? cause.message : String(cause)}`)
38
+ }
39
+ let data: unknown
40
+ try {
41
+ data = parse(source)
42
+ } catch (cause) {
43
+ throw new InvalidBlueprintError(`${path} is not valid YAML: ${cause instanceof Error ? cause.message.split('\n')[0] : String(cause)}`)
44
+ }
45
+ // An app's `blend.yaml` is a Blends manifest (with the starters it grew from kept beside it in blueprints/); a short runtime definition is also accepted.
46
+ return isBlendsManifest(data) ? blueprintFromManifest(data, catalogWithStarters(readStarters(join(dirname(path), 'blueprints')))) : parseBlueprint(data)
47
+ }
48
+
49
+ /** The starter definitions an app keeps in its `blueprints/` folder, each a Blends manifest of kind Blueprint. */
50
+ export function readStarters(folder: string): Array<{ id: string, document: unknown }> {
51
+ if (!existsSync(folder)) return []
52
+ return readdirSync(folder).filter(file => /\.ya?ml$/u.test(file)).map(file => {
53
+ const path = join(folder, file)
54
+ let document: unknown
55
+ try { document = parse(readFileSync(path, 'utf8')) } catch (cause) { throw new InvalidBlueprintError(`${path} is not valid YAML: ${cause instanceof Error ? cause.message.split('\n')[0] : String(cause)}`) }
56
+ const id = (document as { metadata?: { id?: unknown } } | null)?.metadata?.id
57
+ if (typeof id !== 'string') throw new InvalidBlueprintError(`${path} has no metadata.id`)
58
+ return { id, document }
59
+ })
60
+ }
61
+
62
+ export function blueprintFromEnvironment(env: NodeJS.ProcessEnv = process.env): Blueprint {
63
+ const selected = env.ACRYL_BLUEPRINT?.trim()
64
+ const chosen = selected !== undefined && BLUEPRINT_FILE_EXTENSIONS.has(extname(selected).toLowerCase())
65
+ ? readBlueprintFile(selected)
66
+ : selectBlueprint(env.ACRYL_BLUEPRINT)
67
+ const overrides = Object.fromEntries(BRAND_ENV.flatMap(([variable, field]) => {
68
+ const value = env[variable]
69
+ return value === undefined || value === '' ? [] : [[field, value]]
70
+ }))
71
+ if (Object.keys(overrides).length === 0) return chosen
72
+ const base = chosen.brand.kind === 'custom' ? chosen.brand.identity : { name: chosen.name }
73
+ return withBrand(chosen, brandIdentity({ ...base, ...overrides }))
74
+ }
@@ -0,0 +1,181 @@
1
+ /**
2
+ * CLI/TUI's own `desktopProfiles`/`desktopPnpm` capabilities (spec 034,
3
+ * completing T006 for the third surface) - what `@acryldev/cordis-plugin-market`'s
4
+ * install service needs for a CLI-driven Market install/uninstall to do a
5
+ * real package operation, instead of the "ACRYL is required" gate it shows
6
+ * without them.
7
+ *
8
+ * Adapted directly from `web-market-install.ts` - see that file's own doc
9
+ * comment for why this is deliberately not a port of Desktop's much larger
10
+ * `pnpm.ts`/`install-recovery.ts` (a crash-recovery WAL built around
11
+ * Electron's own generation-restart cycle, which neither Web nor a CLI
12
+ * process has an equivalent of). The one real difference from Web: the CLI
13
+ * has more than one named profile (Web's is always `web`), so the profile
14
+ * name is a constructor parameter here, not a literal.
15
+ *
16
+ * Install mechanics reuse `dsh plugin --profile <name> add/remove`, the same
17
+ * path a human operator already uses - confirmed (like Web) to have no
18
+ * `--profile` restriction, unlike Desktop's packaged CLI.
19
+ */
20
+
21
+ import { spawn } from 'node:child_process'
22
+ import { createRequire } from 'node:module'
23
+ import { dirname, join } from 'node:path'
24
+ import { PassThrough, Readable } from 'node:stream'
25
+ import { type Context, Service } from '@deepseek-ai/cordis'
26
+ import { pinnedPnpmEnv } from './pinned-pnpm.ts'
27
+ import { reconcileProfileLayout, type PnpmProfileConfig } from './profile-layout.ts'
28
+
29
+ /** Matches `@acryldev/cordis-plugin-market`'s own `MarketDesktopProfile` shape. */
30
+ export interface CliMarketProfile {
31
+ readonly name: string
32
+ readonly dir: string
33
+ }
34
+
35
+ /** Matches `@acryldev/cordis-plugin-market`'s own `MarketDesktopPnpmOutcome` shape. */
36
+ export interface CliMarketPnpmOutcome {
37
+ readonly exitCode: number | null
38
+ readonly signal: NodeJS.Signals | null
39
+ }
40
+
41
+ /** Matches `@acryldev/cordis-plugin-market`'s own `MarketDesktopPnpmHandle` shape. */
42
+ export interface CliMarketPnpmHandle {
43
+ readonly stdout: Readable
44
+ readonly stderr: Readable
45
+ readonly done: Promise<CliMarketPnpmOutcome>
46
+ cancel(): void
47
+ }
48
+
49
+ // No `declare module '@deepseek-ai/cordis'` augmentation here - same reason
50
+ // as web-market-install.ts: acryl-desktop's own pnpm.ts/desktop-plugins.ts
51
+ // already declare these names on Context with their own, richer types, and
52
+ // `Service`'s constructor takes a plain string name, not `keyof Context`, so
53
+ // providing under these exact names needs no static declaration at all.
54
+
55
+ /** Matches `@acryldev/cordis-plugin-market`'s own `MarketDesktopPnpm` shape exactly. */
56
+ export interface CliMarketPnpm {
57
+ runPlugin(args: readonly string[], invokingDir: string, signal?: AbortSignal): CliMarketPnpmHandle
58
+ installPlugin(request: {
59
+ readonly pnpmOptions?: readonly string[]
60
+ readonly invokingDir: string
61
+ readonly recovery: { readonly packageName: string; readonly packageVersion: string; readonly receiptId: string }
62
+ readonly signal?: AbortSignal
63
+ }): Promise<CliMarketPnpmHandle>
64
+ recoveredInstallReceiptIds(): Promise<readonly string[]>
65
+ acknowledgeRecoveredInstall(receiptId: string): Promise<void>
66
+ rollbackPluginInstall(receiptId: string): Promise<boolean>
67
+ acknowledgeLiveInstall(packageName: string): Promise<void>
68
+ }
69
+
70
+ const require = createRequire(import.meta.url)
71
+
72
+ /** Absolute path to the pinned `@deepseek-ai/dsh` CLI's own compiled entry. */
73
+ function resolveDshBin(): string {
74
+ const manifestPath = require.resolve('@deepseek-ai/dsh/package.json')
75
+ return join(dirname(manifestPath), 'lib/bin.js')
76
+ }
77
+
78
+ /** The one profile this TUI process actually booted. */
79
+ export class CliProfilesService extends Service {
80
+ constructor(ctx: Context, private readonly profile: CliMarketProfile) {
81
+ super(ctx, 'desktopProfiles')
82
+ }
83
+
84
+ get current(): CliMarketProfile {
85
+ return this.profile
86
+ }
87
+ }
88
+
89
+ /**
90
+ * Runs `dsh plugin --profile <name> <verb> <...args>` as a real child
91
+ * process, inheriting this process's own `DSH_HOME` - `-w` included for
92
+ * pnpm's own workspace-root safety check on a profile's single-package pnpm
93
+ * workspace (identical reproduction to Web's and Desktop's own install path).
94
+ */
95
+ export class CliPnpmService extends Service implements CliMarketPnpm {
96
+ private readonly dshBin: string
97
+ private readonly profileName: string
98
+ private readonly profileDir: string
99
+
100
+ constructor(ctx: Context, config: PnpmProfileConfig) {
101
+ super(ctx, 'desktopPnpm')
102
+ this.profileName = config.name
103
+ this.profileDir = config.dir
104
+ this.dshBin = resolveDshBin()
105
+ }
106
+
107
+ runPlugin(args: readonly string[], _invokingDir: string, signal?: AbortSignal): CliMarketPnpmHandle {
108
+ // Never let a pnpm relink a profile another pnpm laid out (see profile-layout.ts).
109
+ reconcileProfileLayout(this.profileDir)
110
+ const child = spawn(process.execPath, [this.dshBin, 'plugin', '--profile', this.profileName, ...args, '-w'], {
111
+ // The pinned pnpm, not whatever the machine has on PATH (see pinned-pnpm.ts).
112
+ env: pinnedPnpmEnv(process.env),
113
+ signal,
114
+ })
115
+ const stdout = new PassThrough()
116
+ const stderr = new PassThrough()
117
+ child.stdout?.pipe(stdout)
118
+ child.stderr?.pipe(stderr)
119
+ // 'close', not 'exit': 'exit' can fire before the piped stdout/stderr
120
+ // have finished draining into `stdout`/`stderr` above, which raced a
121
+ // real caller reading `stderr` after `done` resolved - a fast failure
122
+ // (this profile's dsh wrapper prints one line and exits immediately)
123
+ // showed a near-empty stderr capture because the pipe hadn't flushed
124
+ // yet. 'close' is Node's own guarantee that both streams have ended.
125
+ const done = new Promise<CliMarketPnpmOutcome>((resolve, reject) => {
126
+ child.once('error', reject)
127
+ child.once('close', (exitCode, exitSignal) => resolve({ exitCode, signal: exitSignal }))
128
+ })
129
+ return {
130
+ stdout,
131
+ stderr,
132
+ done,
133
+ cancel: () => { child.kill() },
134
+ }
135
+ }
136
+
137
+ async installPlugin(request: {
138
+ readonly pnpmOptions?: readonly string[]
139
+ readonly invokingDir: string
140
+ readonly recovery: { readonly packageName: string; readonly packageVersion: string; readonly receiptId: string }
141
+ readonly signal?: AbortSignal
142
+ }): Promise<CliMarketPnpmHandle> {
143
+ const target = `${request.recovery.packageName}@${request.recovery.packageVersion}`
144
+ const options = request.pnpmOptions === undefined ? [] : [...request.pnpmOptions]
145
+ // A version of ACRYL's own tooling published minutes before an install
146
+ // attempt is the normal case here (Market installs are how a person
147
+ // actually picks up a just-published plugin), not the untrusted-fresh-
148
+ // package scenario pnpm's own `minimumReleaseAge` supply-chain default
149
+ // guards against - reproduced directly: a real install of a package
150
+ // this session had itself published minutes earlier failed with
151
+ // `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` on a pnpm whose default
152
+ // enables the policy. Overridden only for this one `add` invocation,
153
+ // not the user's global pnpm config, which stays untouched.
154
+ return this.runPlugin(['add', '--config.minimum-release-age=0', ...options, target], request.invokingDir, request.signal)
155
+ }
156
+
157
+ // No crash-recovery WAL (see this module's own doc comment) - there is
158
+ // never anything to report as recovered, acknowledge, or roll back.
159
+ async recoveredInstallReceiptIds(): Promise<readonly string[]> {
160
+ return []
161
+ }
162
+
163
+ async acknowledgeRecoveredInstall(_receiptId: string): Promise<void> {}
164
+
165
+ async rollbackPluginInstall(_receiptId: string): Promise<boolean> {
166
+ return false
167
+ }
168
+
169
+ async acknowledgeLiveInstall(_packageName: string): Promise<void> {}
170
+ }
171
+
172
+ /**
173
+ * Provide `desktopProfiles`/`desktopPnpm` on the host root for this CLI
174
+ * process's own booted profile.
175
+ * @param ctx - the host root.
176
+ * @param profile - the profile this TUI process actually composed.
177
+ */
178
+ export function provideCliMarketInstall(ctx: Context, profile: CliMarketProfile): void {
179
+ ctx.plugin(CliProfilesService, profile)
180
+ ctx.plugin(CliPnpmService, { name: profile.name, dir: profile.dir })
181
+ }
@@ -0,0 +1,176 @@
1
+ /**
2
+ * CLI/TUI's own `desktopPlugins` + `livePluginActivation` capabilities (spec
3
+ * 034, completing T006 for the third surface) - the package-name-shaped view
4
+ * `@acryldev/cordis-plugin-market`'s install service needs, plus real live activation
5
+ * so an install through the TUI's own `/plugins` command takes effect
6
+ * without restarting the process.
7
+ *
8
+ * Adapted directly from `web-market-plugins.ts` - not a new lifecycle
9
+ * implementation. It wraps the same shared `AcrPluginLifecycleController`
10
+ * (spec 034 T005) the CLI's own `acryl plugin enable/disable` and Desktop's
11
+ * Lifecycle tab already drive.
12
+ */
13
+
14
+ import { randomUUID } from 'node:crypto'
15
+ import { type Context, Service } from '@deepseek-ai/cordis'
16
+ import type { AcrPluginLifecycleController } from '@acryldev/control'
17
+ import {
18
+ mountAcrylPluginLifecycle,
19
+ type DshPluginLifecycleOptions,
20
+ } from './plugin-lifecycle.ts'
21
+
22
+ export interface CliMarketPluginBundle {
23
+ readonly bundleId: string
24
+ readonly packageName: string
25
+ readonly status: 'active' | 'disabled'
26
+ readonly mutable: boolean
27
+ }
28
+
29
+ interface PreviewEntry {
30
+ readonly entryId: string
31
+ readonly packageName: string
32
+ readonly targetEnabled: boolean
33
+ readonly expiresAt: number
34
+ }
35
+
36
+ // No `declare module '@deepseek-ai/cordis'` augmentation here - same reason
37
+ // as web-market-plugins.ts.
38
+
39
+ const PREVIEW_TTL_MS = 5 * 60 * 1000
40
+ const MAX_PREVIEWS = 256
41
+ /** Matches @acryldev/cordis-plugin-market's own PACKAGE_NAME_PATTERN. */
42
+ const NPM_PACKAGE_NAME_PATTERN = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u
43
+
44
+ /** Matches `@acryldev/cordis-plugin-market`'s own `MarketDesktopPlugins` shape exactly. */
45
+ export class CliPluginsService extends Service {
46
+ private readonly previews = new Map<string, PreviewEntry>()
47
+
48
+ private readonly controller: AcrPluginLifecycleController
49
+ private readonly profileName: string
50
+
51
+ constructor(ctx: Context, options: { readonly controller: AcrPluginLifecycleController; readonly profileName: string }) {
52
+ super(ctx, 'desktopPlugins')
53
+ this.controller = options.controller
54
+ this.profileName = options.profileName
55
+ }
56
+
57
+ list(): readonly CliMarketPluginBundle[] {
58
+ return this.controller.snapshot().entries
59
+ .filter(entry => NPM_PACKAGE_NAME_PATTERN.test(entry.moduleName))
60
+ .map(entry => ({
61
+ bundleId: entry.entryId,
62
+ packageName: entry.moduleName,
63
+ status: entry.enabled ? 'active' : 'disabled',
64
+ mutable: entry.mutable,
65
+ }))
66
+ }
67
+
68
+ disabledPackageNames(): readonly string[] {
69
+ return this.controller.snapshot().entries
70
+ .filter(entry => !entry.enabled && NPM_PACKAGE_NAME_PATTERN.test(entry.moduleName))
71
+ .map(entry => entry.moduleName)
72
+ }
73
+
74
+ isDisabled(packageName: string): boolean {
75
+ return this.disabledPackageNames().includes(packageName)
76
+ }
77
+
78
+ private mintPreview(bundleId: string, targetEnabled: boolean): { readonly previewId: string; readonly profileName: string; readonly packageName: string; readonly expiresAt: string } {
79
+ const entry = this.controller.snapshot().entries.find(candidate => candidate.entryId === bundleId)
80
+ if (entry === undefined) throw new Error(`cli plugins: no such bundle ${JSON.stringify(bundleId)}`)
81
+ if (!entry.mutable) throw new Error(`cli plugins: bundle ${JSON.stringify(bundleId)} is not user-mutable`)
82
+ const expectedCurrent = !targetEnabled
83
+ if (entry.enabled !== expectedCurrent) {
84
+ throw new Error(`cli plugins: bundle ${JSON.stringify(bundleId)} is already ${entry.enabled ? 'enabled' : 'disabled'}`)
85
+ }
86
+ if (this.previews.size >= MAX_PREVIEWS) {
87
+ const oldest = this.previews.keys().next().value
88
+ if (oldest !== undefined) this.previews.delete(oldest)
89
+ }
90
+ const previewId = randomUUID()
91
+ const expiresAt = Date.now() + PREVIEW_TTL_MS
92
+ this.previews.set(previewId, { entryId: bundleId, packageName: entry.moduleName, targetEnabled, expiresAt })
93
+ return { previewId, profileName: this.profileName, packageName: entry.moduleName, expiresAt: new Date(expiresAt).toISOString() }
94
+ }
95
+
96
+ previewDisable(bundleId: string) {
97
+ return this.mintPreview(bundleId, false)
98
+ }
99
+
100
+ previewEnable(bundleId: string) {
101
+ return this.mintPreview(bundleId, true)
102
+ }
103
+
104
+ // Same reasoning as WebPluginsService.execute() (web-market-plugins.ts):
105
+ // `controller.setEnabled()` applies live via Cordis' reactive Loader before
106
+ // resolving, so a resolved call always means `live: true`. Omitting this
107
+ // field left `MarketDesktopPlugins.executeEnable/executeDisable`'s
108
+ // `restartRequired` computation (@acryldev/cordis-plugin-market/src/host/routes.ts)
109
+ // permanently `true` for CLI too - same copy-pasted gap as Web had.
110
+ private async execute(previewId: string, targetEnabled: boolean): Promise<{ readonly packageName: string; readonly live: boolean }> {
111
+ const preview = this.previews.get(previewId)
112
+ if (preview === undefined || preview.targetEnabled !== targetEnabled) {
113
+ throw new Error('cli plugins: preview not found or expired')
114
+ }
115
+ this.previews.delete(previewId)
116
+ if (Date.now() > preview.expiresAt) throw new Error('cli plugins: preview expired')
117
+ await this.controller.setEnabled(preview.entryId, targetEnabled)
118
+ return { packageName: preview.packageName, live: true }
119
+ }
120
+
121
+ executeDisable(previewId: string): Promise<{ readonly packageName: string; readonly live: boolean }> {
122
+ return this.execute(previewId, false)
123
+ }
124
+
125
+ executeEnable(previewId: string): Promise<{ readonly packageName: string; readonly live: boolean }> {
126
+ return this.execute(previewId, true)
127
+ }
128
+ }
129
+
130
+ /**
131
+ * Live activation for a CLI/TUI process - the same shared
132
+ * `AcrPluginLifecycleController` Web and Desktop already drive, mounting a
133
+ * just-installed package into the live Loader tree without a process
134
+ * restart. The TUI's own `/plugins` command calls this directly after a
135
+ * successful install and then refreshes its own dynamic slash-command list
136
+ * (spec 034 T009) - there is no separate renderer process to reload here,
137
+ * unlike Web's `location.reload()` or Desktop's Client webContents reload.
138
+ */
139
+ export class CliLiveActivationService extends Service {
140
+ constructor(ctx: Context, private readonly controller: AcrPluginLifecycleController) {
141
+ super(ctx, 'livePluginActivation')
142
+ }
143
+
144
+ async activate(packageName: string): Promise<void> {
145
+ await this.controller.activate(packageName)
146
+ }
147
+
148
+ async deactivate(packageName: string): Promise<void> {
149
+ await this.controller.deactivate(packageName)
150
+ }
151
+
152
+ requireModules(owner: string, modules: readonly string[]): Promise<void> {
153
+ return this.controller.requireModules(owner, modules)
154
+ }
155
+
156
+ setEnabled(packageName: string, enabled: boolean): Promise<boolean> {
157
+ return this.controller.setEnabledByPackageName(packageName, enabled)
158
+ }
159
+
160
+ statusOf(packageName: string): 'active' | 'disabled' | undefined {
161
+ return this.controller.statusOfPackage(packageName)
162
+ }
163
+ }
164
+
165
+ /**
166
+ * Mount the shared plugin lifecycle for this CLI process and provide the
167
+ * market-shaped view over it, plus live activation.
168
+ * @param ctx - the host root.
169
+ * @param options - the same options shape the CLI's own `plugin-command.ts` already builds.
170
+ */
171
+ export function provideCliMarketPlugins(ctx: Context, options: DshPluginLifecycleOptions): AcrPluginLifecycleController {
172
+ const lifecycle = mountAcrylPluginLifecycle(ctx, options)
173
+ ctx.plugin(CliPluginsService, { controller: lifecycle.controller, profileName: options.profileName })
174
+ ctx.plugin(CliLiveActivationService, lifecycle.controller)
175
+ return lifecycle.controller
176
+ }
@@ -0,0 +1,61 @@
1
+ /**
2
+ * The Blueprint vocabulary of ACRYL's coding capabilities: which capability ids exist, which product surfaces each one declares itself for,
3
+ * and which of them need the framework router. Blueprint parsing and the built-in IDE Blueprint are runtime domain and read this table.
4
+ *
5
+ * How a capability composes on a surface (its Loader rows, the packages the surface must make resolvable, the shell-mode split) lives in
6
+ * `@acryldev/coding-capabilities`, which the surfaces compose from: the runtime decides what a Blueprint may name, the surface decides what
7
+ * runs. The two tables must name the same ids; the composition package's test asserts it both ways (spec 051 T021).
8
+ *
9
+ * @module @acryldev/harness-runtime/coding-capabilities
10
+ */
11
+
12
+ export type AcrylSurface = 'tui' | 'web' | 'desktop'
13
+
14
+ export type AcrylCodingCapabilityId =
15
+ | 'persona'
16
+ | 'agent-roster'
17
+ | 'session-stats'
18
+ | 'authorization'
19
+ | 'acryl-settings'
20
+ | 'workspace'
21
+ | 'plugin-admin'
22
+ | 'sign-in'
23
+ | 'launcher-screen'
24
+ | 'account-callback'
25
+ | 'support'
26
+ | 'agent-control-ui'
27
+ | 'advanced-shell'
28
+
29
+ /**
30
+ * The shell a surface renders the coding UI in. `advanced` replaces the stock DSH frame with the ACRYL
31
+ * shell (Projects list, tabbed canvas, right panel); `compatibility` keeps the stock frame. Desktop lets
32
+ * the user choose; Web always runs `advanced`, so both surfaces share one workspace.
33
+ */
34
+ export type AcrylShellMode = 'compatibility' | 'advanced'
35
+
36
+ /** One capability as a Blueprint names it. Its composition (rows and packages) is `@acryldev/coding-capabilities`'. */
37
+ export interface AcrylCodingCapabilityDeclaration {
38
+ readonly id: AcrylCodingCapabilityId
39
+ /**
40
+ * The capability serves its HTTP through the framework's router (`ctx.router`, `ctx.routerHttp`), which the `framework-kit` row brings.
41
+ * Without that row its plugin waits PENDING with nothing said, so a Blueprint that composes it must also compose the kit.
42
+ */
43
+ readonly needsRouter?: boolean
44
+ }
45
+
46
+ /** Every capability a Blueprint may name, and which of them need the framework router. */
47
+ export const ACRYL_CODING_CAPABILITIES: readonly AcrylCodingCapabilityDeclaration[] = [
48
+ { id: 'persona' },
49
+ { id: 'agent-roster' },
50
+ { id: 'session-stats' },
51
+ { id: 'authorization' },
52
+ { id: 'acryl-settings' },
53
+ { id: 'workspace', needsRouter: true },
54
+ { id: 'plugin-admin', needsRouter: true },
55
+ { id: 'sign-in', needsRouter: true },
56
+ { id: 'launcher-screen', needsRouter: true },
57
+ { id: 'account-callback' },
58
+ { id: 'support', needsRouter: true },
59
+ { id: 'agent-control-ui', needsRouter: true },
60
+ { id: 'advanced-shell' },
61
+ ]