@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
package/src/skills.ts ADDED
@@ -0,0 +1,434 @@
1
+ import { cp, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rm } from "node:fs/promises";
2
+ import { createRequire } from "node:module";
3
+ import { homedir, tmpdir } from "node:os";
4
+ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
5
+ import { fileURLToPath } from "node:url";
6
+
7
+ import { Array, Console, Context, Effect, Layer, Option, Schema, Stdio, Stream } from "effect";
8
+
9
+ import { Argument, Command, Flag } from "effect/cli";
10
+ import { ChildProcess, ChildProcessSpawner } from "effect/process";
11
+
12
+ const directory = new URL("../skills/dual-fde/", import.meta.url);
13
+ const references = [
14
+ "access",
15
+ "author-plugins",
16
+ "cli",
17
+ "manage-plugins",
18
+ "migrations-deployment",
19
+ "openapi-plugins",
20
+ "sdk-docs",
21
+ "upgrades",
22
+ "working-context",
23
+ ] as const;
24
+ const Read = Schema.Struct({
25
+ full: Schema.Boolean,
26
+ reference: Schema.optional(Schema.Literals(references)),
27
+ });
28
+ const Agent = Schema.String.check(Schema.isPattern(/^[a-z][a-z0-9-]*$/));
29
+ const Install = Schema.Struct({
30
+ agents: Schema.Array(Agent).check(Schema.isMinLength(1)),
31
+ global: Schema.Boolean,
32
+ /** User scope root, also the installer's HOME. */
33
+ home: Schema.NonEmptyString,
34
+ /** Project scope root and installer working directory. */
35
+ project: Schema.NonEmptyString,
36
+ yes: Schema.Boolean,
37
+ });
38
+ const Installed = Schema.fromJsonString(
39
+ Schema.Array(Schema.Struct({ name: Schema.String, path: Schema.String })),
40
+ );
41
+
42
+ export class SkillsError extends Schema.TaggedError<SkillsError>()("SkillsError", {
43
+ cause: Schema.optional(Schema.Defect()),
44
+ message: Schema.String,
45
+ }) {}
46
+
47
+ const Staged = Schema.fromJsonString(
48
+ Schema.Array(
49
+ Schema.Struct({
50
+ mode: Schema.Literal("copy"),
51
+ name: Schema.Literal("dual-fde"),
52
+ path: Schema.String,
53
+ scope: Schema.Literals(["project", "global"]),
54
+ status: Schema.Literal("installed"),
55
+ }),
56
+ ).check(Schema.isMinLength(1), Schema.isMaxLength(1)),
57
+ );
58
+ const Missing = Schema.Struct({ code: Schema.Literal("ENOENT") });
59
+
60
+ // Unlike installer discovery, lstat sees invalid skills, files and dangling links.
61
+ const inspectDestination = (destination: string) =>
62
+ Effect.runPromise(
63
+ Effect.forEach(
64
+ Array.unfold(Option.some(destination), current =>
65
+ Option.map(
66
+ current,
67
+ path =>
68
+ [
69
+ path,
70
+ dirname(path) === path ? Option.none<string>() : Option.some(dirname(path)),
71
+ ] as const,
72
+ ),
73
+ ),
74
+ current =>
75
+ Effect.gen(function* () {
76
+ const entry = yield* Effect.tryPromise(() => lstat(current)).pipe(
77
+ Effect.catchIf(
78
+ cause => Schema.is(Missing)(cause.cause),
79
+ () => Effect.void,
80
+ ),
81
+ );
82
+ if (entry && (current === destination || !entry.isDirectory())) {
83
+ return yield* new SkillsError({
84
+ message: `Refusing existing target or non-directory/symlink ancestor: ${current}. Preserve customer edits and move the conflict aside before reinstalling.`,
85
+ });
86
+ }
87
+ }),
88
+ { discard: true },
89
+ ),
90
+ );
91
+
92
+ export type Interface = {
93
+ readonly get: (options: typeof Read.Type) => Effect.Effect<string, SkillsError>;
94
+ readonly install: (options: typeof Install.Type) => Effect.Effect<void, SkillsError>;
95
+ };
96
+ export class Service extends Context.Service<Service, Interface>()("@dual-os/cli/Skills") {}
97
+
98
+ export const layer = Layer.effect(
99
+ Service,
100
+ Effect.gen(function* () {
101
+ const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
102
+ const stdio = yield* Stdio.Stdio;
103
+ const inspect = Effect.fn("Skills.inspect")(function* (command: ChildProcess.Command) {
104
+ const child = yield* spawner.spawn(command);
105
+ const [output, diagnostics, code] = yield* Effect.all(
106
+ [
107
+ Stream.mkString(Stream.decodeText(child.stdout)),
108
+ Stream.mkString(Stream.decodeText(child.stderr)),
109
+ child.exitCode,
110
+ ],
111
+ { concurrency: "unbounded" },
112
+ );
113
+ if (code !== 0) {
114
+ return yield* new SkillsError({
115
+ cause: new Error(diagnostics),
116
+ message:
117
+ "Pinned skills installer refused discovery/staging. Check --agent; custom path overrides are refused for --yes. No customer files were changed.",
118
+ });
119
+ }
120
+ return output;
121
+ }, Effect.scoped);
122
+ const get = Effect.fn("Skills.get")(
123
+ function* (input: typeof Read.Type) {
124
+ const options = yield* Schema.decodeUnknownEffect(Read)(input);
125
+ if (options.full && options.reference !== undefined) {
126
+ return yield* new SkillsError({ message: "Use either --reference or --full, not both." });
127
+ }
128
+ return yield* Effect.tryPromise({
129
+ catch: cause =>
130
+ new SkillsError({
131
+ cause,
132
+ message: "Bundled skill unavailable. Reinstall this exact CLI package.",
133
+ }),
134
+ try: async () => {
135
+ const paths = options.full
136
+ ? ["SKILL.md", ...Array.map(references, name => `references/${name}.md`)]
137
+ : [options.reference ? `references/${options.reference}.md` : "SKILL.md"];
138
+ return Array.join(
139
+ await Promise.all(
140
+ Array.map(paths, async path => {
141
+ const text = await readFile(new URL(path, directory), "utf8");
142
+ return options.full ? `# ${path}\n\n${text}` : text;
143
+ }),
144
+ ),
145
+ "\n\n",
146
+ );
147
+ },
148
+ });
149
+ },
150
+ Effect.mapError(cause =>
151
+ cause instanceof SkillsError
152
+ ? cause
153
+ : new SkillsError({ cause, message: "Invalid skill read options." }),
154
+ ),
155
+ );
156
+ const install = Effect.fn("Skills.install")(
157
+ function* (input: typeof Install.Type) {
158
+ const options = yield* Schema.decodeUnknownEffect(Install)(input);
159
+ const terminal = (yield* stdio.stdinIsTerminal) && (yield* stdio.stdoutIsTerminal);
160
+ if (!options.yes && !terminal) {
161
+ return yield* new SkillsError({
162
+ message:
163
+ "Skill installation requires an interactive terminal or explicit --yes with --agent. No files were changed.",
164
+ });
165
+ }
166
+ if (process.versions["bun"]) {
167
+ return yield* new SkillsError({
168
+ message: "Run skill installation with Node 22.20+ (not Bun).",
169
+ });
170
+ }
171
+ const executable = yield* Effect.try({
172
+ catch: cause =>
173
+ new SkillsError({
174
+ cause,
175
+ message: "Pinned skills installer unavailable. Reinstall the CLI dependencies.",
176
+ }),
177
+ try: () =>
178
+ join(
179
+ dirname(createRequire(import.meta.url).resolve("skills/package.json")),
180
+ "bin/cli.mjs",
181
+ ),
182
+ });
183
+ const command = (args: readonly string[]) =>
184
+ ChildProcess.make(process.execPath, [executable, ...args], {
185
+ cwd: options.project,
186
+ env: { DISABLE_TELEMETRY: "1", HOME: options.home, USERPROFILE: options.home },
187
+ extendEnv: true,
188
+ });
189
+ const scope = options.global ? ["--global"] : [];
190
+ const output = yield* inspect(command(["list", "--json", ...scope]));
191
+ const installed = yield* Schema.decodeUnknownEffect(Installed)(output);
192
+ if (
193
+ Array.some(
194
+ installed,
195
+ skill => skill.name === "dual-fde" || basename(skill.path) === "dual-fde",
196
+ )
197
+ ) {
198
+ return yield* new SkillsError({
199
+ message:
200
+ "dual-fde already exists in this scope. Preserve/review customer edits and move the existing installation aside before explicitly reinstalling. No files were changed.",
201
+ });
202
+ }
203
+ if (options.yes) {
204
+ // 1.7.0 has no no-clobber/plan API; list omits malformed skills and add
205
+ // destroys targets even in copy mode. Never run add --yes in user scope.
206
+ // Upstream chooses paths in a write-restricted staging scope; Dual only
207
+ // publishes its copies to absent paths, without an agent-path registry.
208
+ yield* Effect.gen(function* () {
209
+ const stage = yield* Effect.acquireRelease(
210
+ Effect.tryPromise(async () =>
211
+ realpath(await mkdtemp(join(tmpdir(), "dual-skills-"))),
212
+ ),
213
+ path => Effect.promise(() => rm(path, { force: true, recursive: true })),
214
+ );
215
+ const home = join(stage, "home");
216
+ const project = join(stage, "project");
217
+ yield* Effect.tryPromise(async () => {
218
+ await mkdir(home);
219
+ await mkdir(project);
220
+ // Preserve upstream's home-root detection (e.g. legacy agent roots)
221
+ // without exposing their contents to writes in the staging process.
222
+ if (options.global) {
223
+ for (const entry of await readdir(options.home, { withFileTypes: true })) {
224
+ if (entry.isDirectory() || entry.isSymbolicLink()) {
225
+ await mkdir(join(home, entry.name));
226
+ }
227
+ }
228
+ }
229
+ });
230
+ const sourceBase = options.global ? home : project;
231
+ const targetBase = yield* Effect.tryPromise(() =>
232
+ realpath(options.global ? options.home : options.project),
233
+ );
234
+ const destinations = new Map<string, string>();
235
+ for (const agent of new Set(options.agents)) {
236
+ const result = yield* inspect(
237
+ ChildProcess.make(
238
+ process.execPath,
239
+ [
240
+ "--permission",
241
+ "--allow-fs-read=*",
242
+ `--allow-fs-write=${stage}`,
243
+ executable,
244
+ "add",
245
+ fileURLToPath(directory),
246
+ "--skill",
247
+ "dual-fde",
248
+ "--agent",
249
+ agent,
250
+ "--copy",
251
+ "--yes",
252
+ "--json",
253
+ ...scope,
254
+ ],
255
+ {
256
+ cwd: project,
257
+ env: {
258
+ DISABLE_TELEMETRY: "1",
259
+ HOME: home,
260
+ NODE_OPTIONS: "",
261
+ USERPROFILE: home,
262
+ },
263
+ extendEnv: true,
264
+ },
265
+ ),
266
+ );
267
+ const staged = yield* Schema.decodeUnknownEffect(Staged)(result);
268
+ for (const skill of staged) {
269
+ const path = relative(sourceBase, skill.path);
270
+ if (
271
+ !isAbsolute(skill.path) ||
272
+ isAbsolute(path) ||
273
+ path === ".." ||
274
+ path.startsWith(`..${sep}`) ||
275
+ basename(path) !== "dual-fde" ||
276
+ skill.scope !== (options.global ? "global" : "project")
277
+ ) {
278
+ return yield* new SkillsError({
279
+ message:
280
+ "Installer returned an unexpected staging path/scope. No customer files were changed.",
281
+ });
282
+ }
283
+ destinations.set(resolve(targetBase, path), skill.path);
284
+ }
285
+ }
286
+ // Check every destination before publishing any of them. In particular,
287
+ // reject symlink ancestors and malformed/missing SKILL.md collisions.
288
+ yield* Effect.tryPromise({
289
+ catch: cause =>
290
+ cause instanceof SkillsError
291
+ ? cause
292
+ : new SkillsError({
293
+ cause,
294
+ message:
295
+ "Could not publish the snapshot without overwriting. Inspect any partial installation before retrying.",
296
+ }),
297
+ try: async () => {
298
+ for (const [destination] of destinations) {
299
+ await inspectDestination(destination);
300
+ }
301
+ for (const [destination, source] of destinations) {
302
+ await mkdir(dirname(destination), { recursive: true });
303
+ await inspectDestination(destination);
304
+ await mkdir(destination); // Exclusive claim, never recursive at the target.
305
+ for (const entry of await readdir(source)) {
306
+ await cp(join(source, entry), join(destination, entry), {
307
+ errorOnExist: true,
308
+ force: false,
309
+ recursive: true,
310
+ });
311
+ }
312
+ }
313
+ },
314
+ });
315
+ for (const [destination] of destinations) {
316
+ yield* Console.log(`Installed dual-fde snapshot: ${destination}`);
317
+ }
318
+ }).pipe(Effect.scoped);
319
+ return;
320
+ }
321
+ yield* Console.log(
322
+ options.global
323
+ ? "Installing the bundled snapshot globally. Cancel unexpected overwrites; local sources do not auto-update."
324
+ : "Choose Project in the installer's scope prompt. Cancel unexpected overwrites or scope changes; local sources do not auto-update.",
325
+ );
326
+ const code = yield* spawner.exitCode(
327
+ ChildProcess.make(
328
+ process.execPath,
329
+ [
330
+ executable,
331
+ "add",
332
+ fileURLToPath(directory),
333
+ "--skill",
334
+ "dual-fde",
335
+ ...Array.flatMap(options.agents, agent => ["--agent", agent]),
336
+ ...scope,
337
+ ],
338
+ {
339
+ cwd: options.project,
340
+ env: { DISABLE_TELEMETRY: "1", HOME: options.home, USERPROFILE: options.home },
341
+ extendEnv: true,
342
+ stderr: "inherit",
343
+ stdin: "inherit",
344
+ stdout: "inherit",
345
+ },
346
+ ),
347
+ );
348
+ if (code !== 0) {
349
+ return yield* new SkillsError({
350
+ message: "Skill installer failed or was cancelled. Inspect its output before retrying.",
351
+ });
352
+ }
353
+ },
354
+ Effect.mapError(cause =>
355
+ cause instanceof SkillsError
356
+ ? cause
357
+ : new SkillsError({
358
+ cause,
359
+ message:
360
+ "Could not safely inspect/install skills. No overwrite is attempted. Non-interactive installs require standard agent paths within the selected scope; custom path overrides are refused. Inspect any partial installation before retrying.",
361
+ }),
362
+ ),
363
+ );
364
+ return Service.of({ get, install });
365
+ }),
366
+ );
367
+
368
+ export const command = Command.make("skills").pipe(
369
+ Command.withAlias("skill"),
370
+ Command.withDescription(
371
+ "Read bundled instructions offline or explicitly install a project-scoped snapshot.",
372
+ ),
373
+ Command.withShortDescription("Read/install bundled skills"),
374
+ Command.withSubcommands([
375
+ Command.make("list", {}, () => Console.log("dual-fde")),
376
+ Command.make(
377
+ "get",
378
+ {
379
+ full: Flag.Boolean("full").pipe(
380
+ Flag.withDefault(false),
381
+ Flag.withDescription(
382
+ "Read the index and all nine references; conflicts with --reference",
383
+ ),
384
+ ),
385
+ name: Argument.Literals("name", ["dual-fde"]),
386
+ reference: Flag.Literals("reference", references).pipe(
387
+ Flag.optional,
388
+ Flag.withDescription("Read one task reference instead of the index"),
389
+ ),
390
+ },
391
+ ({ reference, full }) =>
392
+ Effect.flatMap(Service, skills =>
393
+ Effect.flatMap(
394
+ skills.get({ full, reference: Option.getOrUndefined(reference) }),
395
+ Console.log,
396
+ ),
397
+ ),
398
+ ).pipe(
399
+ Command.withDescription(
400
+ "Read only SKILL.md by default. Follow a references/<name>.md link with dual skill get dual-fde --reference <name>.",
401
+ ),
402
+ ),
403
+ Command.make(
404
+ "install",
405
+ {
406
+ agents: Flag.String("agent").pipe(
407
+ Flag.withSchema(Agent),
408
+ Flag.atLeast(1),
409
+ Flag.withDescription("Explicit installer agent identifier; repeat for multiple agents"),
410
+ ),
411
+ global: Flag.Boolean("global").pipe(
412
+ Flag.withDefault(false),
413
+ Flag.withDescription(
414
+ "Explicit opt-in to user-global scope instead of the current project",
415
+ ),
416
+ ),
417
+ yes: Flag.Boolean("yes").pipe(
418
+ Flag.withDefault(false),
419
+ Flag.withAlias("y"),
420
+ Flag.withDescription(
421
+ "Confirm a non-interactive, create-only snapshot install for the selected agents",
422
+ ),
423
+ ),
424
+ },
425
+ // The CLI boundary owns the ambient scope roots; the service never reads them.
426
+ options =>
427
+ Effect.flatMap(Service, skills =>
428
+ skills.install({ ...options, home: homedir(), project: process.cwd() }),
429
+ ),
430
+ ),
431
+ ]),
432
+ );
433
+
434
+ export * as Skills from "./skills.ts";
@@ -0,0 +1,3 @@
1
+ # Copy to ignored .env.compose and pass --env-file .env.compose to Docker Compose.
2
+ # Do not put container-only DNS/config in Bun's auto-loaded .env.
3
+ {{envExample}}
@@ -0,0 +1,4 @@
1
+ # Copy to ignored .env.host. Same host choices/keys as .env.compose, but DATABASE_URL
2
+ # reaches the forwarded PostgreSQL port at 127.0.0.1, not Compose DNS postgres.
3
+ # DUAL_FILE_STORAGE_ROOT stays .dual/storage, shared with full Compose.
4
+ {{envExample}}
@@ -0,0 +1,12 @@
1
+ # syntax=docker/dockerfile:1
2
+ # Customer-owned image. Add selected plugins' OS prerequisites here explicitly.
3
+ FROM {{bunImage}}
4
+ WORKDIR /app
5
+ COPY package.json bun.lock ./
6
+ COPY packages ./packages
7
+ # Registry access is a BuildKit secret, never a COPY, ARG or image environment.
8
+ # Install first in the repository and commit the native lockfile. No resolution drift.
9
+ RUN --mount=type=secret,id=npmrc,target=/root/.npmrc,required=true bun install --frozen-lockfile
10
+ ENV NODE_ENV=production
11
+ EXPOSE {{apiPort}}
12
+ CMD ["bun", "run", "api"]
@@ -0,0 +1,159 @@
1
+ # Customer-owned Compose operation
2
+
3
+ Generation starts no services and performs no initialization. **Explicit Compose
4
+ startup affects the configured database**: migrate → registry-sync → bootstrap
5
+ are distinct one-shot jobs, then API/worker start. API/worker startup never
6
+ migrates. Existing migration semantics apply; no new locking, recovery or rollback
7
+ guarantee is introduced. Never point tests at existing/shared/customer databases.
8
+
9
+ ## Exact pair and immutable images
10
+
11
+ These files were generated from a completed manifest (optionally selected with
12
+ `--release CORE_VERSION` for its newest compatible snapshot, or `--manifest
13
+ 0.0.<pipeline-id>` for an exact snapshot) or an explicit `--release-pair record.json
14
+ --web-image repository@sha256:…`. `dual.release.json` preserves the complete
15
+ manifest and archive integrity, or the legacy coreVersion/imageDigest/commit mapping. Committed, non-secret `release.env` selects
16
+ `DUAL_WEB_IMAGE`; Compose stays static and fails if that selection is missing.
17
+ The core must match the selected manifest (the fixed baseline for legacy pair
18
+ inputs), and the web reference must match its qualified digest. No completed pair/default
19
+ is invented. A supplied record is not a new certification. A local sha256 image
20
+ ID is accepted only for isolated validation, not as a published/portable release.
21
+
22
+ Install with Bun 1.4.2, run check-types/test and test:host against a fresh disposable
23
+ PostgreSQL database, and commit native bun.lock. Skip-install has no installed-tree
24
+ guarantee. Build one customer image containing the host and selected plugins:
25
+
26
+ ```sh
27
+ mkdir -p .dual/storage
28
+ docker build --secret id=npmrc,src=/EXTERNAL/PATH/npmrc --iidfile .dual/image-id .
29
+ ```
30
+
31
+ The Dockerfile uses a versioned Bun 1.4.2 base and --frozen-lockfile. Add selected
32
+ plugins' OS prerequisites there; no monorepo/web source is needed. Registry access
33
+ is an external BuildKit secret, never COPY/ARG/environment baked into an image.
34
+
35
+ Publication/deployment requires separate authorization. Supply CUSTOMER_IMAGE as
36
+ an immutable repository@sha256 digest (or local ID for isolated validation), never
37
+ latest or a mutable tag. Pull the customer digest explicitly before startup:
38
+ customer pull_policy is never, so missing local IDs cannot become registry tags.
39
+ Local web IDs also use never; a registry-qualified web digest can be pulled by
40
+ Compose through your external Docker credentials. API, worker and all jobs use
41
+ the same customer image. Promote these exact bytes, never rebuild per environment.
42
+ The web image is Caddy with the built app: it serves the app and proxies the API
43
+ on one origin, so browser API requests stay same-origin. No backend address is a
44
+ build input.
45
+
46
+ ## Explicit environment configuration
47
+
48
+ **Shared files.** Local object directories are private to their process user.
49
+ Before the first start, set `user: "<native uid>:<native gid>"` on `x-customer`
50
+ in `compose.yaml` when switching between container and native modes; obtain the
51
+ values with `id -u` and `id -g`. Keep this identity for every customer service.
52
+ Existing data with a different owner needs an authorized ownership transfer;
53
+ do not widen directory permissions or silently change ownership.
54
+
55
+ Use Docker Compose >= 2.24.4. Copy .env.compose.example to ignored .env.compose.
56
+ Supply authorized auth/vault keys, sender identity, bootstrap admin/organization,
57
+ and selected S3/SMTP/telemetry settings externally. Local PostgreSQL uses
58
+ `postgres:5432`, user/database `dual`, and the supplied POSTGRES_PASSWORD; set
59
+ DATABASE_URL accordingly. No credentials are generated or collected. Bootstrap
60
+ reruns never reset passwords or elevate existing users; conflicts stop startup.
61
+
62
+ APP_ORIGIN, BETTER_AUTH_URL and SERVER_PUBLIC_URL all name the web origin
63
+ (generated {{appOrigin}}), not the private API. DUAL_HTTP_PORT binds loopback,
64
+ not a production ingress. Do not print resolved Compose environments into logs.
65
+ Do not place container-only DNS/configuration in Bun's auto-loaded .env: these
66
+ modes deliberately use separate .env.compose and .env.host files. All real .env\*
67
+ and registry files are excluded from Git/images; only examples are committed.
68
+
69
+ The web service's site address (`DUAL_SITE_ADDRESS`) comes from validated
70
+ `--hostname`; localhost keeps the catch-all local listener. Other names restrict
71
+ HTTP Host matching; arrange local name resolution yourself. No certificates or
72
+ public TLS are provisioned. API/probe ports follow `--api-port`; host-run
73
+ overrides must match the API listener. The API upstream is an environment
74
+ parameter (`DUAL_API_UPSTREAM`). It is trusted operator configuration, not a
75
+ client/request input: use only an internal host:port address, never untrusted
76
+ strings, credentials or Caddy fragments. Public/auth origins remain runtime
77
+ configuration; changing DUAL_HTTP_PORT requires updating all three.
78
+
79
+ The web service sends the build's Brotli copies to browsers that accept them and
80
+ caches hashed assets for a year. No hosted deployment files are
81
+ regenerated. Bootstrap still requires the full existing credential set when the
82
+ explicit initialization job runs; removing those fields is not a supported skip.
83
+
84
+ ## Full Compose
85
+
86
+ ```sh
87
+ docker compose --env-file .env.compose --env-file release.env up -d --wait
88
+ docker compose --env-file .env.compose --env-file release.env ps
89
+ docker compose --env-file .env.compose --env-file release.env run --rm --no-deps registry-sync bun run registry:check
90
+ ```
91
+
92
+ Local files use the customer-owned .dual/storage bind directory shared by API and
93
+ worker. PostgreSQL uses a persistent named volume. `docker compose --env-file
94
+ .env.compose --env-file release.env down` preserves both. Never use -v on an existing environment unless
95
+ intentionally authorized to destroy its database. Diagnose failed migration,
96
+ registry or bootstrap jobs before retrying; do not force or bypass blockers.
97
+
98
+ For external PostgreSQL append `-f compose.yaml -f compose.external.yaml` to the
99
+ Compose command and supply an authorized DATABASE_URL. This disables local
100
+ PostgreSQL/readiness dependencies, not provisions the external server. S3, SMTP
101
+ and OTLP use existing external services when selected; no OpenSandbox or telemetry
102
+ backend is mandatory for just-bash. If OpenSandbox was selected, its external
103
+ server/image configuration is required by API and worker; see OPEN-SANDBOX.md.
104
+
105
+ ## Host-run API and worker
106
+
107
+ This is an alternative to full Compose, not a concurrent stack. Stop the full
108
+ stack with `down` without -v first. Keep the same built/pre-pulled customer image:
109
+ initialization jobs still use it even though API/worker will run locally.
110
+
111
+ In .env.compose choose available DUAL_POSTGRES_PORT (generated {{postgresPort}}) and
112
+ DUAL_API_PORT (default {{apiPort}}); keep DATABASE_URL using `postgres:5432` for jobs.
113
+ Copy .env.host.example to ignored .env.host. Supply the same application keys and
114
+ selected host services, but DATABASE_URL must use `127.0.0.1:<DUAL_POSTGRES_PORT>`
115
+ with the same approved credentials. Match DUAL_API_PORT and public origins to
116
+ .env.compose; keep DUAL_FILE_STORAGE_ROOT=.dual/storage. Both local processes and
117
+ full Compose share those files. Do not retain a database while changing its file
118
+ storage location without an authorized data-transfer plan.
119
+
120
+ ```sh
121
+ mkdir -p .dual/storage
122
+ docker compose --env-file .env.compose --env-file release.env -f compose.yaml -f compose.host.yaml up -d --wait
123
+ # Separate host terminals:
124
+ bun run api:local
125
+ bun run worker:local
126
+ # Optional watch-mode alternatives: bun run dev:api / bun run dev:worker
127
+ ```
128
+
129
+ On native Linux append `-f compose.host-linux.yaml` to the Compose command. This
130
+ supplies host-gateway mappings. Desktop/Colima already resolve host.docker.internal
131
+ to the physical host: do NOT override their DNS with a VM gateway. Colima needs
132
+ the repository under a VM-shared path such as $HOME. Local API listeners must be
133
+ reachable from containers; use an isolated development machine/firewall, not an
134
+ untrusted public interface. Only web/Postgres published ports are loopback-bound.
135
+
136
+ Open the same web URL. Browser API requests stay same-origin; the web service
137
+ reaches host.docker.internal:<DUAL_API_PORT>. It may start before the
138
+ local API, so transient gateway failures are expected until it is healthy. Neither
139
+ local command migrates or synchronizes. Compose startup may run initialization
140
+ jobs; obtain database-operation authorization first. The external PostgreSQL
141
+ overlay also works here with reachable internal/host URLs for the same database.
142
+
143
+ ## Adoption and ownership
144
+
145
+ Generated files are customer-owned. There is no managed mode switch, regeneration
146
+ over existing edits, or generator upgrade system. Older repositories using named
147
+ file volumes need a separately authorized transfer to adopt this shared bind
148
+ layout; generation never copies stored data. Upgrades require an explicit adoption
149
+ MR reviewing pins/native lockfile, core/web pair, customer code, SQL migration
150
+ compatibility and registry plan/check/sync together. For a frontend-only update,
151
+ review and commit just `release.env` and `dual.release.json` using a completed
152
+ release asset with the same installed core version; do not bump backend packages.
153
+ For a core update, also change exact package pins and the native lockfile and
154
+ validate migrations/customer code. Never regenerate over customer-owned files or
155
+ edit `dual.scaffold.json` to pretend the original scaffold used newer artifacts.
156
+ An already open frontend checks `/api/version`: green means a recently reachable,
157
+ exactly matching core; red means mismatch, unavailable, invalid or stale metadata.
158
+ The icon does not force reload or discard unsaved work. Previous image pairs can be
159
+ restored only when database compatibility permits it; no DB rollback is promised.
@@ -0,0 +1,14 @@
1
+ **/node_modules
2
+ .git
3
+ .gitmodules
4
+ .agents/
5
+ vendor/
6
+ .env
7
+ .env.*
8
+ **/.env
9
+ **/.env.*
10
+ **/.npmrc
11
+ **/bunfig.toml
12
+ .dual
13
+ coverage
14
+ dist
@@ -0,0 +1,7 @@
1
+ # Docker Compose >= 2.24.0. Use with -f compose.yaml -f compose.external.yaml.
2
+ # Supply DATABASE_URL for the authorized external PostgreSQL server in .env.compose.
3
+ services:
4
+ postgres:
5
+ profiles: [unused-local-database]
6
+ migrate:
7
+ depends_on: !reset {}
@@ -0,0 +1,5 @@
1
+ # Native Linux Docker only: Desktop/Colima already resolve host.docker.internal
2
+ # to the physical host. Do not override their DNS with the VM's Docker gateway.
3
+ services:
4
+ web:
5
+ extra_hosts: ["host.docker.internal:host-gateway"]
@@ -0,0 +1,15 @@
1
+ # Docker Compose >= 2.24.4. API/worker run on the host, not in containers.
2
+ # Use with -f compose.yaml -f compose.host.yaml. Jobs remain explicit Compose jobs.
3
+ services:
4
+ postgres:
5
+ ports:
6
+ - "127.0.0.1:{{hostPostgresPort}}:5432"
7
+ api:
8
+ profiles: [full-compose-only]
9
+ worker:
10
+ profiles: [full-compose-only]
11
+ web:
12
+ environment:
13
+ DUAL_API_UPSTREAM: "host.docker.internal:{{hostApiPort}}"
14
+ depends_on: !override
15
+ bootstrap: { condition: service_completed_successfully }