@ekanos/harness 0.17.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 +30 -16
  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,231 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ import { redactSensitive } from "../lib/redact.js";
4
+ import {
5
+ EXECUTOR_LIMITS,
6
+ REFUSAL_MESSAGES,
7
+ jsonBytes,
8
+ validateInput,
9
+ validateOutput
10
+ } from "./semantics.js";
11
+ const OP_KEY = /^(tool|action)\/([a-z][a-z0-9_-]*)$/;
12
+ class DeadlineError extends Error {
13
+ constructor() {
14
+ super("operation deadline exceeded");
15
+ this.name = "DeadlineError";
16
+ }
17
+ }
18
+ function createFileFixtureSource(projectRoot) {
19
+ return {
20
+ read(integration, opKey, scenario) {
21
+ const file = path.join(
22
+ projectRoot,
23
+ "fixtures",
24
+ integration,
25
+ `${opKey.replace("/", "-")}.${scenario}.json`
26
+ );
27
+ const root = path.join(projectRoot, "fixtures");
28
+ if (!path.resolve(file).startsWith(path.resolve(root) + path.sep)) {
29
+ return { found: false };
30
+ }
31
+ try {
32
+ return {
33
+ found: true,
34
+ value: JSON.parse(fs.readFileSync(file, "utf8"))
35
+ };
36
+ } catch (error) {
37
+ if (error.code === "ENOENT") {
38
+ return { found: false };
39
+ }
40
+ throw new Error(`fixture ${file} is not valid JSON`);
41
+ }
42
+ }
43
+ };
44
+ }
45
+ function scrubText(text, secrets) {
46
+ let out = text;
47
+ for (const secret of secrets) {
48
+ if (secret.length >= 4) out = out.split(secret).join("\u2039redacted\u203A");
49
+ }
50
+ return out;
51
+ }
52
+ async function runOperation(request, deps) {
53
+ const now = deps.now ?? Date.now;
54
+ const startedAt = now();
55
+ const limits = { ...EXECUTOR_LIMITS, ...deps.limits };
56
+ const integration = deps.integrations.find(
57
+ (candidate) => candidate.integration === request.integration
58
+ );
59
+ const secrets = integration ? deps.live.secretsFor(integration) : [];
60
+ const inputBytes = jsonBytes(request.input ?? {}) ?? 0;
61
+ let operation = null;
62
+ let mode = null;
63
+ let approvalId;
64
+ const record = (status, extra) => deps.runLog.append({
65
+ integration: request.integration,
66
+ version: integration?.version ?? "",
67
+ opKey: request.op,
68
+ effect: operation?.effect ?? null,
69
+ channel: request.channel,
70
+ mode,
71
+ provenance: integration?.provenance ?? null,
72
+ status,
73
+ ...extra.reason ? { reason: extra.reason } : {},
74
+ ...extra.detail ? { detail: scrubText(extra.detail, secrets) } : {},
75
+ durationMs: Math.max(0, now() - startedAt),
76
+ inputBytes,
77
+ outputBytes: extra.outputBytes ?? 0,
78
+ ...request.origin ? { origin: request.origin } : {},
79
+ ...approvalId ? { approvalId } : {}
80
+ });
81
+ const refuse = (reason, detail, status = "refused") => {
82
+ const safeDetail = detail ? scrubText(detail, secrets) : void 0;
83
+ const run2 = record(status, {
84
+ reason,
85
+ ...safeDetail ? { detail: safeDetail } : {}
86
+ });
87
+ return {
88
+ result: {
89
+ ok: false,
90
+ reason,
91
+ message: REFUSAL_MESSAGES[reason],
92
+ ...safeDetail ? { detail: safeDetail } : {}
93
+ },
94
+ run: run2,
95
+ ...approvalId ? { approvalId } : {}
96
+ };
97
+ };
98
+ if (!integration) return refuse("slot_unknown");
99
+ const parsedKey = OP_KEY.exec(request.op);
100
+ if (!parsedKey) return refuse("operation_not_declared");
101
+ const kind = parsedKey[1];
102
+ const name = parsedKey[2];
103
+ const id = `${integration.integration}@${integration.version}/${kind}/${name}`;
104
+ if (!integration.operations.includes(id))
105
+ return refuse("operation_not_declared");
106
+ operation = integration.contract.operations.find((candidate) => candidate.id === id) ?? null;
107
+ if (!operation) return refuse("operation_not_in_contract");
108
+ mode = request.mode ?? await deps.defaultModeFor?.(integration, operation.effect) ?? integration.defaultMode;
109
+ if (!integration.modes.includes(integration.bindingMode) || !integration.runModes.includes(mode)) {
110
+ return refuse("mode_not_permitted");
111
+ }
112
+ if (operation.effect === "write" && !request.gate) {
113
+ const gated = request.channel === "workflow" || deps.channels.httpWrites === "approval";
114
+ if (!gated) return refuse("write_refused_on_channel");
115
+ const pending = deps.approvals.request(
116
+ {
117
+ kind: "operation",
118
+ integration: integration.integration,
119
+ version: integration.version,
120
+ opKey: request.op,
121
+ channel: request.channel,
122
+ mode,
123
+ args: request.input,
124
+ provenance: integration.provenance
125
+ },
126
+ deps.approvalTimeoutMs
127
+ );
128
+ approvalId = pending.id;
129
+ const decision = await pending.decision;
130
+ if (decision !== "approved") {
131
+ return refuse(
132
+ "write_not_approved",
133
+ decision === "rejected" ? "rejected in the approvals tray" : "the approval expired"
134
+ );
135
+ }
136
+ }
137
+ const inputCheck = validateInput(
138
+ operation,
139
+ request.input,
140
+ limits.maxInputBytes
141
+ );
142
+ if (!inputCheck.valid) {
143
+ return refuse(
144
+ inputCheck.reason === "too_large" ? "input_too_large" : "invalid_input",
145
+ inputCheck.errors.join("; ")
146
+ );
147
+ }
148
+ let output;
149
+ let timer;
150
+ try {
151
+ const invocation = mode === "live" ? deps.live.invoke({
152
+ integration,
153
+ operation,
154
+ kind,
155
+ name,
156
+ input: request.input ?? {}
157
+ }) : Promise.resolve().then(
158
+ () => fixtureOutput(
159
+ deps.fixtures,
160
+ integration.integration,
161
+ request.op,
162
+ request.scenario ?? "default",
163
+ integration.contract,
164
+ operation
165
+ )
166
+ );
167
+ const deadline = new Promise((_, reject) => {
168
+ timer = setTimeout(() => reject(new DeadlineError()), limits.deadlineMs);
169
+ });
170
+ output = await Promise.race([invocation, deadline]);
171
+ } catch (error) {
172
+ if (error instanceof DeadlineError) {
173
+ return refuse("deadline_exceeded", void 0, "error");
174
+ }
175
+ return refuse(
176
+ "execution_failed",
177
+ error instanceof Error ? error.message : String(error),
178
+ "error"
179
+ );
180
+ } finally {
181
+ if (timer) clearTimeout(timer);
182
+ }
183
+ if (output !== void 0) output = JSON.parse(JSON.stringify(output));
184
+ const outputCheck = validateOutput(operation, output, limits.maxOutputBytes);
185
+ if (!outputCheck.valid) {
186
+ return refuse(
187
+ outputCheck.reason === "too_large" ? "output_too_large" : "output_invalid",
188
+ outputCheck.errors.join("; "),
189
+ "error"
190
+ );
191
+ }
192
+ if (mode === "live") {
193
+ const serialized = JSON.stringify(output);
194
+ if (secrets.some(
195
+ (secret) => secret.length >= 8 && serialized.includes(secret)
196
+ )) {
197
+ return refuse(
198
+ "output_invalid",
199
+ "the response contains a stored credential and was withheld",
200
+ "error"
201
+ );
202
+ }
203
+ }
204
+ const outputBytes = jsonBytes(output) ?? 0;
205
+ const run = record("ok", { outputBytes });
206
+ return {
207
+ result: { ok: true, data: output },
208
+ run,
209
+ ...approvalId ? { approvalId } : {}
210
+ };
211
+ }
212
+ function fixtureOutput(fixtures, integration, opKey, scenario, _contract, operation) {
213
+ if (scenario === "error") {
214
+ const authored2 = fixtures.read(integration, opKey, "error");
215
+ throw new Error(
216
+ authored2.found ? `error scenario: ${typeof authored2.value === "string" ? authored2.value : JSON.stringify(redactSensitive(authored2.value))}` : "error scenario"
217
+ );
218
+ }
219
+ const authored = fixtures.read(integration, opKey, scenario);
220
+ if (authored.found) return structuredClone(authored.value);
221
+ if (operation.outputExample !== void 0) {
222
+ return structuredClone(operation.outputExample);
223
+ }
224
+ throw new Error(
225
+ `no fixture for ${integration} ${opKey} (${scenario}) and the contract has no outputExample: add fixtures/${integration}/${opKey.replace("/", "-")}.${scenario}.json, or record from a real run with --from live`
226
+ );
227
+ }
228
+ export {
229
+ createFileFixtureSource,
230
+ runOperation
231
+ };
@@ -0,0 +1,71 @@
1
+ import { type IntegrationEntry, type Lockfile } from '@ekanos/integration-schema';
2
+ import type { BindingMode, HarnessKind, RunMode } from '../../api-types.js';
3
+ /**
4
+ * Reads the three small, static files that describe an experience project to
5
+ * the harness without executing any code: `ekanos.json` (kind +
6
+ * `integrations`), `ekanos.local.json` (overrides) and `ekanos.lock.json`
7
+ * (pins).
8
+ *
9
+ * The schemas below are the harness's READ side of lane A's
10
+ * `EkanosJsonSchema` / `LocalOverridesSchema` / `LockfileSchema`
11
+ * (`@ekanos/integration-schema`). They are deliberately tolerant of fields
12
+ * they do not use, and deliberately strict about the ones they do — a typo in
13
+ * an override must fail loudly, because the alternative is a silent registry
14
+ * integration where the developer thought they had a local one.
15
+ *
16
+ * The deprecated `uses` shape (an aliased slot) is still read for one
17
+ * version: its entries come back as `integrations`, with `renames` mapping an
18
+ * old alias to its integration so an `ekanos.local.json` written against the
19
+ * alias keeps working.
20
+ */
21
+ export declare const OVERRIDES_FILENAME = "ekanos.local.json";
22
+ export declare const LOCK_FILENAME = "ekanos.lock.json";
23
+ export declare const INTEGRATION_OVERRIDE_ENV_PREFIX = "EKANOS_INTEGRATION_OVERRIDE_";
24
+ export type ProjectManifest = {
25
+ kind: HarnessKind;
26
+ slug: string | null;
27
+ /** Every integration slug the project declares (`slug` or `integrations[]`). */
28
+ slugs: string[];
29
+ entry: string | null;
30
+ /** An experience's integrations; operations are canonical ids. */
31
+ integrations: IntegrationEntry[];
32
+ /** True when ekanos.json still uses the deprecated `uses` key. */
33
+ deprecatedUses: boolean;
34
+ /** Old `uses` alias -> integration, where they differ. */
35
+ renames: Record<string, string>;
36
+ contractsDir: string;
37
+ };
38
+ export type { IntegrationEntry };
39
+ export type LockIntegration = Lockfile['integrations'][string];
40
+ export declare class ProjectFileError extends Error {
41
+ readonly file: string;
42
+ constructor(file: string, message: string);
43
+ }
44
+ export declare function readProjectManifest(projectRoot: string): ProjectManifest;
45
+ /** `kind` of a project directory, or null when it has no (readable) ekanos.json. */
46
+ export declare function readProjectKind(projectRoot: string): HarnessKind | null;
47
+ export interface IntegrationOverride {
48
+ integration: string;
49
+ /** Absolute path of the integration project. */
50
+ path: string;
51
+ mode: RunMode;
52
+ via: 'file' | 'env';
53
+ }
54
+ export interface ProjectOverrides {
55
+ overrides: IntegrationOverride[];
56
+ bindingMode: Record<string, BindingMode>;
57
+ /** True when ekanos.local.json used the deprecated `slots` key. */
58
+ deprecatedSlotsKey: boolean;
59
+ }
60
+ /**
61
+ * `ekanos.local.json` plus `EKANOS_INTEGRATION_OVERRIDE_<INTEGRATION>` env
62
+ * vars (the deprecated `EKANOS_SLOT_OVERRIDE_<INTEGRATION>` is honoured too).
63
+ * An env var wins over the file for the same integration, and counts as an
64
+ * active override identically (publish refuses on either). Integration names
65
+ * map to the env suffix upper-cased with `-` as `_`.
66
+ *
67
+ * `renames` maps a deprecated `uses` alias to its integration so a file or env
68
+ * var written against the alias still lands on the right integration.
69
+ */
70
+ export declare function readProjectOverrides(projectRoot: string, env: Readonly<Record<string, string | undefined>>, integrationNames: readonly string[], renames?: Readonly<Record<string, string>>): ProjectOverrides;
71
+ export declare function readLockfile(projectRoot: string): Record<string, LockIntegration>;
@@ -0,0 +1,215 @@
1
+ import {
2
+ IntegrationEntrySchema,
3
+ LegacyUsesEntrySchema,
4
+ LocalOverridesSchema,
5
+ LockfileSchema,
6
+ canonicalOperationId,
7
+ integrationOverrideEnvName,
8
+ legacySlotOverrideEnvName,
9
+ upgradeLegacyUses
10
+ } from "@ekanos/integration-schema";
11
+ import * as fs from "node:fs";
12
+ import * as path from "node:path";
13
+ import { z } from "zod";
14
+ const OVERRIDES_FILENAME = "ekanos.local.json";
15
+ const LOCK_FILENAME = "ekanos.lock.json";
16
+ const INTEGRATION_OVERRIDE_ENV_PREFIX = "EKANOS_INTEGRATION_OVERRIDE_";
17
+ const ProjectManifestSchema = z.object({
18
+ kind: z.enum(["integration", "experience"]).default("integration"),
19
+ slug: z.string().optional(),
20
+ entry: z.string().optional(),
21
+ /** An experience: the integrations it depends on. An integration repo: `[{ slug, entry }]`. */
22
+ integrations: z.array(z.unknown()).optional(),
23
+ /** Deprecated experience form. */
24
+ uses: z.array(LegacyUsesEntrySchema).optional(),
25
+ contractsDir: z.string().default("contracts")
26
+ }).passthrough();
27
+ const IntegrationListItemSchema = z.object({
28
+ slug: z.string(),
29
+ entry: z.string()
30
+ });
31
+ class ProjectFileError extends Error {
32
+ constructor(file, message) {
33
+ super(`${file}: ${message}`);
34
+ this.file = file;
35
+ this.name = "ProjectFileError";
36
+ }
37
+ }
38
+ function readJson(file) {
39
+ let raw;
40
+ try {
41
+ raw = fs.readFileSync(file, "utf8");
42
+ } catch (error) {
43
+ if (error.code === "ENOENT") return void 0;
44
+ throw new ProjectFileError(
45
+ file,
46
+ `cannot be read (${error instanceof Error ? error.message : String(error)}).`
47
+ );
48
+ }
49
+ try {
50
+ return JSON.parse(raw);
51
+ } catch {
52
+ throw new ProjectFileError(file, "is not valid JSON.");
53
+ }
54
+ }
55
+ function formatIssues(error) {
56
+ return error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
57
+ }
58
+ function readProjectManifest(projectRoot) {
59
+ const file = path.join(projectRoot, "ekanos.json");
60
+ const raw = readJson(file);
61
+ if (raw === void 0) {
62
+ throw new ProjectFileError(file, "does not exist.");
63
+ }
64
+ const parsed = ProjectManifestSchema.safeParse(raw);
65
+ if (!parsed.success) {
66
+ throw new ProjectFileError(file, formatIssues(parsed.error));
67
+ }
68
+ const { kind } = parsed.data;
69
+ const declared = parsed.data.integrations ?? [];
70
+ if (kind === "experience") {
71
+ let entries = [];
72
+ let renames = {};
73
+ let deprecatedUses = false;
74
+ if (declared.length > 0) {
75
+ for (const [index, item] of declared.entries()) {
76
+ const entry = IntegrationEntrySchema.safeParse(item);
77
+ if (!entry.success) {
78
+ throw new ProjectFileError(
79
+ file,
80
+ formatIssues(
81
+ new z.ZodError(
82
+ entry.error.issues.map((issue) => ({
83
+ ...issue,
84
+ path: ["integrations", index, ...issue.path]
85
+ }))
86
+ )
87
+ )
88
+ );
89
+ }
90
+ entries.push(entry.data);
91
+ }
92
+ } else if (parsed.data.uses && parsed.data.uses.length > 0) {
93
+ deprecatedUses = true;
94
+ const upgraded = upgradeLegacyUses(parsed.data.uses);
95
+ renames = upgraded.renames;
96
+ entries = upgraded.entries.map(
97
+ (entry) => IntegrationEntrySchema.parse(entry)
98
+ );
99
+ }
100
+ return {
101
+ kind,
102
+ slug: parsed.data.slug ?? null,
103
+ slugs: parsed.data.slug ? [parsed.data.slug] : [],
104
+ entry: parsed.data.entry ?? null,
105
+ integrations: entries.map((entry) => ({
106
+ ...entry,
107
+ operations: entry.operations.map(
108
+ (id) => canonicalOperationId(entry, id)
109
+ )
110
+ })),
111
+ deprecatedUses,
112
+ renames,
113
+ contractsDir: parsed.data.contractsDir
114
+ };
115
+ }
116
+ const list = declared.flatMap((item) => {
117
+ const entry = IntegrationListItemSchema.safeParse(item);
118
+ return entry.success ? [entry.data] : [];
119
+ });
120
+ const first = list[0];
121
+ return {
122
+ kind,
123
+ slug: parsed.data.slug ?? first?.slug ?? null,
124
+ slugs: [
125
+ ...parsed.data.slug ? [parsed.data.slug] : [],
126
+ ...list.map((i) => i.slug)
127
+ ],
128
+ entry: parsed.data.entry ?? first?.entry ?? null,
129
+ integrations: [],
130
+ deprecatedUses: false,
131
+ renames: {},
132
+ contractsDir: parsed.data.contractsDir
133
+ };
134
+ }
135
+ function readProjectKind(projectRoot) {
136
+ try {
137
+ return readProjectManifest(projectRoot).kind;
138
+ } catch {
139
+ return null;
140
+ }
141
+ }
142
+ function readProjectOverrides(projectRoot, env, integrationNames, renames = {}) {
143
+ const file = path.join(projectRoot, OVERRIDES_FILENAME);
144
+ const raw = readJson(file);
145
+ const result = {
146
+ overrides: [],
147
+ bindingMode: {},
148
+ deprecatedSlotsKey: false
149
+ };
150
+ const byIntegration = /* @__PURE__ */ new Map();
151
+ const resolveName = (name) => renames[name] ?? name;
152
+ if (raw !== void 0) {
153
+ const parsed = LocalOverridesSchema.safeParse(raw);
154
+ if (!parsed.success) {
155
+ throw new ProjectFileError(file, formatIssues(parsed.error));
156
+ }
157
+ for (const [key, entry] of Object.entries(parsed.data.integrations)) {
158
+ const integration = resolveName(key);
159
+ byIntegration.set(integration, {
160
+ integration,
161
+ path: path.resolve(projectRoot, entry.path),
162
+ mode: entry.mode ?? "fixtures",
163
+ via: "file"
164
+ });
165
+ }
166
+ result.deprecatedSlotsKey = parsed.data.deprecatedSlotsKey;
167
+ result.bindingMode = Object.fromEntries(
168
+ Object.entries(parsed.data.bindingMode ?? {}).map(([key, mode]) => [
169
+ resolveName(key),
170
+ mode
171
+ ])
172
+ );
173
+ }
174
+ const aliases = new Map(
175
+ Object.entries(renames).map(([alias, integration]) => [integration, alias])
176
+ );
177
+ for (const integration of integrationNames) {
178
+ const names = [
179
+ integrationOverrideEnvName(integration),
180
+ legacySlotOverrideEnvName(integration),
181
+ ...aliases.has(integration) ? [legacySlotOverrideEnvName(aliases.get(integration))] : []
182
+ ];
183
+ const value = names.map((key) => env[key]?.trim()).find((candidate) => candidate);
184
+ if (value) {
185
+ byIntegration.set(integration, {
186
+ integration,
187
+ path: path.resolve(projectRoot, value),
188
+ mode: byIntegration.get(integration)?.mode ?? "fixtures",
189
+ via: "env"
190
+ });
191
+ }
192
+ }
193
+ result.overrides = [...byIntegration.values()];
194
+ return result;
195
+ }
196
+ function readLockfile(projectRoot) {
197
+ const file = path.join(projectRoot, LOCK_FILENAME);
198
+ const raw = readJson(file);
199
+ if (raw === void 0) return {};
200
+ const parsed = LockfileSchema.safeParse(raw);
201
+ if (!parsed.success) {
202
+ throw new ProjectFileError(file, formatIssues(parsed.error));
203
+ }
204
+ return parsed.data.integrations;
205
+ }
206
+ export {
207
+ INTEGRATION_OVERRIDE_ENV_PREFIX,
208
+ LOCK_FILENAME,
209
+ OVERRIDES_FILENAME,
210
+ ProjectFileError,
211
+ readLockfile,
212
+ readProjectKind,
213
+ readProjectManifest,
214
+ readProjectOverrides
215
+ };
@@ -0,0 +1,68 @@
1
+ /**
2
+ * ─────────────────────────────────────────────────────────────────────────────
3
+ * THE HARNESS-PRIVATE PUBLISHED-INTEGRATION CACHE (decision O1)
4
+ * ─────────────────────────────────────────────────────────────────────────────
5
+ *
6
+ * When the developer's Source owns (or holds `develop` on) an integration, a
7
+ * registry integration may run LIVE: the harness installs the PUBLISHED package
8
+ * `@companydotcom/integration-<slug>@<exact version in the pinned line>` into
9
+ *
10
+ * <project>/.ekanos/cache/integrations/<slug>@<version>/package
11
+ *
12
+ * and nowhere else. It is never added to the experience's `package.json` or
13
+ * `node_modules`, so the `experience-boundary` check keeps meaning what it
14
+ * says about the experience's own source.
15
+ *
16
+ * The registry token comes from the documented partner-registry environment
17
+ * variable `npm_config_//npm.pkg.github.com/:_authToken`. It is read, sent as
18
+ * a bearer header to the registry host ONLY (never to a redirect target or the
19
+ * tarball's host if that differs), passed to the child package manager through
20
+ * the same variable, and scrubbed from every error text. It is never written
21
+ * to disk and never logged.
22
+ *
23
+ * `@ekanos/*` (and react/zod) peers are SYMLINKED from the project's own
24
+ * `node_modules`, so a cached integration runs against the tarball-pinned SDK
25
+ * the project was installed with rather than a second copy from a registry.
26
+ */
27
+ export declare const DEFAULT_REGISTRY_URL = "https://npm.pkg.github.com";
28
+ export declare const PACKAGE_SCOPE = "@companydotcom";
29
+ export declare const CACHE_MARKER = ".ekanos-cache.json";
30
+ export declare function integrationPackageName(slug: string): string;
31
+ export declare function registryTokenEnvName(registryUrl: string): string;
32
+ export declare function cacheRoot(projectRoot: string): string;
33
+ export type EnsureResult = {
34
+ ok: true;
35
+ version: string;
36
+ /** Directory of the installed package (has its own `node_modules`). */
37
+ packageDir: string;
38
+ fromCache: boolean;
39
+ } | {
40
+ ok: false;
41
+ reason: 'no_token' | 'registry_unreachable' | 'registry_rejected' | 'no_version_in_line' | 'integrity_failed' | 'install_failed';
42
+ message: string;
43
+ };
44
+ export interface EnsureDeps {
45
+ env: Readonly<Record<string, string | undefined>>;
46
+ fetch: typeof globalThis.fetch;
47
+ registryUrl: string;
48
+ /** Unpack a `.tgz` so its `package/` folder lands in `destDir`. */
49
+ extract: (tarball: string, destDir: string) => Promise<void>;
50
+ /** Install the package's own dependencies inside `packageDir`. */
51
+ installDependencies: (args: {
52
+ packageDir: string;
53
+ env: Record<string, string>;
54
+ }) => Promise<void>;
55
+ }
56
+ export declare function defaultEnsureDeps(env?: Readonly<Record<string, string | undefined>>): EnsureDeps;
57
+ /** Replace every occurrence of the token in `text`. */
58
+ export declare function scrub(text: string, token: string | undefined): string;
59
+ export declare function ensurePublishedIntegration(args: {
60
+ projectRoot: string;
61
+ integration: string;
62
+ line: string;
63
+ }, deps?: EnsureDeps): Promise<EnsureResult>;
64
+ /**
65
+ * Unpack with the system `tar`, after listing the archive: an entry that is
66
+ * absolute, contains `..`, or sits outside `package/` aborts the install.
67
+ */
68
+ export declare function extractWithSystemTar(tarball: string, destDir: string): Promise<void>;