clinkx 1.3.0 → 1.4.1

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 (179) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +13 -6
  3. package/clinkx-workflows/dist/child-env.d.ts +3 -0
  4. package/clinkx-workflows/dist/child-env.js +11 -0
  5. package/clinkx-workflows/dist/child-env.js.map +1 -1
  6. package/clinkx-workflows/dist/dashboard/api-routes.d.ts +21 -0
  7. package/clinkx-workflows/dist/dashboard/api-routes.js +27 -0
  8. package/clinkx-workflows/dist/dashboard/api-routes.js.map +1 -1
  9. package/clinkx-workflows/dist/dashboard/auth/challenge-store.d.ts +13 -0
  10. package/clinkx-workflows/dist/dashboard/auth/challenge-store.js.map +1 -1
  11. package/clinkx-workflows/dist/dashboard/auth/controller.d.ts +27 -0
  12. package/clinkx-workflows/dist/dashboard/auth/controller.js +262 -23
  13. package/clinkx-workflows/dist/dashboard/auth/controller.js.map +1 -1
  14. package/clinkx-workflows/dist/dashboard/auth/settings-step-up.d.ts +62 -0
  15. package/clinkx-workflows/dist/dashboard/auth/settings-step-up.js +70 -0
  16. package/clinkx-workflows/dist/dashboard/auth/settings-step-up.js.map +1 -0
  17. package/clinkx-workflows/dist/dashboard/request-admission.d.ts +6 -0
  18. package/clinkx-workflows/dist/dashboard/request-admission.js +9 -0
  19. package/clinkx-workflows/dist/dashboard/request-admission.js.map +1 -1
  20. package/clinkx-workflows/dist/dashboard/server-factory.js +15 -1
  21. package/clinkx-workflows/dist/dashboard/server-factory.js.map +1 -1
  22. package/clinkx-workflows/dist/dashboard/settings-contract.d.ts +1806 -0
  23. package/clinkx-workflows/dist/dashboard/settings-contract.js +630 -0
  24. package/clinkx-workflows/dist/dashboard/settings-contract.js.map +1 -0
  25. package/clinkx-workflows/dist/dashboard/settings-process-reader.d.ts +48 -0
  26. package/clinkx-workflows/dist/dashboard/settings-process-reader.js +195 -0
  27. package/clinkx-workflows/dist/dashboard/settings-process-reader.js.map +1 -0
  28. package/clinkx-workflows/dist/dashboard/settings-routes.d.ts +87 -0
  29. package/clinkx-workflows/dist/dashboard/settings-routes.js +690 -0
  30. package/clinkx-workflows/dist/dashboard/settings-routes.js.map +1 -0
  31. package/clinkx-workflows/dist/dashboard-ui/assets/index-CX4FrhYN.js +122 -0
  32. package/clinkx-workflows/dist/dashboard-ui/assets/style-C5guUjwN.css +1 -0
  33. package/clinkx-workflows/dist/dashboard-ui/index.html +2 -2
  34. package/clinkx-workflows/dist/durable-file-core.d.ts +76 -0
  35. package/clinkx-workflows/dist/durable-file-core.js +146 -0
  36. package/clinkx-workflows/dist/durable-file-core.js.map +1 -0
  37. package/clinkx-workflows/dist/durable-file.d.ts +8 -64
  38. package/clinkx-workflows/dist/durable-file.js +14 -137
  39. package/clinkx-workflows/dist/durable-file.js.map +1 -1
  40. package/clinkx-workflows/dist/index.js +68 -2
  41. package/clinkx-workflows/dist/index.js.map +1 -1
  42. package/clinkx-workflows/dist/settings/audit.d.ts +101 -0
  43. package/clinkx-workflows/dist/settings/audit.js +318 -0
  44. package/clinkx-workflows/dist/settings/audit.js.map +1 -0
  45. package/clinkx-workflows/dist/settings/bootstrap.d.ts +35 -0
  46. package/clinkx-workflows/dist/settings/bootstrap.js +52 -0
  47. package/clinkx-workflows/dist/settings/bootstrap.js.map +1 -0
  48. package/clinkx-workflows/dist/settings/codec.d.ts +51 -0
  49. package/clinkx-workflows/dist/settings/codec.js +410 -0
  50. package/clinkx-workflows/dist/settings/codec.js.map +1 -0
  51. package/clinkx-workflows/dist/settings/durable-write.d.ts +48 -0
  52. package/clinkx-workflows/dist/settings/durable-write.js +31 -0
  53. package/clinkx-workflows/dist/settings/durable-write.js.map +1 -0
  54. package/clinkx-workflows/dist/settings/index.d.ts +20 -0
  55. package/clinkx-workflows/dist/settings/index.js +23 -0
  56. package/clinkx-workflows/dist/settings/index.js.map +1 -0
  57. package/clinkx-workflows/dist/settings/loader.d.ts +80 -0
  58. package/clinkx-workflows/dist/settings/loader.js +577 -0
  59. package/clinkx-workflows/dist/settings/loader.js.map +1 -0
  60. package/clinkx-workflows/dist/settings/lock.d.ts +108 -0
  61. package/clinkx-workflows/dist/settings/lock.js +344 -0
  62. package/clinkx-workflows/dist/settings/lock.js.map +1 -0
  63. package/clinkx-workflows/dist/settings/paths.d.ts +65 -0
  64. package/clinkx-workflows/dist/settings/paths.js +173 -0
  65. package/clinkx-workflows/dist/settings/paths.js.map +1 -0
  66. package/clinkx-workflows/dist/settings/process-heartbeat.d.ts +47 -0
  67. package/clinkx-workflows/dist/settings/process-heartbeat.js +305 -0
  68. package/clinkx-workflows/dist/settings/process-heartbeat.js.map +1 -0
  69. package/clinkx-workflows/dist/settings/registry.d.ts +178 -0
  70. package/clinkx-workflows/dist/settings/registry.js +1290 -0
  71. package/clinkx-workflows/dist/settings/registry.js.map +1 -0
  72. package/clinkx-workflows/dist/settings/schema.d.ts +404 -0
  73. package/clinkx-workflows/dist/settings/schema.js +415 -0
  74. package/clinkx-workflows/dist/settings/schema.js.map +1 -0
  75. package/clinkx-workflows/dist/settings/store.d.ts +157 -0
  76. package/clinkx-workflows/dist/settings/store.js +842 -0
  77. package/clinkx-workflows/dist/settings/store.js.map +1 -0
  78. package/clinkx-workflows/dist/stdio-entry.d.ts +2 -0
  79. package/clinkx-workflows/dist/stdio-entry.js +52 -0
  80. package/clinkx-workflows/dist/stdio-entry.js.map +1 -0
  81. package/dist/dashboard-cli.d.ts +11 -3
  82. package/dist/dashboard-cli.js +199 -33
  83. package/dist/dashboard-cli.js.map +1 -1
  84. package/dist/dashboard-companion/client.d.ts +14 -0
  85. package/dist/dashboard-companion/client.js +16 -0
  86. package/dist/dashboard-companion/client.js.map +1 -1
  87. package/dist/dashboard-companion/credential-expectation.d.ts +23 -0
  88. package/dist/dashboard-companion/credential-expectation.js +50 -0
  89. package/dist/dashboard-companion/credential-expectation.js.map +1 -0
  90. package/dist/dashboard-companion/host-channel.d.ts +36 -0
  91. package/dist/dashboard-companion/host-channel.js +78 -0
  92. package/dist/dashboard-companion/host-channel.js.map +1 -0
  93. package/dist/dashboard-companion/host-status.d.ts +179 -0
  94. package/dist/dashboard-companion/host-status.js +122 -0
  95. package/dist/dashboard-companion/host-status.js.map +1 -0
  96. package/dist/dashboard-companion/protocol.js +17 -0
  97. package/dist/dashboard-companion/protocol.js.map +1 -1
  98. package/dist/dashboard-companion/standalone-assets.d.ts +8 -0
  99. package/dist/dashboard-companion/standalone-assets.js +7 -1
  100. package/dist/dashboard-companion/standalone-assets.js.map +1 -1
  101. package/dist/dashboard-companion/standalone-entry.js +34 -13
  102. package/dist/dashboard-companion/standalone-entry.js.map +1 -1
  103. package/dist/dashboard-gateway/control-plane/contracts.d.ts +38 -38
  104. package/dist/dashboard-gateway/tunnel-http.js +20 -0
  105. package/dist/dashboard-gateway/tunnel-http.js.map +1 -1
  106. package/dist/desktop-host/child-env.d.ts +23 -0
  107. package/dist/desktop-host/child-env.js +70 -0
  108. package/dist/desktop-host/child-env.js.map +1 -0
  109. package/dist/desktop-host/daemon-entry.d.ts +2 -0
  110. package/dist/desktop-host/daemon-entry.js +50 -0
  111. package/dist/desktop-host/daemon-entry.js.map +1 -0
  112. package/dist/desktop-host/daemon-env.d.ts +12 -0
  113. package/dist/desktop-host/daemon-env.js +35 -0
  114. package/dist/desktop-host/daemon-env.js.map +1 -0
  115. package/dist/desktop-host/daemon-protocol.d.ts +210 -0
  116. package/dist/desktop-host/daemon-protocol.js +56 -0
  117. package/dist/desktop-host/daemon-protocol.js.map +1 -0
  118. package/dist/desktop-host/daemon.d.ts +50 -0
  119. package/dist/desktop-host/daemon.js +441 -0
  120. package/dist/desktop-host/daemon.js.map +1 -0
  121. package/dist/desktop-host/enrollment.d.ts +17 -0
  122. package/dist/desktop-host/enrollment.js +25 -0
  123. package/dist/desktop-host/enrollment.js.map +1 -0
  124. package/dist/desktop-host/import.d.ts +14 -0
  125. package/dist/desktop-host/import.js +95 -0
  126. package/dist/desktop-host/import.js.map +1 -0
  127. package/dist/desktop-host/profile.d.ts +130 -0
  128. package/dist/desktop-host/profile.js +176 -0
  129. package/dist/desktop-host/profile.js.map +1 -0
  130. package/dist/desktop-host/service.d.ts +6 -0
  131. package/dist/desktop-host/service.js +7 -0
  132. package/dist/desktop-host/service.js.map +1 -0
  133. package/dist/desktop-host/supervisor.d.ts +57 -0
  134. package/dist/desktop-host/supervisor.js +256 -0
  135. package/dist/desktop-host/supervisor.js.map +1 -0
  136. package/dist/desktop-host/view-state.d.ts +138 -0
  137. package/dist/desktop-host/view-state.js +27 -0
  138. package/dist/desktop-host/view-state.js.map +1 -0
  139. package/dist/elaris/config.d.ts +10 -0
  140. package/dist/elaris/config.js +27 -1
  141. package/dist/elaris/config.js.map +1 -1
  142. package/dist/elaris/tools.js +4 -1
  143. package/dist/elaris/tools.js.map +1 -1
  144. package/dist/index.d.ts +0 -31
  145. package/dist/index.js +41 -404
  146. package/dist/index.js.map +1 -1
  147. package/dist/lib.d.ts +17 -0
  148. package/dist/lib.js +17 -0
  149. package/dist/lib.js.map +1 -0
  150. package/dist/progress-report/lock.d.ts +17 -59
  151. package/dist/progress-report/lock.js +25 -329
  152. package/dist/progress-report/lock.js.map +1 -1
  153. package/dist/registry.d.ts +7 -0
  154. package/dist/registry.js +21 -7
  155. package/dist/registry.js.map +1 -1
  156. package/dist/server.js +75 -4
  157. package/dist/server.js.map +1 -1
  158. package/dist/settings-cli/clients.d.ts +137 -0
  159. package/dist/settings-cli/clients.js +1124 -0
  160. package/dist/settings-cli/clients.js.map +1 -0
  161. package/dist/settings-cli/commands.d.ts +67 -0
  162. package/dist/settings-cli/commands.js +726 -0
  163. package/dist/settings-cli/commands.js.map +1 -0
  164. package/dist/settings-cli/format.d.ts +34 -0
  165. package/dist/settings-cli/format.js +40 -0
  166. package/dist/settings-cli/format.js.map +1 -0
  167. package/dist/settings-cli/main.d.ts +18 -0
  168. package/dist/settings-cli/main.js +256 -0
  169. package/dist/settings-cli/main.js.map +1 -0
  170. package/dist/stdio-main.d.ts +73 -0
  171. package/dist/stdio-main.js +455 -0
  172. package/dist/stdio-main.js.map +1 -0
  173. package/docs/configuration.md +340 -39
  174. package/docs/security.md +150 -6
  175. package/docs/verification/README.md +28 -2
  176. package/docs/verification/workflow-handoff.md +86 -0
  177. package/package.json +3 -3
  178. package/clinkx-workflows/dist/dashboard-ui/assets/index-DRId2DVA.js +0 -119
  179. package/clinkx-workflows/dist/dashboard-ui/assets/style-CHAw57y5.css +0 -1
@@ -0,0 +1,76 @@
1
+ /**
2
+ * Crash-durable file publication: the one implementation behind run state
3
+ * (`durable-file.ts`) and the dashboard settings documents
4
+ * (`settings/durable-write.ts`).
5
+ *
6
+ * Replace mode writes a unique same-directory temporary opened
7
+ * `O_CREAT|O_EXCL|O_NOFOLLOW`, applies the mode with `fchmod` (never trusting
8
+ * the umask: the dashboard container reads these files as another user),
9
+ * fsyncs and closes it, renames it over the target, then fsyncs the parent
10
+ * directory. Exclusive mode keeps the `wx` create-once contract by creating
11
+ * and writing the target itself under the same flags, then fsyncing the
12
+ * parent directory.
13
+ *
14
+ * A write, fchmod, fsync, close or rename failure removes the file this call
15
+ * created: the temporary in replace mode, where the target is untouched until
16
+ * the rename; the target itself in exclusive mode, where it is visible under
17
+ * its final name while being written. An existing target makes exclusive mode
18
+ * fail with EEXIST and is never removed. Only a failed directory fsync after
19
+ * that point is a `DurablePublishError`, so callers know the new bytes are
20
+ * already there.
21
+ *
22
+ * This module imports node built-ins only and never logs by default: the
23
+ * settings CLI reaches it and must stay free of the logger/pino.
24
+ */
25
+ export interface DurableWriteOptions {
26
+ readonly mode: number;
27
+ /** Create-only: fail with EEXIST instead of replacing an existing target. */
28
+ readonly exclusive?: boolean | undefined;
29
+ }
30
+ /**
31
+ * The persistence seam. Production paths always resolve to
32
+ * `durableFileWriter`; tests that do not exercise durability may pass a fast
33
+ * writer through the store/tool options (there is deliberately no env switch).
34
+ */
35
+ export interface FileWriter {
36
+ writeFile(path: string, data: string | Uint8Array, options: DurableWriteOptions): Promise<void>;
37
+ /** Make a directory's entries (a new child directory, a rename) durable. */
38
+ syncDirectory(path: string): Promise<void>;
39
+ }
40
+ /** The new bytes are visible at `path`; only the directory fsync failed. */
41
+ export declare class DurablePublishError extends Error {
42
+ readonly published: true;
43
+ readonly path: string;
44
+ constructor(path: string, cause: unknown);
45
+ }
46
+ export interface DurableFileHandle {
47
+ writeFile(data: string | Uint8Array): Promise<void>;
48
+ chmod(mode: number): Promise<void>;
49
+ sync(): Promise<void>;
50
+ stat(): Promise<{
51
+ readonly dev: number | bigint;
52
+ }>;
53
+ close(): Promise<void>;
54
+ }
55
+ /** Filesystem operations the writer uses; injectable for order/fault tests. */
56
+ export interface DurableFsOps {
57
+ open(path: string, flags: number, mode?: number): Promise<DurableFileHandle>;
58
+ rename(from: string, to: string): Promise<void>;
59
+ unlink(path: string): Promise<void>;
60
+ }
61
+ export interface DurableFileWriterDeps {
62
+ readonly fs?: DurableFsOps | undefined;
63
+ readonly tempSuffix?: (() => string) | undefined;
64
+ readonly warn?: ((fields: Record<string, unknown>, message: string) => void) | undefined;
65
+ }
66
+ export declare function createDurableFileWriterCore(deps?: DurableFileWriterDeps): FileWriter;
67
+ /**
68
+ * `mkdir -p` whose newly created entries are durable: each directory this call
69
+ * created is fsynced into its parent, so a file later published beneath it
70
+ * cannot outlive its own path after a crash.
71
+ *
72
+ * It lives here, not in `durable-file.ts`, because it needs no diagnostics
73
+ * sink beyond the writer's own — keeping it importable from logger-free
74
+ * contexts such as the settings store (P7).
75
+ */
76
+ export declare function mkdirDurable(writer: FileWriter, path: string, mode?: number): Promise<void>;
@@ -0,0 +1,146 @@
1
+ import { randomBytes } from "node:crypto";
2
+ import { constants as fsConstants } from "node:fs";
3
+ import { mkdir, open, rename, unlink } from "node:fs/promises";
4
+ import { basename, dirname, join, relative, sep } from "node:path";
5
+ /** The new bytes are visible at `path`; only the directory fsync failed. */
6
+ export class DurablePublishError extends Error {
7
+ published = true;
8
+ // An explicit field, not a parameter property: the settings fork test loads
9
+ // this module with Node's strip-only type removal, which rejects those.
10
+ path;
11
+ constructor(path, cause) {
12
+ super(`published ${path} but could not fsync its directory: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
13
+ this.name = "DurablePublishError";
14
+ this.path = path;
15
+ }
16
+ }
17
+ const CREATE_FLAGS = fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW;
18
+ const DIRECTORY_FLAGS = fsConstants.O_RDONLY | (fsConstants.O_DIRECTORY ?? 0);
19
+ const nodeFs = {
20
+ open: async (path, flags, mode) => await open(path, flags, mode),
21
+ rename,
22
+ unlink,
23
+ };
24
+ function errnoCode(error) {
25
+ return typeof error === "object" && error !== null && "code" in error
26
+ ? String(error.code)
27
+ : undefined;
28
+ }
29
+ export function createDurableFileWriterCore(deps = {}) {
30
+ const fs = deps.fs ?? nodeFs;
31
+ const tempSuffix = deps.tempSuffix ?? (() => `${String(process.pid)}.${randomBytes(8).toString("hex")}`);
32
+ const warn = deps.warn ?? (() => undefined);
33
+ // Some filesystems (certain network/FUSE mounts) reject a directory fsync.
34
+ // That is tolerated, but reported once per filesystem rather than per write.
35
+ const warnedFilesystems = new Set();
36
+ async function syncDirectory(path) {
37
+ const handle = await fs.open(path, DIRECTORY_FLAGS);
38
+ try {
39
+ try {
40
+ await handle.sync();
41
+ }
42
+ catch (error) {
43
+ const code = errnoCode(error);
44
+ if (code !== "EINVAL" && code !== "ENOTSUP")
45
+ throw error;
46
+ const key = await handle.stat().then((stat) => String(stat.dev), () => path);
47
+ if (!warnedFilesystems.has(key)) {
48
+ warnedFilesystems.add(key);
49
+ warn({ directory: path, code }, "directory fsync is unsupported on this filesystem; renames are not crash-durable here");
50
+ }
51
+ }
52
+ }
53
+ finally {
54
+ await handle.close();
55
+ }
56
+ }
57
+ /**
58
+ * Create `path` (never following or reusing an existing entry), write, fchmod
59
+ * and fsync it. Any failure after creation removes the file it created.
60
+ */
61
+ async function createSynced(path, data, mode) {
62
+ const handle = await fs.open(path, CREATE_FLAGS, mode);
63
+ try {
64
+ await handle.writeFile(data);
65
+ await handle.chmod(mode);
66
+ await handle.sync();
67
+ }
68
+ catch (error) {
69
+ await handle.close().catch(() => { });
70
+ await discard(path);
71
+ throw error;
72
+ }
73
+ try {
74
+ await handle.close();
75
+ }
76
+ catch (error) {
77
+ await discard(path);
78
+ throw error;
79
+ }
80
+ }
81
+ async function discard(path) {
82
+ try {
83
+ await fs.unlink(path);
84
+ }
85
+ catch (error) {
86
+ if (errnoCode(error) !== "ENOENT") {
87
+ warn({ path, err: error instanceof Error ? error.message : String(error) }, "failed to remove an unpublished durable-write file");
88
+ }
89
+ }
90
+ }
91
+ async function publishDirectory(target) {
92
+ try {
93
+ await syncDirectory(dirname(target));
94
+ }
95
+ catch (error) {
96
+ throw new DurablePublishError(target, error);
97
+ }
98
+ }
99
+ return {
100
+ syncDirectory,
101
+ async writeFile(path, data, options) {
102
+ if (options.exclusive === true) {
103
+ await createSynced(path, data, options.mode);
104
+ await publishDirectory(path);
105
+ return;
106
+ }
107
+ const temporary = join(dirname(path), `.${basename(path)}.${tempSuffix()}.tmp`);
108
+ await createSynced(temporary, data, options.mode);
109
+ try {
110
+ await fs.rename(temporary, path);
111
+ }
112
+ catch (error) {
113
+ await discard(temporary);
114
+ throw error;
115
+ }
116
+ await publishDirectory(path);
117
+ },
118
+ };
119
+ }
120
+ /**
121
+ * `mkdir -p` whose newly created entries are durable: each directory this call
122
+ * created is fsynced into its parent, so a file later published beneath it
123
+ * cannot outlive its own path after a crash.
124
+ *
125
+ * It lives here, not in `durable-file.ts`, because it needs no diagnostics
126
+ * sink beyond the writer's own — keeping it importable from logger-free
127
+ * contexts such as the settings store (P7).
128
+ */
129
+ export async function mkdirDurable(writer, path, mode) {
130
+ const first = await mkdir(path, { recursive: true, ...(mode === undefined ? {} : { mode }) });
131
+ if (first === undefined)
132
+ return;
133
+ const created = [first];
134
+ const rest = relative(first, path);
135
+ if (rest !== "") {
136
+ let current = first;
137
+ for (const part of rest.split(sep)) {
138
+ current = join(current, part);
139
+ created.push(current);
140
+ }
141
+ }
142
+ for (const directory of created) {
143
+ await writer.syncDirectory(dirname(directory));
144
+ }
145
+ }
146
+ //# sourceMappingURL=durable-file-core.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"durable-file-core.js","sourceRoot":"","sources":["../src/durable-file-core.ts"],"names":[],"mappings":"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"}
@@ -1,69 +1,13 @@
1
+ import { type DurableFileWriterDeps, type FileWriter } from "./durable-file-core.js";
1
2
  /**
2
- * Crash-durable file publication for run state and the files it references.
3
- *
4
- * Replace mode writes a unique same-directory temporary opened
5
- * `O_CREAT|O_EXCL|O_NOFOLLOW`, applies the mode with `fchmod` (never trusting
6
- * the umask: the dashboard container reads run files as another user), fsyncs
7
- * and closes it, renames it over the target, then fsyncs the parent
8
- * directory. Exclusive mode keeps the `wx` create-once contract by creating
9
- * and writing the target itself under the same flags, then fsyncing the
10
- * parent directory.
11
- *
12
- * A write, fchmod, fsync, close or rename failure removes the file this call
13
- * created: the temporary in replace mode, where the target is untouched until
14
- * the rename; the target itself in exclusive mode, where it is visible under
15
- * its final name while being written. An existing target makes exclusive mode
16
- * fail with EEXIST and is never removed. Only a failed directory fsync after
17
- * that point is a `DurablePublishError`, so callers know the new bytes are
18
- * already there.
3
+ * Run-state entry point for crash-durable writes. The implementation and its
4
+ * contract live in `durable-file-core.ts`; this module adds the logger as the
5
+ * default diagnostics sink, the production writer, and re-exports
6
+ * `mkdirDurable` (which is implemented in the core so logger-free consumers
7
+ * such as the settings store can reach it).
19
8
  */
20
- export interface DurableWriteOptions {
21
- readonly mode: number;
22
- /** Create-only: fail with EEXIST instead of replacing an existing target. */
23
- readonly exclusive?: boolean | undefined;
24
- }
25
- /**
26
- * The persistence seam. Production paths always resolve to
27
- * `durableFileWriter`; tests that do not exercise durability may pass a fast
28
- * writer through the store/tool options (there is deliberately no env switch).
29
- */
30
- export interface FileWriter {
31
- writeFile(path: string, data: string | Uint8Array, options: DurableWriteOptions): Promise<void>;
32
- /** Make a directory's entries (a new child directory, a rename) durable. */
33
- syncDirectory(path: string): Promise<void>;
34
- }
35
- /** The new bytes are visible at `path`; only the directory fsync failed. */
36
- export declare class DurablePublishError extends Error {
37
- readonly path: string;
38
- readonly published: true;
39
- constructor(path: string, cause: unknown);
40
- }
41
- export interface DurableFileHandle {
42
- writeFile(data: string | Uint8Array): Promise<void>;
43
- chmod(mode: number): Promise<void>;
44
- sync(): Promise<void>;
45
- stat(): Promise<{
46
- readonly dev: number | bigint;
47
- }>;
48
- close(): Promise<void>;
49
- }
50
- /** Filesystem operations the writer uses; injectable for order/fault tests. */
51
- export interface DurableFsOps {
52
- open(path: string, flags: number, mode?: number): Promise<DurableFileHandle>;
53
- rename(from: string, to: string): Promise<void>;
54
- unlink(path: string): Promise<void>;
55
- }
56
- export interface DurableFileWriterDeps {
57
- readonly fs?: DurableFsOps | undefined;
58
- readonly tempSuffix?: (() => string) | undefined;
59
- readonly warn?: ((fields: Record<string, unknown>, message: string) => void) | undefined;
60
- }
9
+ export { DurablePublishError, type DurableFileHandle, type DurableFileWriterDeps, type DurableFsOps, type DurableWriteOptions, type FileWriter, } from "./durable-file-core.js";
10
+ export { mkdirDurable } from "./durable-file-core.js";
61
11
  export declare function createDurableFileWriter(deps?: DurableFileWriterDeps): FileWriter;
62
12
  export declare const durableFileWriter: FileWriter;
63
13
  export declare function resolveFileWriter(writer: FileWriter | undefined): FileWriter;
64
- /**
65
- * `mkdir -p` whose newly created entries are durable: each directory this call
66
- * created is fsynced into its parent, so a file later published beneath it
67
- * cannot outlive its own path after a crash. Existing directories cost nothing.
68
- */
69
- export declare function mkdirDurable(writer: FileWriter, path: string, mode?: number): Promise<void>;
@@ -1,145 +1,22 @@
1
- import { randomBytes } from "node:crypto";
2
- import { constants as fsConstants } from "node:fs";
3
- import { mkdir, open, rename, unlink } from "node:fs/promises";
4
- import { basename, dirname, join, relative, sep } from "node:path";
5
1
  import { logger } from "./logger.js";
6
- /** The new bytes are visible at `path`; only the directory fsync failed. */
7
- export class DurablePublishError extends Error {
8
- path;
9
- published = true;
10
- constructor(path, cause) {
11
- super(`published ${path} but could not fsync its directory: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
12
- this.path = path;
13
- this.name = "DurablePublishError";
14
- }
15
- }
16
- const CREATE_FLAGS = fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW;
17
- const DIRECTORY_FLAGS = fsConstants.O_RDONLY | (fsConstants.O_DIRECTORY ?? 0);
18
- const nodeFs = {
19
- open: async (path, flags, mode) => await open(path, flags, mode),
20
- rename,
21
- unlink,
22
- };
23
- function errnoCode(error) {
24
- return typeof error === "object" && error !== null && "code" in error
25
- ? String(error.code)
26
- : undefined;
27
- }
2
+ import { createDurableFileWriterCore } from "./durable-file-core.js";
3
+ /**
4
+ * Run-state entry point for crash-durable writes. The implementation and its
5
+ * contract live in `durable-file-core.ts`; this module adds the logger as the
6
+ * default diagnostics sink, the production writer, and re-exports
7
+ * `mkdirDurable` (which is implemented in the core so logger-free consumers
8
+ * such as the settings store can reach it).
9
+ */
10
+ export { DurablePublishError, } from "./durable-file-core.js";
11
+ export { mkdirDurable } from "./durable-file-core.js";
28
12
  export function createDurableFileWriter(deps = {}) {
29
- const fs = deps.fs ?? nodeFs;
30
- const tempSuffix = deps.tempSuffix ?? (() => `${String(process.pid)}.${randomBytes(8).toString("hex")}`);
31
- const warn = deps.warn ?? ((fields, message) => logger.warn(fields, message));
32
- // Some filesystems (certain network/FUSE mounts) reject a directory fsync.
33
- // That is tolerated, but reported once per filesystem rather than per write.
34
- const warnedFilesystems = new Set();
35
- async function syncDirectory(path) {
36
- const handle = await fs.open(path, DIRECTORY_FLAGS);
37
- try {
38
- try {
39
- await handle.sync();
40
- }
41
- catch (error) {
42
- const code = errnoCode(error);
43
- if (code !== "EINVAL" && code !== "ENOTSUP")
44
- throw error;
45
- const key = await handle.stat().then((stat) => String(stat.dev), () => path);
46
- if (!warnedFilesystems.has(key)) {
47
- warnedFilesystems.add(key);
48
- warn({ directory: path, code }, "directory fsync is unsupported on this filesystem; renames are not crash-durable here");
49
- }
50
- }
51
- }
52
- finally {
53
- await handle.close();
54
- }
55
- }
56
- /**
57
- * Create `path` (never following or reusing an existing entry), write, fchmod
58
- * and fsync it. Any failure after creation removes the file it created.
59
- */
60
- async function createSynced(path, data, mode) {
61
- const handle = await fs.open(path, CREATE_FLAGS, mode);
62
- try {
63
- await handle.writeFile(data);
64
- await handle.chmod(mode);
65
- await handle.sync();
66
- }
67
- catch (error) {
68
- await handle.close().catch(() => { });
69
- await discard(path);
70
- throw error;
71
- }
72
- try {
73
- await handle.close();
74
- }
75
- catch (error) {
76
- await discard(path);
77
- throw error;
78
- }
79
- }
80
- async function discard(path) {
81
- try {
82
- await fs.unlink(path);
83
- }
84
- catch (error) {
85
- if (errnoCode(error) !== "ENOENT") {
86
- warn({ path, err: error instanceof Error ? error.message : String(error) }, "failed to remove an unpublished durable-write file");
87
- }
88
- }
89
- }
90
- async function publishDirectory(target) {
91
- try {
92
- await syncDirectory(dirname(target));
93
- }
94
- catch (error) {
95
- throw new DurablePublishError(target, error);
96
- }
97
- }
98
- return {
99
- syncDirectory,
100
- async writeFile(path, data, options) {
101
- if (options.exclusive === true) {
102
- await createSynced(path, data, options.mode);
103
- await publishDirectory(path);
104
- return;
105
- }
106
- const temporary = join(dirname(path), `.${basename(path)}.${tempSuffix()}.tmp`);
107
- await createSynced(temporary, data, options.mode);
108
- try {
109
- await fs.rename(temporary, path);
110
- }
111
- catch (error) {
112
- await discard(temporary);
113
- throw error;
114
- }
115
- await publishDirectory(path);
116
- },
117
- };
13
+ return createDurableFileWriterCore({
14
+ ...deps,
15
+ warn: deps.warn ?? ((fields, message) => logger.warn(fields, message)),
16
+ });
118
17
  }
119
18
  export const durableFileWriter = createDurableFileWriter();
120
19
  export function resolveFileWriter(writer) {
121
20
  return writer ?? durableFileWriter;
122
21
  }
123
- /**
124
- * `mkdir -p` whose newly created entries are durable: each directory this call
125
- * created is fsynced into its parent, so a file later published beneath it
126
- * cannot outlive its own path after a crash. Existing directories cost nothing.
127
- */
128
- export async function mkdirDurable(writer, path, mode) {
129
- const first = await mkdir(path, { recursive: true, ...(mode === undefined ? {} : { mode }) });
130
- if (first === undefined)
131
- return;
132
- const created = [first];
133
- const rest = relative(first, path);
134
- if (rest !== "") {
135
- let current = first;
136
- for (const part of rest.split(sep)) {
137
- current = join(current, part);
138
- created.push(current);
139
- }
140
- }
141
- for (const directory of created) {
142
- await writer.syncDirectory(dirname(directory));
143
- }
144
- }
145
22
  //# sourceMappingURL=durable-file.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"durable-file.js","sourceRoot":"","sources":["../src/durable-file.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"durable-file.js","sourceRoot":"","sources":["../src/durable-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,2BAA2B,EAA+C,MAAM,wBAAwB,CAAC;AAElH;;;;;;GAMG;AAEH,OAAO,EACL,mBAAmB,GAMpB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,MAAM,UAAU,uBAAuB,CAAC,OAA8B,EAAE;IACtE,OAAO,2BAA2B,CAAC;QACjC,GAAG,IAAI;QACP,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACvE,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAe,uBAAuB,EAAE,CAAC;AAEvE,MAAM,UAAU,iBAAiB,CAAC,MAA8B;IAC9D,OAAO,MAAM,IAAI,iBAAiB,CAAC;AACrC,CAAC"}
@@ -12,13 +12,15 @@
12
12
  */
13
13
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
14
14
  import { serializeMessage } from "@modelcontextprotocol/sdk/shared/stdio.js";
15
- import { realpathSync } from "node:fs";
15
+ import { realpathSync, readFileSync } from "node:fs";
16
16
  import { fileURLToPath, pathToFileURL } from "node:url";
17
17
  import { createWorkflowServer } from "./server.js";
18
18
  import { logger, assertStderrLogger } from "./logger.js";
19
19
  import { shutdownCoordinator } from "./shutdown.js";
20
20
  import { getActiveWorkflowHandlerCount, getActiveWorkflowRunCount, setWorkflowActivityObserver, } from "./workflow-tools.js";
21
21
  import { createStdioWatchdog } from "./stdio-watchdog.js";
22
+ import { getSettingsApplication } from "./settings/bootstrap.js";
23
+ import { startSettingsHeartbeat } from "./settings/process-heartbeat.js";
22
24
  export { registerWorkflowTools, getWorkflowToolDefinitions, handleWorkflowToolCall, WORKFLOW_TOOL_NAMES, } from "./workflow-tools.js";
23
25
  export { inspectVerifiedRepairRecord } from "./verified-repair/result.js";
24
26
  export { createWorkflowServer } from "./server.js";
@@ -264,9 +266,63 @@ export function installShutdownHandlers(shutdownOnce, targetProcess = process) {
264
266
  runShutdown("unhandledRejection", 1);
265
267
  });
266
268
  }
269
+ /** Package version for the settings heartbeat (matches serverInfo's source). */
270
+ function readPackageVersion() {
271
+ // dist/../package.json at runtime, src/../package.json under vitest.
272
+ try {
273
+ const parsed = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
274
+ if (typeof parsed === "object" &&
275
+ parsed !== null &&
276
+ "version" in parsed &&
277
+ typeof parsed.version === "string" &&
278
+ parsed.version.length > 0) {
279
+ return parsed.version;
280
+ }
281
+ }
282
+ catch {
283
+ // Fall through to the serverInfo constant below.
284
+ }
285
+ return "0.1.0";
286
+ }
287
+ /**
288
+ * Start the standalone settings heartbeat (A2-3). Runs only when the shim
289
+ * (dist/stdio-entry.js) applied startup settings in this process: without a
290
+ * bootstrap application (library import, direct dist/index.js launch, or a
291
+ * child running with CLINKX_SETTINGS=off) there is nothing honest to publish.
292
+ */
293
+ function startStandaloneSettingsHeartbeat() {
294
+ const application = getSettingsApplication();
295
+ if (application == null)
296
+ return undefined;
297
+ if (application.state === "off" || application.settingsDir === "") {
298
+ return undefined;
299
+ }
300
+ const entry = "workflows-standalone";
301
+ return startSettingsHeartbeat({
302
+ application,
303
+ entry,
304
+ version: readPackageVersion(),
305
+ dir: application.settingsDir,
306
+ warn: (message) => logger.warn({ component: "settings-heartbeat" }, message),
307
+ });
308
+ }
267
309
  async function main() {
268
310
  assertStderrLogger();
311
+ const settingsApplication = getSettingsApplication();
312
+ if (settingsApplication != null) {
313
+ for (const warning of settingsApplication.warnings) {
314
+ logger.warn({ component: "settings" }, warning);
315
+ }
316
+ logger.info({
317
+ settings_state: settingsApplication.state,
318
+ settings_dir: settingsApplication.settingsDir,
319
+ ...(settingsApplication.revision !== undefined
320
+ ? { settings_revision: settingsApplication.revision }
321
+ : {}),
322
+ }, "startup settings applied");
323
+ }
269
324
  const server = createWorkflowServer();
325
+ const heartbeat = startStandaloneSettingsHeartbeat();
270
326
  const transport = new StdioServerTransport();
271
327
  let activeResponseSends = 0;
272
328
  let watchdog;
@@ -276,6 +332,7 @@ async function main() {
276
332
  abortAtEntry: (reason) => {
277
333
  shutdownCoordinator.beginShutdown(reason);
278
334
  watchdog?.stop();
335
+ heartbeat?.stop();
279
336
  },
280
337
  cleanup: async (reason) => {
281
338
  watchdog?.stop();
@@ -343,7 +400,16 @@ function isCliEntrypoint() {
343
400
  if (entry == null)
344
401
  return false;
345
402
  try {
346
- return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
403
+ const resolvedEntry = realpathSync(entry);
404
+ if (resolvedEntry === realpathSync(fileURLToPath(import.meta.url))) {
405
+ return true;
406
+ }
407
+ // dist/stdio-entry.js (the settings bootstrap shim, A2-3) dynamically
408
+ // imports this module as its main after applying startup settings; it is
409
+ // an entry alias, not a library consumer. Library imports of this module
410
+ // (createWorkflowServer users) still start nothing.
411
+ const shimPath = fileURLToPath(new URL("./stdio-entry.js", import.meta.url));
412
+ return resolvedEntry === realpathSync(shimPath);
347
413
  }
348
414
  catch {
349
415
  return import.meta.url === pathToFileURL(entry).href;