@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,490 @@
1
+ import type { Contract, ExecutionChannel, OperationRefusalReason } from '@ekanos/integration-schema';
2
+ /**
3
+ * ─────────────────────────────────────────────────────────────────────────────
4
+ * THE `/__ekanos/api/*` WIRE CONTRACT
5
+ * ─────────────────────────────────────────────────────────────────────────────
6
+ *
7
+ * Types only (plus two constants) — safe to import from a `'use client'`
8
+ * module. Re-exported from `@ekanos/harness/api`, and importable on its own as
9
+ * `@ekanos/harness/api-types`. The server half (`createHarnessApiHandlers`)
10
+ * answers every route below; the Integration console and the Experience view
11
+ * (lane D) code against these shapes and nothing else. All bodies are JSON.
12
+ * Every route sits behind the loopback guard.
13
+ *
14
+ * GET /__ekanos/api/integrations -> IntegrationsResponse
15
+ * GET /__ekanos/api/contract/:integration -> ContractResponse
16
+ * POST /__ekanos/api/ops/run -> RunOperationResponse
17
+ * GET /__ekanos/api/approvals -> ApprovalsResponse
18
+ * POST /__ekanos/api/approvals/:id -> DecideApprovalResponse
19
+ * GET /__ekanos/api/runs?after=<cursor> -> RunsResponse (poll; cursor is monotonic)
20
+ * GET /__ekanos/api/experience -> ExperienceResponse (404 in an integration repo)
21
+ * POST /__ekanos/api/events/emit -> EmitEventResponse
22
+ * POST /__ekanos/api/health/:integration -> HealthResponse
23
+ * POST /__ekanos/api/workflows/:id/run -> WorkflowRunResponse
24
+ * GET /__ekanos/api/credentials/:integration -> CredentialsResponse (which keys are set, never values)
25
+ * PUT /__ekanos/api/credentials/:integration -> CredentialsResponse (body: SaveCredentialsRequest)
26
+ * PUT /__ekanos/api/integrations/:integration/mode -> IntegrationRuntime (body: SetRuntimeModeRequest)
27
+ * PUT /__ekanos/api/credentials/:integration/activation -> CredentialsResponse (body: SaveActivationRequest)
28
+ * POST /__ekanos/api/credentials/:integration/disconnect -> CredentialsResponse (body: DisconnectCredentialsRequest)
29
+ */
30
+ export declare const HARNESS_API_PREFIX = "/__ekanos/api";
31
+ /** Next treats a leading `_` folder as private; the shell mounts the route under this encoded segment. */
32
+ export declare const HARNESS_API_ROUTE_SEGMENT = "%5F%5Fekanos";
33
+ export type HarnessKind = 'integration' | 'experience';
34
+ export type { ExecutionChannel };
35
+ export type RunMode = 'fixtures' | 'live';
36
+ export type BindingMode = 'team' | 'invoker' | 'user';
37
+ export type FixtureScenario = 'default' | 'empty' | 'error';
38
+ /**
39
+ * The host executor's refusal reasons and channels, same strings, owned by
40
+ * `@ekanos/integration-schema` (`executor-semantics.ts`).
41
+ */
42
+ export type { OperationRefusalReason };
43
+ export type OperationResult<T = unknown> = {
44
+ ok: true;
45
+ data: T;
46
+ } | {
47
+ ok: false;
48
+ reason: OperationRefusalReason;
49
+ /** The host's message for this reason, verbatim. */
50
+ message: string;
51
+ /**
52
+ * Dev-only explanation (what failed validation, the integration's error).
53
+ * The host never returns it; credentials are scrubbed from it.
54
+ */
55
+ detail?: string;
56
+ };
57
+ export type IntegrationProvenance = {
58
+ kind: 'registry';
59
+ contractVersion: string;
60
+ digest: string;
61
+ /** `catalog` = the host catalog via the CLI session; `dir` = a contracts directory; `snapshot` = the committed copy. */
62
+ source: 'catalog' | 'dir' | 'package' | 'snapshot';
63
+ /** Where it came from: a directory, a catalog host, a package spec. */
64
+ origin: string;
65
+ /** The committed snapshot was used because no live source answered. */
66
+ stale: boolean;
67
+ /** Registry package version running live from the private cache, when installed. */
68
+ cachedPackage?: {
69
+ name: string;
70
+ version: string;
71
+ };
72
+ } | {
73
+ kind: 'local';
74
+ path: string;
75
+ packageVersion: string;
76
+ contractVersion: string;
77
+ digest: string;
78
+ /**
79
+ * Why it is local. `override` (default when absent): `ekanos.local.json`
80
+ * or an env var. `repo`: the integration is a package of the same repo
81
+ * as the experience; resolved automatically, never an override.
82
+ */
83
+ scope?: 'override' | 'repo';
84
+ /** `path` relative to the repo root, when the integration is inside the repo. */
85
+ relPath?: string;
86
+ };
87
+ export interface IntegrationView {
88
+ integration: string;
89
+ version: string;
90
+ /** Canonical operation ids allowed by the experience's `uses` entry. */
91
+ operations: string[];
92
+ modes: BindingMode[];
93
+ /** The binding mode the harness uses for this integration. */
94
+ bindingMode: BindingMode;
95
+ provenance: IntegrationProvenance;
96
+ /** Which run modes are available: registry use-only -> fixtures; local, or registry+develop -> both. */
97
+ runModes: RunMode[];
98
+ /** The mode a call uses when it names none. */
99
+ defaultMode: RunMode;
100
+ /** The dev holds `develop` on this integration (catalog), or it is a local override. */
101
+ canDevelop: boolean | 'unverified';
102
+ /**
103
+ * An integration project's OWN integration (provenance `local`, but nothing
104
+ * overrides anything: the project is what it is). Never blocks publishing.
105
+ */
106
+ self?: boolean;
107
+ /** Resolved to a package of the same repo (provenance `local`, `scope: 'repo'`). */
108
+ sameRepo?: boolean;
109
+ /** What a call that names no mode does right now, and why. */
110
+ runtime?: IntegrationRuntime;
111
+ }
112
+ /**
113
+ * The mode an unspecified call resolves to. Reads of a connected integration
114
+ * run live with its stored credentials (or with none, for an integration that
115
+ * needs no connection); everything else answers from fixtures
116
+ * (an unconnected integration, or one forced to fixtures). Writes are held for
117
+ * approval whichever mode applies.
118
+ */
119
+ export interface IntegrationRuntime {
120
+ mode: RunMode;
121
+ reason: 'connected' | 'no_connection_needed' | 'not_connected' | 'forced_fixtures' | 'configured' | 'fixtures_only';
122
+ connected: boolean;
123
+ forced: boolean;
124
+ /** The integration connects through an OAuth loop. */
125
+ oauth: boolean;
126
+ /** It works as shipped, so it counts as connected and has nothing to connect. */
127
+ noConnectionNeeded?: boolean;
128
+ /** What the stored local credentials point at (non-sensitive fields only). */
129
+ target: ConnectionTargetField[];
130
+ /** The one source of truth for status and live/fixtures; the fields above derive from it. */
131
+ facts: IntegrationConnectionFacts;
132
+ }
133
+ /** How an integration connects: nothing, API keys, or an OAuth loop. */
134
+ export type ConnectionKind = 'none' | 'keys' | 'oauth';
135
+ /**
136
+ * The status of an integration's connection. `no_connection_needed` works as
137
+ * shipped, `managed` is held by Ekanos (a registry integration), `unreadable`
138
+ * means the harness could not read its credentials.
139
+ */
140
+ export type ConnectionFactState = 'connected' | 'not_connected' | 'no_connection_needed' | 'managed' | 'unreadable';
141
+ /** Why a call that names no mode answers as it does. */
142
+ export type ConnectionAnswerReason = 'connected' | 'no_connection_needed' | 'not_connected' | 'forced_fixtures' | 'configured' | 'fixtures_only';
143
+ /**
144
+ * Everything any screen says about one integration's connection, computed in
145
+ * one place on the server (`deriveConnectionFacts`). No component derives
146
+ * status itself: it renders these.
147
+ */
148
+ export interface IntegrationConnectionFacts {
149
+ kind: ConnectionKind;
150
+ state: ConnectionFactState;
151
+ /** Why it is not connected (names of missing keys), never a value. */
152
+ detail?: string;
153
+ /** What the stored local credentials point at (non-sensitive fields only). */
154
+ target: ConnectionTargetField[];
155
+ /** The integration has code to run live. */
156
+ supportsLive: boolean;
157
+ /** What a call that names no mode answers from right now. */
158
+ answers: RunMode;
159
+ answersWhy: ConnectionAnswerReason;
160
+ /** The dev forced this integration to fixtures for this session. */
161
+ forced: boolean;
162
+ }
163
+ export interface SetRuntimeModeRequest {
164
+ /** `fixtures` forces fixtures; `auto` follows the connection. */
165
+ mode: 'auto' | 'fixtures';
166
+ }
167
+ export interface ActiveOverride {
168
+ integration: string;
169
+ path: string;
170
+ /** `file` = ekanos.local.json, `env` = EKANOS_INTEGRATION_OVERRIDE_<INTEGRATION>. */
171
+ via: 'file' | 'env';
172
+ mode: RunMode;
173
+ }
174
+ export interface IntegrationsResponse {
175
+ kind: HarnessKind;
176
+ integrations: IntegrationView[];
177
+ overrides: ActiveOverride[];
178
+ /** True while any override is active: `ekanos publish` refuses. */
179
+ publishBlocked: boolean;
180
+ /** Pre-rendered startup table, identical to what the CLI prints. */
181
+ provenanceLines: string[];
182
+ /** Resolution problems that did not stop startup (stale snapshot, drift, unverified permission). */
183
+ notices: string[];
184
+ /** Hard resolution errors per integration; the harness refuses to serve calls for these integrations. */
185
+ errors: Array<{
186
+ integration: string;
187
+ message: string;
188
+ }>;
189
+ }
190
+ export interface UsedBy {
191
+ kind: 'widget' | 'page' | 'workflow' | 'review-queue';
192
+ id: string;
193
+ }
194
+ export interface ContractResponse {
195
+ integration: string;
196
+ version: string;
197
+ contract: Contract;
198
+ provenance: IntegrationProvenance;
199
+ /** Operation id -> where the experience uses it (static analysis of declarations). */
200
+ usedBy: Record<string, UsedBy[]>;
201
+ }
202
+ export interface RunOperationRequest {
203
+ integration: string;
204
+ /** Relative operation key, `tool/get_headlines` or `action/create-draft`. Never a canonical id. */
205
+ op: string;
206
+ input?: unknown;
207
+ channel: ExecutionChannel;
208
+ /** Defaults to the integration's `defaultMode`. `live` on a fixtures-only integration is refused. */
209
+ mode?: RunMode;
210
+ /** Scenario for fixtures mode. */
211
+ scenario?: FixtureScenario;
212
+ /** Free text recorded on the run row (`widget:content-queue`, `console`). */
213
+ origin?: string;
214
+ }
215
+ /** Server-internal: the workflow runner passes the gate its upstream approval_gate cleared. Never accepted from a request body. */
216
+ export interface InternalWriteGate {
217
+ stepId: string;
218
+ }
219
+ export interface RunOperationResponse {
220
+ result: OperationResult;
221
+ runId: string;
222
+ /** Set when the call was held for, or refused after, an approval decision. */
223
+ approvalId?: string;
224
+ }
225
+ export type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
226
+ interface ApprovalBase {
227
+ id: string;
228
+ createdAt: string;
229
+ status: ApprovalStatus;
230
+ decidedAt?: string;
231
+ }
232
+ /** Gates one operation call (a write on an approval-gated channel). */
233
+ export interface OperationApprovalView extends ApprovalBase {
234
+ kind: 'operation';
235
+ integration: string;
236
+ version: string;
237
+ opKey: string;
238
+ channel: ExecutionChannel;
239
+ mode: RunMode;
240
+ /** sha256 of the canonical-JSON input, so the same payload is recognisable. */
241
+ argsHash: string;
242
+ /** Input with credentials redacted. */
243
+ args: unknown;
244
+ provenance: IntegrationProvenance;
245
+ }
246
+ /** A workflow `approval_gate` step: approving lets the writes downstream of it run. */
247
+ export interface GateApprovalView extends ApprovalBase {
248
+ kind: 'gate';
249
+ summary: string;
250
+ workflowId: string;
251
+ stepId: string;
252
+ }
253
+ export type ApprovalView = OperationApprovalView | GateApprovalView;
254
+ export interface ApprovalsResponse {
255
+ approvals: ApprovalView[];
256
+ }
257
+ export interface DecideApprovalRequest {
258
+ decision: 'approve' | 'reject';
259
+ }
260
+ export interface DecideApprovalResponse {
261
+ approval: ApprovalView;
262
+ }
263
+ export interface RunRecord {
264
+ id: string;
265
+ /** Monotonic; pass the highest seen as `after`. */
266
+ seq: number;
267
+ ts: string;
268
+ integration: string;
269
+ version: string;
270
+ opKey: string;
271
+ effect: 'read' | 'write' | null;
272
+ channel: ExecutionChannel;
273
+ mode: RunMode | null;
274
+ provenance: IntegrationProvenance | null;
275
+ status: 'ok' | 'refused' | 'error';
276
+ reason?: OperationRefusalReason;
277
+ /** Dev-only; same scrubbing as `OperationResult.detail`. */
278
+ detail?: string;
279
+ durationMs: number;
280
+ inputBytes: number;
281
+ outputBytes: number;
282
+ origin?: string;
283
+ approvalId?: string;
284
+ }
285
+ export interface RunsResponse {
286
+ runs: RunRecord[];
287
+ /** Highest `seq` in the log; poll with `after=<cursor>`. */
288
+ cursor: number;
289
+ }
290
+ export type CheckStatus = 'ok' | 'failed' | 'unknown';
291
+ export interface ExperienceWorkflowStep {
292
+ id: string;
293
+ type: string;
294
+ label: string;
295
+ integration?: string;
296
+ /** Relative operation key, `tool/get_headlines`. */
297
+ opKey?: string;
298
+ }
299
+ export interface ExperienceResponse {
300
+ name: string;
301
+ workflows: Array<{
302
+ id: string;
303
+ title: string;
304
+ description?: string;
305
+ steps: ExperienceWorkflowStep[];
306
+ }>;
307
+ reviewQueue: Array<{
308
+ id: string;
309
+ title: string;
310
+ integration: string;
311
+ opKey: string;
312
+ args: unknown;
313
+ }>;
314
+ /** `pins` is the resolver's verdict; `boundary` is `ekanos check`'s and is `unknown` here. */
315
+ checks: {
316
+ pins: CheckStatus;
317
+ boundary: CheckStatus;
318
+ };
319
+ }
320
+ export interface EmitEventRequest {
321
+ integration: string;
322
+ event: string;
323
+ payload: unknown;
324
+ /** Defaults to the integration's default mode. `live` dispatches to the handler. */
325
+ mode?: RunMode;
326
+ /** Webhook id to deliver to; defaults to the one named like the event. */
327
+ webhook?: string;
328
+ }
329
+ export interface EmitEventResponse {
330
+ /** Payload validated against the contract event schema. */
331
+ valid: boolean;
332
+ errors: string[];
333
+ /** `ran`: the integration's webhook handler ran (live); `validated-only`: validated and recorded, nothing dispatched. */
334
+ outcome: 'ran' | 'validated-only';
335
+ /** For `ran`: `{ webhook, status, detail?, events? }`; for a live emit with no handler: `{ reason: 'no_handler', webhooks }`. */
336
+ detail?: unknown;
337
+ /** Experience workflow ids whose trigger names this event. */
338
+ matchingWorkflows: string[];
339
+ }
340
+ export interface HealthResponse {
341
+ outcome: 'checked' | 'not-checked-locally';
342
+ status?: 'healthy' | 'degraded' | 'unhealthy' | 'unknown';
343
+ detail?: string;
344
+ }
345
+ export interface WorkflowStepResult {
346
+ id: string;
347
+ type: string;
348
+ status: 'ok' | 'refused' | 'rejected' | 'not-simulated' | 'error';
349
+ detail?: string;
350
+ output?: unknown;
351
+ runId?: string;
352
+ }
353
+ export interface WorkflowRunResponse {
354
+ workflowId: string;
355
+ steps: WorkflowStepResult[];
356
+ completed: boolean;
357
+ }
358
+ export interface CredentialsResponse {
359
+ integration: string;
360
+ /** Where the store lives, rooted at the INTEGRATION's project. */
361
+ root: string;
362
+ /** `registry-fixtures` = no credential UI for this integration. */
363
+ manageable: boolean;
364
+ declared: string[];
365
+ set: string[];
366
+ missing: string[];
367
+ activationFieldsSet: string[];
368
+ /**
369
+ * What the stored local credentials point at: the non-sensitive activation
370
+ * fields only (a project id, a dataset). Never a secret, not even masked.
371
+ */
372
+ target: ConnectionTargetField[];
373
+ /** `root` relative to the repo root, when inside one. */
374
+ displayRoot?: string;
375
+ /** The integration's code connects through an OAuth loop. */
376
+ oauth?: boolean;
377
+ /** Connection status and live/fixtures answer, from the one function. */
378
+ facts: IntegrationConnectionFacts;
379
+ }
380
+ /** One non-sensitive field of the local credentials, shown beside "Connected". */
381
+ export interface ConnectionTargetField {
382
+ key: string;
383
+ label: string;
384
+ value: string;
385
+ }
386
+ export interface DisconnectCredentialsRequest {
387
+ /**
388
+ * Also blank the declared secret names. An API-key integration's keys ARE
389
+ * its connection; an OAuth integration's declared names are the app's client
390
+ * credentials, which a disconnect keeps.
391
+ */
392
+ clearKeys?: boolean;
393
+ }
394
+ export interface SaveCredentialsRequest {
395
+ /** Declared secret name -> value. Empty string clears. Only declared names are accepted. */
396
+ values: Record<string, string>;
397
+ }
398
+ export interface SaveActivationRequest {
399
+ /**
400
+ * What the integration's activation form submitted. Only the string fields
401
+ * are stored, in the integration's own `.ekanos/local-secrets.json`; they
402
+ * replace whatever was stored before.
403
+ */
404
+ activationData: Record<string, unknown>;
405
+ }
406
+ export type ApiErrorBody = {
407
+ error: {
408
+ code: string;
409
+ message: string;
410
+ };
411
+ };
412
+ /** How an integration is connected: `ekanos.json`'s contract `connection.auth`. */
413
+ export type RepoConnectionType = 'keys' | 'oauth' | 'shipped';
414
+ /**
415
+ * Local connection status. `not_needed`: the integration ships its own
416
+ * configuration. `managed`: resolved from the registry, so Ekanos holds the
417
+ * connection and the harness answers from fixtures.
418
+ */
419
+ export type RepoConnectionStatus = 'connected' | 'not_connected' | 'not_needed' | 'managed';
420
+ /** Who connects once published: the Source, a team, or each person. */
421
+ export type RepoConnectLevel = 'source' | 'team' | 'user';
422
+ export interface RepoConnection {
423
+ type: RepoConnectionType;
424
+ status: RepoConnectionStatus;
425
+ /** Why it is not connected (names of missing keys), never a value. */
426
+ detail?: string;
427
+ /** Levels the integration declares it supports. */
428
+ levels: RepoConnectLevel[];
429
+ /** Where the credentials live: the integration package's own local store. */
430
+ storeRoot?: string;
431
+ /** `storeRoot` relative to the repo root. */
432
+ displayRoot?: string;
433
+ /** Non-sensitive fields of the local credentials, when connected. */
434
+ target?: ConnectionTargetField[];
435
+ /** The one source of truth every chip renders. */
436
+ facts: IntegrationConnectionFacts;
437
+ }
438
+ export interface RepoIntegrationRow {
439
+ name: string;
440
+ version: string;
441
+ contractVersion: string | null;
442
+ connection: RepoConnection | null;
443
+ /** Set when the package could not be read or its contract derived. */
444
+ error?: string;
445
+ consoleHref: string;
446
+ /** Experience packages of this repo that use it. */
447
+ usedBy: string[];
448
+ }
449
+ export interface RepoExperienceIntegration {
450
+ name: string;
451
+ modes: BindingMode[];
452
+ /** The integration is a package of this repo. */
453
+ sameRepo: boolean;
454
+ connection: RepoConnection | null;
455
+ /** Levels this experience will ask for once published, within what the integration supports. */
456
+ levels: RepoConnectLevel[];
457
+ /** The experience asks for a level the integration does not support. */
458
+ levelProblem?: string;
459
+ /** Link to connect it (the integration's console), when it is a package of this repo. */
460
+ connectHref: string | null;
461
+ }
462
+ export interface RepoExperienceRow {
463
+ name: string;
464
+ version: string;
465
+ viewHref: string;
466
+ connectHref: string;
467
+ integrations: RepoExperienceIntegration[];
468
+ error?: string;
469
+ }
470
+ export interface RepoResponse {
471
+ root: string;
472
+ counts: {
473
+ integrations: number;
474
+ experiences: number;
475
+ connected: number;
476
+ notConnected: number;
477
+ /** Integrations that work as shipped, with nothing to connect. */
478
+ noConnectionNeeded: number;
479
+ };
480
+ integrations: RepoIntegrationRow[];
481
+ experiences: RepoExperienceRow[];
482
+ problems: Array<{
483
+ where: string;
484
+ message: string;
485
+ }>;
486
+ }
487
+ export interface RepoDisconnectResponse {
488
+ integration: string;
489
+ connection: RepoConnection | null;
490
+ }
@@ -0,0 +1,6 @@
1
+ const HARNESS_API_PREFIX = "/__ekanos/api";
2
+ const HARNESS_API_ROUTE_SEGMENT = "%5F%5Fekanos";
3
+ export {
4
+ HARNESS_API_PREFIX,
5
+ HARNESS_API_ROUTE_SEGMENT
6
+ };
package/dist/api.d.ts CHANGED
@@ -1,5 +1,8 @@
1
1
  import { type HarnessApiDeps, type HarnessRouteParams } from './internal/server/api-router.js';
2
+ import { type EkanosApiDeps } from './internal/server/ekanos-api-router.js';
3
+ import { type RepoApiDeps } from './internal/server/repo-api-router.js';
2
4
  import type { HarnessIntegration } from './registry.js';
5
+ export * from './api-types.js';
3
6
  /**
4
7
  * `@ekanos/harness/api` — the SERVER half of the harness.
5
8
  *
@@ -40,3 +43,33 @@ export type NextRouteHandler = (request: Request, context: {
40
43
  params: Promise<HarnessRouteParams>;
41
44
  }) => Promise<Response>;
42
45
  export declare function createHarnessApiHandlers(integrations: readonly HarnessIntegration[], deps?: Partial<HarnessApiDeps>): HarnessApiHandlers;
46
+ export type { EkanosApiDeps };
47
+ export interface EkanosApiHandlers {
48
+ GET: EkanosRouteHandler;
49
+ POST: EkanosRouteHandler;
50
+ PUT: EkanosRouteHandler;
51
+ }
52
+ export type EkanosRouteHandler = (request: Request, context: {
53
+ params: Promise<{
54
+ path?: string[];
55
+ }>;
56
+ }) => Promise<Response>;
57
+ /**
58
+ * The handlers behind `/__ekanos/api/*`. The shell mounts them at
59
+ * `app/%5F%5Fekanos/api/[...path]/route.ts` (Next treats a leading `_` folder
60
+ * as private, so the underscores are percent-encoded on disk).
61
+ *
62
+ * One router per process, kept on `globalThis` so a dev-server recompile of the
63
+ * route module does not drop the approvals tray, the run log or the resolved
64
+ * integrations mid-session.
65
+ */
66
+ export declare function createEkanosApiHandlers(deps?: Partial<EkanosApiDeps>): EkanosApiHandlers;
67
+ export type { RepoApiDeps };
68
+ /**
69
+ * The handlers behind `/__ekanos/api/*` when `ekanos dev` runs at a repo root:
70
+ * the repo overview, Connections, and each package's own API under
71
+ * `/__ekanos/api/packages/<integrations|experiences>/<name>/…`. Mounted at the
72
+ * same route file as `createEkanosApiHandlers`, which a single-package shell
73
+ * keeps using.
74
+ */
75
+ export declare function createRepoApiHandlers(deps?: Partial<RepoApiDeps>): EkanosApiHandlers;
package/dist/api.js CHANGED
@@ -1,6 +1,14 @@
1
1
  import {
2
2
  createHarnessApiRouter
3
3
  } from "./internal/server/api-router.js";
4
+ import {
5
+ createEkanosApiRouter
6
+ } from "./internal/server/ekanos-api-router.js";
7
+ import { resolveProjectRoot } from "./internal/server/project-root.js";
8
+ import {
9
+ createRepoApiRouter
10
+ } from "./internal/server/repo-api-router.js";
11
+ export * from "./api-types.js";
4
12
  function createHarnessApiHandlers(integrations, deps = {}) {
5
13
  const route = createHarnessApiRouter(integrations, deps);
6
14
  const handler = async (request, context) => {
@@ -12,6 +20,33 @@ function createHarnessApiHandlers(integrations, deps = {}) {
12
20
  };
13
21
  return { GET: handler, POST: handler, PUT: handler };
14
22
  }
23
+ const ROUTER_STORE = /* @__PURE__ */ Symbol.for("ekanos.harness.ekanos-api-router");
24
+ function createEkanosApiHandlers(deps = {}) {
25
+ const carrier = globalThis;
26
+ const router = carrier[ROUTER_STORE] ??= createEkanosApiRouter(deps);
27
+ const handler = async (request, context) => {
28
+ const params = await context.params;
29
+ return router(request, Array.isArray(params.path) ? params.path : []);
30
+ };
31
+ return { GET: handler, POST: handler, PUT: handler };
32
+ }
33
+ const REPO_ROUTER_STORE = /* @__PURE__ */ Symbol.for("ekanos.harness.repo-api-router");
34
+ function createRepoApiHandlers(deps = {}) {
35
+ const carrier = globalThis;
36
+ const env = deps.env ?? process.env;
37
+ const root = resolveProjectRoot({ env, cwd: process.cwd() });
38
+ const router = carrier[REPO_ROUTER_STORE] ??= createRepoApiRouter({
39
+ ...deps,
40
+ repoRoot: deps.repoRoot ?? (root.ok ? root.root : process.cwd())
41
+ });
42
+ const handler = async (request, context) => {
43
+ const params = await context.params;
44
+ return router(request, Array.isArray(params.path) ? params.path : []);
45
+ };
46
+ return { GET: handler, POST: handler, PUT: handler };
47
+ }
15
48
  export {
16
- createHarnessApiHandlers
49
+ createEkanosApiHandlers,
50
+ createHarnessApiHandlers,
51
+ createRepoApiHandlers
17
52
  };
package/dist/app.js CHANGED
@@ -2,7 +2,12 @@ import { RootLayout } from "./internal/routes/root-layout.js";
2
2
  import { IndexPage } from "./internal/routes/index-page.js";
3
3
  const harnessMetadata = {
4
4
  title: "Ekanos Integration Harness",
5
- description: "Render integration widgets, marketplace tiles and activation forms in real Ekanos chrome, from fixtures, with no Supabase, auth or network."
5
+ description: "Render integration widgets, marketplace tiles and activation forms in real Ekanos chrome, from fixtures, with no Supabase, auth or network.",
6
+ // Declared so the browser does not ask for /favicon.ico, which the shell
7
+ // does not serve: that request was the 404 on every page.
8
+ icons: {
9
+ icon: "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='7' fill='%23c4623a'/%3E%3Cpath d='M10 9h12v3.5H14v2.5h7v3.5h-7v2.5h8V24H10z' fill='white'/%3E%3C/svg%3E"
10
+ }
6
11
  };
7
12
  export {
8
13
  IndexPage,
@@ -0,0 +1,17 @@
1
+ import type { ApprovalDecision, PendingApproval } from '../lib/console-types.js';
2
+ /** `tool/draft_post` -> `draft_post`: the name the person reads, without its kind prefix. */
3
+ export declare function approvalOperationName(opKey: string): string;
4
+ /** The one-line summary of the waiting writes, e.g. `1 write waiting for approval: linkedin draft_post`. */
5
+ export declare function approvalsSummary(approvals: readonly Pick<PendingApproval, 'integration' | 'opKey'>[]): string;
6
+ /** One pending write: the op, the integration, the args hash, and the two buttons. */
7
+ export declare function ApprovalCard({ approval, pending, onDecide, }: {
8
+ approval: PendingApproval;
9
+ pending?: boolean;
10
+ onDecide: (decision: ApprovalDecision) => void;
11
+ }): import("react").JSX.Element;
12
+ /**
13
+ * Every write waiting on a decision, from the console, a widget or a workflow
14
+ * run. Renders nothing when the queue is empty; with a pending write it is the
15
+ * first thing on the page.
16
+ */
17
+ export declare function ApprovalsTray(): import("react").JSX.Element | null;