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,178 @@
1
+ /**
2
+ * Settings registry — the S0-1 freeze point for dashboard-managed ClinkX
3
+ * environment keys.
4
+ *
5
+ * Single source of truth for every key the dashboard Settings feature may
6
+ * write: canonical env name, type, bounds, class, consumers, read timing,
7
+ * invalid-value policy, cross-key requirements, legacy aliases, docs and the
8
+ * encode() function that renders a file value in the consumer's exact legacy
9
+ * env grammar.
10
+ *
11
+ * Constraints (DECISIONS.md 2026-11-03 + TASKS.md amendments):
12
+ * - Precedence per key: explicit env > settings file > built-in default
13
+ * (OQ-3: an env var present with an empty value, and legacy aliases, count
14
+ * as env-present). The loader is A1-1; this registry only describes keys.
15
+ * - Apply model is restart-only (coordinator decision 8): every key is
16
+ * restartRequired.
17
+ * - Keys whose values feed the workflow resume fingerprint
18
+ * (buildChildConfigFingerprint, clinkx-workflows/src/state.ts) are flagged
19
+ * affectsResumeFingerprint; editing them can strand unfinished resumable
20
+ * runs.
21
+ * - Policy keys declare onInvalid {restrictive} (owner decision 7); the one
22
+ * exception is CLINKX_ALLOWED_ROOTS (OQ-8: invalid file value is NOT filled,
23
+ * the consumer no-config default — cwd() — applies, with a loud warning).
24
+ * - Reader-first persistence flags encode exactly "true"/"false" so a filled
25
+ * value can never widen into another grammar.
26
+ *
27
+ * This module must stay dependency-free (no zod, no logger, no config): the
28
+ * startup bootstrap (A1-1) loads it before any module import that could pull
29
+ * pino or clinkx-workflows/src/config.js, and tests walk its import closure.
30
+ */
31
+ /** Env override that disables settings loading entirely (value `off`). */
32
+ export declare const SETTINGS_OFF_ENV = "CLINKX_SETTINGS";
33
+ /** Env override for the settings directory (absolute; validated by A1-1). */
34
+ export declare const SETTINGS_DIR_ENV = "CLINKX_SETTINGS_DIR";
35
+ export type SettingValue = string | number | boolean | string[];
36
+ export type SettingClass = "tuning" | "retention" | "feature" | "reader_first" | "policy" | "secret";
37
+ export type SettingType = "bool" | "int" | "enum" | "string" | "url" | "list";
38
+ /** When the consumer reads the key (drives UI restart messaging). */
39
+ export type SettingReadTiming = "module_load" | "startup" | "startup_singleton" | "per_call";
40
+ /** Boolean env grammars found in consumers (inventory §6: six forms). */
41
+ export type BoolGrammar = "exact_true" | "env_bool" | "not_false" | "truthy_set" | "allow_secrets_tokens";
42
+ /**
43
+ * Integer env grammars. The silent families fall back to the default on an
44
+ * invalid value; the strict families throw. The codec mirrors each exactly —
45
+ * the settings schema must not silently "fix" consumer semantics.
46
+ */
47
+ export type IntGrammar = "safe_parse_int" | "env_int" | "env_non_negative_int" | "trimmed_non_negative_int" | "env_positive_int" | "safe_parse_non_neg_int" | "positive_seconds_strict" | "cb_max_concurrent" | "idle_timeout_seconds";
48
+ /**
49
+ * Invalid-value policy (owner decision 7):
50
+ * - "default": the key is NOT filled from the file (consumer built-in default
51
+ * applies) and a warning is recorded.
52
+ * - {restrictive}: the restrictive value is filled using the key's legacy
53
+ * grammar. For `url` keys the restrictive value "" means "leave unset"
54
+ * (never fill an empty string into the environment).
55
+ */
56
+ export type SettingOnInvalid = "default" | {
57
+ readonly restrictive: SettingValue;
58
+ };
59
+ export interface SettingDocs {
60
+ readonly title: string;
61
+ readonly summary: string;
62
+ readonly warning?: string;
63
+ }
64
+ interface SettingDescriptorBase {
65
+ readonly key: string;
66
+ readonly class: SettingClass;
67
+ readonly unit: string;
68
+ /** Consumer read sites (internal; never projected to the browser). */
69
+ readonly consumers: readonly string[];
70
+ readonly readTiming: SettingReadTiming;
71
+ readonly restartRequired: true;
72
+ readonly affectsResumeFingerprint: boolean;
73
+ readonly onInvalid: SettingOnInvalid;
74
+ /** Registry keys that must also be resolvable for this key's value to apply. */
75
+ readonly requires?: readonly string[];
76
+ /** Older env names still honored by the consumer for this key. */
77
+ readonly legacyAliases?: readonly string[];
78
+ readonly docs: SettingDocs;
79
+ /** Render a value in the consumer's exact legacy env grammar. */
80
+ readonly encode: (value: SettingValue) => string;
81
+ }
82
+ export interface BoolSettingDescriptor extends SettingDescriptorBase {
83
+ readonly type: "bool";
84
+ readonly grammar: BoolGrammar;
85
+ readonly default: boolean;
86
+ }
87
+ export interface IntSettingDescriptor extends SettingDescriptorBase {
88
+ readonly type: "int";
89
+ readonly grammar: IntGrammar;
90
+ readonly default: number;
91
+ readonly min: number;
92
+ /** Omitted when the consumer grammar is unbounded above. */
93
+ readonly max?: number;
94
+ }
95
+ export interface EnumSettingDescriptor extends SettingDescriptorBase {
96
+ readonly type: "enum";
97
+ readonly choices: readonly string[];
98
+ readonly default: string;
99
+ }
100
+ export interface StringSettingDescriptor extends SettingDescriptorBase {
101
+ readonly type: "string";
102
+ readonly minLength: number;
103
+ readonly maxLength: number;
104
+ /** "" default means "unset" (consumer treats empty as absent). */
105
+ readonly default: string;
106
+ readonly pattern?: RegExp;
107
+ /**
108
+ * True when the consumer treats a whitespace-only value as unset (Elaris
109
+ * model id). Default (absent) mirrors CLINKX_WORKFLOWS_CONTEXT_DEFAULT_CURATOR,
110
+ * whose consumer throws on a non-empty but blank value.
111
+ */
112
+ readonly blankIsUnset?: boolean;
113
+ /**
114
+ * True when the consumer passes a present env value through verbatim
115
+ * (`process.env[k] ?? default`, app-server version gates): an empty value
116
+ * stays empty instead of falling back to the default, so `""` must never
117
+ * be "helpfully" replaced by the pinned version.
118
+ */
119
+ readonly blankIsVerbatim?: boolean;
120
+ }
121
+ export interface UrlSettingDescriptor extends SettingDescriptorBase {
122
+ readonly type: "url";
123
+ /** "" default means "unset" (Elaris requires the key only when enabled). */
124
+ readonly default: string;
125
+ }
126
+ export interface ListSettingDescriptor extends SettingDescriptorBase {
127
+ readonly type: "list";
128
+ readonly separator: ",";
129
+ /** [] default means "unset" (consumer falls back to its no-config default). */
130
+ readonly default: string[];
131
+ }
132
+ export type SettingDescriptor = BoolSettingDescriptor | IntSettingDescriptor | EnumSettingDescriptor | StringSettingDescriptor | UrlSettingDescriptor | ListSettingDescriptor;
133
+ export declare const SETTINGS_KEYS: readonly string[];
134
+ /**
135
+ * Registry key identifier. The runtime authority is SETTINGS_REGISTRY — keys
136
+ * arrive from JSON at every boundary and are validated against it — so this
137
+ * is a domain alias, not a literal union.
138
+ */
139
+ export type SettingsKey = string;
140
+ export declare const SETTINGS_KEY_SET: ReadonlySet<string>;
141
+ export declare const SETTINGS_REGISTRY: Readonly<Record<string, SettingDescriptor>>;
142
+ export declare function getSettingDescriptor(name: string): SettingDescriptor | undefined;
143
+ /** Registry keys of a given class, in registry order. */
144
+ export declare function settingsKeysByClass(cls: SettingClass): readonly string[];
145
+ /** Secret-class keys (exactly the keys allowed in the secrets document). */
146
+ export declare function getSecretSettingKeys(): readonly string[];
147
+ export declare function isSecretSettingKey(name: string): boolean;
148
+ /**
149
+ * Classify a CLINKX_* env name for the env-read scan (S0-1) and the guided
150
+ * trim: registry key, legacy alias of a key, or member of exactly one
151
+ * exclusion list. undefined means unclassified — the scan fails on it.
152
+ */
153
+ export type SettingsNameClassification = {
154
+ readonly kind: "key";
155
+ readonly key: string;
156
+ } | {
157
+ readonly kind: "alias";
158
+ readonly of: string;
159
+ } | {
160
+ readonly kind: "excluded";
161
+ readonly list: SettingsExclusionListName;
162
+ };
163
+ export declare function classifySettingsEnvName(name: string): SettingsNameClassification | undefined;
164
+ export interface SettingsExclusionEntry {
165
+ readonly name: string;
166
+ readonly reason: string;
167
+ }
168
+ export type SettingsExclusionListName = "ENV_ONLY" | "DEPLOYMENT_ONLY" | "DEAD";
169
+ export interface SettingsExclusionList {
170
+ readonly name: SettingsExclusionListName;
171
+ readonly description: string;
172
+ readonly entries: ReadonlyMap<string, string>;
173
+ }
174
+ export declare const SETTINGS_ENV_ONLY: readonly SettingsExclusionEntry[];
175
+ export declare const SETTINGS_DEPLOYMENT_ONLY: readonly SettingsExclusionEntry[];
176
+ export declare const SETTINGS_DEAD: readonly SettingsExclusionEntry[];
177
+ export declare function getSettingsExclusionLists(): readonly SettingsExclusionList[];
178
+ export {};