@ekanos/harness 0.26.0 → 0.28.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 (159) hide show
  1. package/README.md +6 -4
  2. package/dist/api-types.d.ts +4 -0
  3. package/dist/internal/components/approvals-tray.d.ts +44 -6
  4. package/dist/internal/components/approvals-tray.js +252 -30
  5. package/dist/internal/components/connect-controls.js +4 -2
  6. package/dist/internal/components/connect-dialog.d.ts +8 -1
  7. package/dist/internal/components/connect-dialog.js +23 -10
  8. package/dist/internal/components/connect-panel.d.ts +3 -2
  9. package/dist/internal/components/connect-panel.js +680 -340
  10. package/dist/internal/components/connect-steps.d.ts +72 -0
  11. package/dist/internal/components/connect-steps.js +341 -0
  12. package/dist/internal/components/console-not-found.d.ts +14 -0
  13. package/dist/internal/components/console-not-found.js +57 -0
  14. package/dist/internal/components/dashboard-grid.d.ts +10 -5
  15. package/dist/internal/components/dashboard-grid.js +8 -9
  16. package/dist/internal/components/dev-toolbar.d.ts +27 -5
  17. package/dist/internal/components/dev-toolbar.js +214 -176
  18. package/dist/internal/components/ekanos-logo.d.ts +18 -0
  19. package/dist/internal/components/ekanos-logo.js +74 -0
  20. package/dist/internal/components/events-panel.d.ts +13 -4
  21. package/dist/internal/components/events-panel.js +478 -81
  22. package/dist/internal/components/harness-widget-provider.d.ts +6 -8
  23. package/dist/internal/components/harness-widget-provider.js +5 -19
  24. package/dist/internal/components/health-panel.d.ts +8 -1
  25. package/dist/internal/components/health-panel.js +328 -31
  26. package/dist/internal/components/integration-badge.js +4 -2
  27. package/dist/internal/components/integration-tab-skeletons.d.ts +8 -0
  28. package/dist/internal/components/integration-tab-skeletons.js +76 -0
  29. package/dist/internal/components/not-found-state.d.ts +39 -0
  30. package/dist/internal/components/not-found-state.js +127 -0
  31. package/dist/internal/components/operation-runner-panel.d.ts +1 -1
  32. package/dist/internal/components/operation-runner-panel.js +624 -189
  33. package/dist/internal/components/operation-scope.d.ts +13 -0
  34. package/dist/internal/components/operation-scope.js +79 -0
  35. package/dist/internal/components/page-skeletons.d.ts +11 -0
  36. package/dist/internal/components/page-skeletons.js +61 -0
  37. package/dist/internal/components/provenance-banner.d.ts +13 -4
  38. package/dist/internal/components/provenance-banner.js +35 -10
  39. package/dist/internal/components/run-log-copy.d.ts +17 -0
  40. package/dist/internal/components/run-log-copy.js +67 -0
  41. package/dist/internal/components/run-log-detail.d.ts +22 -0
  42. package/dist/internal/components/run-log-detail.js +295 -0
  43. package/dist/internal/components/run-log-empty.d.ts +13 -0
  44. package/dist/internal/components/run-log-empty.js +46 -0
  45. package/dist/internal/components/run-log.d.ts +23 -3
  46. package/dist/internal/components/run-log.js +384 -130
  47. package/dist/internal/components/runtime-strip.d.ts +5 -1
  48. package/dist/internal/components/runtime-strip.js +115 -10
  49. package/dist/internal/components/schema-form.d.ts +2 -1
  50. package/dist/internal/components/schema-form.js +212 -79
  51. package/dist/internal/components/scrollable-nav.js +14 -2
  52. package/dist/internal/components/segmented-control.d.ts +19 -0
  53. package/dist/internal/components/segmented-control.js +46 -0
  54. package/dist/internal/components/shell-header.d.ts +25 -0
  55. package/dist/internal/components/shell-header.js +126 -0
  56. package/dist/internal/components/surface-nav.d.ts +12 -3
  57. package/dist/internal/components/surface-nav.js +72 -83
  58. package/dist/internal/components/widget-surface.d.ts +5 -1
  59. package/dist/internal/components/widget-surface.js +86 -14
  60. package/dist/internal/components/workflow-runner.d.ts +23 -10
  61. package/dist/internal/components/workflow-runner.js +451 -69
  62. package/dist/internal/lib/connect-model.d.ts +134 -0
  63. package/dist/internal/lib/connect-model.js +282 -0
  64. package/dist/internal/lib/connection-facts.js +2 -1
  65. package/dist/internal/lib/console-client.js +5 -2
  66. package/dist/internal/lib/console-hooks.d.ts +4 -1
  67. package/dist/internal/lib/console-hooks.js +3 -2
  68. package/dist/internal/lib/console-types.d.ts +6 -0
  69. package/dist/internal/lib/docs-links.d.ts +28 -0
  70. package/dist/internal/lib/docs-links.js +57 -1
  71. package/dist/internal/lib/event-delivery.d.ts +33 -0
  72. package/dist/internal/lib/event-delivery.js +66 -0
  73. package/dist/internal/lib/experience-runtime.d.ts +2 -1
  74. package/dist/internal/lib/experience-runtime.js +5 -3
  75. package/dist/internal/lib/font-files/OFL-BricolageGrotesque.txt +93 -0
  76. package/dist/internal/lib/font-files/OFL-Figtree.txt +93 -0
  77. package/dist/internal/lib/font-files/bricolage-grotesque-latin-variable.woff2 +0 -0
  78. package/dist/internal/lib/font-files/figtree-latin-variable.woff2 +0 -0
  79. package/dist/internal/lib/fonts.js +13 -12
  80. package/dist/internal/lib/health-model.d.ts +58 -0
  81. package/dist/internal/lib/health-model.js +140 -0
  82. package/dist/internal/lib/integration-console-href.d.ts +15 -0
  83. package/dist/internal/lib/integration-console-href.js +16 -0
  84. package/dist/internal/lib/oauth-setup-guide.d.ts +28 -0
  85. package/dist/internal/lib/oauth-setup-guide.js +35 -1
  86. package/dist/internal/lib/operation-catalog.d.ts +70 -0
  87. package/dist/internal/lib/operation-catalog.js +261 -0
  88. package/dist/internal/lib/overview-model.d.ts +34 -0
  89. package/dist/internal/lib/overview-model.js +91 -0
  90. package/dist/internal/lib/registry-entry.d.ts +8 -0
  91. package/dist/internal/lib/registry-entry.js +11 -0
  92. package/dist/internal/lib/repo-name.d.ts +9 -0
  93. package/dist/internal/lib/repo-name.js +21 -0
  94. package/dist/internal/lib/run-log-view.d.ts +66 -1
  95. package/dist/internal/lib/run-log-view.js +183 -4
  96. package/dist/internal/lib/runner-view.d.ts +15 -0
  97. package/dist/internal/lib/runner-view.js +18 -0
  98. package/dist/internal/lib/schema-form-model.d.ts +17 -0
  99. package/dist/internal/lib/schema-form-model.js +50 -0
  100. package/dist/internal/lib/setup-checklist.d.ts +34 -0
  101. package/dist/internal/lib/setup-checklist.js +79 -0
  102. package/dist/internal/lib/toolbar-context.d.ts +0 -1
  103. package/dist/internal/lib/toolbar-context.js +0 -2
  104. package/dist/internal/lib/toolbar-visibility.d.ts +9 -2
  105. package/dist/internal/lib/toolbar-visibility.js +5 -0
  106. package/dist/internal/lib/use-operation-effects.d.ts +7 -0
  107. package/dist/internal/lib/use-operation-effects.js +28 -0
  108. package/dist/internal/lib/use-run-log-query.d.ts +9 -0
  109. package/dist/internal/lib/use-run-log-query.js +35 -0
  110. package/dist/internal/lib/widget-grid-gaps.d.ts +18 -0
  111. package/dist/internal/lib/widget-grid-gaps.js +41 -0
  112. package/dist/internal/lib/workflow-summary.d.ts +54 -0
  113. package/dist/internal/lib/workflow-summary.js +147 -0
  114. package/dist/internal/routes/console-home-page.js +2 -1
  115. package/dist/internal/routes/experience-connect-page.js +51 -22
  116. package/dist/internal/routes/experience-layout-page.js +75 -26
  117. package/dist/internal/routes/experience-page-host.js +63 -5
  118. package/dist/internal/routes/experience-review-queue-page.d.ts +4 -1
  119. package/dist/internal/routes/experience-review-queue-page.js +108 -12
  120. package/dist/internal/routes/experience-runs-page.js +57 -4
  121. package/dist/internal/routes/experience-summary-page.d.ts +19 -0
  122. package/dist/internal/routes/experience-summary-page.js +219 -62
  123. package/dist/internal/routes/experience-widget-page.js +58 -7
  124. package/dist/internal/routes/experience-widgets-page.d.ts +2 -3
  125. package/dist/internal/routes/experience-widgets-page.js +29 -4
  126. package/dist/internal/routes/experience-workflow-page.js +81 -9
  127. package/dist/internal/routes/experience-workflows-page.js +85 -21
  128. package/dist/internal/routes/integration-layout.js +28 -3
  129. package/dist/internal/routes/integrations-connect-page.js +16 -6
  130. package/dist/internal/routes/integrations-events-page.js +22 -1
  131. package/dist/internal/routes/integrations-health-page.js +16 -1
  132. package/dist/internal/routes/integrations-layout.js +28 -4
  133. package/dist/internal/routes/integrations-list-page.d.ts +0 -1
  134. package/dist/internal/routes/integrations-list-page.js +11 -9
  135. package/dist/internal/routes/integrations-operation-page.js +53 -17
  136. package/dist/internal/routes/integrations-operations-page.js +539 -49
  137. package/dist/internal/routes/integrations-overview-page.js +332 -69
  138. package/dist/internal/routes/integrations-runs-page.js +53 -3
  139. package/dist/internal/routes/integrations-scope.d.ts +15 -2
  140. package/dist/internal/routes/integrations-scope.js +66 -18
  141. package/dist/internal/routes/preview-index-page.js +2 -2
  142. package/dist/internal/routes/repo-home-page.d.ts +2 -2
  143. package/dist/internal/routes/repo-home-page.js +428 -236
  144. package/dist/internal/routes/repo-layout.d.ts +12 -0
  145. package/dist/internal/routes/repo-layout.js +50 -38
  146. package/dist/internal/routes/repo-package-layouts.js +22 -8
  147. package/dist/internal/routes/single-widget-page.d.ts +1 -1
  148. package/dist/internal/routes/single-widget-page.js +28 -5
  149. package/dist/internal/routes/tile-page.d.ts +1 -1
  150. package/dist/internal/routes/tile-page.js +1 -2
  151. package/dist/internal/routes/widgets-page.d.ts +1 -1
  152. package/dist/internal/routes/widgets-page.js +5 -3
  153. package/dist/internal/server/ekanos-api-router.js +20 -5
  154. package/dist/internal/server/repo-api-router.js +20 -7
  155. package/dist/registry.d.ts +4 -5
  156. package/dist/registry.js +0 -1
  157. package/dist/routes.d.ts +5 -0
  158. package/dist/routes.js +2 -0
  159. package/package.json +8 -8
@@ -0,0 +1,134 @@
1
+ import type { ActivationCredentialStatus, ConnectionState, OAuthConnectionStatus } from './console-types.js';
2
+ /**
3
+ * What the Connect tab knows about each credential beyond the wire's name and
4
+ * set flag: a human label, a one-line description, whether it is a secret.
5
+ * Read from the integration's definition when the shell injected its registry
6
+ * entry; every function here also works with none.
7
+ */
8
+ export interface CredentialHint {
9
+ label?: string;
10
+ description?: string;
11
+ secret?: boolean;
12
+ }
13
+ interface OAuthLike {
14
+ credentials: {
15
+ clientIdSecretName: string;
16
+ clientSecretSecretName: string;
17
+ };
18
+ teamApp?: {
19
+ fields: ReadonlyArray<{
20
+ secretName: string;
21
+ label: string;
22
+ description?: string;
23
+ sensitive?: boolean;
24
+ }>;
25
+ };
26
+ }
27
+ /** The parts of an `IntegrationDefinition` that describe credentials. */
28
+ export interface CredentialSource {
29
+ oauth?: OAuthLike;
30
+ oauthConnections?: Record<string, OAuthLike>;
31
+ activation?: {
32
+ fields?: ReadonlyArray<{
33
+ name: string;
34
+ label?: string;
35
+ description?: string;
36
+ secret?: boolean;
37
+ }>;
38
+ };
39
+ webhooks?: ReadonlyArray<{
40
+ signature: 'none' | {
41
+ secretName: string;
42
+ };
43
+ }>;
44
+ }
45
+ /** A declared label without a trailing "(optional)": the row marks that itself. */
46
+ export declare function cleanLabel(label: string): string;
47
+ /** `linear_agent_client_id` → `Agent client ID`, dropping the slug prefix. */
48
+ export declare function humanizeSecretName(name: string, slug?: string): string;
49
+ /** Every credential name the definition says something about. */
50
+ export declare function credentialHints(source: CredentialSource | undefined): Map<string, CredentialHint>;
51
+ /** What saving one key unlocks, shown on its row instead of a bare "Required". */
52
+ export interface KeyPurpose {
53
+ label: string;
54
+ /** Needed for the first connection: what step 1 counts. */
55
+ primary: boolean;
56
+ }
57
+ export interface KeyRow {
58
+ name: string;
59
+ label: string;
60
+ description?: string;
61
+ secret: boolean;
62
+ set: boolean;
63
+ purpose: KeyPurpose;
64
+ }
65
+ type ConnectionKeys = Pick<OAuthConnectionStatus, 'id' | 'label' | 'keys'>;
66
+ /**
67
+ * What one declared key is for, from the OAuth connection whose app it
68
+ * belongs to: the first connection's keys are what authorizing first needs,
69
+ * another connection's keys only that connection, and a webhook signing
70
+ * secret no connection names only incoming webhooks.
71
+ */
72
+ export declare function keyPurpose(name: string, options?: {
73
+ connections?: readonly ConnectionKeys[];
74
+ hints?: Map<string, CredentialHint>;
75
+ required?: boolean;
76
+ }): KeyPurpose;
77
+ /**
78
+ * Whether a key's own description restates its requirement line: both start
79
+ * with "Only" or both with "Optional". The row then shows the
80
+ * description, which is the more specific of the two, once.
81
+ */
82
+ export declare function restatesRequirement(requirement: string, description: string | undefined): boolean;
83
+ export interface KeyGroup {
84
+ id: string;
85
+ title: string;
86
+ description?: string;
87
+ /** The OAuth connection these keys are the app for. */
88
+ connectionId?: string;
89
+ rows: KeyRow[];
90
+ }
91
+ /**
92
+ * The declared keys, grouped by the OAuth connection whose app they belong to
93
+ * (Linear: the main app's two, the agent app's three), then whatever is left
94
+ * (a webhook signing secret). One group with no title when nothing groups.
95
+ */
96
+ export declare function groupKeys(state: Pick<ConnectionState, 'fields' | 'oauthConnections'>, options?: {
97
+ slug?: string;
98
+ hints?: Map<string, CredentialHint>;
99
+ /** False when the integration needs no connection: every key is optional. */
100
+ required?: boolean;
101
+ }): KeyGroup[];
102
+ export interface ActivationRow {
103
+ name: string;
104
+ label: string;
105
+ description?: string;
106
+ required: boolean;
107
+ set: boolean;
108
+ /** The same name is a declared key, whose saved value wins over this one. */
109
+ alsoKey: boolean;
110
+ }
111
+ export declare function activationRows(credential: ActivationCredentialStatus, options?: {
112
+ hints?: Map<string, CredentialHint>;
113
+ keyNames?: ReadonlySet<string>;
114
+ }): ActivationRow[];
115
+ export type StepStatus = 'done' | 'current' | 'todo';
116
+ export interface ConnectStep {
117
+ id: 'keys' | 'authorize';
118
+ title: string;
119
+ status: StepStatus;
120
+ /** One line: how far along the step is. */
121
+ summary: string;
122
+ }
123
+ /**
124
+ * The numbered steps of the Connect tab and where the developer is in them.
125
+ * OAuth: save the app keys, then authorize; the keys step counts what the
126
+ * first connection needs. Keys: save the keys. Nothing to connect: no steps.
127
+ */
128
+ export declare function connectSteps(state: Pick<ConnectionState, 'fields' | 'oauthConnections' | 'facts'>, oauth: boolean, hints?: Map<string, CredentialHint>): ConnectStep[];
129
+ /** Why a connection's Connect button is disabled, or null when it is not. */
130
+ export declare function authorizeBlocker(connection: Pick<OAuthConnectionStatus, 'keys'>, hints?: Map<string, CredentialHint>, slug?: string): string | null;
131
+ export declare function joinWords(words: readonly string[]): string;
132
+ /** `2026-01-01T09:30:00Z` → a short local date and time; the input when unparseable. */
133
+ export declare function formatWhen(iso: string, now?: Date): string;
134
+ export {};
@@ -0,0 +1,282 @@
1
+ const OPTIONAL_SUFFIX = /\s*\(optional\)\s*$/i;
2
+ function cleanLabel(label) {
3
+ return label.replace(OPTIONAL_SUFFIX, "");
4
+ }
5
+ const WORDS = {
6
+ id: "ID",
7
+ api: "API",
8
+ url: "URL",
9
+ oauth: "OAuth",
10
+ ai: "AI"
11
+ };
12
+ function humanizeSecretName(name, slug) {
13
+ const prefix = slug ? `${slug.replace(/-/g, "_")}_` : "";
14
+ const bare = prefix && name.startsWith(prefix) && name.length > prefix.length ? name.slice(prefix.length) : name;
15
+ const words = bare.replace(/([a-z0-9])([A-Z])/g, "$1_$2").split(/[_\-.\s]+/).filter(Boolean).map((word) => WORDS[word.toLowerCase()] ?? word.toLowerCase());
16
+ if (words.length === 0) return name;
17
+ const [first = "", ...rest] = words;
18
+ const head = first === first.toUpperCase() ? first : first.charAt(0).toUpperCase() + first.slice(1);
19
+ return [head, ...rest].join(" ");
20
+ }
21
+ function credentialHints(source) {
22
+ const hints = /* @__PURE__ */ new Map();
23
+ if (!source) return hints;
24
+ const add = (name, hint) => {
25
+ hints.set(name, { ...hint, ...hints.get(name) });
26
+ };
27
+ for (const field of source.activation?.fields ?? []) {
28
+ add(field.name, {
29
+ ...field.label ? { label: cleanLabel(field.label) } : {},
30
+ ...field.description ? { description: field.description } : {},
31
+ ...field.secret === void 0 ? {} : { secret: field.secret }
32
+ });
33
+ }
34
+ const connections = [
35
+ ...source.oauth ? [source.oauth] : [],
36
+ ...Object.values(source.oauthConnections ?? {})
37
+ ];
38
+ for (const connection of connections) {
39
+ for (const field of connection.teamApp?.fields ?? []) {
40
+ add(field.secretName, {
41
+ label: cleanLabel(field.label),
42
+ ...field.description ? { description: field.description } : {},
43
+ secret: field.sensitive !== false
44
+ });
45
+ }
46
+ add(connection.credentials.clientIdSecretName, {
47
+ label: "Client ID",
48
+ secret: false
49
+ });
50
+ add(connection.credentials.clientSecretSecretName, {
51
+ label: "Client secret",
52
+ secret: true
53
+ });
54
+ }
55
+ for (const webhook of source.webhooks ?? []) {
56
+ if (webhook.signature === "none") continue;
57
+ add(webhook.signature.secretName, {
58
+ label: "Webhook signing secret",
59
+ secret: true
60
+ });
61
+ }
62
+ return hints;
63
+ }
64
+ function connectionPhrase(connection) {
65
+ if (connection.id === "default") return "the main connection";
66
+ return /^the\s/i.test(connection.label) ? connection.label : `the ${connection.label}`;
67
+ }
68
+ function keyPurpose(name, options = {}) {
69
+ if (options.required === false) return { label: "Optional", primary: false };
70
+ const connections = options.connections ?? [];
71
+ const owner = connections.find(
72
+ (connection) => connection.keys.some((key) => key.name === name)
73
+ );
74
+ if (owner) {
75
+ const first = owner.id === connections[0]?.id;
76
+ return {
77
+ label: first && connections.length === 1 ? "Needed to authorize" : `Needed for ${connectionPhrase(owner)}`,
78
+ primary: first
79
+ };
80
+ }
81
+ if (isWebhookSecret(name, options.hints?.get(name))) {
82
+ return {
83
+ label: "Only for receiving webhooks",
84
+ primary: connections.length === 0
85
+ };
86
+ }
87
+ return { label: "Needed to connect", primary: true };
88
+ }
89
+ function restatesRequirement(requirement, description) {
90
+ if (!description) return false;
91
+ const lead = (text) => /^\s*(only|optional)\b/i.exec(text)?.[1]?.toLowerCase();
92
+ const a = lead(requirement);
93
+ return a !== void 0 && a === lead(description);
94
+ }
95
+ function rowLabel(name, wireLabel, hint, slug) {
96
+ if (wireLabel !== name) return cleanLabel(wireLabel);
97
+ return hint?.label ?? humanizeSecretName(name, slug);
98
+ }
99
+ function isWebhookSecret(name, hint) {
100
+ return hint?.label === "Webhook signing secret" || /webhook.*(secret|key)$/i.test(name);
101
+ }
102
+ function groupKeys(state, options = {}) {
103
+ const hints = options.hints ?? /* @__PURE__ */ new Map();
104
+ const toRow = (field) => {
105
+ const hint = hints.get(field.key);
106
+ return {
107
+ name: field.key,
108
+ label: rowLabel(field.key, field.label, hint, options.slug),
109
+ ...hint?.description ? { description: hint.description } : {},
110
+ secret: hint?.secret ?? field.secret,
111
+ set: field.set,
112
+ purpose: keyPurpose(field.key, {
113
+ connections: state.oauthConnections ?? [],
114
+ hints,
115
+ ...options.required === void 0 ? {} : { required: options.required }
116
+ })
117
+ };
118
+ };
119
+ const byName = new Map(state.fields.map((field) => [field.key, field]));
120
+ const used = /* @__PURE__ */ new Set();
121
+ const groups = [];
122
+ const connections = state.oauthConnections ?? [];
123
+ for (const connection of connections) {
124
+ const fields = connection.keys.map((key) => byName.get(key.name)).filter((field) => field !== void 0).filter((field) => !used.has(field.key));
125
+ if (fields.length === 0) continue;
126
+ for (const field of fields) used.add(field.key);
127
+ groups.push({
128
+ id: `connection-${connection.id}`,
129
+ title: connections.length > 1 ? `${connection.label} app` : "OAuth app credentials",
130
+ description: connection.teamApp ? `Your team's own app for this connection. ${connection.description ?? ""}`.trim() : "The client credentials of the OAuth app you register with the provider.",
131
+ connectionId: connection.id,
132
+ rows: fields.map(toRow)
133
+ });
134
+ }
135
+ const rest = state.fields.filter((field) => !used.has(field.key));
136
+ if (rest.length > 0) {
137
+ const rows = rest.map(toRow);
138
+ const webhooks = rows.every(
139
+ (row) => isWebhookSecret(row.name, hints.get(row.name))
140
+ );
141
+ groups.push({
142
+ id: "keys",
143
+ title: groups.length === 0 ? "" : webhooks ? "Webhooks" : "Other keys",
144
+ ...groups.length > 0 && webhooks ? {
145
+ description: "Signing secrets the integration checks incoming webhook deliveries against."
146
+ } : {},
147
+ rows
148
+ });
149
+ }
150
+ return groups;
151
+ }
152
+ function activationRows(credential, options = {}) {
153
+ return credential.fields.map((field) => {
154
+ const description = options.hints?.get(field.name)?.description;
155
+ return {
156
+ name: field.name,
157
+ label: cleanLabel(field.label),
158
+ ...description ? { description } : {},
159
+ required: field.required,
160
+ set: field.set,
161
+ alsoKey: options.keyNames?.has(field.name) ?? false
162
+ };
163
+ });
164
+ }
165
+ function countLine(set, total, noun) {
166
+ return `${set} of ${total} ${noun}${total === 1 ? "" : "s"} saved`;
167
+ }
168
+ function plural(count, noun) {
169
+ return `${count} ${noun}${count === 1 ? "" : "s"}`;
170
+ }
171
+ function oauthKeysLine(state, hints) {
172
+ const connections = state.oauthConnections ?? [];
173
+ const first = connections[0];
174
+ if (!first) {
175
+ const set2 = state.fields.filter((field) => field.set).length;
176
+ return {
177
+ summary: countLine(set2, state.fields.length, "key"),
178
+ firstDone: set2 === state.fields.length
179
+ };
180
+ }
181
+ const firstNames = new Set(first.keys.map((key) => key.name));
182
+ const needed = state.fields.filter((field) => firstNames.has(field.key));
183
+ const rest = state.fields.filter((field) => !firstNames.has(field.key));
184
+ const set = needed.filter((field) => field.set).length;
185
+ const firstDone = set === needed.length;
186
+ const head = rest.length === 0 ? countLine(set, needed.length, "key") : `${set} of ${needed.length} saved for ${connectionPhrase(first)}`;
187
+ if (rest.length === 0) return { summary: head, firstDone };
188
+ const adds = [];
189
+ for (const connection of connections.slice(1)) {
190
+ if (connection.keys.some((key) => rest.some((f) => f.key === key.name))) {
191
+ adds.push(connectionPhrase(connection));
192
+ }
193
+ }
194
+ const owned = new Set(connections.flatMap((c) => c.keys.map((k) => k.name)));
195
+ const loose = rest.filter((field) => !owned.has(field.key));
196
+ if (loose.some((field) => isWebhookSecret(field.key, hints?.get(field.key)))) {
197
+ adds.push("webhooks");
198
+ } else if (loose.length > 0) {
199
+ adds.push("other features");
200
+ }
201
+ const restSet = rest.filter((field) => field.set).length;
202
+ const more = restSet === rest.length ? `${plural(rest.length, "key")} for ${joinWords(adds)} saved` : `${plural(rest.length - restSet, "more key")} for ${joinWords(adds)}`;
203
+ return { summary: `${head} \xB7 ${more}`, firstDone };
204
+ }
205
+ function connectSteps(state, oauth, hints) {
206
+ if (state.facts.kind === "none" && !oauth) return [];
207
+ const setCount = state.fields.filter((field) => field.set).length;
208
+ const keysDone = setCount === state.fields.length;
209
+ const connected = state.facts.state === "connected";
210
+ if (!oauth) {
211
+ if (state.fields.length === 0) return [];
212
+ return [
213
+ {
214
+ id: "keys",
215
+ title: "Add your keys",
216
+ status: connected || keysDone ? "done" : "current",
217
+ summary: countLine(setCount, state.fields.length, "key")
218
+ }
219
+ ];
220
+ }
221
+ const connections = state.oauthConnections ?? [];
222
+ const authorized = connections.filter((c) => c.connected).length;
223
+ const { summary, firstDone } = oauthKeysLine(state, hints);
224
+ const steps = [];
225
+ if (state.fields.length > 0) {
226
+ steps.push({
227
+ id: "keys",
228
+ title: "Add your app keys",
229
+ status: firstDone ? "done" : "current",
230
+ summary
231
+ });
232
+ }
233
+ const anyAuthorized = connected || authorized > 0;
234
+ steps.push({
235
+ id: "authorize",
236
+ title: "Authorize",
237
+ status: anyAuthorized ? "done" : firstDone ? "current" : "todo",
238
+ summary: connections.length > 1 ? `${authorized} of ${connections.length} connections authorized` : anyAuthorized ? "Authorized" : firstDone ? "Ready to authorize" : "Waiting for the app keys"
239
+ });
240
+ return steps;
241
+ }
242
+ function authorizeBlocker(connection, hints, slug) {
243
+ const missing = connection.keys.filter((key) => !key.set);
244
+ if (missing.length === 0) return null;
245
+ const names = missing.map(
246
+ (key) => rowLabel(key.name, key.label, hints?.get(key.name), slug)
247
+ );
248
+ return `Save ${joinWords(names)} in step 1 first.`;
249
+ }
250
+ function joinWords(words) {
251
+ if (words.length <= 1) return words.join("");
252
+ return `${words.slice(0, -1).join(", ")} and ${words.at(-1)}`;
253
+ }
254
+ function formatWhen(iso, now = /* @__PURE__ */ new Date()) {
255
+ const date = new Date(iso);
256
+ if (Number.isNaN(date.getTime())) return iso;
257
+ const sameDay = date.toDateString() === now.toDateString();
258
+ const time = date.toLocaleTimeString(void 0, {
259
+ hour: "numeric",
260
+ minute: "2-digit"
261
+ });
262
+ if (sameDay) return `today at ${time}`;
263
+ const day = date.toLocaleDateString(void 0, {
264
+ month: "short",
265
+ day: "numeric",
266
+ ...date.getFullYear() === now.getFullYear() ? {} : { year: "numeric" }
267
+ });
268
+ return `${day} at ${time}`;
269
+ }
270
+ export {
271
+ activationRows,
272
+ authorizeBlocker,
273
+ cleanLabel,
274
+ connectSteps,
275
+ credentialHints,
276
+ formatWhen,
277
+ groupKeys,
278
+ humanizeSecretName,
279
+ joinWords,
280
+ keyPurpose,
281
+ restatesRequirement
282
+ };
@@ -18,13 +18,14 @@ function stateOf(input, kind) {
18
18
  ...input.missing.length > 0 ? { detail: `Missing ${input.missing.join(", ")}` } : {}
19
19
  };
20
20
  }
21
+ if (input.oauthHeld) return { state: "connected" };
21
22
  if (input.missing.length > 0) {
22
23
  return {
23
24
  state: "not_connected",
24
25
  detail: `Save the app keys first: ${input.missing.join(", ")}`
25
26
  };
26
27
  }
27
- return { state: input.oauthHeld ? "connected" : "not_connected" };
28
+ return { state: "not_connected" };
28
29
  }
29
30
  function deriveConnectionFacts(input) {
30
31
  const kind = kindOf(input);
@@ -38,6 +38,7 @@ function contractView(wire) {
38
38
  contractVersion: contract.contractVersion,
39
39
  digest: contract.digest,
40
40
  connection: contract.connection,
41
+ ...contract.health ? { health: true } : {},
41
42
  operations: contract.operations,
42
43
  events: contract.events.map((event) => ({
43
44
  name: event.name,
@@ -266,7 +267,8 @@ function createHttpConsoleClient(fetcher = (input, init) => globalThis.fetch(inp
266
267
  const wire = await post(`/health/${enc(integration)}`);
267
268
  return {
268
269
  status: wire.status ? HEALTH[wire.status] : "unknown",
269
- ...wire.detail ? { message: wire.detail } : {}
270
+ ...wire.detail ? { message: wire.detail } : {},
271
+ checked: wire.outcome === "checked"
270
272
  };
271
273
  },
272
274
  getExperience,
@@ -306,7 +308,8 @@ function createHttpRepoClient(fetcher = (input, init) => globalThis.fetch(input,
306
308
  );
307
309
  return {
308
310
  status: wire.status ? HEALTH[wire.status] : "unknown",
309
- ...wire.detail ? { message: wire.detail } : {}
311
+ ...wire.detail ? { message: wire.detail } : {},
312
+ checked: wire.outcome === "checked"
310
313
  };
311
314
  }
312
315
  };
@@ -19,7 +19,10 @@ export declare const consoleKeys: {
19
19
  export declare function refreshRuntime(queryClient: QueryClient): Promise<[void, void]>;
20
20
  export declare function useRefreshRuntime(): () => Promise<[void, void]>;
21
21
  export declare function useProject(): import("@tanstack/react-query").UseQueryResult<import("./console-types.js").ConsoleProject, Error>;
22
- export declare function useContract(integration: string): import("@tanstack/react-query").UseQueryResult<import("./console-types.js").ConsoleContract, Error>;
22
+ /** `enabled: false` holds the fetch, for a slug not yet known to resolve. */
23
+ export declare function useContract(integration: string, options?: {
24
+ enabled?: boolean;
25
+ }): import("@tanstack/react-query").UseQueryResult<import("./console-types.js").ConsoleContract, Error>;
23
26
  /** The run log polls: every surface appends to it, not just this tab. */
24
27
  export declare function useRuns(): import("@tanstack/react-query").UseQueryResult<import("./console-types.js").RunRecord[], Error>;
25
28
  export declare function useApprovals(): import("@tanstack/react-query").UseQueryResult<import("./console-types.js").PendingApproval[], Error>;
@@ -32,11 +32,12 @@ function useProject() {
32
32
  queryFn: () => client.getProject()
33
33
  });
34
34
  }
35
- function useContract(integration) {
35
+ function useContract(integration, options = {}) {
36
36
  const client = useConsoleClient();
37
37
  return useQuery({
38
38
  queryKey: consoleKeys.contract(integration),
39
- queryFn: () => client.getContract(integration)
39
+ queryFn: () => client.getContract(integration),
40
+ enabled: options.enabled ?? true
40
41
  });
41
42
  }
42
43
  function useRuns() {
@@ -84,6 +84,8 @@ export interface ConsoleContract {
84
84
  events: ConsoleEvent[];
85
85
  /** Keyed by `kind/name`. */
86
86
  usedBy: Record<string, UsedBy[]>;
87
+ /** The contract says the integration declares a `health.check`. */
88
+ health?: boolean;
87
89
  }
88
90
  export interface ConsoleIntegration {
89
91
  integration: string;
@@ -135,6 +137,8 @@ export interface RunRecord {
135
137
  provenance: IntegrationProvenance['kind'] | null;
136
138
  status: 'ok' | 'refused' | 'error';
137
139
  reason?: string;
140
+ /** Dev-only error text, scrubbed of secrets by the server. */
141
+ detail?: string;
138
142
  durationMs: number;
139
143
  inputBytes: number;
140
144
  outputBytes: number;
@@ -242,6 +246,8 @@ export type HealthStatus = 'healthy' | 'degraded' | 'unhealthy' | 'unknown';
242
246
  export interface HealthResult {
243
247
  status: HealthStatus;
244
248
  message?: string;
249
+ /** False when the server ran nothing: the integration declares no `health.check`, or has no local code. */
250
+ checked?: boolean;
245
251
  }
246
252
  export type WorkflowStepType = 'fusion_tool' | 'approval_gate' | 'ai_step' | (string & {});
247
253
  export interface WorkflowStepDefinition {
@@ -3,3 +3,31 @@ export declare const SDK_DOCS_URL = "https://sdk.ekanos.dev";
3
3
  export declare const HARNESS_DOCS_URL = "https://sdk.ekanos.dev/harness/overview";
4
4
  /** The docs page for each harness surface, keyed by `HarnessSurface.segment`. */
5
5
  export declare const SURFACE_DOCS: Readonly<Record<string, string>>;
6
+ /**
7
+ * Every docs page a harness screen links to. Each path is a page in the docs
8
+ * site's navigation and each anchor a heading on it, which a test checks
9
+ * against the docs source.
10
+ */
11
+ export declare const DOCS: {
12
+ readonly repoHome: "https://sdk.ekanos.dev/harness/repo-mode";
13
+ readonly connecting: "https://sdk.ekanos.dev/harness/repo-mode#connecting-integrations";
14
+ readonly provenance: "https://sdk.ekanos.dev/harness/repo-mode#provenance";
15
+ readonly console: "https://sdk.ekanos.dev/harness/integration-console";
16
+ readonly consoleConnect: "https://sdk.ekanos.dev/harness/integration-console#connect";
17
+ readonly consoleOperations: "https://sdk.ekanos.dev/harness/integration-console#operations";
18
+ readonly consoleEvents: "https://sdk.ekanos.dev/harness/integration-console#events";
19
+ readonly consoleHealth: "https://sdk.ekanos.dev/harness/integration-console#health";
20
+ readonly runLog: "https://sdk.ekanos.dev/harness/integration-console#run-log";
21
+ readonly preview: "https://sdk.ekanos.dev/harness/integration-console#preview";
22
+ readonly fixtures: "https://sdk.ekanos.dev/harness/fixtures";
23
+ readonly experiences: "https://sdk.ekanos.dev/guides/experiences";
24
+ readonly pageKinds: "https://sdk.ekanos.dev/guides/experiences#page-kinds";
25
+ readonly layout: "https://sdk.ekanos.dev/guides/experiences#suggest-a-layout";
26
+ readonly workflows: "https://sdk.ekanos.dev/guides/experiences#workflow-templates";
27
+ readonly widgets: "https://sdk.ekanos.dev/sdk/surfaces/widgets";
28
+ readonly experienceView: "https://sdk.ekanos.dev/harness/experience-view";
29
+ readonly experienceWidgets: "https://sdk.ekanos.dev/harness/experience-view#widgets";
30
+ readonly reviewQueue: "https://sdk.ekanos.dev/harness/experience-view#review-queue";
31
+ };
32
+ /** The docs page for the screen at `pathname`, falling back to the harness overview. */
33
+ export declare function docsHrefFor(pathname: string): string;
@@ -6,8 +6,64 @@ const SURFACE_DOCS = {
6
6
  activation: `${SDK_DOCS_URL}/sdk/surfaces/activation-form`,
7
7
  triggers: `${SDK_DOCS_URL}/harness/triggers`
8
8
  };
9
+ const DOCS = {
10
+ repoHome: `${SDK_DOCS_URL}/harness/repo-mode`,
11
+ connecting: `${SDK_DOCS_URL}/harness/repo-mode#connecting-integrations`,
12
+ provenance: `${SDK_DOCS_URL}/harness/repo-mode#provenance`,
13
+ console: `${SDK_DOCS_URL}/harness/integration-console`,
14
+ consoleConnect: `${SDK_DOCS_URL}/harness/integration-console#connect`,
15
+ consoleOperations: `${SDK_DOCS_URL}/harness/integration-console#operations`,
16
+ consoleEvents: `${SDK_DOCS_URL}/harness/integration-console#events`,
17
+ consoleHealth: `${SDK_DOCS_URL}/harness/integration-console#health`,
18
+ runLog: `${SDK_DOCS_URL}/harness/integration-console#run-log`,
19
+ preview: `${SDK_DOCS_URL}/harness/integration-console#preview`,
20
+ fixtures: `${SDK_DOCS_URL}/harness/fixtures`,
21
+ experiences: `${SDK_DOCS_URL}/guides/experiences`,
22
+ pageKinds: `${SDK_DOCS_URL}/guides/experiences#page-kinds`,
23
+ layout: `${SDK_DOCS_URL}/guides/experiences#suggest-a-layout`,
24
+ workflows: `${SDK_DOCS_URL}/guides/experiences#workflow-templates`,
25
+ widgets: `${SDK_DOCS_URL}/sdk/surfaces/widgets`,
26
+ experienceView: `${SDK_DOCS_URL}/harness/experience-view`,
27
+ experienceWidgets: `${SDK_DOCS_URL}/harness/experience-view#widgets`,
28
+ reviewQueue: `${SDK_DOCS_URL}/harness/experience-view#review-queue`
29
+ };
30
+ const CONSOLE_TAB_DOCS = {
31
+ connect: DOCS.consoleConnect,
32
+ operations: DOCS.consoleOperations,
33
+ events: DOCS.consoleEvents,
34
+ health: DOCS.consoleHealth,
35
+ runs: DOCS.runLog
36
+ };
37
+ const EXPERIENCE_TAB_DOCS = {
38
+ widgets: DOCS.experienceWidgets,
39
+ layout: DOCS.layout,
40
+ workflows: DOCS.workflows,
41
+ "review-queue": DOCS.reviewQueue,
42
+ runs: DOCS.runLog,
43
+ connect: DOCS.connecting,
44
+ pages: DOCS.pageKinds
45
+ };
46
+ function docsHrefFor(pathname) {
47
+ const segments = pathname.split("/").filter(Boolean);
48
+ const [first] = segments;
49
+ if (first === void 0) return DOCS.repoHome;
50
+ if (first === "integrations") {
51
+ const tab2 = segments[2];
52
+ if (tab2 === void 0) return DOCS.console;
53
+ if (tab2 === "preview") {
54
+ return SURFACE_DOCS[segments[3] ?? ""] ?? DOCS.preview;
55
+ }
56
+ return CONSOLE_TAB_DOCS[tab2] ?? DOCS.console;
57
+ }
58
+ const tab = first === "experience" ? segments[1] : first === "experiences" ? segments[2] : null;
59
+ if (tab === null) return HARNESS_DOCS_URL;
60
+ if (tab === void 0) return DOCS.experiences;
61
+ return EXPERIENCE_TAB_DOCS[tab] ?? DOCS.experiences;
62
+ }
9
63
  export {
64
+ DOCS,
10
65
  HARNESS_DOCS_URL,
11
66
  SDK_DOCS_URL,
12
- SURFACE_DOCS
67
+ SURFACE_DOCS,
68
+ docsHrefFor
13
69
  };
@@ -0,0 +1,33 @@
1
+ import type { JsonSchema, RunRecord } from './console-types.js';
2
+ /** What the server said about who handled a delivery, read back from `detail`. */
3
+ export type DeliveryHandler = {
4
+ kind: 'ran';
5
+ webhook: string;
6
+ status: string;
7
+ detail?: string;
8
+ events?: number;
9
+ } | {
10
+ kind: 'no_handler';
11
+ webhooks: string[];
12
+ } | {
13
+ kind: 'unknown';
14
+ text: string;
15
+ };
16
+ /** The emit response's `detail` arrives as pretty JSON text; read its shape back. */
17
+ export declare function parseDeliveryDetail(detail: string | undefined): DeliveryHandler | null;
18
+ export interface PayloadField {
19
+ key: string;
20
+ type: string;
21
+ required: boolean;
22
+ description?: string;
23
+ }
24
+ /** A schema node's type in a few words: `string`, `string or null`, `"new" | "follow_up"`. */
25
+ export declare function schemaTypeLabel(schema: JsonSchema): string;
26
+ /** The payload's top-level fields, for the "what this event carries" list. */
27
+ export declare function payloadFields(schema: JsonSchema): PayloadField[];
28
+ export declare function eventDescription(event: {
29
+ description?: string;
30
+ payloadSchema: JsonSchema;
31
+ }): string | null;
32
+ /** This event's deliveries in the run log, newest first. */
33
+ export declare function eventDeliveries(runs: readonly RunRecord[], integration: string, event: string, limit?: number): RunRecord[];