@ekanos/harness 0.20.0 → 0.22.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.
@@ -15,7 +15,9 @@ export declare class ContractFileError extends Error {
15
15
  /** Read and fully verify one contract file. Throws on anything inadmissible. */
16
16
  export declare function readContractFile(file: string): Contract;
17
17
  /**
18
- * Every contract in `dir` for `integration`. Two spellings are read: the
18
+ * Every contract in `dir` for `integration`, a package **token** (`slug` or
19
+ * `ns__slug`), so a namespaced package never matches a global file of the same
20
+ * slug. Two spellings are read: the
19
21
  * monorepo registry's `<integration>.contract.json` and the experience
20
22
  * snapshot's `<integration>@<line>.contract.json`. A file that fails
21
23
  * verification throws — a corrupt registry must not look like "absent".
@@ -1,5 +1,6 @@
1
1
  import {
2
2
  compareSemver,
3
+ contractToken,
3
4
  verifyContract
4
5
  } from "@ekanos/integration-schema";
5
6
  import * as fs from "node:fs";
@@ -41,14 +42,16 @@ function listContractsInDir(dir, integration) {
41
42
  }
42
43
  const out = [];
43
44
  for (const name of names.sort()) {
44
- const match = /^([a-z][a-z0-9-]*)(?:@(\d+(?:\.\d+)?))?\.contract\.json$/.exec(name);
45
+ const match = /^([a-z][a-z0-9-]*(?:__[a-z][a-z0-9-]*)?)(?:@(\d+(?:\.\d+)?))?\.contract\.json$/.exec(
46
+ name
47
+ );
45
48
  if (!match || match[1] !== integration) continue;
46
49
  const file = path.join(dir, name);
47
50
  const contract = readContractFile(file);
48
- if (contract.integration !== integration) {
51
+ if (contractToken(contract) !== integration) {
49
52
  throw new ContractFileError(
50
53
  file,
51
- `declares integration "${contract.integration}", not "${integration}".`
54
+ `declares integration "${contractToken(contract)}", not "${integration}".`
52
55
  );
53
56
  }
54
57
  out.push({ contract, file });
@@ -1,4 +1,5 @@
1
1
  import { validateAgainstSchema } from "@ekanos/integration-schema";
2
+ import fs from "node:fs";
2
3
  import path from "node:path";
3
4
  import { z } from "zod";
4
5
  import { deriveConnectionFacts } from "../lib/connection-facts.js";
@@ -90,6 +91,11 @@ const ActivationBodySchema = z.object({
90
91
  });
91
92
  const RuntimeModeBodySchema = z.object({ mode: z.enum(["auto", "fixtures"]) });
92
93
  const DisconnectBodySchema = z.object({ clearKeys: z.boolean().optional() });
94
+ const RESOLUTION_INPUTS = [
95
+ "ekanos.json",
96
+ "ekanos.lock.json",
97
+ "ekanos.local.json"
98
+ ];
93
99
  function toIntegrationView(integration, runtime) {
94
100
  return {
95
101
  runtime,
@@ -118,11 +124,29 @@ function createEkanosApiRouter(partial = {}) {
118
124
  const loadExp = partial.loadExperience ?? loadExperience;
119
125
  let resolution = null;
120
126
  let experience = null;
127
+ let inputsKey = null;
128
+ function refreshIfInputsChanged() {
129
+ const dir = projectRoot();
130
+ const key = RESOLUTION_INPUTS.map((name) => {
131
+ try {
132
+ const stat = fs.statSync(path.join(dir, name));
133
+ return `${stat.mtimeMs}:${stat.size}`;
134
+ } catch {
135
+ return "-";
136
+ }
137
+ }).join("|");
138
+ if (inputsKey !== null && key !== inputsKey) {
139
+ resolution = null;
140
+ experience = null;
141
+ }
142
+ inputsKey = key;
143
+ }
121
144
  function projectRoot() {
122
145
  if (!root.ok) throw new Error(root.message);
123
146
  return root.root;
124
147
  }
125
148
  function getResolution() {
149
+ refreshIfInputsChanged();
126
150
  resolution ??= (async () => {
127
151
  const dir = projectRoot();
128
152
  const contractsDir = partial.contractsDir ?? env.EKANOS_CONTRACTS_DIR?.trim();
@@ -138,6 +162,7 @@ function createEkanosApiRouter(partial = {}) {
138
162
  return resolution;
139
163
  }
140
164
  function getExperience() {
165
+ refreshIfInputsChanged();
141
166
  experience ??= loadExp(projectRoot());
142
167
  return experience;
143
168
  }
@@ -1,3 +1,4 @@
1
+ import { integrationRefToken } from "@ekanos/integration-schema";
1
2
  import { importEntryFromSource } from "./definition-loader.js";
2
3
  import { readProjectManifest } from "./project-manifest.js";
3
4
  function isRecord(value) {
@@ -130,10 +131,13 @@ function usedByIndex(experience, declaredIntegrations) {
130
131
  if (step.type !== "fusion_tool") continue;
131
132
  const integration = typeof step.slot === "string" ? declaredIntegrations.get(step.slot) : void 0;
132
133
  if (integration && typeof step.tool === "string") {
133
- add(`${integration.integration}@${integration.version}/${step.tool}`, {
134
- kind: "workflow",
135
- id: workflow.id
136
- });
134
+ add(
135
+ `${integrationRefToken(integration.integration) ?? integration.integration}@${integration.version}/${step.tool}`,
136
+ {
137
+ kind: "workflow",
138
+ id: workflow.id
139
+ }
140
+ );
137
141
  }
138
142
  }
139
143
  }
@@ -109,8 +109,9 @@ export interface ResolveIntegrationsOptions {
109
109
  */
110
110
  export declare function repoOf(projectRoot: string, notices?: string[]): RepoDiscovery | null;
111
111
  /**
112
- * An integration package of the same repo as `projectRoot` with this name, other
113
- * than the project itself. Same-repo is not an override: it needs no
112
+ * An integration package of the same repo as `projectRoot` that `name` (a
113
+ * reference: `slug` or `ns/slug`) names, other than the project itself. A
114
+ * namespaced reference matches only under the repo's own namespace. Same-repo is not an override: it needs no
114
115
  * `ekanos.local.json` and never blocks publishing.
115
116
  */
116
117
  export declare function sameRepoPackage(repo: RepoDiscovery | null, projectRoot: string, name: string): RepoPackage | null;
@@ -1,10 +1,13 @@
1
1
  import {
2
- compatLine
2
+ compatLine,
3
+ contractForRef,
4
+ parseIntegrationRef
3
5
  } from "@ekanos/integration-schema";
4
6
  import {
5
7
  RepoManifestError,
6
8
  discoverRepo,
7
- findRepoRoot
9
+ findRepoRoot,
10
+ repoIntegrationForRef
8
11
  } from "@ekanos/integration-schema/repo";
9
12
  import * as fs from "node:fs";
10
13
  import * as path from "node:path";
@@ -41,9 +44,8 @@ function repoOf(projectRoot, notices) {
41
44
  function sameRepoPackage(repo, projectRoot, name) {
42
45
  if (!repo) return null;
43
46
  const here = path.resolve(projectRoot);
44
- return repo.packages.find(
45
- (pkg) => pkg.kind === "integration" && pkg.name === name && pkg.dir !== here
46
- ) ?? null;
47
+ const pkg = repoIntegrationForRef(repo, name);
48
+ return pkg && pkg.dir !== here ? pkg : null;
47
49
  }
48
50
  function relativeToRepo(repo, dir) {
49
51
  if (!repo) return void 0;
@@ -77,7 +79,7 @@ function pinProblems(entry, contract, lines) {
77
79
  return problems;
78
80
  }
79
81
  for (const id of entry.operations) {
80
- const expectedPrefix = `${entry.name}@${entry.version}/`;
82
+ const expectedPrefix = `${parseIntegrationRef(entry.name).slug}@${entry.version}/`;
81
83
  if (!id.startsWith(expectedPrefix) || !findOperation(contract, id)) {
82
84
  problems.push(
83
85
  `integration "${entry.name}": ${entry.name}@${entry.version} does not provide ${opKey(id) || id}.`
@@ -284,7 +286,8 @@ async function resolveLocal(entry, override, bindingMode, options, snapshotDir,
284
286
  `integration "${entry.name}": ${error instanceof Error ? error.message : String(error)}`
285
287
  );
286
288
  }
287
- if (!overrideManifest.slugs.includes(entry.name)) {
289
+ const ref = parseIntegrationRef(entry.name);
290
+ if (!overrideManifest.slugs.includes(ref.slug)) {
288
291
  return fail(
289
292
  `integration "${entry.name}": override at ${override.path} is integration "${overrideManifest.slug ?? "(none)"}", but the integration uses "${entry.name}".`
290
293
  );
@@ -293,7 +296,7 @@ async function resolveLocal(entry, override, bindingMode, options, snapshotDir,
293
296
  if (sameRepo) {
294
297
  } else if (options.catalog) {
295
298
  const row = options.catalog.products.find(
296
- (product) => product.slug === entry.name
299
+ (product) => product.slug === parseIntegrationRef(entry.name).token
297
300
  );
298
301
  const seat = options.catalog.viewer.roles.length > 0;
299
302
  canDevelop = Boolean(row && row.owned === true && seat);
@@ -310,20 +313,23 @@ async function resolveLocal(entry, override, bindingMode, options, snapshotDir,
310
313
  const loadSource = options.loadSourceDefinition ?? loadDefinitionFromSource;
311
314
  const definition = await loadSource(override.path);
312
315
  const packageVersion = readPackageVersion(override.path);
313
- const contract = await contractForOverride({
316
+ const derived = await contractForOverride({
314
317
  definition,
315
318
  projectDir: override.path,
316
319
  packageVersion,
317
320
  derive: options.deriveContract
318
321
  });
319
- if (!contract) {
322
+ if (!derived) {
320
323
  return fail(
321
324
  `integration "${entry.name}": ${override.path} has no contract.json and no contract could be derived; run "ekanos contract" there.`
322
325
  );
323
326
  }
324
- if (contract.integration !== entry.name) {
327
+ let contract;
328
+ try {
329
+ contract = contractForRef(derived, entry.name);
330
+ } catch (error) {
325
331
  return fail(
326
- `integration "${entry.name}": the contract at ${override.path} is for "${contract.integration}", not "${entry.name}".`
332
+ `integration "${entry.name}": the contract at ${override.path} does not fit: ${error instanceof Error ? error.message : String(error)}`
327
333
  );
328
334
  }
329
335
  const problems = pinProblems(entry, contract, [contract.compatLine]);
@@ -416,7 +422,10 @@ function readCommittedContract(dir) {
416
422
  }
417
423
  function snapshotContract(snapshotDir, entry) {
418
424
  try {
419
- return pickLine(listContractsInDir(snapshotDir, entry.name), entry.version)?.contract ?? null;
425
+ return pickLine(
426
+ listContractsInDir(snapshotDir, parseIntegrationRef(entry.name).token),
427
+ entry.version
428
+ )?.contract ?? null;
420
429
  } catch {
421
430
  return null;
422
431
  }
@@ -426,10 +435,11 @@ async function resolveRegistry(entry, bindingMode, options, contractsDir, snapsh
426
435
  result.errors.push({ integration: entry.name, message });
427
436
  return null;
428
437
  };
438
+ const { token } = parseIntegrationRef(entry.name);
429
439
  let canDevelop = "unverified";
430
440
  if (options.catalog) {
431
441
  const row = options.catalog.products.find(
432
- (product) => product.slug === entry.name
442
+ (product) => product.slug === token
433
443
  );
434
444
  if (!row) {
435
445
  return fail(
@@ -453,7 +463,7 @@ async function resolveRegistry(entry, bindingMode, options, contractsDir, snapsh
453
463
  };
454
464
  const ensured = await installer.ensure({
455
465
  projectRoot: options.projectRoot,
456
- integration: entry.name,
466
+ integration: token,
457
467
  version: entry.version
458
468
  });
459
469
  if (ensured.ok) {
@@ -468,7 +478,7 @@ async function resolveRegistry(entry, bindingMode, options, contractsDir, snapsh
468
478
  origin: `${entry.name}@${ensured.version}`,
469
479
  stale: false,
470
480
  cachedPackage: {
471
- name: `@companydotcom/integration-${entry.name}`,
481
+ name: `@companydotcom/integration-${token}`,
472
482
  version: ensured.version
473
483
  }
474
484
  };
@@ -494,7 +504,7 @@ async function resolveRegistry(entry, bindingMode, options, contractsDir, snapsh
494
504
  if (!contract) {
495
505
  let candidates = [];
496
506
  if (contractsDir) {
497
- candidates = listContractsInDir(contractsDir, entry.name);
507
+ candidates = listContractsInDir(contractsDir, token);
498
508
  lines = availableLines(candidates);
499
509
  const picked = pickLine(candidates, entry.version);
500
510
  if (picked) {
@@ -510,7 +520,7 @@ async function resolveRegistry(entry, bindingMode, options, contractsDir, snapsh
510
520
  }
511
521
  }
512
522
  if (!contract) {
513
- const snapshots = listContractsInDir(snapshotDir, entry.name);
523
+ const snapshots = listContractsInDir(snapshotDir, token);
514
524
  lines = [.../* @__PURE__ */ new Set([...lines, ...availableLines(snapshots)])].sort();
515
525
  const picked = pickLine(snapshots, entry.version);
516
526
  if (picked) {
@@ -95,12 +95,18 @@ async function runOperation(request, deps) {
95
95
  ...approvalId ? { approvalId } : {}
96
96
  };
97
97
  };
98
- if (!integration) return refuse("slot_unknown");
98
+ if (!integration) {
99
+ const known = deps.integrations.map((candidate) => candidate.integration);
100
+ return refuse(
101
+ "slot_unknown",
102
+ `"${request.integration}" is not a resolved integration. Known: ${known.length > 0 ? known.join(", ") : "(none)"}.`
103
+ );
104
+ }
99
105
  const parsedKey = OP_KEY.exec(request.op);
100
106
  if (!parsedKey) return refuse("operation_not_declared");
101
107
  const kind = parsedKey[1];
102
108
  const name = parsedKey[2];
103
- const id = `${integration.integration}@${integration.version}/${kind}/${name}`;
109
+ const id = `${integration.integration.slice(integration.integration.indexOf("/") + 1)}@${integration.version}/${kind}/${name}`;
104
110
  if (!integration.operations.includes(id))
105
111
  return refuse("operation_not_declared");
106
112
  operation = integration.contract.operations.find((candidate) => candidate.id === id) ?? null;
@@ -104,8 +104,16 @@ function readProjectManifest(projectRoot) {
104
104
  entry: parsed.data.entry ?? null,
105
105
  integrations: entries.map((entry) => ({
106
106
  ...entry,
107
+ // A contract's operation ids carry the bare slug, even for a package
108
+ // named under a namespace (`vastly/news` -> `news@...`).
107
109
  operations: entry.operations.map(
108
- (id) => canonicalOperationId(entry, id)
110
+ (id) => canonicalOperationId(
111
+ {
112
+ name: entry.name.slice(entry.name.indexOf("/") + 1),
113
+ version: entry.version
114
+ },
115
+ id
116
+ )
109
117
  )
110
118
  })),
111
119
  deprecatedUses,
@@ -29,6 +29,7 @@ export declare function createPinsResolver(options: import('./internal/server/in
29
29
  contract: {
30
30
  schemaVersion: 1;
31
31
  integration: string;
32
+ namespace?: string | undefined;
32
33
  packageVersion: string;
33
34
  contractVersion: string;
34
35
  compatLine: string;
@@ -83,6 +84,7 @@ export declare function createRegistryContractSource(options: {
83
84
  contract: {
84
85
  schemaVersion: 1;
85
86
  integration: string;
87
+ namespace?: string | undefined;
86
88
  packageVersion: string;
87
89
  contractVersion: string;
88
90
  compatLine: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ekanos/harness",
3
- "version": "0.20.0",
3
+ "version": "0.22.0",
4
4
  "private": false,
5
5
  "description": "The Ekanos integration dev harness — every surface of an integration rendered in real Ekanos chrome, from fixtures, with no Supabase or auth; and, in live mode, a real localhost OAuth loop over your own dev-app credentials.",
6
6
  "homepage": "https://sdk.ekanos.dev/harness/overview",
@@ -72,15 +72,15 @@
72
72
  "access": "public"
73
73
  },
74
74
  "dependencies": {
75
- "@ekanos/integration-schema": "0.20.0",
75
+ "@ekanos/integration-schema": "0.22.0",
76
76
  "@fortawesome/fontawesome-free": "^7.3.1",
77
77
  "next-themes": "0.4.6",
78
78
  "tw-animate-css": "1.4.0",
79
79
  "zod": "4.6.7"
80
80
  },
81
81
  "devDependencies": {
82
- "@ekanos/sdk": "0.20.0",
83
- "@ekanos/ui": "0.20.0",
82
+ "@ekanos/sdk": "0.22.0",
83
+ "@ekanos/ui": "0.22.0",
84
84
  "@kit/tsconfig": "0.1.0",
85
85
  "@tailwindcss/postcss": "4.3.3",
86
86
  "@tanstack/react-query": "5.104.4",
@@ -99,8 +99,8 @@
99
99
  "vitest": "4.1.10"
100
100
  },
101
101
  "peerDependencies": {
102
- "@ekanos/sdk": "^0.20.0",
103
- "@ekanos/ui": "^0.20.0",
102
+ "@ekanos/sdk": "^0.22.0",
103
+ "@ekanos/ui": "^0.22.0",
104
104
  "@tanstack/react-query": "^5.101.4",
105
105
  "next": "^16.0.0",
106
106
  "next-intl": "^4.14.7",