@acryldev/harness-runtime 0.0.0-stage → 0.2.11

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/lib/index.mjs +5693 -0
  3. package/lib/index.mjs.map +1 -0
  4. package/lib/types/acryl-home.d.ts +81 -0
  5. package/lib/types/app/new-app.d.ts +65 -0
  6. package/lib/types/app/start-source.d.ts +47 -0
  7. package/lib/types/blueprint/blueprint.d.ts +74 -0
  8. package/lib/types/blueprint/brand-identity.d.ts +26 -0
  9. package/lib/types/blueprint/compose.d.ts +53 -0
  10. package/lib/types/blueprint/definition.d.ts +22 -0
  11. package/lib/types/blueprint/index.d.ts +7 -0
  12. package/lib/types/blueprint/manifest.d.ts +35 -0
  13. package/lib/types/blueprint/selection.d.ts +19 -0
  14. package/lib/types/cli-market-install.d.ts +97 -0
  15. package/lib/types/cli-market-plugins.d.ts +81 -0
  16. package/lib/types/coding-capabilities.d.ts +29 -0
  17. package/lib/types/durable-message.d.ts +18 -0
  18. package/lib/types/engine-dsh.d.ts +181 -0
  19. package/lib/types/engine-files.d.ts +8 -0
  20. package/lib/types/engine-host.d.ts +32 -0
  21. package/lib/types/engine-tools.d.ts +11 -0
  22. package/lib/types/index.d.ts +67 -0
  23. package/lib/types/instance/announce-self.d.ts +38 -0
  24. package/lib/types/instance/app-instance.d.ts +125 -0
  25. package/lib/types/instance/index.d.ts +6 -0
  26. package/lib/types/instance/offline-lock.d.ts +29 -0
  27. package/lib/types/instance/online-secret.d.ts +29 -0
  28. package/lib/types/instance/registry.d.ts +26 -0
  29. package/lib/types/instance/select.d.ts +43 -0
  30. package/lib/types/module-hooks.d.ts +19 -0
  31. package/lib/types/module-resolution.d.ts +31 -0
  32. package/lib/types/package-overlay.d.ts +41 -0
  33. package/lib/types/pinned-pnpm.d.ts +15 -0
  34. package/lib/types/plugin-acryl-workspace-status.d.ts +24 -0
  35. package/lib/types/plugin-doctor.d.ts +49 -0
  36. package/lib/types/plugin-lifecycle-state.d.ts +92 -0
  37. package/lib/types/plugin-lifecycle.d.ts +87 -0
  38. package/lib/types/profile-layout.d.ts +17 -0
  39. package/lib/types/profile-owner.d.ts +25 -0
  40. package/lib/types/profile-repair/backup.d.ts +37 -0
  41. package/lib/types/profile-repair/findings.d.ts +29 -0
  42. package/lib/types/profile-repair/index.d.ts +9 -0
  43. package/lib/types/profile-repair/inspector.d.ts +11 -0
  44. package/lib/types/profile-repair/repair.d.ts +38 -0
  45. package/lib/types/profile-resolution/moved-framework.d.ts +21 -0
  46. package/lib/types/profile-resolution/resolver.d.ts +41 -0
  47. package/lib/types/profile-resolution/service.d.ts +22 -0
  48. package/lib/types/prompt-budget.d.ts +44 -0
  49. package/lib/types/session-bridge.d.ts +57 -0
  50. package/lib/types/session-log-exporter.d.ts +31 -0
  51. package/lib/types/system-prompt-capture.d.ts +29 -0
  52. package/lib/types/web-favicon-data.d.ts +5 -0
  53. package/lib/types/web-favicon.d.ts +23 -0
  54. package/lib/types/web-market-install.d.ts +114 -0
  55. package/lib/types/web-market-plugins.d.ts +106 -0
  56. package/lib/types/web-port.d.ts +15 -0
  57. package/package.json +211 -3
  58. package/src/acryl-home.ts +103 -0
  59. package/src/app/new-app.ts +239 -0
  60. package/src/app/start-source.ts +110 -0
  61. package/src/blueprint/blueprint.ts +141 -0
  62. package/src/blueprint/brand-identity.ts +75 -0
  63. package/src/blueprint/compose.ts +222 -0
  64. package/src/blueprint/definition.ts +92 -0
  65. package/src/blueprint/index.ts +20 -0
  66. package/src/blueprint/manifest.ts +145 -0
  67. package/src/blueprint/selection.ts +74 -0
  68. package/src/cli-market-install.ts +181 -0
  69. package/src/cli-market-plugins.ts +176 -0
  70. package/src/coding-capabilities.ts +61 -0
  71. package/src/durable-message.ts +23 -0
  72. package/src/engine-dsh.ts +856 -0
  73. package/src/engine-files.ts +9 -0
  74. package/src/engine-host.ts +128 -0
  75. package/src/engine-tools.ts +26 -0
  76. package/src/index.ts +436 -0
  77. package/src/instance/announce-self.ts +88 -0
  78. package/src/instance/app-instance.ts +240 -0
  79. package/src/instance/index.ts +45 -0
  80. package/src/instance/offline-lock.ts +71 -0
  81. package/src/instance/online-secret.ts +55 -0
  82. package/src/instance/registry.ts +53 -0
  83. package/src/instance/select.ts +134 -0
  84. package/src/module-hooks.ts +41 -0
  85. package/src/module-resolution.ts +187 -0
  86. package/src/package-overlay.ts +160 -0
  87. package/src/pinned-pnpm.ts +67 -0
  88. package/src/plugin-acryl-workspace-status.ts +99 -0
  89. package/src/plugin-doctor.ts +141 -0
  90. package/src/plugin-lifecycle-state.ts +347 -0
  91. package/src/plugin-lifecycle.ts +223 -0
  92. package/src/profile-layout.ts +97 -0
  93. package/src/profile-owner.ts +52 -0
  94. package/src/profile-repair/backup.ts +119 -0
  95. package/src/profile-repair/findings.ts +43 -0
  96. package/src/profile-repair/index.ts +10 -0
  97. package/src/profile-repair/inspector.ts +156 -0
  98. package/src/profile-repair/repair.ts +137 -0
  99. package/src/profile-resolution/moved-framework.ts +64 -0
  100. package/src/profile-resolution/resolver.ts +876 -0
  101. package/src/profile-resolution/service.ts +99 -0
  102. package/src/prompt-budget.ts +118 -0
  103. package/src/session-bridge.ts +350 -0
  104. package/src/session-log-exporter.ts +68 -0
  105. package/src/system-prompt-capture.ts +99 -0
  106. package/src/web-favicon-data.ts +6 -0
  107. package/src/web-favicon.ts +43 -0
  108. package/src/web-market-install.ts +206 -0
  109. package/src/web-market-plugins.ts +215 -0
  110. package/src/web-port.ts +39 -0
  111. package/tests/account-callback.spec.ts +173 -0
  112. package/tests/acryl-home.spec.ts +39 -0
  113. package/tests/agent-self-hosting.spec.ts +101 -0
  114. package/tests/announce-self.spec.ts +84 -0
  115. package/tests/app-lifecycle.spec.ts +99 -0
  116. package/tests/blank-blueprint.spec.ts +110 -0
  117. package/tests/blueprint-definition.spec.ts +128 -0
  118. package/tests/blueprint.spec.ts +138 -0
  119. package/tests/bulkhead.spec.ts +187 -0
  120. package/tests/coding-vocabulary.spec.ts +15 -0
  121. package/tests/dump-system-prompt.spec.ts +65 -0
  122. package/tests/e2e-real-model.spec.ts +71 -0
  123. package/tests/e2e-restart-real-model.spec.ts +77 -0
  124. package/tests/engine-dsh.spec.ts +340 -0
  125. package/tests/engine-host-mount-root-include.spec.ts +118 -0
  126. package/tests/engine-host.spec.ts +176 -0
  127. package/tests/engine-optional.spec.ts +81 -0
  128. package/tests/extension-examples.spec.ts +261 -0
  129. package/tests/hooks-thread-stack.ts +27 -0
  130. package/tests/instance-patches.spec.ts +25 -0
  131. package/tests/instance.spec.ts +235 -0
  132. package/tests/live/community-plugins.spec.ts +83 -0
  133. package/tests/module-hooks.spec.ts +35 -0
  134. package/tests/module-resolution.spec.ts +265 -0
  135. package/tests/moved-framework.spec.ts +61 -0
  136. package/tests/new-app.spec.ts +132 -0
  137. package/tests/organizer-growth.spec.ts +117 -0
  138. package/tests/pinned-pnpm.spec.ts +34 -0
  139. package/tests/plugin-acryl-workspace-status.spec.ts +63 -0
  140. package/tests/plugin-context.spec.ts +640 -0
  141. package/tests/plugin-doctor.spec.ts +183 -0
  142. package/tests/plugin-enablement-one-store.spec.ts +130 -0
  143. package/tests/plugin-lifecycle-state.spec.ts +169 -0
  144. package/tests/profile-layout.spec.ts +58 -0
  145. package/tests/profile-owner.spec.ts +38 -0
  146. package/tests/profile-repair/profile-repair.spec.ts +231 -0
  147. package/tests/profile-resolution-port.spec.ts +30 -0
  148. package/tests/profile-resolution-service.spec.ts +273 -0
  149. package/tests/profile-resolution-swap.spec.ts +69 -0
  150. package/tests/profile-resolution.spec.ts +2535 -0
  151. package/tests/profile.spec.ts +70 -0
  152. package/tests/project-registry.spec.ts +81 -0
  153. package/tests/prompt-budget.spec.ts +58 -0
  154. package/tests/real-home-guard.spec.ts +178 -0
  155. package/tests/session-bridge.spec.ts +316 -0
  156. package/tests/start-source.spec.ts +65 -0
  157. package/tests/system-prompt-shape.spec.ts +95 -0
  158. package/tests/three-levels.spec.ts +84 -0
  159. package/tests/tool-gateway.spec.ts +116 -0
  160. package/tests/tool-schemas.spec.ts +41 -0
  161. package/tests/web-favicon.spec.ts +42 -0
  162. package/tests/web-port.spec.ts +38 -0
  163. package/tests/web-startup-hold.spec.ts +79 -0
  164. package/tsconfig.json +24 -0
  165. package/tsdown.config.ts +2 -0
  166. package/vitest.config.ts +18 -0
  167. package/README.md +0 -3
@@ -0,0 +1,116 @@
1
+ /**
2
+ * The tool gateway (T051) on the real web engine, the real tool registry and the real ACRYL extension tools. What this pins:
3
+ * the gateway offers only the allowlisted extension tools with their real JSON Schemas; a call through it runs the tool; and the instance
4
+ * secret authenticates the caller but does not bypass per-tool policy: a `tools/pre-execute` policy that denies a tool denies it for a gateway
5
+ * caller exactly as for the DSH chat (the call goes through the registry's own `execute`, so every hook in the pipeline runs). The REST and
6
+ * MCP faces share one gateway, so each is checked against the same policy.
7
+ */
8
+ import { existsSync, readFileSync, mkdtempSync } from 'node:fs'
9
+ import { mkdtemp, rm } from 'node:fs/promises'
10
+ import { tmpdir } from 'node:os'
11
+ import { join } from 'node:path'
12
+ import { provideCmdline } from '@deepseek-ai/dsh-cmdline'
13
+ import { afterEach, describe, expect, it } from 'vitest'
14
+ import { createWebEngineDefinition } from '../src/engine-dsh.ts'
15
+ import { createAcrylEngineHost } from '../src/engine-host.ts'
16
+ import { fileURLToPath } from 'node:url'
17
+ import { codingCapabilities } from '@acryldev/coding-capabilities'
18
+
19
+ const initialDshHome = process.env.DSH_HOME
20
+ const folders: string[] = []
21
+ afterEach(async () => {
22
+ if (initialDshHome === undefined) delete process.env.DSH_HOME
23
+ else process.env.DSH_HOME = initialDshHome
24
+ await Promise.all(folders.splice(0).map(folder => rm(folder, { force: true, recursive: true })))
25
+ })
26
+
27
+ type Host = Awaited<ReturnType<typeof createAcrylEngineHost>>
28
+
29
+ async function boot(): Promise<{ host: Host, origin: string, secret: string }> {
30
+ const home = await mkdtemp(join(tmpdir(), 'acryl-gateway-'))
31
+ folders.push(home)
32
+ process.env.DSH_HOME = home
33
+ const host = await createAcrylEngineHost({
34
+ engines: [createWebEngineDefinition(new URL('../package.json', import.meta.url).href, codingCapabilities)],
35
+ initialEngine: 'dsh',
36
+ prepare: ctx => { provideCmdline(ctx, { args: ['--no-open', '--port', '0'], exit: () => {} }) },
37
+ })
38
+ for (const entry of host.ctx.loader.entries()) {
39
+ if (entry.options.id === '@acryldev/agent-control') entry.update({ config: { online: true, approval: 'none' } })
40
+ }
41
+ await host.ctx.loader.await()
42
+ await new Promise(resolve => setTimeout(resolve, 300))
43
+ const web = host.ctx.get('webServer' as never) as { port: number }
44
+ const secretFile = join(home, 'agent-control-secret')
45
+ const alt = join(home, '.dsh', 'agent-control-secret')
46
+ const path = existsSync(secretFile) ? secretFile : alt
47
+ return { host, origin: `http://127.0.0.1:${String(web.port)}`, secret: readFileSync(path, 'utf8').trim() }
48
+ }
49
+
50
+ async function post(url: string, secret: string, body: unknown): Promise<{ status: number, json: any }> {
51
+ const response = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${secret}` }, body: JSON.stringify(body) })
52
+ return { status: response.status, json: await response.json() }
53
+ }
54
+
55
+ describe('the tool gateway on the real engine', () => {
56
+ it('offers the real extension tools with their schemas, runs one, and refuses everything outside the allowlist', async () => {
57
+ const { host, origin, secret } = await boot()
58
+ try {
59
+ const listed = await (await fetch(`${origin}/api/acryl-agent-control/online/tools`, { headers: { authorization: `Bearer ${secret}` } })).json() as { tools: Array<{ name: string, inputSchema: any }> }
60
+ const names = listed.tools.map(tool => tool.name)
61
+ expect(names).toEqual(expect.arrayContaining(['acryl_plugin_lookup', 'acryl_verify_plugin', 'acryl_install_plugin', 'acryl_list_plugins', 'acryl_remove_plugin']))
62
+ expect(names).not.toContain('bash')
63
+ expect(listed.tools.find(tool => tool.name === 'acryl_install_plugin')?.inputSchema).toMatchObject({ type: 'object', required: ['path'] })
64
+
65
+ expect((await post(`${origin}/api/acryl-agent-control/online/tools`, secret, { name: 'acryl_list_plugins', arguments: {} })).json).toMatchObject({ ok: true, isError: false })
66
+ expect((await post(`${origin}/api/acryl-agent-control/online/tools`, secret, { name: 'bash', arguments: { command: 'id' } })).json).toMatchObject({ ok: false, code: 'not-exposed' })
67
+ expect((await post(`${origin}/api/acryl-agent-control/online/tools`, 'wrong-secret', { name: 'acryl_list_plugins' })).status).toBe(403)
68
+ } finally { await host.dispose() }
69
+ }, 120_000)
70
+
71
+ it('does not let the secret bypass tool policy: a denying pre-execute policy denies a gateway call, over REST and over MCP', async () => {
72
+ const { host, origin, secret } = await boot()
73
+ const seen: string[] = []
74
+ const dispose = host.ctx.on('tools/pre-execute', async (exec: { name: string }, next: () => Promise<unknown>) => {
75
+ seen.push(exec.name)
76
+ if (exec.name === 'acryl_remove_plugin') return { kind: 'deny', reason: 'removal is blocked by test policy' }
77
+ return next()
78
+ })
79
+ try {
80
+ const rest = await post(`${origin}/api/acryl-agent-control/online/tools`, secret, { name: 'acryl_remove_plugin', arguments: { package: 'anything' } })
81
+ expect(rest.json).toMatchObject({ ok: true, isError: true })
82
+ expect(rest.json.text).toContain('removal is blocked by test policy')
83
+
84
+ const mcp = await post(`${origin}/api/acryl-agent-control/mcp`, secret, { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'acryl_remove_plugin', arguments: { package: 'anything' } } })
85
+ expect(mcp.json.result).toMatchObject({ isError: true })
86
+ expect(JSON.stringify(mcp.json.result.content)).toContain('removal is blocked by test policy')
87
+
88
+ // The policy saw both calls (so the pipeline ran), and an un-denied tool through the same path still works.
89
+ expect(seen.filter(name => name === 'acryl_remove_plugin')).toHaveLength(2)
90
+ expect((await post(`${origin}/api/acryl-agent-control/online/tools`, secret, { name: 'acryl_list_plugins', arguments: {} })).json).toMatchObject({ ok: true, isError: false })
91
+ expect(seen).toContain('acryl_list_plugins')
92
+ } finally { dispose(); await host.dispose() }
93
+ }, 120_000)
94
+
95
+ it('installs and removes a plugin an outside agent wrote, over MCP, through the same pipeline', async () => {
96
+ const { host, origin, secret } = await boot()
97
+ const { cpSync, writeFileSync } = await import('node:fs')
98
+ const example = fileURLToPath(new URL('../../../plugins/plugin-context/example-plugins/packages/tool-basic/', import.meta.url))
99
+ const dir = mkdtempSync(join(tmpdir(), 'acryl-gateway-plugin-'))
100
+ folders.push(dir)
101
+ cpSync(example, dir, { recursive: true })
102
+ const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as Record<string, unknown>
103
+ writeFileSync(join(dir, 'package.json'), JSON.stringify({ ...manifest, name: 'acryl-gateway-probe' }))
104
+ writeFileSync(join(dir, 'cordis.patch.yml'), readFileSync(join(dir, 'cordis.patch.yml'), 'utf8').replaceAll('acryl-example-tool', 'acryl-gateway-probe').replaceAll('example-tool', 'gateway-probe'))
105
+ writeFileSync(join(dir, 'index.js'), readFileSync(join(dir, 'index.js'), 'utf8').replace("'acryl-example-tool'", "'acryl-gateway-probe'").replace("name: 'example_echo'", "name: 'gateway_probe'"))
106
+ try {
107
+ const call = (id: number, name: string, args: unknown) => post(`${origin}/api/acryl-agent-control/mcp`, secret, { jsonrpc: '2.0', id, method: 'tools/call', params: { name, arguments: args } })
108
+ expect((await call(1, 'acryl_verify_plugin', { path: dir })).json.result.isError).toBe(false)
109
+ expect((await call(2, 'acryl_install_plugin', { path: dir })).json.result.isError).toBe(false)
110
+ expect(host.ctx.get('tools' as never) && (host.ctx.get('tools' as never) as { get(n: string): unknown }).get('gateway_probe')).toBeDefined()
111
+ expect((await call(3, 'acryl_list_plugins', {})).json.result.content[0].text).toContain('acryl-gateway-probe')
112
+ expect((await call(4, 'acryl_remove_plugin', { package: 'acryl-gateway-probe' })).json.result.isError).toBe(false)
113
+ expect((host.ctx.get('tools' as never) as { get(n: string): unknown }).get('gateway_probe')).toBeUndefined()
114
+ } finally { await host.dispose() }
115
+ }, 240_000)
116
+ })
@@ -0,0 +1,41 @@
1
+ /**
2
+ * ACRYL's typed agent tools compile with DSH's own tool compiler. A plugin's own tests register its tools on a fake port that accepts any
3
+ * schema; DSH 0.2 rejects some (an object without an explicit `additionalProperties`), and that surfaced only at boot, as a tool the agent
4
+ * never saw (spec 043 T007, 2026-10-12).
5
+ */
6
+ import type { Context } from '@deepseek-ai/cordis'
7
+ import { defineTool } from '@deepseek-ai/dsh-tools'
8
+ import { registerPluginTools } from '@acryldev/plugin-admin'
9
+ import { registerContextTool, registerWorkspaceTools } from '@acryldev/workspace'
10
+ import { describe, expect, it } from 'vitest'
11
+
12
+ function portThroughDshCompiler(): { ctx: Context, names: string[] } {
13
+ const names: string[] = []
14
+ const ctx = {
15
+ acrylTools: {
16
+ register: (definition: { name: string }) => { defineTool(definition as never); names.push(definition.name); return () => {} },
17
+ policy: () => () => {},
18
+ },
19
+ } as unknown as Context
20
+ return { ctx, names }
21
+ }
22
+
23
+ describe('ACRYL agent tools compile with DSH', () => {
24
+ it('the workspace tools', () => {
25
+ const { ctx, names } = portThroughDshCompiler()
26
+ registerWorkspaceTools(ctx, {} as never)
27
+ expect(names).toEqual(['acryl_workspace_list', 'acryl_workspace_switch', 'acryl_workspace_create', 'acryl_workspace_add_project'])
28
+ })
29
+
30
+ it('the workspace context tool', () => {
31
+ const { ctx, names } = portThroughDshCompiler()
32
+ registerContextTool(ctx, {} as never)
33
+ expect(names).toEqual(['acryl_workspace_context'])
34
+ })
35
+
36
+ it('the plugin tools', () => {
37
+ const { ctx, names } = portThroughDshCompiler()
38
+ registerPluginTools(ctx, {} as never)
39
+ expect(names).toEqual(['acryl_plugin_list', 'acryl_plugin_set_enabled'])
40
+ })
41
+ })
@@ -0,0 +1,42 @@
1
+ import { describe, expect, it } from 'vitest'
2
+ import { applyWebFavicon, brandWebIndex, WEB_FAVICON_LINKS } from '../src/web-favicon.ts'
3
+
4
+ describe('applyWebFavicon', () => {
5
+ it('replaces the pinned frontend icon links with the ACRYL icon', () => {
6
+ const html = '<html><head><title>x</title><link rel="icon" href="/favicon.svg"><link rel="shortcut icon" href="/a.ico"></head><body></body></html>'
7
+ const out = applyWebFavicon(html)
8
+ expect(out).not.toContain('/favicon.svg')
9
+ expect(out).not.toContain('/a.ico')
10
+ expect(out.match(/rel="icon"/g)).toHaveLength(3)
11
+ expect(out.match(/rel="apple-touch-icon"/g)).toHaveLength(1)
12
+ expect(out).toContain(`${WEB_FAVICON_LINKS}</head>`)
13
+ })
14
+
15
+ it('leaves other links alone and works when there was no icon', () => {
16
+ const out = applyWebFavicon('<head><link rel="stylesheet" href="/s.css"></head>')
17
+ expect(out).toContain('rel="stylesheet"')
18
+ expect(out).toContain('data:image/x-icon;base64,')
19
+ })
20
+ })
21
+
22
+ describe('brandWebIndex', () => {
23
+ const index = '<html><head><title>DeepSeek Harness</title><link rel="icon" type="image/svg+xml" href="./favicon-dark.svg" media="(prefers-color-scheme: dark)" /></head></html>'
24
+
25
+ it('gives the stock ACRYL brand its title and its icon even though a product name is always set (the web face names it ACRYL)', () => {
26
+ const out = brandWebIndex(index, { productName: 'ACRYL', stockBrand: true })
27
+ expect(out).toContain('<title>ACRYL</title>')
28
+ expect(out).not.toContain('favicon-dark.svg')
29
+ expect(out).toContain(WEB_FAVICON_LINKS)
30
+ })
31
+
32
+ it('leaves a custom brand its own icon, and escapes its name in the title', () => {
33
+ const out = brandWebIndex(index, { productName: '<Shop>', stockBrand: false })
34
+ expect(out).toContain('<title>&#60;Shop&#62;</title>')
35
+ expect(out).toContain('favicon-dark.svg')
36
+ expect(out).not.toContain(WEB_FAVICON_LINKS)
37
+ })
38
+
39
+ it('treats a composition that names neither a product nor a brand kind as the stock one', () => {
40
+ expect(brandWebIndex(index, {})).toContain(WEB_FAVICON_LINKS)
41
+ })
42
+ })
@@ -0,0 +1,38 @@
1
+ import { describe, expect, it } from 'vitest'
2
+ import { createServer } from 'node:net'
3
+ import { WEB_PORT_ATTEMPTS, findFreeWebPort, loopbackPortIsFree, webPortPatch } from '../src/web-port.ts'
4
+
5
+ describe('finding a free port', () => {
6
+ it('moves the server on the loopback address only', () => {
7
+ expect(webPortPatch(3081)).toEqual({ id: 'webserver', config: { host: '127.0.0.1', port: 3081 } })
8
+ expect(webPortPatch(3080, '0.0.0.0')).toEqual({ id: 'webserver', config: { host: '0.0.0.0', port: 3080 } })
9
+ })
10
+
11
+ it('starts at the preferred port and moves up one at a time', async () => {
12
+ expect(await findFreeWebPort(3081, async () => true)).toBe(3081)
13
+ const taken = new Set([3081, 3082])
14
+ expect(await findFreeWebPort(3081, async port => !taken.has(port))).toBe(3083)
15
+ })
16
+
17
+ it('skips a port the Fetch standard blocks, so a browser and fetch can open the page', async () => {
18
+ expect(await findFreeWebPort(3659, async () => true)).toBe(3660)
19
+ expect(await findFreeWebPort(3658, async port => port !== 3658)).toBe(3660)
20
+ })
21
+
22
+ it('gives up with a message that says what to change, and never passes 65535', async () => {
23
+ await expect(findFreeWebPort(3081, async () => false)).rejects.toThrow(/ACRYL_WEB_PORT/)
24
+ expect(WEB_PORT_ATTEMPTS).toBeGreaterThan(1)
25
+ await expect(findFreeWebPort(65_535, async () => false)).rejects.toThrow(/65535/)
26
+ })
27
+
28
+ it('sees a real listener on the loopback port', async () => {
29
+ const server = createServer()
30
+ await new Promise<void>(resolve => server.listen({ host: '127.0.0.1', port: 0 }, resolve))
31
+ const { port } = server.address() as { port: number }
32
+ try {
33
+ expect(await loopbackPortIsFree(port)).toBe(false)
34
+ expect(await findFreeWebPort(port)).toBeGreaterThan(port)
35
+ } finally { await new Promise(resolve => server.close(resolve)) }
36
+ expect(await loopbackPortIsFree(port)).toBe(true)
37
+ })
38
+ })
@@ -0,0 +1,79 @@
1
+ /**
2
+ * A Web page opened while the startup pass installs an app's own plugins (specs/001 T097, on real engines): the index served before the pass
3
+ * settles lacks the app's client plugin, so it carries @acryldev/plugin-context's hold script, and the startup route answers once the pass
4
+ * settles (cookie and origin checked like the Host API); the index served after it has the plugin and no hold.
5
+ */
6
+ import { cpSync, realpathSync } from 'node:fs'
7
+ import { mkdtemp, rm } from 'node:fs/promises'
8
+ import { tmpdir } from 'node:os'
9
+ import { join } from 'node:path'
10
+ import { fileURLToPath } from 'node:url'
11
+ import { provideCmdline } from '@deepseek-ai/dsh-cmdline'
12
+ import { STARTUP_PATH } from '@acryldev/plugin-context'
13
+ import { afterEach, describe, expect, it } from 'vitest'
14
+ import { planNewApp, writeNewApp } from '../src/app/new-app.ts'
15
+ import { createWebEngineDefinition } from '../src/engine-dsh.ts'
16
+ import { createAcrylEngineHost } from '../src/engine-host.ts'
17
+ import { codingCapabilities } from '@acryldev/coding-capabilities'
18
+
19
+ const example = fileURLToPath(new URL('../../../plugins/plugin-context/example-plugins/packages/client-slot-header-action/', import.meta.url))
20
+ const PLUGIN = 'acryl-example-client-notes'
21
+ const saved = { ...process.env }
22
+ const temporary: string[] = []
23
+ afterEach(async () => {
24
+ for (const key of Object.keys(process.env)) if (!(key in saved)) delete process.env[key]
25
+ Object.assign(process.env, saved)
26
+ await Promise.all(temporary.splice(0).map(path => rm(path, { force: true, recursive: true })))
27
+ })
28
+
29
+ interface StartupReport { status: string, lines: string[] }
30
+
31
+ describe('the Web index during the startup pass', () => {
32
+ it('holds a page rendered before the app\'s plugins are installed and serves the full graph after', async () => {
33
+ const root = realpathSync(await mkdtemp(join(tmpdir(), 'acryl-web-hold-')))
34
+ temporary.push(root)
35
+ const app = join(root, 'headerapp')
36
+ writeNewApp(planNewApp(app, { title: 'Header App', launcher: '/framework/scripts/blank.mjs' }), { git: false })
37
+ cpSync(example, join(app, 'plugins', 'client-slot-header-action'), { recursive: true, filter: source => !source.includes('/tests') && !source.includes('node_modules') })
38
+ for (const key of ['DSH_HOME', 'ACRYL_WEB_PORT', 'ACRYL_WEB_HOST', 'ACRYL_WEB_TRUSTED_HOSTS', 'ACRYL_INSTANCE', 'ACRYL_LOCAL_PRODUCT_NAME', 'ACRYL_BLUEPRINT']) delete process.env[key]
39
+ process.env.ACRYL_HOME = app
40
+ const host = await createAcrylEngineHost({
41
+ engines: [createWebEngineDefinition(new URL('../package.json', import.meta.url).href, codingCapabilities)],
42
+ initialEngine: 'dsh',
43
+ prepare: ctx => { provideCmdline(ctx, { args: ['--no-open'], exit: () => {} }) },
44
+ })
45
+ try {
46
+ const ctx = host.ctx
47
+ const web = ctx.get('webServer' as never) as unknown as { host: string, port: number, renderIndex(html: string): string }
48
+ const connection = ctx.get('connection')!
49
+ const pluginContext = ctx.get('pluginContext' as never) as unknown as { startupSettled: Promise<StartupReport> }
50
+ const index = () => web.renderIndex('<html><head></head><body></body></html>')
51
+ const origin = `http://127.0.0.1:${String(web.port)}`
52
+
53
+ // The surface prints its URL here. The pass installs with pnpm, which takes seconds, so it has not settled yet.
54
+ const early = await Promise.race([pluginContext.startupSettled.then(() => 'settled'), Promise.resolve('running')])
55
+ expect(early, 'the startup pass settled before the surface served: this test cannot observe the window').toBe('running')
56
+ const before = index()
57
+ expect(before).not.toContain(PLUGIN)
58
+ expect(before).toContain(STARTUP_PATH)
59
+
60
+ // Unauthenticated, and authenticated but from another site: refused like the Host API.
61
+ expect((await fetch(`${origin}${STARTUP_PATH}`)).status).toBe(401)
62
+ const exchange = await fetch(connection.authenticatedUrl(origin), { redirect: 'manual' })
63
+ const cookie = (exchange.headers.get('set-cookie') ?? '').split(';')[0] ?? ''
64
+ expect(cookie).not.toBe('')
65
+ expect((await fetch(`${origin}${STARTUP_PATH}`, { headers: { cookie, 'sec-fetch-site': 'cross-site' } })).status).toBe(403)
66
+
67
+ // The held page's request answers 204 once the pass settles, and not before.
68
+ const held = fetch(`${origin}${STARTUP_PATH}`, { headers: { cookie, origin } })
69
+ const report = await pluginContext.startupSettled
70
+ expect(report).toEqual({ status: 'done', lines: [`installed the app's plugins ${PLUGIN}`] })
71
+ expect((await held).status).toBe(204)
72
+
73
+ // The reloaded page: the full graph, no hold.
74
+ const after = index()
75
+ expect(after).toContain(PLUGIN)
76
+ expect(after).not.toContain(STARTUP_PATH)
77
+ } finally { await host.dispose() }
78
+ }, 300_000)
79
+ })
package/tsconfig.json ADDED
@@ -0,0 +1,24 @@
1
+ {
2
+ "compilerOptions": {
3
+ "target": "ES2024",
4
+ "lib": ["ES2024"],
5
+ "module": "NodeNext",
6
+ "moduleResolution": "NodeNext",
7
+ "allowImportingTsExtensions": true,
8
+ "rootDir": "src",
9
+ "outDir": "lib/types",
10
+ "declaration": true,
11
+ "emitDeclarationOnly": true,
12
+ "esModuleInterop": true,
13
+ "strict": true,
14
+ "exactOptionalPropertyTypes": true,
15
+ "noFallthroughCasesInSwitch": true,
16
+ "noImplicitOverride": true,
17
+ "noUncheckedIndexedAccess": true,
18
+ "noUnusedLocals": true,
19
+ "noUnusedParameters": true,
20
+ "verbatimModuleSyntax": true,
21
+ "types": ["node"]
22
+ },
23
+ "include": ["src/**/*.ts"]
24
+ }
@@ -0,0 +1,2 @@
1
+ import { defineConfig } from 'tsdown'
2
+ export default defineConfig({ entry: ['src/index.ts'], format: 'esm', platform: 'node', target: 'es2024', outDir: 'lib', dts: false, sourcemap: true })
@@ -0,0 +1,18 @@
1
+ import { availableParallelism } from 'node:os'
2
+ import { defineConfig } from 'vitest/config'
3
+
4
+ export default defineConfig({
5
+ test: {
6
+ setupFiles: ['../../scripts/testing/isolate-home.ts'],
7
+ // Most specs here boot a real profile (a Loader tree, a package install): a few seconds on an idle machine, several times that on a loaded
8
+ // one (the gate runs every package's tests at once) or on Windows file systems. A 5 s default timed boots out with nothing wrong, one spec
9
+ // at a time; the budget is set once here instead. A spec that needs more (a real model, an install) still says so itself.
10
+ testTimeout: process.platform === 'win32' ? 60_000 : 30_000,
11
+ // Each worker boots whole engines; one per core starved them on a loaded machine (load 60-110: boots timed out at 60-135 s, while 4 workers ran
12
+ // the whole suite in 43 s at load 103). Bounded, so the suite's own parallelism cannot be the overload.
13
+ maxWorkers: Math.min(4, Math.max(1, Math.floor(availableParallelism() / 2))),
14
+ hookTimeout: process.platform === 'win32' ? 60_000 : 10_000,
15
+ // The profile-resolution tests resolve through Node's module hooks with an explicit importer: import.meta.resolve(specifier, parent).
16
+ execArgv: ['--experimental-import-meta-resolve'],
17
+ },
18
+ })
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.