@ekanos/harness 0.18.0 → 0.19.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 (184) hide show
  1. package/dist/api-types.d.ts +490 -0
  2. package/dist/api-types.js +6 -0
  3. package/dist/api.d.ts +33 -0
  4. package/dist/api.js +36 -1
  5. package/dist/app.js +6 -1
  6. package/dist/internal/components/approvals-tray.d.ts +17 -0
  7. package/dist/internal/components/approvals-tray.js +116 -0
  8. package/dist/internal/components/connect-controls.d.ts +12 -0
  9. package/dist/internal/components/connect-controls.js +69 -0
  10. package/dist/internal/components/connect-dialog.d.ts +19 -0
  11. package/dist/internal/components/connect-dialog.js +61 -0
  12. package/dist/internal/components/connect-panel.d.ts +25 -0
  13. package/dist/internal/components/connect-panel.js +292 -0
  14. package/dist/internal/components/connection-chip.d.ts +14 -0
  15. package/dist/internal/components/connection-chip.js +75 -0
  16. package/dist/internal/components/dashboard-grid.js +38 -24
  17. package/dist/internal/components/dev-toolbar.js +176 -103
  18. package/dist/internal/components/events-panel.d.ts +10 -0
  19. package/dist/internal/components/events-panel.js +111 -0
  20. package/dist/internal/components/health-panel.d.ts +4 -0
  21. package/dist/internal/components/health-panel.js +56 -0
  22. package/dist/internal/components/integration-badge.d.ts +29 -0
  23. package/dist/internal/components/integration-badge.js +105 -0
  24. package/dist/internal/components/local-oauth-panel.js +21 -1
  25. package/dist/internal/components/operation-runner-panel.d.ts +12 -0
  26. package/dist/internal/components/operation-runner-panel.js +331 -0
  27. package/dist/internal/components/provenance-banner.d.ts +12 -0
  28. package/dist/internal/components/provenance-banner.js +107 -0
  29. package/dist/internal/components/repo-connection.d.ts +10 -0
  30. package/dist/internal/components/repo-connection.js +32 -0
  31. package/dist/internal/components/run-log.d.ts +9 -0
  32. package/dist/internal/components/run-log.js +228 -0
  33. package/dist/internal/components/runtime-strip.d.ts +12 -0
  34. package/dist/internal/components/runtime-strip.js +158 -0
  35. package/dist/internal/components/schema-form.d.ts +13 -0
  36. package/dist/internal/components/schema-form.js +382 -0
  37. package/dist/internal/components/scrollable-nav.d.ts +12 -0
  38. package/dist/internal/components/scrollable-nav.js +68 -0
  39. package/dist/internal/components/surface-nav.d.ts +31 -1
  40. package/dist/internal/components/surface-nav.js +238 -31
  41. package/dist/internal/components/workflow-runner.d.ts +14 -0
  42. package/dist/internal/components/workflow-runner.js +104 -0
  43. package/dist/internal/lib/bundled-secrets.d.ts +9 -0
  44. package/dist/internal/lib/bundled-secrets.js +24 -0
  45. package/dist/internal/lib/chrome-slot.d.ts +2 -0
  46. package/dist/internal/lib/chrome-slot.js +25 -0
  47. package/dist/internal/lib/connection-facts.d.ts +44 -0
  48. package/dist/internal/lib/connection-facts.js +116 -0
  49. package/dist/internal/lib/console-client.d.ts +55 -0
  50. package/dist/internal/lib/console-client.js +295 -0
  51. package/dist/internal/lib/console-context.d.ts +40 -0
  52. package/dist/internal/lib/console-context.js +67 -0
  53. package/dist/internal/lib/console-hooks.d.ts +33 -0
  54. package/dist/internal/lib/console-hooks.js +118 -0
  55. package/dist/internal/lib/console-types.d.ts +279 -0
  56. package/dist/internal/lib/console-types.js +0 -0
  57. package/dist/internal/lib/experience-runtime.d.ts +8 -0
  58. package/dist/internal/lib/experience-runtime.js +22 -0
  59. package/dist/internal/lib/preview-sections.d.ts +13 -0
  60. package/dist/internal/lib/preview-sections.js +32 -0
  61. package/dist/internal/lib/repo-context.d.ts +20 -0
  62. package/dist/internal/lib/repo-context.js +64 -0
  63. package/dist/internal/lib/run-log-view.d.ts +24 -0
  64. package/dist/internal/lib/run-log-view.js +57 -0
  65. package/dist/internal/lib/schema-form-model.d.ts +34 -0
  66. package/dist/internal/lib/schema-form-model.js +272 -0
  67. package/dist/internal/lib/toolbar-context.d.ts +9 -1
  68. package/dist/internal/lib/toolbar-context.js +13 -3
  69. package/dist/internal/lib/toolbar-visibility.d.ts +16 -0
  70. package/dist/internal/lib/toolbar-visibility.js +31 -0
  71. package/dist/internal/registry-context.d.ts +2 -0
  72. package/dist/internal/registry-context.js +11 -9
  73. package/dist/internal/routes/activation-page.js +44 -20
  74. package/dist/internal/routes/console-home-page.d.ts +5 -0
  75. package/dist/internal/routes/console-home-page.js +18 -0
  76. package/dist/internal/routes/experience-connect-page.d.ts +6 -0
  77. package/dist/internal/routes/experience-connect-page.js +127 -0
  78. package/dist/internal/routes/experience-page-host.d.ts +2 -0
  79. package/dist/internal/routes/experience-page-host.js +18 -0
  80. package/dist/internal/routes/experience-review-queue-page.d.ts +2 -0
  81. package/dist/internal/routes/experience-review-queue-page.js +60 -0
  82. package/dist/internal/routes/experience-runs-page.d.ts +1 -0
  83. package/dist/internal/routes/experience-runs-page.js +13 -0
  84. package/dist/internal/routes/experience-summary-page.d.ts +1 -0
  85. package/dist/internal/routes/experience-summary-page.js +101 -0
  86. package/dist/internal/routes/experience-widget-page.d.ts +1 -0
  87. package/dist/internal/routes/experience-widget-page.js +26 -0
  88. package/dist/internal/routes/experience-widgets-page.d.ts +6 -0
  89. package/dist/internal/routes/experience-widgets-page.js +22 -0
  90. package/dist/internal/routes/experience-workflow-page.d.ts +1 -0
  91. package/dist/internal/routes/experience-workflow-page.js +24 -0
  92. package/dist/internal/routes/experience-workflows-page.d.ts +1 -0
  93. package/dist/internal/routes/experience-workflows-page.js +44 -0
  94. package/dist/internal/routes/index-page.d.ts +10 -9
  95. package/dist/internal/routes/index-page.js +3 -68
  96. package/dist/internal/routes/integration-layout.d.ts +12 -1
  97. package/dist/internal/routes/integration-layout.js +20 -6
  98. package/dist/internal/routes/integrations-connect-page.d.ts +1 -0
  99. package/dist/internal/routes/integrations-connect-page.js +19 -0
  100. package/dist/internal/routes/integrations-events-page.d.ts +1 -0
  101. package/dist/internal/routes/integrations-events-page.js +10 -0
  102. package/dist/internal/routes/integrations-health-page.d.ts +1 -0
  103. package/dist/internal/routes/integrations-health-page.js +10 -0
  104. package/dist/internal/routes/integrations-layout.d.ts +17 -0
  105. package/dist/internal/routes/integrations-layout.js +106 -0
  106. package/dist/internal/routes/integrations-list-page.d.ts +2 -0
  107. package/dist/internal/routes/integrations-list-page.js +94 -0
  108. package/dist/internal/routes/integrations-operation-page.d.ts +1 -0
  109. package/dist/internal/routes/integrations-operation-page.js +29 -0
  110. package/dist/internal/routes/integrations-operations-page.d.ts +1 -0
  111. package/dist/internal/routes/integrations-operations-page.js +61 -0
  112. package/dist/internal/routes/integrations-overview-page.d.ts +1 -0
  113. package/dist/internal/routes/integrations-overview-page.js +90 -0
  114. package/dist/internal/routes/integrations-runs-page.d.ts +1 -0
  115. package/dist/internal/routes/integrations-runs-page.js +14 -0
  116. package/dist/internal/routes/integrations-scope.d.ts +12 -0
  117. package/dist/internal/routes/integrations-scope.js +39 -0
  118. package/dist/internal/routes/legacy-preview-redirect.d.ts +6 -0
  119. package/dist/internal/routes/legacy-preview-redirect.js +12 -0
  120. package/dist/internal/routes/preview-index-page.d.ts +2 -0
  121. package/dist/internal/routes/preview-index-page.js +14 -0
  122. package/dist/internal/routes/repo-connections-page.d.ts +6 -0
  123. package/dist/internal/routes/repo-connections-page.js +8 -0
  124. package/dist/internal/routes/repo-home-page.d.ts +2 -0
  125. package/dist/internal/routes/repo-home-page.js +320 -0
  126. package/dist/internal/routes/repo-layout.d.ts +7 -0
  127. package/dist/internal/routes/repo-layout.js +76 -0
  128. package/dist/internal/routes/repo-package-layouts.d.ts +20 -0
  129. package/dist/internal/routes/repo-package-layouts.js +104 -0
  130. package/dist/internal/routes/root-layout.d.ts +3 -1
  131. package/dist/internal/routes/root-layout.js +13 -3
  132. package/dist/internal/routes/single-widget-page.js +5 -12
  133. package/dist/internal/routes/tile-page.js +20 -41
  134. package/dist/internal/routes/triggers-page.js +55 -62
  135. package/dist/internal/routes/widgets-page.js +1 -1
  136. package/dist/internal/server/api-router.js +46 -4
  137. package/dist/internal/server/approvals.d.ts +44 -0
  138. package/dist/internal/server/approvals.js +76 -0
  139. package/dist/internal/server/contract-sources.d.ts +28 -0
  140. package/dist/internal/server/contract-sources.js +83 -0
  141. package/dist/internal/server/definition-loader.d.ts +22 -0
  142. package/dist/internal/server/definition-loader.js +125 -0
  143. package/dist/internal/server/ekanos-api-router.d.ts +34 -0
  144. package/dist/internal/server/ekanos-api-router.js +835 -0
  145. package/dist/internal/server/experience-loader.d.ts +57 -0
  146. package/dist/internal/server/experience-loader.js +146 -0
  147. package/dist/internal/server/integration-lookup.d.ts +29 -0
  148. package/dist/internal/server/integration-lookup.js +33 -0
  149. package/dist/internal/server/integration-resolver.d.ts +121 -0
  150. package/dist/internal/server/integration-resolver.js +605 -0
  151. package/dist/internal/server/live-invoker.d.ts +11 -0
  152. package/dist/internal/server/live-invoker.js +106 -0
  153. package/dist/internal/server/local-secrets.d.ts +82 -1
  154. package/dist/internal/server/local-secrets.js +112 -1
  155. package/dist/internal/server/local-state.d.ts +12 -0
  156. package/dist/internal/server/local-state.js +45 -0
  157. package/dist/internal/server/oauth-persistence.d.ts +19 -0
  158. package/dist/internal/server/oauth-persistence.js +76 -0
  159. package/dist/internal/server/operation-runner.d.ts +95 -0
  160. package/dist/internal/server/operation-runner.js +231 -0
  161. package/dist/internal/server/project-manifest.d.ts +71 -0
  162. package/dist/internal/server/project-manifest.js +215 -0
  163. package/dist/internal/server/registry-cache.d.ts +68 -0
  164. package/dist/internal/server/registry-cache.js +328 -0
  165. package/dist/internal/server/repo-api-router.d.ts +33 -0
  166. package/dist/internal/server/repo-api-router.js +391 -0
  167. package/dist/internal/server/run-log.d.ts +22 -0
  168. package/dist/internal/server/run-log.js +32 -0
  169. package/dist/internal/server/semantics.d.ts +28 -0
  170. package/dist/internal/server/semantics.js +67 -0
  171. package/dist/internal/server/session-catalog.d.ts +67 -0
  172. package/dist/internal/server/session-catalog.js +18 -0
  173. package/dist/internal/server/workflow-runner.d.ts +36 -0
  174. package/dist/internal/server/workflow-runner.js +183 -0
  175. package/dist/registry.d.ts +7 -0
  176. package/dist/resolver.d.ts +145 -0
  177. package/dist/resolver.js +211 -0
  178. package/dist/routes.d.ts +64 -2
  179. package/dist/routes.js +59 -3
  180. package/dist/runtime.d.ts +46 -0
  181. package/dist/runtime.js +60 -0
  182. package/package.json +23 -9
  183. package/dist/internal/routes/integration-index-page.d.ts +0 -13
  184. package/dist/internal/routes/integration-index-page.js +0 -17
@@ -0,0 +1,106 @@
1
+ import { invokeWebhook } from "@ekanos/sdk/testing";
2
+ import { getLiveState } from "./live-context.js";
3
+ import {
4
+ declaredSecretNames,
5
+ peekSecretValues,
6
+ readLocalSecrets
7
+ } from "./local-secrets.js";
8
+ import { restoreOauthConnections } from "./oauth-persistence.js";
9
+ function liveIntegration(definition) {
10
+ return {
11
+ slug: definition.slug,
12
+ name: definition.name,
13
+ description: definition.description,
14
+ widgets: [],
15
+ definition
16
+ };
17
+ }
18
+ async function liveStateFor(integration, networkFetch) {
19
+ if (!integration.loadDefinition) {
20
+ throw new Error(
21
+ `integration "${integration.integration}" has no integration code to run live`
22
+ );
23
+ }
24
+ const definition = await integration.loadDefinition();
25
+ const names = declaredSecretNames(definition);
26
+ const secrets = readLocalSecrets({
27
+ projectRoot: integration.credentialRoot,
28
+ slug: definition.slug,
29
+ names
30
+ });
31
+ if (!secrets.ok) throw new Error(secrets.message);
32
+ const state = getLiveState({
33
+ integration: liveIntegration(definition),
34
+ definition,
35
+ adminSecrets: secrets.values,
36
+ accountSecrets: secrets.activation,
37
+ secretsFingerprint: secrets.fingerprint,
38
+ ...networkFetch ? { networkFetch } : {}
39
+ });
40
+ await restoreOauthConnections({
41
+ state,
42
+ definition,
43
+ projectRoot: integration.credentialRoot,
44
+ adminSecrets: secrets.values
45
+ });
46
+ return { state, definition };
47
+ }
48
+ function createLiveInvoker(options = {}) {
49
+ return {
50
+ async invoke({ integration, kind, name, input }) {
51
+ const { state, definition } = await liveStateFor(
52
+ integration,
53
+ options.networkFetch
54
+ );
55
+ if (kind === "tool") {
56
+ const tool = definition.tools?.find(
57
+ (candidate) => candidate.name === name
58
+ );
59
+ if (!tool)
60
+ throw new Error(`"${definition.slug}" declares no tool "${name}"`);
61
+ return tool.run(state.ctx, input);
62
+ }
63
+ const action = definition.actions?.[name];
64
+ if (!action)
65
+ throw new Error(`"${definition.slug}" declares no action "${name}"`);
66
+ const parsed = action.input.safeParse(input);
67
+ if (!parsed.success) {
68
+ throw new Error(
69
+ `action "${name}" input failed its own schema: ${JSON.stringify(parsed.error.issues).slice(0, 400)}`
70
+ );
71
+ }
72
+ return action.handler(state.ctx, parsed.data);
73
+ },
74
+ async deliverWebhook({ integration, webhookId, payload }) {
75
+ const { state, definition } = await liveStateFor(
76
+ integration,
77
+ options.networkFetch
78
+ );
79
+ const webhook = definition.webhooks?.find((w) => w.id === webhookId);
80
+ if (!webhook) {
81
+ throw new Error(
82
+ `"${definition.slug}" declares no webhook "${webhookId}"`
83
+ );
84
+ }
85
+ const { result } = await invokeWebhook(definition, webhookId, payload, {
86
+ context: state.ctx,
87
+ headers: webhook.signature === "none" ? {} : { [webhook.signature.header]: "(unverified \u2014 local transport)" }
88
+ });
89
+ return {
90
+ status: result.status,
91
+ ...result.detail ? { detail: result.detail } : {},
92
+ ...result.events ? { events: result.events } : {}
93
+ };
94
+ },
95
+ secretsFor(integration) {
96
+ return peekSecretValues({
97
+ projectRoot: integration.credentialRoot,
98
+ slug: integration.integration
99
+ });
100
+ }
101
+ };
102
+ }
103
+ export {
104
+ createLiveInvoker,
105
+ liveStateFor
106
+ };
@@ -1,4 +1,4 @@
1
- import { type IntegrationDefinition } from '@ekanos/sdk/integration';
1
+ import { type IntegrationDefinition, type OAuthTokens } from '@ekanos/sdk/integration';
2
2
  /**
3
3
  * ─────────────────────────────────────────────────────────────────────────────
4
4
  * `.ekanos/local-secrets.json` — the harness's admin-tier credential source
@@ -116,3 +116,84 @@ export declare function writeActivationSecrets(args: {
116
116
  slug: string;
117
117
  activationData: unknown;
118
118
  }): LocalSecretsWrite;
119
+ /**
120
+ * Whether an activation-form field holds a credential, judged by its name.
121
+ * The host has no per-field secret marker, so the harness cannot tell a token
122
+ * from a project id by value; a name that says token / secret / key /
123
+ * password / credential / auth is a credential, anything else (a project id,
124
+ * a dataset, a region) is configuration and may appear in a response.
125
+ */
126
+ export declare function isSensitiveFieldName(name: string): boolean;
127
+ /**
128
+ * Every non-empty credential value stored for `slug` — the admin tier (every
129
+ * declared secret name) and the activation-tier fields whose name marks a credential — WITHOUT creating or changing the
130
+ * file. For scrubbing: the operation runner removes these from anything it
131
+ * returns or logs.
132
+ */
133
+ export declare function peekSecretValues(args: {
134
+ projectRoot: string;
135
+ slug: string;
136
+ }): string[];
137
+ /**
138
+ * A non-sensitive activation-form field, shown next to "Connected" so a
139
+ * developer can see WHAT the local credentials point at (a project id, a
140
+ * dataset). `label` is the field's key: the harness holds no form definition.
141
+ */
142
+ export interface ConnectionTargetField {
143
+ key: string;
144
+ label: string;
145
+ value: string;
146
+ }
147
+ /**
148
+ * The fields of a stored activation submission that are safe to show: string
149
+ * fields whose name does not mark a credential (`isSensitiveFieldName`, the
150
+ * rule the credential scrub uses), that no declared secret name claims, and
151
+ * whose value looks like an identifier rather than a pasted secret blob.
152
+ * Secrets are never partially masked; they are simply absent.
153
+ */
154
+ export declare function selectConnectionTarget(activation: Record<string, string>, declaredNames?: readonly string[]): ConnectionTargetField[];
155
+ export type LocalSecretsClear = {
156
+ ok: true;
157
+ removed: boolean;
158
+ } | {
159
+ ok: false;
160
+ message: string;
161
+ };
162
+ /**
163
+ * Remove `slug`'s `activationData` block, and nothing else: other slugs, the
164
+ * admin-tier names (OAuth client credentials) and the help line stay. Never
165
+ * creates the file or the slug's block, and keeps the file at 0600.
166
+ */
167
+ export declare function clearActivationBlock(args: {
168
+ projectRoot: string;
169
+ slug: string;
170
+ }): LocalSecretsClear;
171
+ /**
172
+ * The block key holding the OAuth tokens a completed Connect obtained, one
173
+ * entry per connection id. Persisted so a connection lasts until Disconnect
174
+ * rather than until the dev server restarts; the file is 0600 and under the
175
+ * gitignored `.ekanos/`, like every other credential here.
176
+ */
177
+ export declare const OAUTH_BLOCK_KEY = "oauthTokens";
178
+ export interface StoredOauthConnection {
179
+ tokens: OAuthTokens;
180
+ obtainedAt: string;
181
+ expiresAt: string | null;
182
+ scope: string | null;
183
+ /** Which OAuth app issued them: a changed client id invalidates them. */
184
+ clientKey: string;
185
+ }
186
+ /** A short digest of the client id, so a stored token can be tied to its app. */
187
+ export declare function oauthClientKey(clientId: string): string;
188
+ /** Every stored OAuth connection for `slug`, by connection id. Never creates the file. */
189
+ export declare function readOauthConnections(args: {
190
+ projectRoot: string;
191
+ slug: string;
192
+ }): Record<string, StoredOauthConnection>;
193
+ /** Store (replacing) one connection's tokens, keeping everything else in the file. */
194
+ export declare function writeOauthConnection(args: {
195
+ projectRoot: string;
196
+ slug: string;
197
+ connectionId: string;
198
+ connection: StoredOauthConnection;
199
+ }): LocalSecretsWrite;
@@ -57,6 +57,7 @@ function writeDocument(file, doc) {
57
57
  encoding: "utf8",
58
58
  mode: 384
59
59
  });
60
+ fs.chmodSync(file, 384);
60
61
  }
61
62
  function fingerprintOf(values, activation) {
62
63
  const hash = createHash("sha256");
@@ -189,11 +190,121 @@ function writeActivationSecrets(args) {
189
190
  writeDocument(file, doc);
190
191
  return { ok: true };
191
192
  }
193
+ function isSensitiveFieldName(name) {
194
+ return /secret|token|passw|credential|auth|bearer|signature|(^|[-_ ])key($|[-_ ])|[a-z]key$|api[-_ ]?key|private[-_ ]?key/i.test(
195
+ name
196
+ );
197
+ }
198
+ function peekSecretValues(args) {
199
+ const file = path.join(args.projectRoot, LOCAL_SECRETS_RELATIVE_PATH);
200
+ let existing;
201
+ try {
202
+ existing = readDocument(file);
203
+ } catch {
204
+ return [];
205
+ }
206
+ if (existing.kind !== "ok") return [];
207
+ const block = existing.doc[args.slug];
208
+ if (!isRecord(block)) return [];
209
+ const values = [];
210
+ for (const [key, value] of Object.entries(block)) {
211
+ if (typeof value === "string" && value.trim().length > 0) {
212
+ values.push(value);
213
+ } else if (key === ACTIVATION_BLOCK_KEY) {
214
+ for (const [field, fieldValue] of Object.entries(stringFields(value))) {
215
+ if (isSensitiveFieldName(field)) values.push(fieldValue);
216
+ }
217
+ } else if (key === OAUTH_BLOCK_KEY && isRecord(value)) {
218
+ for (const stored of Object.values(value)) {
219
+ if (!isStoredOauth(stored)) continue;
220
+ values.push(stored.tokens.accessToken);
221
+ if (stored.tokens.refreshToken) values.push(stored.tokens.refreshToken);
222
+ }
223
+ }
224
+ }
225
+ return values;
226
+ }
227
+ const TARGET_VALUE_MAX_LENGTH = 80;
228
+ function selectConnectionTarget(activation, declaredNames = []) {
229
+ const declared = new Set(declaredNames);
230
+ return Object.entries(activation).filter(
231
+ ([key, value]) => !declared.has(key) && !isSensitiveFieldName(key) && value.trim().length > 0 && value.length <= TARGET_VALUE_MAX_LENGTH && !/\s/.test(value)
232
+ ).sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => ({ key, label: key, value }));
233
+ }
234
+ function clearActivationBlock(args) {
235
+ const file = path.join(args.projectRoot, LOCAL_SECRETS_RELATIVE_PATH);
236
+ const existing = readDocument(file);
237
+ if (existing.kind === "missing") return { ok: true, removed: false };
238
+ if (existing.kind === "corrupt") {
239
+ return {
240
+ ok: false,
241
+ message: `${file} is not a JSON object; fix or delete it by hand first.`
242
+ };
243
+ }
244
+ const block = existing.doc[args.slug];
245
+ if (!isRecord(block) || !(ACTIVATION_BLOCK_KEY in block || OAUTH_BLOCK_KEY in block)) {
246
+ return { ok: true, removed: false };
247
+ }
248
+ const rest = { ...block };
249
+ delete rest[ACTIVATION_BLOCK_KEY];
250
+ delete rest[OAUTH_BLOCK_KEY];
251
+ writeDocument(file, { ...existing.doc, [args.slug]: rest });
252
+ return { ok: true, removed: true };
253
+ }
254
+ const OAUTH_BLOCK_KEY = "oauthTokens";
255
+ function oauthClientKey(clientId) {
256
+ return createHash("sha256").update(clientId).digest("hex").slice(0, 16);
257
+ }
258
+ function isStoredOauth(value) {
259
+ return isRecord(value) && isRecord(value.tokens) && typeof value.tokens.accessToken === "string" && typeof value.obtainedAt === "string" && typeof value.clientKey === "string";
260
+ }
261
+ function readOauthConnections(args) {
262
+ const file = path.join(args.projectRoot, LOCAL_SECRETS_RELATIVE_PATH);
263
+ let existing;
264
+ try {
265
+ existing = readDocument(file);
266
+ } catch {
267
+ return {};
268
+ }
269
+ if (existing.kind !== "ok") return {};
270
+ const block = existing.doc[args.slug];
271
+ if (!isRecord(block) || !isRecord(block[OAUTH_BLOCK_KEY])) return {};
272
+ return Object.fromEntries(
273
+ Object.entries(block[OAUTH_BLOCK_KEY]).filter(
274
+ (entry) => isStoredOauth(entry[1])
275
+ )
276
+ );
277
+ }
278
+ function writeOauthConnection(args) {
279
+ const file = path.join(args.projectRoot, LOCAL_SECRETS_RELATIVE_PATH);
280
+ const existing = readDocument(file);
281
+ if (existing.kind === "corrupt") {
282
+ return {
283
+ ok: false,
284
+ message: `${file} is not a JSON object; fix or delete it by hand first.`
285
+ };
286
+ }
287
+ const doc = existing.kind === "ok" ? { ...existing.doc } : { "//": HELP };
288
+ const block = isRecord(doc[args.slug]) ? { ...doc[args.slug] } : {};
289
+ const held = isRecord(block[OAUTH_BLOCK_KEY]) ? block[OAUTH_BLOCK_KEY] : {};
290
+ block[OAUTH_BLOCK_KEY] = { ...held, [args.connectionId]: args.connection };
291
+ doc[args.slug] = block;
292
+ writeDocument(file, doc);
293
+ return { ok: true };
294
+ }
192
295
  export {
193
296
  ACTIVATION_BLOCK_KEY,
194
297
  LOCAL_SECRETS_RELATIVE_PATH,
298
+ OAUTH_BLOCK_KEY,
299
+ clearActivationBlock,
195
300
  declaredSecretNames,
301
+ isSensitiveFieldName,
302
+ oauthClientKey,
303
+ peekSecretValues,
196
304
  readLocalSecrets,
305
+ readOauthConnections,
306
+ selectConnectionTarget,
197
307
  writeActivationSecrets,
198
- writeLocalSecrets
308
+ writeLocalSecrets,
309
+ writeOauthConnection
199
310
  };
@@ -0,0 +1,12 @@
1
+ /**
2
+ * `.ekanos/local-state.json` — non-secret local choices, kept apart from
3
+ * credentials. Today: which integrations the dev pinned to fixtures, keyed by
4
+ * integration slug (`{ "pinnedFixtures": { "<slug>": true } }`), so integrations
5
+ * that share one file (registry integrations of an experience) pin one by one.
6
+ * `.ekanos/` is gitignored; `.ekanos/harness` is the only part `ekanos dev`
7
+ * regenerates, so this file survives that.
8
+ */
9
+ export declare const LOCAL_STATE_RELATIVE_PATH: string;
10
+ export declare function isPinnedToFixtures(root: string, slug: string): boolean;
11
+ /** Pin sets this slug's key; unpin removes it, and the file once empty. */
12
+ export declare function setPinnedToFixtures(root: string, slug: string, pinned: boolean): void;
@@ -0,0 +1,45 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ const LOCAL_STATE_RELATIVE_PATH = path.join(
4
+ ".ekanos",
5
+ "local-state.json"
6
+ );
7
+ function readPins(file) {
8
+ try {
9
+ const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
10
+ const pins = typeof parsed === "object" && parsed !== null ? parsed.pinnedFixtures : void 0;
11
+ if (typeof pins !== "object" || pins === null) return {};
12
+ return Object.fromEntries(
13
+ Object.entries(pins).filter(([, value]) => value === true)
14
+ );
15
+ } catch (error) {
16
+ if (error.code !== "ENOENT") {
17
+ console.error("[harness] local-state.json could not be read", error);
18
+ }
19
+ return {};
20
+ }
21
+ }
22
+ function isPinnedToFixtures(root, slug) {
23
+ return readPins(path.join(root, LOCAL_STATE_RELATIVE_PATH))[slug] === true;
24
+ }
25
+ function setPinnedToFixtures(root, slug, pinned) {
26
+ const file = path.join(root, LOCAL_STATE_RELATIVE_PATH);
27
+ const pins = readPins(file);
28
+ if (pinned) pins[slug] = true;
29
+ else delete pins[slug];
30
+ if (Object.keys(pins).length === 0) {
31
+ fs.rmSync(file, { force: true });
32
+ return;
33
+ }
34
+ fs.mkdirSync(path.dirname(file), { recursive: true });
35
+ fs.writeFileSync(
36
+ file,
37
+ `${JSON.stringify({ pinnedFixtures: pins }, null, 2)}
38
+ `
39
+ );
40
+ }
41
+ export {
42
+ LOCAL_STATE_RELATIVE_PATH,
43
+ isPinnedToFixtures,
44
+ setPinnedToFixtures
45
+ };
@@ -0,0 +1,19 @@
1
+ import { type IntegrationDefinition, type OAuthTokens } from '@ekanos/sdk/integration';
2
+ import type { LiveConnection, LiveState } from './live-context.js';
3
+ export declare function persistOauthConnection(args: {
4
+ projectRoot: string;
5
+ slug: string;
6
+ connectionId: string;
7
+ clientId: string;
8
+ tokens: OAuthTokens;
9
+ fact: LiveConnection;
10
+ }): void;
11
+ /** Whether tokens are stored for `slug`, whether or not a live context holds them. */
12
+ export declare function hasStoredOauthConnection(projectRoot: string, slug: string): boolean;
13
+ /** Replay stored tokens into a freshly built live context, once per context. */
14
+ export declare function restoreOauthConnections(args: {
15
+ state: LiveState;
16
+ definition: IntegrationDefinition;
17
+ projectRoot: string;
18
+ adminSecrets: Readonly<Record<string, string>>;
19
+ }): Promise<void>;
@@ -0,0 +1,76 @@
1
+ import {
2
+ DEFAULT_OAUTH_CONNECTION_ID
3
+ } from "@ekanos/sdk/integration";
4
+ import {
5
+ oauthClientKey,
6
+ readOauthConnections,
7
+ writeOauthConnection
8
+ } from "./local-secrets.js";
9
+ function oauthFor(definition, connectionId) {
10
+ if (connectionId === DEFAULT_OAUTH_CONNECTION_ID) return definition.oauth;
11
+ const named = definition.oauthConnections ?? {};
12
+ return Object.hasOwn(named, connectionId) ? named[connectionId] : void 0;
13
+ }
14
+ function persistOauthConnection(args) {
15
+ const written = writeOauthConnection({
16
+ projectRoot: args.projectRoot,
17
+ slug: args.slug,
18
+ connectionId: args.connectionId,
19
+ connection: {
20
+ tokens: args.tokens,
21
+ obtainedAt: args.fact.obtainedAt,
22
+ expiresAt: args.fact.expiresAt,
23
+ scope: args.fact.scope,
24
+ clientKey: oauthClientKey(args.clientId)
25
+ }
26
+ });
27
+ if (!written.ok) {
28
+ console.error(
29
+ `[harness:${args.slug}] could not keep the OAuth connection: ${written.message}`
30
+ );
31
+ }
32
+ }
33
+ function hasStoredOauthConnection(projectRoot, slug) {
34
+ return Object.keys(readOauthConnections({ projectRoot, slug })).length > 0;
35
+ }
36
+ const restored = /* @__PURE__ */ new WeakSet();
37
+ async function restoreOauthConnections(args) {
38
+ if (restored.has(args.state)) return;
39
+ restored.add(args.state);
40
+ const stored = readOauthConnections({
41
+ projectRoot: args.projectRoot,
42
+ slug: args.state.slug
43
+ });
44
+ for (const [connectionId, connection] of Object.entries(stored)) {
45
+ const oauth = oauthFor(args.definition, connectionId);
46
+ if (!oauth) continue;
47
+ const clientId = args.adminSecrets[oauth.credentials.clientIdSecretName];
48
+ if (!clientId || oauthClientKey(clientId) !== connection.clientKey) {
49
+ continue;
50
+ }
51
+ try {
52
+ await oauth.onTokens(args.state.ctx, connection.tokens);
53
+ } catch (error) {
54
+ console.error(
55
+ `[harness:${args.state.slug}] restoring the OAuth connection "${connectionId}" failed; connect again.`,
56
+ error
57
+ );
58
+ continue;
59
+ }
60
+ const fact = {
61
+ obtainedAt: connection.obtainedAt,
62
+ expiresAt: connection.expiresAt,
63
+ scope: connection.scope
64
+ };
65
+ if (connectionId === DEFAULT_OAUTH_CONNECTION_ID) {
66
+ args.state.connection = fact;
67
+ } else {
68
+ args.state.connections[connectionId] = fact;
69
+ }
70
+ }
71
+ }
72
+ export {
73
+ hasStoredOauthConnection,
74
+ persistOauthConnection,
75
+ restoreOauthConnections
76
+ };
@@ -0,0 +1,95 @@
1
+ import type { ContractOperation, OperationKind } from '@ekanos/integration-schema';
2
+ import type { ExecutionChannel, FixtureScenario, InternalWriteGate, OperationResult, RunMode, RunOperationRequest, RunRecord } from '../../api-types.js';
3
+ import type { ApprovalsTray } from './approvals.js';
4
+ import type { ResolvedIntegration } from './integration-resolver.js';
5
+ import type { RunLog } from './run-log.js';
6
+ import { type ExecutorLimits } from './semantics.js';
7
+ /**
8
+ * ─────────────────────────────────────────────────────────────────────────────
9
+ * THE LOCAL OPERATION RUNNER — the host executor, minus the host
10
+ * ─────────────────────────────────────────────────────────────────────────────
11
+ *
12
+ * Same step order and same reason strings as
13
+ * the host's experience executor:
14
+ *
15
+ * 1 integration exists slot_unknown
16
+ * 2 op is in the experience's allowlist operation_not_declared
17
+ * 3 op exists in the resolved contract operation_not_in_contract
18
+ * 4 binding/run mode is permitted mode_not_permitted
19
+ * 5 effect gate (writes) write_refused_on_channel /
20
+ * write_not_approved
21
+ * 6 input validates + size cap invalid_input / input_too_large
22
+ * 7 invoke under a deadline deadline_exceeded / execution_failed
23
+ * 8 output validates, FAIL-CLOSED + cap output_invalid / output_too_large
24
+ * 9 a run-log row, always
25
+ *
26
+ * Where it deliberately differs from the host: `channels.httpWrites`
27
+ * defaults to `'approval'` (decision O2 — existing widgets write, and the
28
+ * tray is how a human gates them), where the host's phase 1 still refuses an
29
+ * HTTP write outright. Set `'refuse'` to mirror the host exactly.
30
+ */
31
+ export type HttpWritePolicy = 'refuse' | 'approval';
32
+ export interface FixtureSource {
33
+ /** A scenario fixture for `integration`'s operation, or `undefined` when none is authored. */
34
+ read(integration: string, opKey: string, scenario: FixtureScenario): {
35
+ found: true;
36
+ value: unknown;
37
+ } | {
38
+ found: false;
39
+ };
40
+ }
41
+ export interface LiveInvoker {
42
+ invoke(args: {
43
+ integration: ResolvedIntegration;
44
+ operation: ContractOperation;
45
+ kind: OperationKind;
46
+ name: string;
47
+ input: unknown;
48
+ }): Promise<unknown>;
49
+ /**
50
+ * Deliver one payload to a declared webhook handler on the live context
51
+ * (`events/emit` in live mode). Optional: an invoker that cannot run
52
+ * handlers leaves emits validate-and-record only.
53
+ */
54
+ deliverWebhook?(args: {
55
+ integration: ResolvedIntegration;
56
+ webhookId: string;
57
+ payload: unknown;
58
+ }): Promise<{
59
+ status: string;
60
+ detail?: string;
61
+ events?: unknown;
62
+ }>;
63
+ /** Strings that must never appear in any text the runner returns or logs. */
64
+ secretsFor(integration: ResolvedIntegration): string[];
65
+ }
66
+ export interface RunnerDeps {
67
+ integrations: readonly ResolvedIntegration[];
68
+ channels: {
69
+ httpWrites: HttpWritePolicy;
70
+ };
71
+ approvals: ApprovalsTray;
72
+ runLog: RunLog;
73
+ fixtures: FixtureSource;
74
+ live: LiveInvoker;
75
+ limits?: Partial<ExecutorLimits>;
76
+ /**
77
+ * The mode for a request that names none. Absent, the integration's own
78
+ * default applies. Only consulted after the operation is known, so a read
79
+ * can differ from a write.
80
+ */
81
+ defaultModeFor?: (integration: ResolvedIntegration, effect: ContractOperation['effect']) => Promise<RunMode>;
82
+ /** Milliseconds a held approval waits for a decision. */
83
+ approvalTimeoutMs?: number;
84
+ now?: () => number;
85
+ }
86
+ export interface RunOutcome {
87
+ result: OperationResult;
88
+ run: RunRecord;
89
+ approvalId?: string;
90
+ }
91
+ export declare function createFileFixtureSource(projectRoot: string): FixtureSource;
92
+ export declare function runOperation(request: RunOperationRequest & {
93
+ gate?: InternalWriteGate;
94
+ }, deps: RunnerDeps): Promise<RunOutcome>;
95
+ export type { ExecutionChannel };