@rcpooley/concord 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (176) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +318 -0
  3. package/bin/concord.service +69 -0
  4. package/dist/age.d.ts +20 -0
  5. package/dist/age.d.ts.map +1 -0
  6. package/dist/age.js +58 -0
  7. package/dist/age.js.map +1 -0
  8. package/dist/cli/main.d.ts +3 -0
  9. package/dist/cli/main.d.ts.map +1 -0
  10. package/dist/cli/main.js +301 -0
  11. package/dist/cli/main.js.map +1 -0
  12. package/dist/daemon.d.ts +4 -0
  13. package/dist/daemon.d.ts.map +1 -0
  14. package/dist/daemon.js +394 -0
  15. package/dist/daemon.js.map +1 -0
  16. package/dist/eval-config.d.ts +2 -0
  17. package/dist/eval-config.d.ts.map +1 -0
  18. package/dist/eval-config.js +45 -0
  19. package/dist/eval-config.js.map +1 -0
  20. package/dist/exec.d.ts +168 -0
  21. package/dist/exec.d.ts.map +1 -0
  22. package/dist/exec.js +313 -0
  23. package/dist/exec.js.map +1 -0
  24. package/dist/git.d.ts +59 -0
  25. package/dist/git.d.ts.map +1 -0
  26. package/dist/git.js +265 -0
  27. package/dist/git.js.map +1 -0
  28. package/dist/hook.d.ts +37 -0
  29. package/dist/hook.d.ts.map +1 -0
  30. package/dist/hook.js +89 -0
  31. package/dist/hook.js.map +1 -0
  32. package/dist/index.d.ts +18 -0
  33. package/dist/index.d.ts.map +1 -0
  34. package/dist/index.js +15 -0
  35. package/dist/index.js.map +1 -0
  36. package/dist/init.d.ts +76 -0
  37. package/dist/init.d.ts.map +1 -0
  38. package/dist/init.js +236 -0
  39. package/dist/init.js.map +1 -0
  40. package/dist/loader.d.ts +35 -0
  41. package/dist/loader.d.ts.map +1 -0
  42. package/dist/loader.js +230 -0
  43. package/dist/loader.js.map +1 -0
  44. package/dist/module.d.ts +116 -0
  45. package/dist/module.d.ts.map +1 -0
  46. package/dist/module.js +100 -0
  47. package/dist/module.js.map +1 -0
  48. package/dist/modules/apt/index.d.ts +45 -0
  49. package/dist/modules/apt/index.d.ts.map +1 -0
  50. package/dist/modules/apt/index.js +249 -0
  51. package/dist/modules/apt/index.js.map +1 -0
  52. package/dist/modules/apt/schema.d.ts +63 -0
  53. package/dist/modules/apt/schema.d.ts.map +1 -0
  54. package/dist/modules/apt/schema.js +75 -0
  55. package/dist/modules/apt/schema.js.map +1 -0
  56. package/dist/modules/checkout/index.d.ts +88 -0
  57. package/dist/modules/checkout/index.d.ts.map +1 -0
  58. package/dist/modules/checkout/index.js +382 -0
  59. package/dist/modules/checkout/index.js.map +1 -0
  60. package/dist/modules/checkout/schema.d.ts +52 -0
  61. package/dist/modules/checkout/schema.d.ts.map +1 -0
  62. package/dist/modules/checkout/schema.js +132 -0
  63. package/dist/modules/checkout/schema.js.map +1 -0
  64. package/dist/modules/cloudflare/api.d.ts +64 -0
  65. package/dist/modules/cloudflare/api.d.ts.map +1 -0
  66. package/dist/modules/cloudflare/api.js +98 -0
  67. package/dist/modules/cloudflare/api.js.map +1 -0
  68. package/dist/modules/cloudflare/index.d.ts +74 -0
  69. package/dist/modules/cloudflare/index.d.ts.map +1 -0
  70. package/dist/modules/cloudflare/index.js +374 -0
  71. package/dist/modules/cloudflare/index.js.map +1 -0
  72. package/dist/modules/cloudflare/schema.d.ts +62 -0
  73. package/dist/modules/cloudflare/schema.d.ts.map +1 -0
  74. package/dist/modules/cloudflare/schema.js +85 -0
  75. package/dist/modules/cloudflare/schema.js.map +1 -0
  76. package/dist/modules/docker/index.d.ts +83 -0
  77. package/dist/modules/docker/index.d.ts.map +1 -0
  78. package/dist/modules/docker/index.js +470 -0
  79. package/dist/modules/docker/index.js.map +1 -0
  80. package/dist/modules/docker/registry.d.ts +35 -0
  81. package/dist/modules/docker/registry.d.ts.map +1 -0
  82. package/dist/modules/docker/registry.js +95 -0
  83. package/dist/modules/docker/registry.js.map +1 -0
  84. package/dist/modules/docker/render.d.ts +45 -0
  85. package/dist/modules/docker/render.d.ts.map +1 -0
  86. package/dist/modules/docker/render.js +162 -0
  87. package/dist/modules/docker/render.js.map +1 -0
  88. package/dist/modules/docker/schema.d.ts +231 -0
  89. package/dist/modules/docker/schema.d.ts.map +1 -0
  90. package/dist/modules/docker/schema.js +335 -0
  91. package/dist/modules/docker/schema.js.map +1 -0
  92. package/dist/modules/docker/sweeper.d.ts +64 -0
  93. package/dist/modules/docker/sweeper.d.ts.map +1 -0
  94. package/dist/modules/docker/sweeper.js +94 -0
  95. package/dist/modules/docker/sweeper.js.map +1 -0
  96. package/dist/modules/file/index.d.ts +79 -0
  97. package/dist/modules/file/index.d.ts.map +1 -0
  98. package/dist/modules/file/index.js +305 -0
  99. package/dist/modules/file/index.js.map +1 -0
  100. package/dist/modules/file/schema.d.ts +45 -0
  101. package/dist/modules/file/schema.d.ts.map +1 -0
  102. package/dist/modules/file/schema.js +114 -0
  103. package/dist/modules/file/schema.js.map +1 -0
  104. package/dist/modules/index.d.ts +20 -0
  105. package/dist/modules/index.d.ts.map +1 -0
  106. package/dist/modules/index.js +11 -0
  107. package/dist/modules/index.js.map +1 -0
  108. package/dist/modules/porkbun/api.d.ts +36 -0
  109. package/dist/modules/porkbun/api.d.ts.map +1 -0
  110. package/dist/modules/porkbun/api.js +62 -0
  111. package/dist/modules/porkbun/api.js.map +1 -0
  112. package/dist/modules/porkbun/index.d.ts +50 -0
  113. package/dist/modules/porkbun/index.d.ts.map +1 -0
  114. package/dist/modules/porkbun/index.js +236 -0
  115. package/dist/modules/porkbun/index.js.map +1 -0
  116. package/dist/modules/porkbun/schema.d.ts +38 -0
  117. package/dist/modules/porkbun/schema.d.ts.map +1 -0
  118. package/dist/modules/porkbun/schema.js +39 -0
  119. package/dist/modules/porkbun/schema.js.map +1 -0
  120. package/dist/modules/script/index.d.ts +43 -0
  121. package/dist/modules/script/index.d.ts.map +1 -0
  122. package/dist/modules/script/index.js +116 -0
  123. package/dist/modules/script/index.js.map +1 -0
  124. package/dist/modules/script/schema.d.ts +25 -0
  125. package/dist/modules/script/schema.d.ts.map +1 -0
  126. package/dist/modules/script/schema.js +63 -0
  127. package/dist/modules/script/schema.js.map +1 -0
  128. package/dist/modules/systemd/index.d.ts +93 -0
  129. package/dist/modules/systemd/index.d.ts.map +1 -0
  130. package/dist/modules/systemd/index.js +394 -0
  131. package/dist/modules/systemd/index.js.map +1 -0
  132. package/dist/modules/systemd/render.d.ts +41 -0
  133. package/dist/modules/systemd/render.d.ts.map +1 -0
  134. package/dist/modules/systemd/render.js +252 -0
  135. package/dist/modules/systemd/render.js.map +1 -0
  136. package/dist/modules/systemd/schema.d.ts +293 -0
  137. package/dist/modules/systemd/schema.d.ts.map +1 -0
  138. package/dist/modules/systemd/schema.js +302 -0
  139. package/dist/modules/systemd/schema.js.map +1 -0
  140. package/dist/modules/systemd/sweeper.d.ts +31 -0
  141. package/dist/modules/systemd/sweeper.d.ts.map +1 -0
  142. package/dist/modules/systemd/sweeper.js +77 -0
  143. package/dist/modules/systemd/sweeper.js.map +1 -0
  144. package/dist/plans.d.ts +132 -0
  145. package/dist/plans.d.ts.map +1 -0
  146. package/dist/plans.js +315 -0
  147. package/dist/plans.js.map +1 -0
  148. package/dist/records.d.ts +37 -0
  149. package/dist/records.d.ts.map +1 -0
  150. package/dist/records.js +100 -0
  151. package/dist/records.js.map +1 -0
  152. package/dist/registry.d.ts +38 -0
  153. package/dist/registry.d.ts.map +1 -0
  154. package/dist/registry.js +31 -0
  155. package/dist/registry.js.map +1 -0
  156. package/dist/runner.d.ts +48 -0
  157. package/dist/runner.d.ts.map +1 -0
  158. package/dist/runner.js +150 -0
  159. package/dist/runner.js.map +1 -0
  160. package/dist/scheduler.d.ts +36 -0
  161. package/dist/scheduler.d.ts.map +1 -0
  162. package/dist/scheduler.js +77 -0
  163. package/dist/scheduler.js.map +1 -0
  164. package/dist/schema.d.ts +762 -0
  165. package/dist/schema.d.ts.map +1 -0
  166. package/dist/schema.js +185 -0
  167. package/dist/schema.js.map +1 -0
  168. package/dist/secret.d.ts +24 -0
  169. package/dist/secret.d.ts.map +1 -0
  170. package/dist/secret.js +3 -0
  171. package/dist/secret.js.map +1 -0
  172. package/dist/ui.d.ts +62 -0
  173. package/dist/ui.d.ts.map +1 -0
  174. package/dist/ui.js +288 -0
  175. package/dist/ui.js.map +1 -0
  176. package/package.json +57 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Robert Pooley
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,318 @@
1
+ # Concord
2
+
3
+ A declarative config reconciler. You describe your hosts in a typed config
4
+ repo (containers, files, packages, systemd units, git checkouts, DNS
5
+ records) and push it. A small daemon pulls the repo, plans the difference
6
+ against reality and applies it.
7
+
8
+ **It does not replace the services it drives.** Docker keeps building and
9
+ supervising containers; systemd keeps supervising units; your DNS provider keeps
10
+ serving DNS. Concord says what should exist and drives their interfaces until it
11
+ does. Every module is a small, replaceable driver, so nothing home-rolled is
12
+ load-bearing.
13
+
14
+ This package is two things:
15
+
16
+ - **the reconciler**: the `concord` CLI and the `concord-daemon` that runs it on
17
+ a loop;
18
+ - **the schema library** your config repo imports, as types only, to get a
19
+ typechecked config.
20
+
21
+ > The package is scoped (`@rcpooley/concord`) because the bare name `concord` on
22
+ > the public npm registry is an unrelated package. Always run the CLI through an
23
+ > install (`npm run …`, or the global binary), never `npx concord`. npx falls
24
+ > back to the registry when a local bin is missing.
25
+
26
+ ## How it works
27
+
28
+ - **One primary host runs the daemon.** It reaches every other host over ssh
29
+ (or locally, for itself), so the other hosts need sshd, a key the primary
30
+ trusts and the tools the modules drive (Docker, systemd, git). They don't
31
+ need Concord itself.
32
+ - **The config is a git repo you own.** It default-exports a `ConcordConfig`
33
+ from `concord.ts`: a host registry and an ordered list of modules.
34
+ - **Secrets are age-encrypted in the config repo.** Anyone with the public key
35
+ (`age.pub`, committed) can add a secret. Only the daemon holds the private
36
+ key, in its environment.
37
+ - **The daemon reconciles on an interval** (default 15 minutes), and early
38
+ when asked: on `SIGHUP` (`systemctl reload concord`) or on a GitHub push
39
+ webhook. Each cycle pulls the config, evaluates it, plans every module in
40
+ order, and applies. A failure aborts the rest of the run, and the daemon
41
+ never claims convergence for a run that errored. It logs the failure and
42
+ tries again next cycle.
43
+ - **How Concord runs is never decided by the config.** Every daemon setting is
44
+ an environment variable, so a broken config can't take away the mechanism
45
+ that would fix it.
46
+
47
+ ## Install
48
+
49
+ On the host that will run the daemon, as the user it should run as (not
50
+ root). That user needs passwordless `sudo`, and the host needs systemd, git
51
+ and Node 20 or newer.
52
+
53
+ ```bash
54
+ sudo npm install -g @rcpooley/concord # or without sudo, if your npm prefix is user-owned (nvm)
55
+ concord init
56
+ ```
57
+
58
+ `concord init` checks those prerequisites, then:
59
+
60
+ - writes `/etc/concord.env` (root-only, 0600) with a **new age key** and an
61
+ empty `CONCORD_CONFIG_REPO`, and prints the key's public half for your config
62
+ repo's `age.pub`;
63
+ - writes `/etc/systemd/system/concord.service` for this user and this install
64
+ of node;
65
+ - enables and starts the service, which waits until it has a config repo.
66
+
67
+ Then point it at your config repo and restart:
68
+
69
+ ```bash
70
+ sudoedit /etc/concord.env # set CONCORD_CONFIG_REPO
71
+ sudo systemctl restart concord
72
+ journalctl -u concord -f
73
+ ```
74
+
75
+ Or pass `--config-repo <url>` to `concord init` to skip that step. The daemon
76
+ needs read access to the repo, so use a URL its user can already fetch, for
77
+ example over ssh with a deploy key.
78
+
79
+ `concord init` is safe to re-run. An existing env file is never touched, since
80
+ it holds the key your secrets are encrypted to. An existing unit that differs
81
+ (after moving node, say) is replaced only with `--replace-unit`. `--dry-run`
82
+ shows what it would do.
83
+
84
+ ## Usage
85
+
86
+ ```
87
+ concord plan # pull config, compute the plan, change nothing
88
+ # --no-sync: plan the checkout as-is; --result FILE: JSON result
89
+ concord run # pull config, compute the plan, apply it
90
+ concord keygen # generate an age keypair
91
+ concord secret set KEY # encrypt stdin into the config repo's secrets.ts
92
+ concord secret list # list declared secret names
93
+ ```
94
+
95
+ Environment:
96
+
97
+ | Var | Purpose |
98
+ |---|---|
99
+ | `CONCORD_CONFIG_REPO` | git URL of the config repo (required for `run`/`plan` and the daemon) |
100
+ | `CONCORD_AGE_KEY` | age private key, which decrypts secrets at runtime (required likewise) |
101
+ | `CONCORD_HOME` | working dir, default `~/.concord` |
102
+ | `CONCORD_CONFIG_DIR` | override the config checkout path |
103
+ | `CONCORD_INTERVAL_SECONDS` | daemon: seconds between reconciles (default 900, minimum 30) |
104
+ | `CONCORD_HOOK_SECRET` | daemon: GitHub webhook HMAC secret; unset means no webhook |
105
+ | `CONCORD_HOOK_SOCKET` | daemon: webhook socket (default `/run/concord/hook.sock`) |
106
+ | `CONCORD_UI_SOCKET` | daemon: UI/API socket (default `/run/concord/ui.sock`; `off` disables) |
107
+
108
+ ## Running the daemon
109
+
110
+ The daemon runs under systemd as an ordinary user with passwordless `sudo`
111
+ (the apt, file and systemd modules need it). `bin/concord.service` is the
112
+ template `concord init` renders the unit from. It reads its whole
113
+ configuration from `/etc/concord.env` (mode 0600, because it holds the age
114
+ key).
115
+
116
+ **Until `CONCORD_CONFIG_REPO` and `CONCORD_AGE_KEY` are both set, the daemon
117
+ waits.** It logs which ones are missing and does nothing else. It doesn't
118
+ exit, so systemd doesn't restart it in a loop. Set them, then
119
+ `sudo systemctl restart concord`. A reload won't do it, because systemd reads
120
+ the environment file only at start.
121
+
122
+ Day to day:
123
+
124
+ | | |
125
+ |---|---|
126
+ | Logs | `journalctl -u concord.service` |
127
+ | Reconcile now | `sudo systemctl reload concord` (SIGHUP to the daemon only). Never `systemctl kill -s HUP`, which signals every process in the unit and kills an apply in flight. |
128
+ | Stop | `sudo systemctl stop concord` finishes the cycle in flight first (up to 5 minutes) |
129
+ | Update | Concord never updates itself. The daemon logs a warning each cycle when a newer version exists: `sudo npm install -g @rcpooley/concord@<version>`, then `sudo systemctl restart concord`. |
130
+
131
+ **The webhook is optional.** With `CONCORD_HOOK_SECRET` set, the daemon listens
132
+ on `CONCORD_HOOK_SOCKET` for GitHub push deliveries, verifies the HMAC, and
133
+ reconciles. It never parses the payload, because Concord resolves every tracked
134
+ ref itself, so one org-level webhook covers every repo. Route a public HTTPS
135
+ endpoint to the socket with your reverse proxy. If the route breaks, deploys
136
+ are slower, never lost: the interval still runs.
137
+
138
+ ## The UI and plan API
139
+
140
+ The daemon also serves a UI and a JSON API on `CONCORD_UI_SOCKET`. **There is
141
+ no authentication.** Route it only on a private network (a VPN, a LAN, an ssh
142
+ tunnel), never publicly. Nothing in it changes production; the only write is
143
+ "plan this branch", which reads.
144
+
145
+ It shows the recent reconciles with their logs, and plans any branch of the
146
+ config on request. **Planning a change**: work on a branch, push it, plan it,
147
+ then merge it. Merging is the deploy.
148
+
149
+ ```bash
150
+ git checkout -b my-change origin/main # in your config repo
151
+ # edit, npm run typecheck, commit
152
+ git push -u origin my-change
153
+ curl -s -X POST 'https://<your UI address>/api/plans?wait=600' \
154
+ -H 'content-type: application/json' \
155
+ -d "{\"branch\": \"my-change\", \"sha\": \"$(git rev-parse HEAD)\"}"
156
+ # read result.modules[].ops, then merge my-change into main
157
+ ```
158
+
159
+ - A plan is the whole desired state of the branch, so **a branch behind `main`
160
+ is refused**, because it would show someone else's change being undone.
161
+ Rebase onto `origin/main` and push again.
162
+ - `sha` is optional; when given, the plan is refused unless the branch is at it.
163
+ - `?wait=N` holds the request until the plan finishes (at most 600 s). Without
164
+ it you get the queued plan back at once; poll `GET /api/plans/<id>?wait=N`.
165
+ - Plans run one at a time, in a child `concord plan --no-sync --result` against
166
+ a clone of their own (`$CONCORD_HOME/plans`), never the daemon's checkout.
167
+
168
+ | | |
169
+ |---|---|
170
+ | `GET /api/status` | idle or reconciling, next run, reconciler version and staleness |
171
+ | `GET /api/runs`, `/api/runs/<id>` | recent reconciles; the detail has the log |
172
+ | `POST /api/plans` `{branch, sha?}` | queue a plan (`202`); `400` bad input, `429` queue full |
173
+ | `GET /api/plans`, `/api/plans/<id>` | recent plans; the detail has the changes per module and the log |
174
+
175
+ A plan's `status` is `queued`, `running`, `planned`, `refused` (behind main, no
176
+ such branch, sha mismatch; see `error`) or `failed` (the plan aborted, timed
177
+ out, or crashed). `result.modules[].ops` are the changes; `ahead` is what the
178
+ branch adds over main.
179
+
180
+ ## Authoring a config repo
181
+
182
+ A config repo needs this package as a dev dependency (for the types and the
183
+ CLI), TypeScript, and an `age.pub`:
184
+
185
+ ```
186
+ git clone <your config repo> && cd <it>
187
+ npm install
188
+ printf '%s' 'value' | npm run secret -- set my-key # with "secret": "concord secret" in package.json
189
+ npm run typecheck
190
+ ```
191
+
192
+ `CONCORD_CONFIG_DIR` is unnecessary there: the CLI uses the current directory
193
+ when it contains an `age.pub`. Adding a secret needs only the public key, so
194
+ anyone (or any agent) can author a config without being able to read it.
195
+
196
+ ## How the config crosses the boundary
197
+
198
+ The config repo exports **plain data**, not class instances:
199
+
200
+ ```ts
201
+ import type { ConcordConfig } from '@rcpooley/concord' // erased at compile time
202
+ import { secrets } from './secrets.js'
203
+
204
+ const hosts = {
205
+ primary: { ip: '127.0.0.1', user: 'deploy', transport: 'local' },
206
+ web1: { ip: '10.0.0.12', user: 'deploy' }, // reached over ssh
207
+ } as const
208
+
209
+ export default {
210
+ schemaVersion: 8,
211
+ hosts,
212
+ modules: [
213
+ {
214
+ type: 'porkbun', id: 'porkbun',
215
+ apiKey: secrets['porkbun-api-key'], secretKey: secrets['porkbun-secret-key'],
216
+ zones: { /* … */ },
217
+ },
218
+ ],
219
+ } satisfies ConcordConfig<typeof hosts>
220
+ ```
221
+
222
+ `import type` vanishes during compilation, so **the config repo has zero runtime
223
+ dependency on this package**. The reconciler reads inert data, validates it with
224
+ zod, and builds its own module instances via `registry.ts`.
225
+
226
+ That property is load-bearing. An earlier design passed class instances across
227
+ this boundary, which meant the config's copy of the classes had to be forced to
228
+ resolve to the running reconciler via a symlink — and that symlink deleted the
229
+ running code when the CLI was invoked from inside a config checkout, which in
230
+ turn sent `npx` off to execute an unrelated package from the public registry.
231
+ Data across the boundary, instances built here.
232
+
233
+ It also means the resolved config is plain JSON you can dump and inspect.
234
+
235
+ ## Two DNS modules, two ownership rules
236
+
237
+ `porkbun` and `cloudflare` diff DNS the same way but disagree about what a zone
238
+ IS, and the difference decides what gets deleted.
239
+
240
+ **`porkbun`** — a declared zone is the whole truth. A live record the config
241
+ does not declare is removed. A zone absent from `zones` is never touched at all.
242
+
243
+ **`cloudflare`** — a declared zone is shared. Every record the module writes
244
+ carries a comment marked `concord:<id>`, and only marked records are ever
245
+ edited or deleted; anything else in the zone is reported once per run and left
246
+ alone. It is the systemd sweeper's rule (`X-Concord=1`) rather than the docker
247
+ sweeper's: the module can only ever remove what it created.
248
+
249
+ That is what lets a human co-own a zone — add a record in the dashboard and
250
+ Concord will not touch it. The cost is that Concord will not adopt one either:
251
+ declaring a record that already exists unowned fails the plan with a message
252
+ naming it, rather than silently taking it over. Delete it in the dashboard, or
253
+ stop declaring it.
254
+
255
+ ## Writing a module
256
+
257
+ ```ts
258
+ export class MyModule extends Module<MyState, MyOp> {
259
+ readonly kind = 'mymodule'
260
+ async desired(): Promise<MyState> { /* from this.config */ }
261
+ async read(): Promise<MyState> { /* enumerate the live target */ }
262
+ diff(actual, desired): MyOp[] { /* pure, no I/O */ }
263
+ async apply(ops): Promise<void> { /* call the service's API */ }
264
+ }
265
+ ```
266
+
267
+ A module declares its config schema **once**, in zod; the TypeScript type is
268
+ inferred from it (`z.infer`), so the author-time type and the runtime validator
269
+ cannot drift. `.strict()` is what rejects unknown keys. Register the class in
270
+ `registry.ts` and add the schema to the union in `schema.ts` — the registry is a
271
+ mapped type over the union, so forgetting one fails to compile.
272
+
273
+ Rules that are not negotiable:
274
+
275
+ - **`read()` is the entry requirement.** A module that cannot enumerate its
276
+ target does not get to be a module. That is what buys plan-before-apply, drift
277
+ detection, and safe adoption.
278
+ - **Every op declares its `kind`** (`create`/`update`/`delete`/`custom`), so the
279
+ runner can count, render, and later gate destructive changes without knowing
280
+ anything about the domain.
281
+ - **`diff()` is pure.** No network calls. It must be safe to run constantly.
282
+ - **Stable instance `id`**, passed to the constructor. Two instances of one
283
+ module have to be distinguishable in plans and logs.
284
+
285
+ ### Bringing a module online against existing production
286
+
287
+ 1. Implement `read()` and `diff()`. Leave `apply()` throwing `NotImplementedError`.
288
+ 2. Run `concord plan` and read the output.
289
+ 3. Seed the config from what `read()` returned.
290
+ 4. Iterate until **the plan is empty**.
291
+ 5. Only then implement `apply()`.
292
+
293
+ An empty plan against untouched production is the acceptance test that the module
294
+ understands reality before it is permitted to change it.
295
+
296
+ ## Releasing
297
+
298
+ Releases are manual. `main` can run ahead of the published version, and a
299
+ running daemon only reports itself out of date once a newer version is
300
+ published.
301
+
302
+ ```bash
303
+ git checkout main && git pull
304
+ npm version patch # or minor / major; commits the bump and tags it vX.Y.Z
305
+ git push --follow-tags
306
+ npm publish # runs the tests first (prepublishOnly)
307
+ ```
308
+
309
+ Bump the **major** version whenever `SCHEMA_VERSION` changes: configs written
310
+ for the old schema are rejected by the new reconciler until they are updated.
311
+
312
+ Then update each daemon when you choose to:
313
+
314
+ ```bash
315
+ sudo npm install -g @rcpooley/concord@X.Y.Z
316
+ sudo systemctl restart concord
317
+ ```
318
+
@@ -0,0 +1,69 @@
1
+ # TEMPLATE for the unit. `concord init` fills in the {{…}} placeholders for
2
+ # the installing user and this install, and writes the result to
3
+ # /etc/systemd/system/concord.service. Concord's own systemd module refuses to
4
+ # manage that file, because whether and when Concord runs must survive a
5
+ # broken config: it is placed once, at install time, never by the config.
6
+ #
7
+ # The daemon owns its own interval, so there is no timer.
8
+
9
+ [Unit]
10
+ Description=Concord — declarative fleet reconciler
11
+ Documentation=https://www.npmjs.com/package/@rcpooley/concord
12
+ After=network-online.target docker.service
13
+ Wants=network-online.target
14
+
15
+ # Retry forever. There is no timer behind this any more, so if systemd ever
16
+ # gave up after the default burst of restarts, nothing would bring Concord
17
+ # back and the fleet would stop reconciling silently. A timer retried forever
18
+ # by construction; this is how that property is preserved.
19
+ StartLimitIntervalSec=0
20
+
21
+ [Service]
22
+ Type=simple
23
+ User={{USER}}
24
+ EnvironmentFile=/etc/concord.env
25
+
26
+ # systemd creates and cleans /run/concord, so the webhook socket has a home
27
+ # that survives nothing and needs no bootstrapping. A reverse proxy in a
28
+ # container should bind-mount this DIRECTORY, never the socket file — a file bind mount would pin the old inode
29
+ # the moment the daemon restarted and recreated it.
30
+ RuntimeDirectory=concord
31
+ RuntimeDirectoryMode=0755
32
+ # Without this, systemd DELETES and recreates /run/concord on every restart —
33
+ # and the proxy's bind mount then points at the old, orphaned directory inode,
34
+ # so every webhook request 502s until the container is recreated. Mounting the
35
+ # directory rather than the socket file is necessary but not sufficient; the
36
+ # directory has to outlive the service too.
37
+ RuntimeDirectoryPreserve=yes
38
+ WorkingDirectory={{HOME}}
39
+ # The node that ran `concord init`, by absolute path: apt, nvm and snap all put
40
+ # it somewhere different. PATH starts with node's own directory so the daemon's
41
+ # children (npm, git) resolve the same way they did for the installing user;
42
+ # systemd's default PATH would miss nvm and /snap/bin.
43
+ Environment=PATH={{PATH}}
44
+ ExecStart={{NODE}} {{DAEMON}}
45
+
46
+ # SIGHUP asks for an immediate reconcile without restarting the process —
47
+ # `systemctl reload concord` is the manual poke that `systemctl start` used
48
+ # to be, and it is the same path the webhook will use.
49
+ ExecReload=/bin/kill -HUP $MAINPID
50
+
51
+ Restart=always
52
+ RestartSec=30
53
+ # A cycle can be a container build. Give it room to finish rather than being
54
+ # killed halfway through an apply.
55
+ TimeoutStopSec=300
56
+ # SIGTERM goes to the daemon ONLY. It finishes the cycle in flight, exits, and
57
+ # only then are leftover children (ssh masters) SIGKILLed. The default,
58
+ # control-group, SIGTERMed every process at once — killing the very deploy the
59
+ # daemon was "finishing". KillMode does not affect
60
+ # `systemctl kill`, which signals the whole cgroup unless given
61
+ # --kill-whom=main: poke with `systemctl reload`, never `systemctl kill`.
62
+ KillMode=mixed
63
+
64
+ # Deliberately NO SyslogIdentifier: setting one detached the daemon's own
65
+ # output from `journalctl -u concord.service`, which is the command anyone
66
+ # actually types. A custom tag is not worth making the logs hard to find.
67
+
68
+ [Install]
69
+ WantedBy=multi-user.target
package/dist/age.d.ts ADDED
@@ -0,0 +1,20 @@
1
+ import type { Secret } from './secret.js';
2
+ /** Generate a fresh age identity. Returns { identity, recipient }. */
3
+ export declare function generateKeypair(): Promise<{
4
+ identity: string;
5
+ recipient: string;
6
+ }>;
7
+ export declare function encryptToRecipient(recipient: string, plaintext: string): Promise<string>;
8
+ /**
9
+ * Decrypts secrets declared in the config repo.
10
+ *
11
+ * FAILS CLOSED: a missing key, a decrypt error, or an empty result is a hard
12
+ * error that aborts the run. A module never applies with a half-resolved
13
+ * secret and never overwrites a good value with an empty one.
14
+ */
15
+ export declare class SecretResolver {
16
+ #private;
17
+ constructor(identity: string);
18
+ resolve(secret: Secret): Promise<string>;
19
+ }
20
+ //# sourceMappingURL=age.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"age.d.ts","sourceRoot":"","sources":["../src/age.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC,sEAAsE;AACtE,wBAAsB,eAAe,IAAI,OAAO,CAAC;IAC/C,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAC,CAID;AAED,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CAKjB;AAED;;;;;;GAMG;AACH,qBAAa,cAAc;;gBAIb,QAAQ,EAAE,MAAM;IAWtB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAiC/C"}
package/dist/age.js ADDED
@@ -0,0 +1,58 @@
1
+ import * as age from 'age-encryption';
2
+ /** Generate a fresh age identity. Returns { identity, recipient }. */
3
+ export async function generateKeypair() {
4
+ const identity = await age.generateIdentity();
5
+ const recipient = await age.identityToRecipient(identity);
6
+ return { identity, recipient };
7
+ }
8
+ export async function encryptToRecipient(recipient, plaintext) {
9
+ const e = new age.Encrypter();
10
+ e.addRecipient(recipient);
11
+ const bytes = await e.encrypt(plaintext);
12
+ return Buffer.from(bytes).toString('base64');
13
+ }
14
+ /**
15
+ * Decrypts secrets declared in the config repo.
16
+ *
17
+ * FAILS CLOSED: a missing key, a decrypt error, or an empty result is a hard
18
+ * error that aborts the run. A module never applies with a half-resolved
19
+ * secret and never overwrites a good value with an empty one.
20
+ */
21
+ export class SecretResolver {
22
+ #decrypter;
23
+ #cache = new Map();
24
+ constructor(identity) {
25
+ const key = identity.trim();
26
+ if (!key) {
27
+ throw new Error('CONCORD_AGE_KEY is empty. Refusing to run — secrets cannot be resolved.');
28
+ }
29
+ this.#decrypter = new age.Decrypter();
30
+ this.#decrypter.addIdentity(key);
31
+ }
32
+ async resolve(secret) {
33
+ const ciphertext = secret;
34
+ const cached = this.#cache.get(ciphertext);
35
+ if (cached !== undefined)
36
+ return cached;
37
+ if (typeof ciphertext !== 'string' || ciphertext.length === 0) {
38
+ throw new Error('Secret reference is empty. Check secrets.ts in the config repo.');
39
+ }
40
+ let plaintext;
41
+ try {
42
+ const bytes = Buffer.from(ciphertext, 'base64');
43
+ plaintext = await this.#decrypter.decrypt(bytes, 'text');
44
+ }
45
+ catch (err) {
46
+ throw new Error(`Failed to decrypt a secret (${ciphertext.slice(0, 12)}…): ` +
47
+ `${err instanceof Error ? err.message : String(err)}. ` +
48
+ `Is CONCORD_AGE_KEY the private half of the config repo's age.pub?`);
49
+ }
50
+ if (plaintext.length === 0) {
51
+ throw new Error(`A secret decrypted to an empty string (${ciphertext.slice(0, 12)}…). ` +
52
+ `Refusing to continue — this is how good values get overwritten with blanks.`);
53
+ }
54
+ this.#cache.set(ciphertext, plaintext);
55
+ return plaintext;
56
+ }
57
+ }
58
+ //# sourceMappingURL=age.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"age.js","sourceRoot":"","sources":["../src/age.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAA;AAGrC,sEAAsE;AACtE,MAAM,CAAC,KAAK,UAAU,eAAe;IAInC,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,gBAAgB,EAAE,CAAA;IAC7C,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAA;IACzD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAA;AAChC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,SAAiB,EACjB,SAAiB;IAEjB,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,SAAS,EAAE,CAAA;IAC7B,CAAC,CAAC,YAAY,CAAC,SAAS,CAAC,CAAA;IACzB,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IACxC,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IACzB,UAAU,CAAe;IACzB,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAA;IAElC,YAAY,QAAgB;QAC1B,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAA;QAC3B,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CACb,yEAAyE,CAC1E,CAAA;QACH,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,IAAI,GAAG,CAAC,SAAS,EAAE,CAAA;QACrC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;IAClC,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAAc;QAC1B,MAAM,UAAU,GAAG,MAAgB,CAAA;QACnC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;QAC1C,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAA;QAEvC,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CACb,iEAAiE,CAClE,CAAA;QACH,CAAC;QAED,IAAI,SAAiB,CAAA;QACrB,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAA;YAC/C,SAAS,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;QAC1D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,+BAA+B,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM;gBAC1D,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI;gBACvD,mEAAmE,CACtE,CAAA;QACH,CAAC;QAED,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,0CAA0C,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM;gBACrE,6EAA6E,CAChF,CAAA;QACH,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,SAAS,CAAC,CAAA;QACtC,OAAO,SAAS,CAAA;IAClB,CAAC;CACF"}
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=main.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":""}