@walkeros/config 4.7.0-next-1790722899482 → 4.7.0

package/CHANGELOG.md

@@ -1,6 +1,14 @@
 # @walkeros/config
 
-## 4.7.0-next-1790722899482
+## 4.7.0
+
+### Minor Changes
+
+- 64b06de: Packages with several exports, such as the GCP and AWS sources and
+  destinations, now publish a settings schema per export. `walkeros validate`
+  and MCP `package_get` use the schema of the export a step imports. Pub/Sub,
+  BigQuery, SNS and SQS steps pinned to this release or later are checked
+  instead of skipped; older pins still report a skip.
 
 ### Patch Changes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walkeros/config",
-  "version": "4.7.0-next-1790722899482",
+  "version": "4.7.0",
   "type": "module",
   "description": "Shared development configuration for walkerOS packages (TypeScript, ESLint, Jest, tsup)",
   "license": "MIT",

package/tsup/__tests__/exportMaps.test.mjs

@@ -0,0 +1,129 @@
+import {
+  assertExportMaps,
+  assertStepSettings,
+  publishedExports,
+} from '../exportMaps.mjs';
+
+const two = { destinationA: 'A', destinationB: 'B' };
+const examples = { destinationA: {}, destinationB: {} };
+const schemas = {
+  destinationA: { settings: {} },
+  destinationB: { settings: {}, setup: {} },
+};
+
+describe('assertExportMaps', () => {
+  it.each([
+    ['no declared exports and no maps', undefined, {}],
+    ['a single export and no maps', { destinationA: 'A' }, {}],
+    [
+      'two exports with matching maps',
+      two,
+      { exportExamples: examples, exportSchemas: schemas },
+    ],
+  ])('passes for %s', (_label, declared, maps) => {
+    expect(() => assertExportMaps('@walkeros/x', declared, maps)).not.toThrow();
+  });
+
+  it.each([
+    [
+      'exportSchemas missing',
+      two,
+      { exportExamples: examples },
+      '@walkeros/x: exportSchemas is missing',
+    ],
+    [
+      'exportExamples missing',
+      two,
+      { exportSchemas: schemas },
+      '@walkeros/x: exportExamples is missing',
+    ],
+    [
+      'an export missing from exportSchemas',
+      two,
+      {
+        exportExamples: examples,
+        exportSchemas: { destinationA: { settings: {} } },
+      },
+      '@walkeros/x: exportSchemas is missing export "destinationB"',
+    ],
+    [
+      'an undeclared export in exportSchemas',
+      two,
+      {
+        exportExamples: examples,
+        exportSchemas: { ...schemas, destinationC: { settings: {} } },
+      },
+      '@walkeros/x: exportSchemas has undeclared export "destinationC"',
+    ],
+    [
+      'an exportSchemas entry without settings',
+      two,
+      {
+        exportExamples: examples,
+        exportSchemas: { ...schemas, destinationB: { setup: {} } },
+      },
+      '@walkeros/x: exportSchemas.destinationB has no settings schema',
+    ],
+    [
+      'an export missing from exportExamples',
+      two,
+      { exportExamples: { destinationA: {} }, exportSchemas: schemas },
+      '@walkeros/x: exportExamples is missing export "destinationB"',
+    ],
+    [
+      'maps on a single-export package',
+      { destinationA: 'A' },
+      { exportSchemas: { destinationA: { settings: {} } } },
+      '@walkeros/x: exportSchemas is set but the package declares fewer than two exports',
+    ],
+  ])('throws for %s', (_label, declared, maps, message) => {
+    expect(() => assertExportMaps('@walkeros/x', declared, maps)).toThrow(
+      new Error(message),
+    );
+  });
+});
+
+describe('assertStepSettings', () => {
+  it.each(['source', 'transformer', 'destination', 'store'])(
+    'throws for a %s package without schemas.settings',
+    (type) => {
+      expect(() => assertStepSettings('@walkeros/x', type, {})).toThrow(
+        new Error('@walkeros/x: schemas.settings is missing'),
+      );
+    },
+  );
+
+  it.each([
+    ['a destination with settings', 'destination', { settings: {} }],
+    ['a package without a type', undefined, {}],
+    ['a non-step package', 'core', {}],
+  ])('passes for %s', (_label, type, published) => {
+    expect(() =>
+      assertStepSettings('@walkeros/x', type, published),
+    ).not.toThrow();
+  });
+});
+
+describe('publishedExports', () => {
+  it.each([
+    [
+      'a multi-export package keeps its declared exports',
+      { type: 'destination', exports: two },
+      two,
+    ],
+    [
+      'a single-export package keeps its one declared export',
+      { type: 'destination', exports: { destinationA: 'A' } },
+      { destinationA: 'A' },
+    ],
+    [
+      'a step package without declared exports publishes an empty list',
+      { type: 'source' },
+      {},
+    ],
+    ['a non-step package publishes no list', { type: 'core' }, undefined],
+    ['a package without a type publishes no list', {}, undefined],
+  ])('%s', (_label, walkerOS, expected) => {
+    expect(publishedExports(walkerOS)).toEqual(expected);
+  });
+});

package/tsup/exportMaps.mjs

@@ -0,0 +1,78 @@
+// Guards for published step metadata in dist/walkerOS.json. A package that
+// declares two or more exports in package.json `walkerOS.exports` ships
+// `exportExamples` and `exportSchemas` keyed by exactly those export names,
+// the default export included, so a reader never falls back to another
+// export's examples or settings schema.
+
+const STEP_TYPES = ['source', 'transformer', 'destination', 'store'];
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function assertKeys(packageName, mapName, map, declared) {
+  if (!isRecord(map)) throw new Error(`${packageName}: ${mapName} is missing`);
+  for (const name of declared) {
+    if (!(name in map))
+      throw new Error(`${packageName}: ${mapName} is missing export "${name}"`);
+  }
+  for (const name of Object.keys(map)) {
+    if (!declared.includes(name))
+      throw new Error(
+        `${packageName}: ${mapName} has undeclared export "${name}"`,
+      );
+  }
+}
+
+/**
+ * Throw when the per-export maps do not match the declared exports: with two
+ * or more exports both maps list every export and each `exportSchemas` entry
+ * carries a `settings` schema; with fewer, neither map is present.
+ */
+function assertExportMaps(packageName, declaredExports, maps) {
+  const declared = isRecord(declaredExports)
+    ? Object.keys(declaredExports)
+    : [];
+  const { exportExamples, exportSchemas } = maps;
+
+  if (declared.length < 2) {
+    for (const [mapName, map] of [
+      ['exportExamples', exportExamples],
+      ['exportSchemas', exportSchemas],
+    ]) {
+      if (map !== undefined)
+        throw new Error(
+          `${packageName}: ${mapName} is set but the package declares fewer than two exports`,
+        );
+    }
+    return;
+  }
+
+  assertKeys(packageName, 'exportExamples', exportExamples, declared);
+  assertKeys(packageName, 'exportSchemas', exportSchemas, declared);
+  for (const [name, entry] of Object.entries(exportSchemas)) {
+    if (!isRecord(entry) || !isRecord(entry.settings))
+      throw new Error(
+        `${packageName}: exportSchemas.${name} has no settings schema`,
+      );
+  }
+}
+
+/** Throw when a step package (source, transformer, destination, store) publishes no settings schema. */
+function assertStepSettings(packageName, type, schemas) {
+  if (!STEP_TYPES.includes(type)) return;
+  if (!isRecord(schemas) || !isRecord(schemas.settings))
+    throw new Error(`${packageName}: schemas.settings is missing`);
+}
+
+/**
+ * The `$meta.exports` a package publishes: its declared `walkerOS.exports`,
+ * else an empty list for a step package, so a reader can tell a package
+ * without named exports from an older package that published no list.
+ */
+function publishedExports(walkerOS) {
+  if (isRecord(walkerOS.exports)) return walkerOS.exports;
+  return STEP_TYPES.includes(walkerOS.type) ? {} : undefined;
+}
+
+export { assertExportMaps, assertStepSettings, publishedExports };

package/tsup/index.mjs

@@ -3,6 +3,11 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { resolve, join } from 'path';
 import { pathToFileURL } from 'url';
 import { assertNoPublishedCredentials } from './credentialGuard.mjs';
+import {
+  assertExportMaps,
+  assertStepSettings,
+  publishedExports,
+} from './exportMaps.mjs';
 
 const baseConfig = {
   entry: ['src/index.ts'],
@@ -17,7 +22,10 @@ const getVersion = () => {
     const pkg = JSON.parse(readFileSync(packagePath, 'utf8'));
     return pkg.version || '0.0.0';
   } catch (error) {
-    console.warn('Could not read package.json for version injection:', error.message);
+    console.warn(
+      'Could not read package.json for version injection:',
+      error.message,
+    );
     return '0.0.0';
   }
 };
@@ -141,7 +149,9 @@ const buildDev = (customConfig = {}) => {
       // Check the built module exists
       const devMjsPath = resolve(cwd, 'dist/dev.mjs');
       if (!existsSync(devMjsPath)) {
-        console.warn('[buildDev] dist/dev.mjs not found, skipping walkerOS.json generation');
+        console.warn(
+          '[buildDev] dist/dev.mjs not found, skipping walkerOS.json generation',
+        );
         return;
       }
 
@@ -174,7 +184,8 @@ const buildDev = (customConfig = {}) => {
           : [walkerOS.platform];
       }
       if (walkerOS.renderer) meta.renderer = walkerOS.renderer;
-      if (walkerOS.exports) meta.exports = walkerOS.exports;
+      const exports = publishedExports(walkerOS);
+      if (exports) meta.exports = exports;
 
       // Docs URL (manual, from walkerOS.docs in package.json)
       if (walkerOS.docs) meta.docs = walkerOS.docs;
@@ -182,7 +193,9 @@ const buildDev = (customConfig = {}) => {
       // Source URL (auto-derived from repository.directory)
       const repo = pkg.repository;
       if (repo?.directory) {
-        const repoUrl = (repo.url || '').replace(/^git\+/, '').replace(/\.git$/, '');
+        const repoUrl = (repo.url || '')
+          .replace(/^git\+/, '')
+          .replace(/\.git$/, '');
         if (repoUrl) meta.source = `${repoUrl}/tree/main/${repo.directory}/src`;
       }
 
@@ -200,6 +213,13 @@ const buildDev = (customConfig = {}) => {
           output.exportExamples = exportExamples;
       }
 
+      // Multi-export packages ship schemas per export, same shape as schemas
+      if (devModule.exportSchemas) {
+        const exportSchemas = toSerializable(devModule.exportSchemas);
+        if (exportSchemas && Object.keys(exportSchemas).length > 0)
+          output.exportSchemas = exportSchemas;
+      }
+
       if (hints && Object.keys(hints).length > 0) {
         output.hints = hints;
       }
@@ -211,6 +231,13 @@ const buildDev = (customConfig = {}) => {
         hints: output.hints,
       });
 
+      // Per-export maps match walkerOS.exports; step packages ship settings
+      assertExportMaps(pkg.name, walkerOS.exports, {
+        exportExamples: output.exportExamples,
+        exportSchemas: output.exportSchemas,
+      });
+      assertStepSettings(pkg.name, walkerOS.type, schemas);
+
       // Validate
       if (Object.keys(schemas).length === 0) {
         console.warn('[buildDev] Warning: schemas is empty');