@dual-os/cli 0.0.0-stage → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (254) hide show
  1. package/LICENSE +4 -0
  2. package/README.md +15 -2
  3. package/dist/_virtual/_rolldown/runtime.js +13 -0
  4. package/dist/auth/credentials.d.ts +17 -0
  5. package/dist/auth/credentials.d.ts.map +1 -0
  6. package/dist/auth/credentials.js +57 -0
  7. package/dist/auth/credentials.js.map +1 -0
  8. package/dist/auth/destination.d.ts +22 -0
  9. package/dist/auth/destination.d.ts.map +1 -0
  10. package/dist/auth/destination.js +49 -0
  11. package/dist/auth/destination.js.map +1 -0
  12. package/dist/auth/http.d.ts +12 -0
  13. package/dist/auth/http.d.ts.map +1 -0
  14. package/dist/auth/http.js +34 -0
  15. package/dist/auth/http.js.map +1 -0
  16. package/dist/auth/login.d.ts +22 -0
  17. package/dist/auth/login.d.ts.map +1 -0
  18. package/dist/auth/login.js +98 -0
  19. package/dist/auth/login.js.map +1 -0
  20. package/dist/auth/protocol.d.ts +26 -0
  21. package/dist/auth/protocol.d.ts.map +1 -0
  22. package/dist/auth/protocol.js +31 -0
  23. package/dist/auth/protocol.js.map +1 -0
  24. package/dist/baseline.d.ts +18 -0
  25. package/dist/baseline.d.ts.map +1 -0
  26. package/dist/baseline.js +22 -0
  27. package/dist/baseline.js.map +1 -0
  28. package/dist/bin.d.ts +1 -0
  29. package/dist/bin.js +7 -0
  30. package/dist/bin.js.map +1 -0
  31. package/dist/cli.d.ts +19 -0
  32. package/dist/cli.d.ts.map +1 -0
  33. package/dist/cli.js +492 -0
  34. package/dist/cli.js.map +1 -0
  35. package/dist/create/choices.d.ts +58 -0
  36. package/dist/create/choices.d.ts.map +1 -0
  37. package/dist/create/choices.js +121 -0
  38. package/dist/create/choices.js.map +1 -0
  39. package/dist/create/deployment.d.ts +48 -0
  40. package/dist/create/deployment.d.ts.map +1 -0
  41. package/dist/create/deployment.js +66 -0
  42. package/dist/create/deployment.js.map +1 -0
  43. package/dist/create/scaffold.d.ts +57 -0
  44. package/dist/create/scaffold.d.ts.map +1 -0
  45. package/dist/create/scaffold.js +198 -0
  46. package/dist/create/scaffold.js.map +1 -0
  47. package/dist/create/source-reference.d.ts +39 -0
  48. package/dist/create/source-reference.d.ts.map +1 -0
  49. package/dist/create/source-reference.js +185 -0
  50. package/dist/create/source-reference.js.map +1 -0
  51. package/dist/create/template.d.ts +116 -0
  52. package/dist/create/template.d.ts.map +1 -0
  53. package/dist/create/template.js +211 -0
  54. package/dist/create/template.js.map +1 -0
  55. package/dist/diagnostics.d.ts +6 -0
  56. package/dist/diagnostics.d.ts.map +1 -0
  57. package/dist/diagnostics.js +18 -0
  58. package/dist/diagnostics.js.map +1 -0
  59. package/dist/help.d.ts +16 -0
  60. package/dist/help.d.ts.map +1 -0
  61. package/dist/help.js +73 -0
  62. package/dist/help.js.map +1 -0
  63. package/dist/openapi/bundle.d.ts +18 -0
  64. package/dist/openapi/bundle.d.ts.map +1 -0
  65. package/dist/openapi/bundle.js +201 -0
  66. package/dist/openapi/bundle.js.map +1 -0
  67. package/dist/openapi/discovery.d.ts +30 -0
  68. package/dist/openapi/discovery.d.ts.map +1 -0
  69. package/dist/openapi/discovery.js +325 -0
  70. package/dist/openapi/discovery.js.map +1 -0
  71. package/dist/openapi/emit.d.ts +52 -0
  72. package/dist/openapi/emit.d.ts.map +1 -0
  73. package/dist/openapi/emit.js +596 -0
  74. package/dist/openapi/emit.js.map +1 -0
  75. package/dist/openapi/graphql.d.ts +102 -0
  76. package/dist/openapi/graphql.d.ts.map +1 -0
  77. package/dist/openapi/graphql.js +294 -0
  78. package/dist/openapi/graphql.js.map +1 -0
  79. package/dist/openapi/identity.d.ts +88 -0
  80. package/dist/openapi/identity.d.ts.map +1 -0
  81. package/dist/openapi/identity.js +98 -0
  82. package/dist/openapi/identity.js.map +1 -0
  83. package/dist/openapi/mcp.d.ts +21 -0
  84. package/dist/openapi/mcp.d.ts.map +1 -0
  85. package/dist/openapi/mcp.js +133 -0
  86. package/dist/openapi/mcp.js.map +1 -0
  87. package/dist/openapi/operations.d.ts +165 -0
  88. package/dist/openapi/operations.d.ts.map +1 -0
  89. package/dist/openapi/operations.js +361 -0
  90. package/dist/openapi/operations.js.map +1 -0
  91. package/dist/openapi/overlay.d.ts +23 -0
  92. package/dist/openapi/overlay.d.ts.map +1 -0
  93. package/dist/openapi/overlay.js +115 -0
  94. package/dist/openapi/overlay.js.map +1 -0
  95. package/dist/openapi/plugin.d.ts +83 -0
  96. package/dist/openapi/plugin.d.ts.map +1 -0
  97. package/dist/openapi/plugin.js +468 -0
  98. package/dist/openapi/plugin.js.map +1 -0
  99. package/dist/openapi/polymorphism.d.ts +21 -0
  100. package/dist/openapi/polymorphism.d.ts.map +1 -0
  101. package/dist/openapi/polymorphism.js +96 -0
  102. package/dist/openapi/polymorphism.js.map +1 -0
  103. package/dist/openapi/postman.d.ts +21 -0
  104. package/dist/openapi/postman.d.ts.map +1 -0
  105. package/dist/openapi/postman.js +286 -0
  106. package/dist/openapi/postman.js.map +1 -0
  107. package/dist/openapi/schema.d.ts +178 -0
  108. package/dist/openapi/schema.d.ts.map +1 -0
  109. package/dist/openapi/schema.js +1234 -0
  110. package/dist/openapi/schema.js.map +1 -0
  111. package/dist/openapi/select.d.ts +22 -0
  112. package/dist/openapi/select.d.ts.map +1 -0
  113. package/dist/openapi/select.js +79 -0
  114. package/dist/openapi/select.js.map +1 -0
  115. package/dist/openapi/spec.d.ts +147 -0
  116. package/dist/openapi/spec.d.ts.map +1 -0
  117. package/dist/openapi/spec.js +263 -0
  118. package/dist/openapi/spec.js.map +1 -0
  119. package/dist/openapi/swagger.d.ts +166 -0
  120. package/dist/openapi/swagger.d.ts.map +1 -0
  121. package/dist/openapi/swagger.js +298 -0
  122. package/dist/openapi/swagger.js.map +1 -0
  123. package/dist/openapi/versions.d.ts +52 -0
  124. package/dist/openapi/versions.d.ts.map +1 -0
  125. package/dist/openapi/versions.js +120 -0
  126. package/dist/openapi/versions.js.map +1 -0
  127. package/dist/plugin/archive.d.ts +27 -0
  128. package/dist/plugin/archive.d.ts.map +1 -0
  129. package/dist/plugin/archive.js +170 -0
  130. package/dist/plugin/archive.js.map +1 -0
  131. package/dist/plugin/bundle.d.ts +27 -0
  132. package/dist/plugin/bundle.d.ts.map +1 -0
  133. package/dist/plugin/bundle.js +328 -0
  134. package/dist/plugin/bundle.js.map +1 -0
  135. package/dist/plugin/init.d.ts +18 -0
  136. package/dist/plugin/init.d.ts.map +1 -0
  137. package/dist/plugin/init.js +121 -0
  138. package/dist/plugin/init.js.map +1 -0
  139. package/dist/plugin/inspection.d.ts +24 -0
  140. package/dist/plugin/inspection.d.ts.map +1 -0
  141. package/dist/plugin/inspection.js +24 -0
  142. package/dist/plugin/inspection.js.map +1 -0
  143. package/dist/plugin/package.d.ts +26 -0
  144. package/dist/plugin/package.d.ts.map +1 -0
  145. package/dist/plugin/package.js +73 -0
  146. package/dist/plugin/package.js.map +1 -0
  147. package/dist/plugin/publication.d.ts +29 -0
  148. package/dist/plugin/publication.d.ts.map +1 -0
  149. package/dist/plugin/publication.js +65 -0
  150. package/dist/plugin/publication.js.map +1 -0
  151. package/dist/plugin/validation.d.ts +15 -0
  152. package/dist/plugin/validation.d.ts.map +1 -0
  153. package/dist/plugin/validation.js +119 -0
  154. package/dist/plugin/validation.js.map +1 -0
  155. package/dist/release/archives.d.ts +33 -0
  156. package/dist/release/archives.d.ts.map +1 -0
  157. package/dist/release/archives.js +81 -0
  158. package/dist/release/archives.js.map +1 -0
  159. package/dist/release/release-manifest.d.ts +182 -0
  160. package/dist/release/release-manifest.d.ts.map +1 -0
  161. package/dist/release/release-manifest.js +79 -0
  162. package/dist/release/release-manifest.js.map +1 -0
  163. package/dist/release/releases.d.ts +36 -0
  164. package/dist/release/releases.d.ts.map +1 -0
  165. package/dist/release/releases.js +122 -0
  166. package/dist/release/releases.js.map +1 -0
  167. package/dist/skills.d.ts +35 -0
  168. package/dist/skills.d.ts.map +1 -0
  169. package/dist/skills.js +257 -0
  170. package/dist/skills.js.map +1 -0
  171. package/package.json +73 -4
  172. package/skills/dual-fde/SKILL.md +38 -0
  173. package/skills/dual-fde/references/access.md +62 -0
  174. package/skills/dual-fde/references/author-plugins.md +54 -0
  175. package/skills/dual-fde/references/cli.md +97 -0
  176. package/skills/dual-fde/references/manage-plugins.md +78 -0
  177. package/skills/dual-fde/references/migrations-deployment.md +84 -0
  178. package/skills/dual-fde/references/openapi-plugins.md +47 -0
  179. package/skills/dual-fde/references/sdk-docs.md +56 -0
  180. package/skills/dual-fde/references/upgrades.md +115 -0
  181. package/skills/dual-fde/references/working-context.md +69 -0
  182. package/src/auth/credentials.ts +84 -0
  183. package/src/auth/destination.ts +83 -0
  184. package/src/auth/http.ts +39 -0
  185. package/src/auth/login.ts +177 -0
  186. package/src/auth/protocol.ts +37 -0
  187. package/src/baseline.ts +15 -0
  188. package/src/bin.ts +4 -0
  189. package/src/cli.ts +969 -0
  190. package/src/create/choices.ts +177 -0
  191. package/src/create/deployment.ts +96 -0
  192. package/src/create/scaffold.ts +334 -0
  193. package/src/create/source-reference.ts +212 -0
  194. package/src/create/template.ts +300 -0
  195. package/src/diagnostics.ts +8 -0
  196. package/src/help.ts +142 -0
  197. package/src/openapi/bundle.ts +290 -0
  198. package/src/openapi/discovery.ts +438 -0
  199. package/src/openapi/emit.ts +1031 -0
  200. package/src/openapi/graphql.ts +375 -0
  201. package/src/openapi/identity.ts +153 -0
  202. package/src/openapi/mcp.ts +165 -0
  203. package/src/openapi/operations.ts +781 -0
  204. package/src/openapi/overlay.ts +195 -0
  205. package/src/openapi/plugin.ts +856 -0
  206. package/src/openapi/polymorphism.ts +207 -0
  207. package/src/openapi/postman.ts +403 -0
  208. package/src/openapi/schema.ts +2138 -0
  209. package/src/openapi/select.ts +113 -0
  210. package/src/openapi/spec.ts +401 -0
  211. package/src/openapi/swagger.ts +422 -0
  212. package/src/openapi/versions.ts +174 -0
  213. package/src/plugin/archive.ts +244 -0
  214. package/src/plugin/bundle.ts +572 -0
  215. package/src/plugin/init.ts +178 -0
  216. package/src/plugin/inspection.ts +19 -0
  217. package/src/plugin/package.ts +140 -0
  218. package/src/plugin/publication.ts +128 -0
  219. package/src/plugin/validation.ts +213 -0
  220. package/src/release/archives.ts +133 -0
  221. package/src/release/release-manifest.ts +79 -0
  222. package/src/release/releases.ts +210 -0
  223. package/src/skills.ts +434 -0
  224. package/templates/compose/.env.compose.example.hbs +3 -0
  225. package/templates/compose/.env.host.example.hbs +4 -0
  226. package/templates/compose/Dockerfile.hbs +12 -0
  227. package/templates/compose/OPERATIONS.md.hbs +159 -0
  228. package/templates/compose/_dockerignore +14 -0
  229. package/templates/compose/compose.external.yaml +7 -0
  230. package/templates/compose/compose.host-linux.yaml +5 -0
  231. package/templates/compose/compose.host.yaml.hbs +15 -0
  232. package/templates/compose/compose.yaml.hbs +85 -0
  233. package/templates/compose/release.env.hbs +2 -0
  234. package/templates/default/.env.example.hbs +79 -0
  235. package/templates/default/README.md.hbs +150 -0
  236. package/templates/default/_gitignore +11 -0
  237. package/templates/default/packages/customer-plugin/src/Customer.ts.hbs +17 -0
  238. package/templates/default/packages/customer-plugin/tsconfig.json +15 -0
  239. package/templates/default/packages/execution-layer/src/App.ts.hbs +7 -0
  240. package/templates/default/packages/execution-layer/src/Host.ts.hbs +31 -0
  241. package/templates/default/packages/execution-layer/src/Telemetry.ts.hbs +23 -0
  242. package/templates/default/packages/execution-layer/src/api.ts.hbs +21 -0
  243. package/templates/default/packages/execution-layer/src/bootstrap.ts +22 -0
  244. package/templates/default/packages/execution-layer/src/migrate.ts +11 -0
  245. package/templates/default/packages/execution-layer/src/registry-check.ts +29 -0
  246. package/templates/default/packages/execution-layer/src/registry-sync.ts +14 -0
  247. package/templates/default/packages/execution-layer/src/worker.ts.hbs +16 -0
  248. package/templates/default/packages/execution-layer/test/app.host-test.ts.hbs +58 -0
  249. package/templates/default/packages/execution-layer/test/app.test.ts.hbs +16 -0
  250. package/templates/default/tsconfig.json +5 -0
  251. package/templates/default/vitest.config.ts +5 -0
  252. package/templates/default/vitest.host.config.ts +6 -0
  253. package/templates/opensandbox/OPEN-SANDBOX.md +25 -0
  254. package/templates/opensandbox/docker/agent-sandbox.Dockerfile +41 -0
@@ -0,0 +1,85 @@
1
+ # Explicit startup is database-affecting. Use only an authorized environment.
2
+ # No build section: build once, supply an immutable image, promote without rebuilds.
3
+ x-customer: &customer
4
+ image: ${CUSTOMER_IMAGE:?Supply an immutable customer repository@sha256 digest or local sha256 image ID}
5
+ # Pull a published immutable customer digest explicitly before startup.
6
+ # Missing local IDs must fail, not be interpreted as registry tags.
7
+ pull_policy: never
8
+ env_file: .env.compose
9
+ environment:
10
+ DUAL_FILE_STORAGE_ROOT: /var/lib/dual/files
11
+ DUAL_API_PORT: "{{apiPort}}"
12
+ volumes:
13
+ # The same customer-owned persistent directory is used in both dev modes.
14
+ - ./.dual/storage:/var/lib/dual/files
15
+
16
+ services:
17
+ postgres:
18
+ image: postgres@sha256:cf78e76683b9ca8c5733cbbdce6c9262b45b6767934dd0a95e671f9a0fc20685
19
+ environment:
20
+ POSTGRES_USER: dual
21
+ POSTGRES_DB: dual
22
+ # The local Postgres image rejects an empty password. External-DB mode
23
+ # does not require unused local credentials.
24
+ POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-}
25
+ volumes:
26
+ - postgres:/var/lib/postgresql/data
27
+ healthcheck:
28
+ test: [CMD-SHELL, pg_isready -U dual -d dual]
29
+ interval: 2s
30
+ timeout: 3s
31
+ retries: 30
32
+ migrate:
33
+ <<: *customer
34
+ command: [bun, run, migrate]
35
+ restart: "no"
36
+ depends_on:
37
+ postgres: { condition: service_healthy }
38
+ registry-sync:
39
+ <<: *customer
40
+ command: [bun, run, "registry:sync"]
41
+ restart: "no"
42
+ depends_on:
43
+ migrate: { condition: service_completed_successfully }
44
+ bootstrap:
45
+ <<: *customer
46
+ command: [bun, run, bootstrap]
47
+ restart: "no"
48
+ depends_on:
49
+ registry-sync: { condition: service_completed_successfully }
50
+ api:
51
+ <<: *customer
52
+ command: [bun, run, api]
53
+ restart: unless-stopped
54
+ depends_on:
55
+ bootstrap: { condition: service_completed_successfully }
56
+ healthcheck:
57
+ test:
58
+ [
59
+ CMD,
60
+ bun,
61
+ -e,
62
+ "const r = await fetch('http://127.0.0.1:{{apiPort}}/api/health'); process.exit(r.status === 204 ? 0 : 1)",
63
+ ]
64
+ interval: 2s
65
+ timeout: 3s
66
+ retries: 40
67
+ worker:
68
+ <<: *customer
69
+ command: [bun, run, worker]
70
+ restart: unless-stopped
71
+ depends_on:
72
+ bootstrap: { condition: service_completed_successfully }
73
+ # Caddy with the built app: serves the app and proxies the API on one origin.
74
+ web:
75
+ image: ${DUAL_WEB_IMAGE:?Set DUAL_WEB_IMAGE in the committed release.env to the verified immutable web reference}
76
+ pull_policy: {{webPullPolicy}}
77
+ environment:
78
+ DUAL_API_UPSTREAM: api:{{apiPort}}
79
+ DUAL_SITE_ADDRESS: "{{siteAddress}}"
80
+ ports:
81
+ - "127.0.0.1:{{hostHttpPort}}:80"
82
+ depends_on:
83
+ api: { condition: service_healthy }
84
+ volumes:
85
+ postgres:
@@ -0,0 +1,2 @@
1
+ # Non-secret release selection. Commit with dual.release.json; never put credentials here.
2
+ DUAL_WEB_IMAGE={{webImage}}
@@ -0,0 +1,79 @@
1
+ # Supply secrets externally. No credentials are generated or collected.
2
+ # DATABASE_URL must identify your explicitly approved PostgreSQL database.
3
+ DATABASE_URL=
4
+ BETTER_AUTH_SECRET=
5
+ BETTER_AUTH_URL={{apiOrigin}}
6
+ APP_ORIGIN={{appOrigin}}
7
+ SERVER_PUBLIC_URL={{apiOrigin}}
8
+ # Required sender identity, even when logging-only email performs NO DELIVERY.
9
+ DUAL_AUTH_EMAIL_FROM=
10
+ # Configure a keyring using the installed core credential-vault documentation.
11
+ DUAL_CREDENTIAL_VAULT_KEYRING=
12
+ DUAL_FILE_STORAGE_ROOT=.dual/storage
13
+ DUAL_API_PORT={{apiPort}}
14
+ {{#opensandbox}}
15
+
16
+ # Existing external OpenSandbox server, reachable from BOTH API and worker.
17
+ # No local server/socket is generated. Use host:port or an HTTP(S) URL without
18
+ # embedded credentials; supply the API key separately. See OPEN-SANDBOX.md.
19
+ OPEN_SANDBOX_DOMAIN=
20
+ OPEN_SANDBOX_API_KEY=
21
+ # Required image accessible to that server's daemon, with Linux shell and rg.
22
+ DUAL_OPEN_SANDBOX_IMAGE=
23
+ DUAL_OPEN_SANDBOX_TTL_SECONDS=86400
24
+ DUAL_OPEN_SANDBOX_REQUEST_TIMEOUT_SECONDS=120
25
+ DUAL_OPEN_SANDBOX_READY_TIMEOUT_SECONDS=60
26
+ # SDK metrics to the sandbox server; separate from Dual OTLP telemetry.
27
+ OPENSANDBOX_DISABLE_METRICS=1
28
+ {{/opensandbox}}
29
+ {{#smtp}}
30
+ # Selected SMTP email: real delivery through your configured relay.
31
+ {{else}}
32
+ # Logging-only email: NO DELIVERY. Replace the host layer for real email.
33
+ {{/smtp}}
34
+ {{#telemetryDisabled}}
35
+ # Telemetry is disabled in the generated layer; OTEL variables do not enable it.
36
+ {{else}}
37
+ # Optional telemetry export; disabled when absent. No backend is provisioned.
38
+ # OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
39
+ {{/telemetryDisabled}}
40
+
41
+ # Explicit database-affecting bootstrap: supply values before bun run bootstrap.
42
+ # Compose startup also runs this initialization job when Compose is generated.
43
+ DUAL_BOOTSTRAP_EMAIL=
44
+ DUAL_BOOTSTRAP_PASSWORD=
45
+ DUAL_BOOTSTRAP_NAME=
46
+ DUAL_BOOTSTRAP_ORGANIZATION_NAME=
47
+ DUAL_BOOTSTRAP_ORGANIZATION_SLUG=
48
+ {{#compose}}
49
+
50
+ CUSTOMER_IMAGE=
51
+ POSTGRES_PASSWORD=
52
+ DUAL_HTTP_PORT={{httpPort}}
53
+ # Keep all three auth/public origins above equal to the proxy origin.
54
+ # If DUAL_HTTP_PORT changes, update all three origins accordingly.
55
+ {{/compose}}
56
+ {{#s3}}
57
+
58
+ # Existing S3-compatible bucket; no bucket or credentials are provisioned.
59
+ DUAL_FILE_STORAGE_S3_BUCKET=
60
+ DUAL_FILE_STORAGE_S3_REGION=auto
61
+ # DUAL_FILE_STORAGE_S3_ENDPOINT=
62
+ # DUAL_FILE_STORAGE_S3_FORCE_PATH_STYLE=false
63
+ # Supply AWS SDK credentials externally, or both DUAL_FILE_STORAGE_S3_ACCESS_KEY_ID
64
+ # and DUAL_FILE_STORAGE_S3_SECRET_ACCESS_KEY. Never commit them.
65
+ {{/s3}}
66
+ {{#smtp}}
67
+
68
+ # Existing SMTP relay. User/password remain external; real email delivery.
69
+ SMTP_HOST=
70
+ SMTP_PORT=587
71
+ SMTP_SECURE=false
72
+ # SMTP_USER=
73
+ # SMTP_PASS=
74
+ {{/smtp}}
75
+ {{#compose}}
76
+
77
+ # Host-run mode only: forward local PostgreSQL; match DUAL_API_PORT in both files.
78
+ DUAL_POSTGRES_PORT={{postgresPort}}
79
+ {{/compose}}
@@ -0,0 +1,150 @@
1
+ # Customer-owned Dual execution layer
2
+
3
+ This Bun workspace and its local plugin are yours to edit. Nothing here is
4
+ published, provisioned, deployed or automatically upgraded by Dual.
5
+
6
+ ## Install and validate
7
+
8
+ Use Bun 1.4.2 (also pinned by the generated Dockerfile; older Bun cannot read its native lockfile v2). Configure approved private registry access externally (VPN and
9
+ read-only credentials in your user configuration/environment). Do not paste
10
+ credentials into this repository. The bootstrap command is dual create from
11
+ @dual-os/cli; configure the private @dual scope externally.
12
+
13
+ Generation discovers the newest completed template-supported release manifest and
14
+ installs by default. --release CORE_VERSION selects its newest compatible snapshot
15
+ for that exact core; --manifest 0.0.<pipeline-id> selects an exact manifest. The
16
+ manifest owns package/plugin pins and the qualified image together.
17
+ With --bare --skip-install and no release selector it is offline and has no
18
+ pair/Compose or lockfile. An explicit selector still requires registry reads. Install (or retry a failed install) from this directory:
19
+
20
+ ```sh
21
+ bun install
22
+ bun run check-types
23
+ bun run test
24
+ ```
25
+
26
+ Commit Bun's native bun.lock after successful installation. Dual versions and
27
+ Effect are pinned exactly. dual.scaffold.json records the starting choices,
28
+ not credentials or a dependency solver. Exact replay uses
29
+ `dual create NEW --replay dual.scaffold.json` with the recorded CLI version.
30
+ bootstrapVersion is null because the approved entrypoint is the single scoped CLI,
31
+ not a separate bootstrap package. Replay checks
32
+ registry availability even with --skip-install, and fails instead of substituting
33
+ artifacts. It does not reproduce an installed dependency tree: commit bun.lock.
34
+ Never replay into an existing customer repository.
35
+
36
+ ## Read-only references
37
+
38
+ Git submodules at `vendor/dual` and `vendor/fdes-docs` pin committed product source
39
+ and FDE guidance snapshots. Runtime dependencies remain the installed public
40
+ `@dual/*` and `@dual-os/*` packages. Creation performs no Git fetch and creates no commit. Read
41
+ [DUAL-SOURCE.md](DUAL-SOURCE.md) and [FDE-DOCS.md](FDE-DOCS.md) for pins,
42
+ external authentication, engagement access boundaries and individual checkout
43
+ instructions; run `bun run source:init` to explicitly download both references
44
+ without recursion. FDE docs require separate GitLab project access.
45
+ The vendor tree is outside workspace/typecheck inputs and Docker build contexts.
46
+ Review and stage your application files before creating the first Git commit.
47
+
48
+ ## Project identity
49
+
50
+ The friendly name, slug, npm scope, root package name, application ID and local
51
+ plugin/provider ID are recorded in dual.scaffold.json. Override at creation with
52
+ --name, --slug, --package-scope, --package-name, --app-id and --plugin-id.
53
+ The interactive wizard suggests editable slug/scope values from the name and
54
+ preserves explicit flags. Static Customer.ts filenames are not runtime identities.
55
+ The default packages are dual-<slug>, @<slug>/execution-layer and @<slug>/plugin.
56
+
57
+ ## Selected host preset
58
+
59
+ {{#playground}}
60
+ **Playground-style, not a clone of Hosted Playground.** This preset defaults to
61
+ external OpenSandbox; explicit workspace selection can override it. It keeps
62
+ customer app identity and plugin selections, local files, logging-only email and
63
+ opt-in generic OTLP. It does not select extra integrations, Resend, Linear support,
64
+ PostHog, demo data, accounts or DNS/TLS. Online pair discovery is independent of preset.
65
+ {{else}}
66
+ Customer defaults are preserved; workspace and other choices can be overridden.
67
+ {{/playground}}
68
+ {{#opensandbox}}
69
+ **OpenSandbox selected:** install the exact `@dual/workspace-opensandbox` artifact
70
+ and configure an existing external server for both API and worker. See
71
+ OPEN-SANDBOX.md. No fallback to just-bash, server provisioning or socket mount.
72
+ {{else}}
73
+ **just-bash selected:** no OpenSandbox SDK/artifact or server is required.
74
+ {{/opensandbox}}
75
+
76
+ This is template customer-bun-v13 / replay schema 9. Historical records (including v12/schema 8, v11 and v10/schema 7 and v9/schema 6)
77
+ must use their recorded CLI; this CLI rejects them rather than upgrading them.
78
+
79
+ ## Explicit host setup
80
+
81
+ For direct, non-Compose hosting, copy .env.example to .env and supply your approved
82
+ database and secrets. For api:local, worker:local or dev:* scripts, copy
83
+ .env.host.example to .env.host and supply the same approved configuration.
84
+ If Compose artifacts are present, follow OPERATIONS.md instead:
85
+ use .env.compose and .env.host separately to avoid Bun auto-loading container DNS. Follow
86
+ the installed @dual/core README for the credential-vault keyring format and
87
+ configuration. API and worker share DATABASE_URL and local persistent storage.
88
+ The defaults are PostgreSQL, local files, JustBash and **logging-only email:
89
+ no messages are delivered**. Use --interactive or equivalent --database postgresql,
90
+ --workspace just-bash|opensandbox, --file-storage local|s3, --email logging-only-no-delivery|smtp
91
+ and --telemetry opt-in|disabled flags. Inspect dual.scaffold.json for your choices.
92
+ S3 requires an existing bucket and externally supplied credentials; SMTP requires
93
+ an existing relay and can deliver real email. No service is provisioned. Only
94
+ supported public host implementations are offered (not memory test adapters).
95
+ {{#telemetryDisabled}}
96
+ Telemetry is disabled in the generated layer; setting an OTEL URL cannot enable it.
97
+ {{else}}
98
+ Telemetry export is opt-in via the commented URL.
99
+ {{/telemetryDisabled}}
100
+ API, HTTP proxy and forwarded PostgreSQL ports are recorded independently. Use
101
+ --api-port, --http-port and --postgres-port at creation; their defaults avoid each
102
+ other. Explicit collisions are rejected for host-mode compatibility. If changing
103
+ ports afterward, synchronize env files, Compose and auth/public origins.
104
+ No services start merely by importing the definition, app or host layer.
105
+
106
+ After obtaining authorization for database-affecting operations, explicitly run
107
+ bun run migrate, then bun run registry:check and bun run registry:sync. These
108
+ are distinct maintenance operations; API and worker do not initialize state.
109
+ Start them explicitly with bun run api and bun run worker in separate terminals.
110
+ Generation provisions no database, web image, container, account or Provider Connection.
111
+ The separate `bun run bootstrap` command uses the public Bootstrap API to prepare
112
+ an authorized initial admin/organization from externally supplied DUAL*BOOTSTRAP*\*
113
+ settings. It is not called by API/worker startup and never resets existing passwords.
114
+
115
+ ## Customer-owned tests
116
+
117
+ bun run test invokes the real public SDK runtime without infrastructure. The
118
+ separate bun run test:host command requires DUAL_TEST_DATABASE_URL pointing to an
119
+ existing, dedicated disposable PostgreSQL database. It fails if that variable is
120
+ absent; it never falls back to DATABASE_URL. Supply it explicitly in the command
121
+ environment, not the application's .env file.
122
+
123
+ The host test explicitly runs public migrations and registry synchronization,
124
+ then checks the in-process server using @dual/core/testing hostLayer and
125
+ configLayer. hostLayer includes secretEncryptionLayer, memory credentials, email
126
+ and files; its fixed public test keys must never protect persistent/production
127
+ data. Web-handler disposal closes scoped connections; it does not drop data.
128
+
129
+ You own Vitest, database provisioning, migration authorization, isolation/reset
130
+ between suites and database cleanup, including interruption recovery. Use a fresh
131
+ database per suite and destroy it afterward. No provisioning, migration or server
132
+ startup happens during imports, generation or the default smoke test.
133
+
134
+ The fixed template pins core to 0.0.1 and SDK/DualSpec/config to 0.0.0.
135
+ Online discovery accepts only completed catalog pairs matching that core; it never
136
+ selects independent latest package versions. Exact replay retains the saved pair,
137
+ not a new latest resolution.
138
+ Publish the customer plugin with `dual plugin push packages/customer-plugin`.
139
+ To give every organization a public plugin package, add its npm name to
140
+ `Dual.withStandardPlugins` in packages/execution-layer/src/App.ts: the worker
141
+ installs its latest release. Inspect dual.scaffold.json for exact metadata;
142
+ subsequent changes are yours. npm is needed for metadata-only archive reads; Bun
143
+ owns dependency resolution and installation.
144
+ When generation discovers a pair or uses an explicit --release-pair and --web-image,
145
+ OPERATIONS.md documents customer-owned full Compose and its initialization jobs.
146
+ Bare offline inspection without a pair omits Compose. A local image ID is only
147
+ local proof, never published-release acceptance. Use dual release resolve for
148
+ read-only upgrade discovery, then analyze, approve and update customer pins/pair/image
149
+ together; resolution does not apply an upgrade or authorize deployment.
150
+ The bundled FDE skill is in .agents/skills/dual-fde/. Never regenerate over customer edits.
@@ -0,0 +1,11 @@
1
+ node_modules/
2
+ .env
3
+ .env.*
4
+ !.env.example
5
+ !.env.host.example
6
+ !.env.compose.example
7
+ .dual/
8
+ dist/
9
+ coverage/
10
+ .npmrc
11
+ bunfig.toml
@@ -0,0 +1,17 @@
1
+ import { Effect, Schema } from "effect";
2
+
3
+ import { Action, Plugin } from "@dual-os/sdk";
4
+
5
+ const ping = Action.make("ping", { description: {{nameJson}} + " smoke action",
6
+ input: Schema.Struct({ message: Schema.String }),
7
+ output: Schema.Struct({ echoed: Schema.String }),
8
+ });
9
+ const definition = Plugin.make({{pluginIdJson}}).pipe(
10
+ Plugin.withName({{nameJson}}), Plugin.withAction(ping),
11
+ );
12
+ const handlers = Plugin.toLayer(definition, handlers =>
13
+ handlers.action("ping", input => Effect.succeed({ echoed: input.message })),
14
+ );
15
+ export const customerPlugin = definition.pipe(Plugin.provide(handlers));
16
+
17
+ export * as Customer from "./Customer.ts";
@@ -0,0 +1,15 @@
1
+ {
2
+ "compilerOptions": {
3
+ "declaration": true,
4
+ "module": "NodeNext",
5
+ "moduleResolution": "NodeNext",
6
+ "noEmitOnError": true,
7
+ "outDir": "dist",
8
+ "rewriteRelativeImportExtensions": true,
9
+ "rootDir": "src",
10
+ "skipLibCheck": true,
11
+ "strict": true,
12
+ "target": "ES2022"
13
+ },
14
+ "include": ["src/**/*.ts"]
15
+ }
@@ -0,0 +1,7 @@
1
+ import { Dual } from "@dual/core";
2
+
3
+ // Publish the customer plugin with `dual plugin push packages/customer-plugin`.
4
+ // Dual.withStandardPlugins names npm packages every organization gets at their latest release.
5
+ export const app = Dual.make({{appIdJson}}, { name: {{nameJson}} });
6
+
7
+ export * as App from "./App.ts";
@@ -0,0 +1,31 @@
1
+ {{#smtp}}
2
+ import { SmtpEmail } from "@dual/core/email/SmtpEmail";
3
+ {{/smtp}}
4
+ {{#s3}}
5
+ import { S3FileStorage } from "@dual/core/file-storage/S3FileStorage";
6
+ {{/s3}}
7
+ {{#opensandbox}}
8
+ import { OpenSandboxProvider } from "@dual/workspace-opensandbox";
9
+ {{/opensandbox}}
10
+ import { HostDefaults } from "@dual/core/HostDefaults";
11
+ import { Layer } from "effect";
12
+
13
+ const database = HostDefaults.DefaultDb;
14
+ const storage = {{#s3}}S3FileStorage.layerFromEnv{{else}}HostDefaults.DefaultFileStorage{{/s3}};
15
+ const vault = HostDefaults.DefaultCredentialVault.pipe(Layer.provide(database));
16
+ // Shared by API and worker. Explicit OpenSandbox selection never falls back. Workflow runs open
17
+ // their own sandboxes, so the provider stays visible beside the workspace.
18
+ const workspace = {{#opensandbox}}HostDefaults.AgentWorkspace{{else}}HostDefaults.JustBashAgentWorkspace{{/opensandbox}}.pipe(
19
+ {{#opensandbox}}
20
+ Layer.provideMerge(OpenSandboxProvider.layerFromEnv()),
21
+ {{/opensandbox}}
22
+ Layer.provide(Layer.merge(database, storage)),
23
+ );
24
+ {{#smtp}}
25
+ // SMTP delivers real email through your externally configured relay.
26
+ {{else}}
27
+ // LogEmail logs messages only. It NEVER delivers email.
28
+ {{/smtp}}
29
+ export const host = Layer.mergeAll(database, storage, vault, workspace, {{#smtp}}SmtpEmail.layerFromEnv{{else}}HostDefaults.DefaultEmail{{/smtp}});
30
+
31
+ export * as Host from "./Host.ts";
@@ -0,0 +1,23 @@
1
+ {{#telemetryDisabled}}
2
+ import { Layer } from "effect";
3
+ export const telemetry = (_serviceName: string) => Layer.empty;
4
+ {{else}}
5
+ import { Config, Effect, Layer, Option } from "effect";
6
+ import { FetchHttpClient } from "effect/http";
7
+ import { OtlpSerialization, OtlpTracer } from "effect/observability";
8
+
9
+ // No exporter is started unless a customer explicitly configures this URL.
10
+ export const telemetry = (serviceName: string) =>
11
+ Layer.unwrap(
12
+ Effect.gen(function* () {
13
+ const url = yield* Config.option(Config.URL("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"));
14
+ if (Option.isNone(url)) return Layer.empty;
15
+ return OtlpTracer.layer({ url: url.value.toString(), resource: { serviceName } }).pipe(
16
+ Layer.provide(OtlpSerialization.layerJson),
17
+ Layer.provide(FetchHttpClient.layer),
18
+ );
19
+ }),
20
+ );
21
+
22
+ {{/telemetryDisabled}}
23
+ export * as Telemetry from "./Telemetry.ts";
@@ -0,0 +1,21 @@
1
+ import { NodeRuntime } from "@effect/platform-node";
2
+ import { Server } from "@dual/core/Server";
3
+ import { Config, ConfigProvider, Effect } from "effect";
4
+ import { FetchHttpClient } from "effect/http";
5
+ import { App } from "./App.ts";
6
+ import { Host } from "./Host.ts";
7
+ import { Telemetry } from "./Telemetry.ts";
8
+
9
+ Effect.gen(function* () {
10
+ const port = yield* Config.Port("DUAL_API_PORT").pipe(Config.withDefault({{apiPort}}));
11
+ return yield* Server.make(App.app).pipe(
12
+ Server.withPort(port),
13
+ Server.provide(Host.host),
14
+ Server.withObservability(Telemetry.telemetry({{apiServiceJson}})),
15
+ Server.run,
16
+ );
17
+ }).pipe(
18
+ Effect.provide(FetchHttpClient.layer),
19
+ Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromEnv()),
20
+ NodeRuntime.runMain,
21
+ );
@@ -0,0 +1,22 @@
1
+ import { NodeRuntime } from "@effect/platform-node";
2
+
3
+ import { Config, ConfigProvider, Effect } from "effect";
4
+
5
+ import { Bootstrap } from "@dual/core/Bootstrap";
6
+
7
+ // Explicit one-shot preparation. Never called by API/worker startup or imports.
8
+ Effect.gen(function* () {
9
+ const input = yield* Config.all({
10
+ email: Config.String("DUAL_BOOTSTRAP_EMAIL"),
11
+ password: Config.Redacted("DUAL_BOOTSTRAP_PASSWORD"),
12
+ name: Config.String("DUAL_BOOTSTRAP_NAME"),
13
+ organizationName: Config.String("DUAL_BOOTSTRAP_ORGANIZATION_NAME"),
14
+ organizationSlug: Config.String("DUAL_BOOTSTRAP_ORGANIZATION_SLUG"),
15
+ });
16
+ yield* Bootstrap.run(input);
17
+ yield* Effect.logInfo("Bootstrap preparation complete");
18
+ }).pipe(
19
+ Effect.provide(Bootstrap.defaultLayer),
20
+ Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromEnv()),
21
+ NodeRuntime.runMain,
22
+ );
@@ -0,0 +1,11 @@
1
+ import { NodeRuntime } from "@effect/platform-node";
2
+
3
+ import { ConfigProvider, Effect } from "effect";
4
+
5
+ import { Migrations } from "@dual/core/Migrations";
6
+
7
+ // Explicit maintenance command. API and worker never migrate.
8
+ Migrations.runFromEnv.pipe(
9
+ Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromEnv()),
10
+ NodeRuntime.runMain,
11
+ );
@@ -0,0 +1,29 @@
1
+ import { NodeRuntime } from "@effect/platform-node";
2
+
3
+ import { ConfigProvider, Effect } from "effect";
4
+
5
+ import { RegistryDeployment } from "@dual/core";
6
+
7
+ import { App } from "./App.ts";
8
+
9
+ export function logReport(report: RegistryDeployment.Report) {
10
+ return Effect.logInfo("Registry report").pipe(
11
+ Effect.annotateLogs({
12
+ mode: report.mode,
13
+ status: report.status,
14
+ dualIdentifier: report.plan.dualIdentifier,
15
+ planHash: report.plan.planHash,
16
+ changes: report.plan.changes.length,
17
+ diagnostics: report.plan.diagnostics.length,
18
+ blockers: report.plan.blockers.length,
19
+ }),
20
+ );
21
+ }
22
+
23
+ if (import.meta.main) {
24
+ RegistryDeployment.checkApp(App.app).pipe(
25
+ Effect.tap(logReport),
26
+ Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromEnv()),
27
+ NodeRuntime.runMain,
28
+ );
29
+ }
@@ -0,0 +1,14 @@
1
+ import { NodeRuntime } from "@effect/platform-node";
2
+
3
+ import { ConfigProvider, Effect } from "effect";
4
+
5
+ import { RegistryDeployment } from "@dual/core";
6
+
7
+ import { App } from "./App.ts";
8
+ import { logReport } from "./registry-check.ts";
9
+
10
+ RegistryDeployment.syncApp(App.app).pipe(
11
+ Effect.tap(logReport),
12
+ Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromEnv()),
13
+ NodeRuntime.runMain,
14
+ );
@@ -0,0 +1,16 @@
1
+ import { NodeRuntime } from "@effect/platform-node";
2
+ import { Worker } from "@dual/core/Worker";
3
+ import { ConfigProvider, Effect } from "effect";
4
+ import { FetchHttpClient } from "effect/http";
5
+ import { App } from "./App.ts";
6
+ import { Host } from "./Host.ts";
7
+ import { Telemetry } from "./Telemetry.ts";
8
+
9
+ Worker.make(App.app).pipe(
10
+ Worker.provide(Host.host),
11
+ Worker.withObservability(Telemetry.telemetry({{workerServiceJson}})),
12
+ Worker.run,
13
+ Effect.provide(FetchHttpClient.layer),
14
+ Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromEnv()),
15
+ NodeRuntime.runMain,
16
+ );
@@ -0,0 +1,58 @@
1
+ import { expect, it } from "@effect/vitest";
2
+ import { Migrations } from "@dual/core/Migrations";
3
+ import { RegistryDeployment } from "@dual/core";
4
+ import { Server } from "@dual/core/Server";
5
+ import { Testing } from "@dual/core/testing";
6
+ import { Config, ConfigProvider, Effect, Schema } from "effect";
7
+ import { FetchHttpClient } from "effect/http";
8
+ import { App } from "../src/App.ts";
9
+
10
+ const Hello = Schema.Struct({
11
+ message: Schema.String,
12
+ dual: Schema.Struct({ identifier: Schema.String }),
13
+ });
14
+
15
+ // This explicit suite changes schema/registry state. Supply a dedicated disposable
16
+ // database, never the application DATABASE_URL. The customer owns its cleanup.
17
+ it.effect(
18
+ "serves the customer app using public core test layers",
19
+ () =>
20
+ Effect.gen(function* () {
21
+ const databaseUrl = yield* Config.Redacted("DUAL_TEST_DATABASE_URL").pipe(
22
+ Effect.provide(
23
+ ConfigProvider.layer(
24
+ ConfigProvider.fromUnknown({
25
+ DUAL_TEST_DATABASE_URL: process.env["DUAL_TEST_DATABASE_URL"],
26
+ }),
27
+ ),
28
+ ),
29
+ );
30
+ const options = { databaseUrl };
31
+ const config = Testing.configLayer(options);
32
+ // hostLayer already includes Testing.secretEncryptionLayer's known test key.
33
+ const server = Server.make(App.app).pipe(
34
+ Server.provide(Testing.hostLayer(options)),
35
+ Server.provide(config),
36
+ // Like api.ts: plugin sign-ins such as Databricks OAuth make HTTP calls.
37
+ Server.provide(FetchHttpClient.layer),
38
+ );
39
+ yield* Migrations.run({ url: databaseUrl });
40
+ yield* RegistryDeployment.syncApp(App.app).pipe(Effect.provide(config));
41
+ const web = yield* Effect.acquireRelease(
42
+ Effect.sync(() => Server.toWebHandler(server)),
43
+ (web) => Effect.promise(() => web.dispose()),
44
+ );
45
+ const health = yield* Effect.promise(() =>
46
+ web.handler(new Request("http://localhost:3000/api/health")),
47
+ );
48
+ expect(health.status).toBe(204);
49
+ const response = yield* Effect.promise(() =>
50
+ web.handler(new Request("http://localhost:3000/api")),
51
+ );
52
+ expect(response.status).toBe(200);
53
+ const hello = yield* Schema.decodeUnknownEffect(Hello)(
54
+ yield* Effect.promise(() => response.json()),
55
+ );
56
+ expect(hello.dual).toMatchObject({ identifier: {{appIdJson}} });
57
+ }),
58
+ );
@@ -0,0 +1,16 @@
1
+ import { expect, it } from "@effect/vitest";
2
+ import { DualRuntime } from "@dual-os/sdk";
3
+ import { Customer } from {{pluginPackageJson}};
4
+ import pluginPackage from {{pluginMetadataJson}} with { type: "json" };
5
+ import { Effect } from "effect";
6
+
7
+ it.effect("executes the customer-owned plugin without infrastructure", () =>
8
+ Effect.gen(function* () {
9
+ const customer = DualRuntime.fromPlugin(Customer.customerPlugin, pluginPackage.version);
10
+ const result = yield* DualRuntime.invoke(customer, {
11
+ actionId: {{pingIdJson}},
12
+ input: { message: "hello" },
13
+ });
14
+ expect(result.data).toEqual({ echoed: "hello" });
15
+ }),
16
+ );
@@ -0,0 +1,5 @@
1
+ {
2
+ "extends": "@deslop/coding-standards/tsconfig.json",
3
+ "compilerOptions": { "types": ["bun-types"] },
4
+ "include": ["packages/**/*.ts", "vitest*.config.ts"]
5
+ }
@@ -0,0 +1,5 @@
1
+ import { defineConfig } from "vitest/config";
2
+ export const testTimeout = 60_000;
3
+ export default defineConfig({
4
+ test: { include: ["packages/**/*.test.ts"], testTimeout, hookTimeout: testTimeout },
5
+ });
@@ -0,0 +1,6 @@
1
+ import { defineConfig } from "vitest/config";
2
+
3
+ import { testTimeout } from "./vitest.config.ts";
4
+ export default defineConfig({
5
+ test: { include: ["packages/**/*.host-test.ts"], testTimeout, hookTimeout: testTimeout },
6
+ });