@ekanos/integration-schema 0.1.1 → 0.1.3

package/dist/integration-definition.js

@@ -30,7 +30,7 @@ function componentRefSchema(what) {
     });
 }
 const zodSchemaRef = z.custom((value) => typeof (value === null || value === void 0 ? void 0 : value.safeParse) === 'function', {
-    message: 'Every storage key must declare a zod schema (e.g. z.object({ … })) — ctx.storage validates reads and writes against it (capability-context ruling 1).',
+    message: 'Every storage key must declare a zod schema (e.g. z.object({ … })) — ctx.storage validates reads and writes against it.',
 });
 const nonEmpty = (what) => z.string().min(1, { message: `${what} must be a non-empty string.` });
 const slugSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, {
@@ -39,9 +39,90 @@ const slugSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, {
 const widgetIdSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, {
     message: 'Widget ids are kebab-case and globally unique, e.g. "acme-crm-pipeline" — prefix with the integration slug to stay collision-free.',
 });
-const storageKeySchema = z.string().regex(/^[a-z0-9_-]+(?:\/[a-z0-9_-]+)?$/, {
-    message: 'Storage keys are "<dataType>" or "<dataType>/<subtype>" in lowercase [a-z0-9_-] — they map onto the account/user product-data columns (capability-context ruling 6).',
-});
+/**
+ * The `data_type` values each storage scope permits.
+ *
+ * THIS IS THE SOURCE OF TRUTH, and it lives here rather than in the host
+ * because this package is the one a partner's `defineIntegration()` validates
+ * against — a declaration naming an impossible data_type should fail at
+ * authoring time, not on the first `ctx.storage` call in production. The host
+ * (`apps/web/lib/server/integration-context.ts`) imports these same arrays for
+ * its runtime check, so the two cannot drift.
+ *
+ * They mirror the DB CHECK constraints on `account_product_data` and
+ * `user_product_data` (`apps/web/supabase/schemas/26-integrations.sql`), with
+ * one deliberate subtraction: see `RESERVED_STORAGE_DATA_TYPES`.
+ */
+export const ACCOUNT_STORAGE_DATA_TYPES = [
+    'activation',
+    'settings',
+    'metrics_summary',
+    'sync_state',
+    'cache',
+];
+export const USER_STORAGE_DATA_TYPES = [
+    'config',
+    'preferences',
+    'cache',
+];
+/**
+ * In the DB CHECK but NEVER addressable through `ctx.storage`.
+ *
+ * `secret` rows are host-managed per-name credential rows whose values live in
+ * Vault; partner code reaches them only through `ctx.secrets`, which never
+ * exposes a value or a vault id. Letting a partner DECLARE `secret` storage
+ * would hand them a key that collides with host-managed secret rows, so it is
+ * rejected here with its own message rather than the generic "not an allowed
+ * data_type" — an author who wrote `secret` meant something specific and needs
+ * to be pointed at `ctx.secrets`.
+ *
+ * Kept as its own list rather than simply omitted from the arrays above so the
+ * reason survives: `secret` is a real column value, not a typo.
+ */
+export const RESERVED_STORAGE_DATA_TYPES = ['secret'];
+/** VARCHAR(100) on both the data_type and data_subtype columns. */
+const MAX_STORAGE_SEGMENT_LENGTH = 100;
+const STORAGE_KEY_SHAPE = /^[a-z0-9_-]+(?:\/[a-z0-9_-]+)?$/;
+/**
+ * A storage key is `"<dataType>"` or `"<dataType>/<subtype>"`, mapped onto the
+ * `(data_type, data_subtype)` columns. Scope-specific because the two tables
+ * carry different CHECK constraints — `settings` is an account data_type and
+ * `preferences` a user one, and neither is valid in the other's scope.
+ */
+function storageKeySchemaFor(scope) {
+    const allowed = scope === 'account' ? ACCOUNT_STORAGE_DATA_TYPES : USER_STORAGE_DATA_TYPES;
+    return z.string().superRefine((key, ctx) => {
+        const fail = (message) => ctx.addIssue({ code: z.ZodIssueCode.custom, message });
+        if (!STORAGE_KEY_SHAPE.test(key)) {
+            fail(`Storage key "${key}" is malformed. Keys are "<dataType>" or ` +
+                `"<dataType>/<subtype>" in lowercase [a-z0-9_-], with at most one ` +
+                `"/" and no empty segment.`);
+            return;
+        }
+        const slashIndex = key.indexOf('/');
+        const dataType = slashIndex === -1 ? key : key.slice(0, slashIndex);
+        const dataSubtype = slashIndex === -1 ? undefined : key.slice(slashIndex + 1);
+        if (RESERVED_STORAGE_DATA_TYPES.includes(dataType)) {
+            fail(`Storage key "${key}" uses the reserved "${dataType}" data_type, ` +
+                `which ctx.storage can never read or write. Integration secrets are ` +
+                `host-managed — declare nothing here and use ctx.secrets.get/set/names ` +
+                `instead; a secret's value and its vault id are never reachable ` +
+                `through ctx.storage.`);
+            return;
+        }
+        if (!allowed.includes(dataType)) {
+            fail(`Storage key "${key}" is invalid for the ${scope} scope: ` +
+                `"${dataType}" is not an allowed ${scope} data_type. Use one of ` +
+                `[${allowed.join(', ')}] (the database CHECK constraint).`);
+            return;
+        }
+        if (dataSubtype !== undefined &&
+            dataSubtype.length > MAX_STORAGE_SEGMENT_LENGTH) {
+            fail(`Storage key "${key}" has a subtype longer than ` +
+                `${MAX_STORAGE_SEGMENT_LENGTH} characters (the column width).`);
+        }
+    });
+}
 const toolNameSchema = z.string().regex(/^[a-z][a-z0-9_]*$/, {
     message: 'Tool names are lowercase snake_case starting with a letter, e.g. "list_invoices" — the model calls them by this exact string.',
 });
@@ -312,7 +393,7 @@ const storageKeyDeclarationRef = z
         !isZodSchemaLike(value.schema)) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: 'Every storage key must declare either a zod schema (e.g. z.object({ … })) or a { schema, clientReadable } descriptor — ctx.storage validates reads and writes against the schema (capability-context ruling 1), and clientReadable (default false) is what opts the key in to the browser-readable storage route.',
+            message: 'Every storage key must declare either a zod schema (e.g. z.object({ … })) or a { schema, clientReadable } descriptor — ctx.storage validates reads and writes against the schema, and clientReadable (default false) is what opts the key in to the browser-readable storage route.',
         });
         return;
     }
@@ -330,7 +411,7 @@ const storageKeyDeclarationRef = z
         });
     }
 });
-const storageScopeSchema = z.record(storageKeySchema, storageKeyDeclarationRef);
+const storageScopeSchemaFor = (scope) => z.record(storageKeySchemaFor(scope), storageKeyDeclarationRef);
 const componentsSchema = z
     .object({
     activationForm: componentRefSchema('components.activationForm').optional(),
@@ -361,8 +442,8 @@ export const IntegrationDefinitionSchema = z
     tools: z.array(toolSchema).optional(),
     storage: z
         .object({
-        account: storageScopeSchema.optional(),
-        user: storageScopeSchema.optional(),
+        account: storageScopeSchemaFor('account').optional(),
+        user: storageScopeSchemaFor('user').optional(),
     })
         .strict()
         .optional(),
@@ -429,14 +510,6 @@ function findDuplicates(values) {
     }
     return [...duplicates];
 }
-function formatIssues(issues) {
-    return issues
-        .map((issue) => {
-        const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';
-        return `  - ${path}: ${issue.message}`;
-    })
-        .join('\n');
-}
 const HOST_ASSIGNED_REMINDER = 'Host-assigned fields are never partner-authorable: productId, kind, trust ' +
     'tier, and machine exposure (credentialModel) do not exist on ' +
     'IntegrationDefinition, per-tool effect/sensitivity belong in the ' +
@@ -444,6 +517,70 @@ const HOST_ASSIGNED_REMINDER = 'Host-assigned fields are never partner-authorabl
     'widgetConfigId, workspaceId, collapsed, isPinned, health, ' +
     'integrationMetadata) are populated by the platform at runtime — remove ' +
     'them from the definition.';
+const PLAIN_DATA_HINT = 'Declarations must be finite plain data. Remove the cycle, getter/setter, ' +
+    'or class/exotic instance the message names so the value cannot change ' +
+    'after validation, then re-run validate.';
+/** Per-issue remediation. Unrecognized keys get the host-assigned reminder. */
+function hintForIssue(issue) {
+    if (issue.code === z.ZodIssueCode.unrecognized_keys) {
+        return HOST_ASSIGNED_REMINDER;
+    }
+    const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+    return (`Correct the value at "${path}" so it satisfies ` +
+        `@ekanos/integration-schema's IntegrationDefinitionSchema, then re-run ` +
+        `validate.`);
+}
+/**
+ * The single, shared implementation behind BOTH the non-throwing collector and
+ * the throwing `parseIntegrationDefinition`. Runs the plain-data structural
+ * check first (short-circuiting exactly as the throwing path always has), then
+ * the canonical zod parse. Returns the findings, the sanitized `data` on
+ * success, and whether an unrecognized key was among the failures (the
+ * throwing path appends the host-assigned reminder only in that case).
+ */
+function collectDefinitionResult(input, options = {}) {
+    const { file } = options;
+    // Structural pre-check: the same rule assertPlainDeclaration throws on, but
+    // captured as a finding. If it fails we stop here, matching the throwing
+    // path which never reaches safeParse once the pre-check throws.
+    try {
+        assertPlainDeclaration(input);
+    }
+    catch (error) {
+        return {
+            findings: [
+                Object.assign(Object.assign({ check: 'definition.plain-data', severity: 'error' }, (file ? { file } : {})), { message: error instanceof Error ? error.message : String(error), hint: PLAIN_DATA_HINT }),
+            ],
+            hasUnrecognizedKey: false,
+        };
+    }
+    const result = IntegrationDefinitionSchema.safeParse(input);
+    if (result.success) {
+        deepFreezeDefinition(result.data);
+        return {
+            findings: [],
+            data: result.data,
+            hasUnrecognizedKey: false,
+        };
+    }
+    const hasUnrecognizedKey = result.error.issues.some((issue) => issue.code === z.ZodIssueCode.unrecognized_keys);
+    const findings = result.error.issues.map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+        return Object.assign(Object.assign({ check: 'definition.schema', severity: 'error' }, (file ? { file } : {})), { 
+            // The zod path, not a source line — see the Finding doc comment.
+            message: `${path}: ${issue.message}`, hint: hintForIssue(issue) });
+    });
+    return { findings, hasUnrecognizedKey };
+}
+/**
+ * Non-throwing sibling of `parseIntegrationDefinition`: validates a single
+ * integration definition against the canonical schema and returns structured
+ * findings instead of throwing a pre-formatted string. An empty array means
+ * the definition is valid. Used by `@ekanos/cli validate`.
+ */
+export function collectDefinitionFindings(input, options = {}) {
+    return collectDefinitionResult(input, options).findings;
+}
 /**
  * A zod schema (storage leaf) or a React exotic (`memo`/`forwardRef`, an
  * object tagged with `$$typeof`). NOTHING here reads a property value:
@@ -559,32 +696,37 @@ export function deepFreezeDefinition(value) {
  * whose message is a remediation instruction.
  */
 export function parseIntegrationDefinition(input) {
-    assertPlainDeclaration(input);
-    const result = IntegrationDefinitionSchema.safeParse(input);
-    if (!result.success) {
-        const slug = typeof (input === null || input === void 0 ? void 0 : input.slug) === 'string'
-            ? ` for "${input.slug}"`
-            : '';
-        // The reminder is six lines about fields the author may not have written.
-        // Appending it to EVERY failure buries the one line that matters — a bad
-        // semver or a malformed cron arrives under a paragraph about productId and
-        // trust tiers. Show it only when an unrecognized key is what failed, which
-        // is the case it was written for.
-        const hasUnrecognizedKey = result.error.issues.some((issue) => issue.code === z.ZodIssueCode.unrecognized_keys);
-        throw new Error(`Invalid integration definition${slug}:\n` +
-            formatIssues(result.error.issues) +
-            (hasUnrecognizedKey ? `\n${HOST_ASSIGNED_REMINDER}` : ''));
-    }
-    // F4: freeze inside the canonical parser so BOTH defineIntegration() and
-    // registerPartnerIntegration() register immutable output — the host boundary
-    // no longer hands back mutable arrays. Function/zod leaves stay executable
-    // by design (the T1 model), so this is structural immutability, not
-    // behavioral.
-    deepFreezeDefinition(result.data);
-    // The schema's inferred output matches IntegrationDefinition in every
-    // non-generic field; the storage/tool generics default to the permissive
-    // base, which is exactly right for the loose registration boundary.
-    return result.data;
+    // Built ON TOP of the collector so there is exactly one rule set. The
+    // collector runs assertPlainDeclaration first (short-circuiting), then the
+    // canonical parse, and freezes `data` on success (F4) — so a successful
+    // result here is already the deep-frozen, sanitized definition.
+    const { findings, data, hasUnrecognizedKey } = collectDefinitionResult(input);
+    if (data) {
+        // The schema's inferred output matches IntegrationDefinition in every
+        // non-generic field; the storage/tool generics default to the permissive
+        // base, which is exactly right for the loose registration boundary.
+        return data;
+    }
+    // A plain-data structural failure is thrown verbatim (its message is already
+    // a remediation: "…contains a cycle…", "…is a getter/setter…").
+    const plainDataFinding = findings.find((finding) => finding.check === 'definition.plain-data');
+    if (plainDataFinding) {
+        throw new Error(plainDataFinding.message);
+    }
+    // Schema failures reproduce the historical message shape exactly: each
+    // finding's message is already `${path}: ${issue.message}`, so re-prefixing
+    // with `  - ` reconstructs formatIssues() verbatim.
+    const slug = typeof (input === null || input === void 0 ? void 0 : input.slug) === 'string'
+        ? ` for "${input.slug}"`
+        : '';
+    // The reminder is six lines about fields the author may not have written.
+    // Appending it to EVERY failure buries the one line that matters — a bad
+    // semver or a malformed cron arrives under a paragraph about productId and
+    // trust tiers. Show it only when an unrecognized key is what failed, which
+    // is the case it was written for.
+    throw new Error(`Invalid integration definition${slug}:\n` +
+        findings.map((finding) => `  - ${finding.message}`).join('\n') +
+        (hasUnrecognizedKey ? `\n${HOST_ASSIGNED_REMINDER}` : ''));
 }
 // ---- Cross-definition collision detection (F5) -----------------------------
 /**
@@ -595,24 +737,19 @@ export function parseIntegrationDefinition(input) {
  * to the same EFFECTIVE name (`{slug:"foo",tool:"bar_baz"}` and
  * `{slug:"foo-bar",tool:"baz"}` both become `foo_bar_baz`), so collision
  * checking MUST compare effective names, and runtime discovery MUST throw on a
- * duplicate assignment. Both call this one helper
- * (`packages/agents/src/tools/tool-discovery.ts`).
+ * duplicate assignment. Host-side tool discovery calls this same helper, so
+ * there is one definition of the effective name.
  */
 export function getDiscoveredToolName(slug, rawName) {
     const slugPrefix = slug.replace(/-/g, '_');
     return rawName.startsWith(slugPrefix) ? rawName : `${slugPrefix}_${rawName}`;
 }
 /**
- * Detects cross-definition collisions (duplicate slugs, widget ids, tool
- * names across the partner set) AND collisions against the first-party
- * inventory, throwing one error listing EVERY collision.
- *
- * This is the build-time gate the host registry deliberately lacks:
- * `integrationRegistry.register()` keys by slug via `Map.set` and silently
- * OVERWRITES, and duplicate widget/tool ids resolve last- or
- * first-registration-wins by import order.
+ * THE shared collision rule set, returning structured records. Both the
+ * throwing `validateIntegrationDefinitions` and the non-throwing
+ * `collectCollisionFindings` are built on this, so there is one rule set.
  */
-export function validateIntegrationDefinitions(definitions, firstParty = {}) {
+function computeCollisionRecords(definitions, firstParty = {}) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j;
     const slugCounts = new Map();
     const widgetOwners = new Map();
@@ -635,20 +772,32 @@ export function validateIntegrationDefinitions(definitions, firstParty = {}) {
             ]);
         }
     }
-    const collisions = [];
+    const records = [];
     for (const [slug, count] of slugCounts) {
         if (count > 1) {
-            collisions.push(`slug "${slug}" is declared by ${count} partner definitions — slugs are the registry key and must be globally unique.`);
+            records.push({
+                check: 'collision.slug',
+                message: `slug "${slug}" is declared by ${count} partner definitions — slugs are the registry key and must be globally unique.`,
+                hint: `Rename all but one of the definitions declaring slug "${slug}" so every slug is globally unique.`,
+            });
         }
     }
     for (const [id, owners] of widgetOwners) {
         if (owners.length > 1) {
-            collisions.push(`widget id "${id}" is declared by [${owners.join(', ')}] — widget ids are global (widget_config rows key on them); prefix yours with the integration slug.`);
+            records.push({
+                check: 'collision.widget-id',
+                message: `widget id "${id}" is declared by [${owners.join(', ')}] — widget ids are global (widget_config rows key on them); prefix yours with the integration slug.`,
+                hint: `Prefix widget id "${id}" with your integration slug so it is globally unique.`,
+            });
         }
     }
     for (const [name, owners] of toolOwners) {
         if (owners.length > 1) {
-            collisions.push(`effective tool name "${name}" is declared by [${owners.join(', ')}] — discovery namespaces tool names by slug, so these collapse to one flat key and overwrite each other. Rename so the slug-prefixed names differ.`);
+            records.push({
+                check: 'collision.tool-name',
+                message: `effective tool name "${name}" is declared by [${owners.join(', ')}] — discovery namespaces tool names by slug, so these collapse to one flat key and overwrite each other. Rename so the slug-prefixed names differ.`,
+                hint: `Rename the colliding tools so their slug-prefixed effective names differ from "${name}".`,
+            });
         }
     }
     const reservedSlugs = new Set((_g = firstParty.slugs) !== null && _g !== void 0 ? _g : []);
@@ -656,19 +805,49 @@ export function validateIntegrationDefinitions(definitions, firstParty = {}) {
     const reservedTools = new Set((_j = firstParty.toolNames) !== null && _j !== void 0 ? _j : []);
     for (const [slug, owners] of groupOwners(definitions, (d) => [d.slug])) {
         if (reservedSlugs.has(slug)) {
-            collisions.push(`slug "${slug}" (declared by [${owners.join(', ')}]) collides with a first-party integration — pick a slug no built-in product uses.`);
+            records.push({
+                check: 'collision.reserved-slug',
+                message: `slug "${slug}" (declared by [${owners.join(', ')}]) collides with a first-party integration — pick a slug no built-in product uses.`,
+                hint: `Choose a different slug than "${slug}" — it is reserved by a first-party integration.`,
+            });
         }
     }
     for (const [id, owners] of widgetOwners) {
         if (reservedWidgets.has(id)) {
-            collisions.push(`widget id "${id}" (declared by [${owners.join(', ')}]) collides with a first-party widget — the dashboard resolves widgets by id, so this would hijack it. Prefix with the integration slug.`);
+            records.push({
+                check: 'collision.reserved-widget-id',
+                message: `widget id "${id}" (declared by [${owners.join(', ')}]) collides with a first-party widget — the dashboard resolves widgets by id, so this would hijack it. Prefix with the integration slug.`,
+                hint: `Prefix widget id "${id}" with your integration slug — it is reserved by a first-party widget.`,
+            });
         }
     }
     for (const [name, owners] of toolOwners) {
         if (reservedTools.has(name)) {
-            collisions.push(`effective tool name "${name}" (declared by [${owners.join(', ')}]) collides with a first-party tool — the flat, slug-namespaced tool registry would overwrite one with the other. Rename it.`);
+            records.push({
+                check: 'collision.reserved-tool-name',
+                message: `effective tool name "${name}" (declared by [${owners.join(', ')}]) collides with a first-party tool — the flat, slug-namespaced tool registry would overwrite one with the other. Rename it.`,
+                hint: `Rename the tool so its effective name is not "${name}" — that name is reserved by a first-party tool.`,
+            });
         }
     }
+    return records;
+}
+/**
+ * Non-throwing sibling of `validateIntegrationDefinitions`: returns structured
+ * collision findings across the partner set (and against the first-party
+ * inventory) instead of throwing. An empty array means no collisions. Used by
+ * `@ekanos/cli validate`.
+ */
+export function collectCollisionFindings(definitions, firstParty = {}) {
+    return computeCollisionRecords(definitions, firstParty).map((record) => ({
+        check: record.check,
+        severity: 'error',
+        message: record.message,
+        hint: record.hint,
+    }));
+}
+export function validateIntegrationDefinitions(definitions, firstParty = {}) {
+    const collisions = computeCollisionRecords(definitions, firstParty).map((record) => record.message);
     if (collisions.length > 0) {
         throw new Error(`Integration definitions collide (${collisions.length} collision${collisions.length === 1 ? '' : 's'}):\n` +
             collisions.map((line) => `  - ${line}`).join('\n') +