@eide/foir-cli 0.4.11 → 0.4.14

package/dist/cli.js

@@ -3146,10 +3146,13 @@ async function createPlatformClient(options) {
     headers["Authorization"] = `Bearer ${credentials.accessToken}`;
   }
   const resolved = await resolveProjectContext(options);
-  if (resolved) {
-    headers["x-tenant-id"] = resolved.project.tenantId;
-    headers["x-project-id"] = resolved.project.id;
+  if (!resolved) {
+    throw new Error(
+      "No project selected. Run `foir select-project` to choose a project."
+    );
   }
+  headers["x-tenant-id"] = resolved.project.tenantId;
+  headers["x-project-id"] = resolved.project.id;
   const authInterceptor = (next) => async (req) => {
     for (const [key, value] of Object.entries(headers)) {
       req.header.set(key, value);
@@ -3240,10 +3243,13 @@ async function getStorageAuth(options) {
     baseHeaders["Authorization"] = `Bearer ${credentials.accessToken}`;
   }
   const resolved = await resolveProjectContext(options);
-  if (resolved) {
-    baseHeaders["x-tenant-id"] = resolved.project.tenantId;
-    baseHeaders["x-project-id"] = resolved.project.id;
+  if (!resolved) {
+    throw new Error(
+      "No project selected. Run `foir select-project` to choose a project."
+    );
   }
+  baseHeaders["x-tenant-id"] = resolved.project.tenantId;
+  baseHeaders["x-project-id"] = resolved.project.id;
   let cachedToken = null;
   const getToken = async () => {
     if (cachedToken && Date.now() < cachedToken.expiresAt - 3e4) {
@@ -5105,6 +5111,217 @@ async function reconcileApiKeys(client, apiKeys, summary) {
   }
 }
 
+// src/lib/validate-integrations.ts
+var KEBAB_CASE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+var KNOWN_CREDENTIAL_STRATEGIES = /* @__PURE__ */ new Set([
+  "oauth",
+  "api_key",
+  "shared_secret",
+  "ssh_key",
+  "none",
+  "managed"
+]);
+var KNOWN_EXTENSION_TARGETS = /* @__PURE__ */ new Set(["record", "model-list"]);
+var IntegrationValidationError = class extends Error {
+  errors;
+  constructor(errors) {
+    super(
+      `foir.config.ts failed validation:
+${errors.map((e) => `  - ${e}`).join("\n")}`
+    );
+    this.name = "IntegrationValidationError";
+    this.errors = errors;
+  }
+};
+function validateIntegrationsAndExtensions(manifest) {
+  const errors = [];
+  const warnings = [];
+  const modelsByKey = /* @__PURE__ */ new Map();
+  for (const model of manifest.models ?? []) {
+    modelsByKey.set(model.key, model);
+  }
+  if (manifest.integrations) {
+    for (const [name, integration] of Object.entries(manifest.integrations)) {
+      validateIntegration(name, integration, modelsByKey, errors, warnings);
+    }
+  }
+  if (manifest.extensions) {
+    for (const [name, extension] of Object.entries(manifest.extensions)) {
+      validateExtension(name, extension, modelsByKey, errors);
+    }
+  }
+  return { errors, warnings };
+}
+function assertValid(result) {
+  if (result.errors.length > 0) {
+    throw new IntegrationValidationError(result.errors);
+  }
+}
+function validateIntegration(name, integration, modelsByKey, errors, warnings) {
+  const prefix = `integration '${name}'`;
+  if (!KEBAB_CASE.test(name)) {
+    errors.push(`${prefix}: name must be kebab-case (lowercase, dash-separated)`);
+  }
+  const middlewareUrl = integration.middleware?.url;
+  if (!middlewareUrl || typeof middlewareUrl !== "string") {
+    errors.push(`${prefix}: middleware.url is required`);
+  } else if (!isWellFormedHttpsUrl(middlewareUrl)) {
+    errors.push(
+      `${prefix}: middleware.url must be a well-formed https URL, got '${middlewareUrl}'`
+    );
+  }
+  const strategy = integration.credentials?.strategy;
+  if (!strategy) {
+    errors.push(`${prefix}: credentials.strategy is required`);
+  } else if (!KNOWN_CREDENTIAL_STRATEGIES.has(strategy)) {
+    errors.push(
+      `${prefix}: credentials.strategy '${strategy}' is not one of ${[...KNOWN_CREDENTIAL_STRATEGIES].join(", ")}`
+    );
+  }
+  const sync = integration.sync ?? {};
+  if (Object.keys(sync).length === 0) {
+    errors.push(`${prefix}: sync must declare at least one source type`);
+  }
+  for (const [sourceType, mapping] of Object.entries(sync)) {
+    validateSyncMapping(
+      `${prefix} sync.${sourceType}`,
+      mapping,
+      name,
+      modelsByKey,
+      errors,
+      warnings
+    );
+  }
+}
+function validateSyncMapping(prefix, mapping, integrationName, modelsByKey, errors, warnings) {
+  if (!mapping.model || typeof mapping.model !== "string") {
+    errors.push(`${prefix}: model is required`);
+    return;
+  }
+  const model = modelsByKey.get(mapping.model);
+  const seed = mapping.modelSeed;
+  if (!model && !seed) {
+    errors.push(
+      `${prefix}: missing model '${mapping.model}' referenced by integration '${integrationName}' \u2014 declare it under models or provide a modelSeed`
+    );
+    return;
+  }
+  const fieldKeys = model ? new Set((model.fields ?? []).map((f) => f.key)) : new Set(Object.keys(seed?.fields ?? {}));
+  const naturalKeyField = mapping.naturalKey;
+  if (!naturalKeyField || typeof naturalKeyField !== "string") {
+    errors.push(`${prefix}: naturalKey is required`);
+  } else if (!fieldKeys.has(naturalKeyField)) {
+    errors.push(
+      `${prefix}: naturalKey '${naturalKeyField}' does not exist on ${model ? `model '${mapping.model}'` : `modelSeed for '${mapping.model}'`}`
+    );
+  }
+  const fields = mapping.fields ?? {};
+  if (Object.keys(fields).length === 0) {
+    errors.push(`${prefix}: fields mapping must declare at least one field`);
+  }
+  for (const [sourceField, foirField] of Object.entries(fields)) {
+    if (!foirField || typeof foirField !== "string") {
+      errors.push(
+        `${prefix}: field mapping for source '${sourceField}' must be a non-empty string`
+      );
+      continue;
+    }
+    if (!fieldKeys.has(foirField)) {
+      errors.push(
+        `${prefix}: field mapping '${sourceField} -> ${foirField}' references field '${foirField}' which does not exist on ${model ? `model '${mapping.model}'` : `modelSeed for '${mapping.model}'`}`
+      );
+    }
+  }
+  if (seed) {
+    validateSeedStructure(prefix, seed, errors);
+    if (model) {
+      detectSeedDrift(prefix, seed, model, warnings);
+    }
+  }
+}
+function validateSeedStructure(prefix, seed, errors) {
+  const fields = seed.fields ?? {};
+  if (Object.keys(fields).length === 0) {
+    errors.push(`${prefix}: modelSeed.fields must declare at least one field`);
+    return;
+  }
+  for (const [key, field] of Object.entries(fields)) {
+    if (!field || typeof field !== "object") {
+      errors.push(`${prefix}: modelSeed.fields.${key} must be an object`);
+      continue;
+    }
+    if (!field.type || typeof field.type !== "string") {
+      errors.push(`${prefix}: modelSeed.fields.${key}.type is required`);
+    }
+  }
+}
+function detectSeedDrift(prefix, seed, model, warnings) {
+  const modelFieldTypes = /* @__PURE__ */ new Map();
+  for (const field of model.fields ?? []) {
+    modelFieldTypes.set(field.key, field.type);
+  }
+  for (const [key, field] of Object.entries(seed.fields ?? {})) {
+    const modelType = modelFieldTypes.get(key);
+    if (!modelType) {
+      warnings.push(
+        `${prefix}: modelSeed.fields.${key} is not present on existing model \u2014 modelSeed is ignored on subsequent pushes`
+      );
+    } else if (field.type && modelType !== field.type) {
+      warnings.push(
+        `${prefix}: modelSeed.fields.${key}.type '${field.type}' disagrees with existing model field type '${modelType}' \u2014 modelSeed is ignored on subsequent pushes`
+      );
+    }
+  }
+}
+function validateExtension(name, extension, modelsByKey, errors) {
+  const prefix = `extension '${name}'`;
+  if (!KEBAB_CASE.test(name)) {
+    errors.push(`${prefix}: name must be kebab-case (lowercase, dash-separated)`);
+  }
+  if (!extension.url || typeof extension.url !== "string") {
+    errors.push(`${prefix}: url is required`);
+  } else if (!isWellFormedHttpsUrl(extension.url)) {
+    errors.push(
+      `${prefix}: url must be a well-formed https URL, got '${extension.url}'`
+    );
+  }
+  const placements = extension.placements ?? [];
+  if (placements.length === 0) {
+    errors.push(`${prefix}: placements must declare at least one placement`);
+  }
+  placements.forEach((placement, index) => {
+    const placementPrefix = `${prefix} placements[${index}]`;
+    if (!placement.target || !KNOWN_EXTENSION_TARGETS.has(placement.target)) {
+      errors.push(
+        `${placementPrefix}: target must be one of ${[...KNOWN_EXTENSION_TARGETS].join(", ")}`
+      );
+    }
+    if (!placement.model || typeof placement.model !== "string") {
+      errors.push(`${placementPrefix}: model is required`);
+    } else if (!modelsByKey.has(placement.model)) {
+      errors.push(
+        `${placementPrefix}: missing model '${placement.model}' referenced by extension '${name}'`
+      );
+    }
+    if (!placement.tab || typeof placement.tab !== "string") {
+      errors.push(`${placementPrefix}: tab is required`);
+    }
+    if (!placement.title || typeof placement.title !== "string") {
+      errors.push(`${placementPrefix}: title is required`);
+    }
+  });
+}
+function isWellFormedHttpsUrl(candidate) {
+  try {
+    const parsed = new URL(candidate);
+    if (parsed.protocol !== "https:") return false;
+    if (!parsed.hostname) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/commands/push.ts
 var CONFIG_FILE_NAMES = [
   "foir.config.ts",
@@ -5181,6 +5398,11 @@ function registerPushCommand(program2, globalOpts) {
             'Config must have at least "key" and "name" fields.'
           );
         }
+        const validation = validateIntegrationsAndExtensions(config2);
+        for (const warning of validation.warnings) {
+          console.log(chalk6.yellow(`\u26A0 ${warning}`));
+        }
+        assertValid(validation);
         const client = await createPlatformClient(globalOpts());
         console.log(
           chalk6.dim(`Pushing config "${config2.key}" to platform...`)

package/dist/lib/config-helpers.d.ts

@@ -166,6 +166,57 @@ interface ApplyConfigApiKeyInput {
     /** Restrict file uploads to specific MIME types (e.g. ["image/*", "video/*"]). */
     allowedFileTypes?: string[];
 }
+type CredentialStrategy = 'oauth' | 'api_key' | 'shared_secret' | 'ssh_key' | 'none' | 'managed';
+interface IntegrationMiddlewareInput {
+    /** Full https URL of the middleware handling this integration. */
+    url: string;
+}
+interface IntegrationCredentialsInput {
+    strategy: CredentialStrategy;
+}
+interface ModelSeedFieldInput {
+    type: string;
+    required?: boolean;
+    naturalKey?: boolean;
+    label?: string;
+    helpText?: string;
+    config?: Record<string, unknown>;
+}
+interface ModelSeedInput {
+    fields: Record<string, ModelSeedFieldInput>;
+}
+interface IntegrationSyncMappingInput {
+    /** foir model key this source type writes into. */
+    model: string;
+    /** foir field holding the upstream natural key. UPSERTs are keyed on this. */
+    naturalKey: string;
+    /** Explicit source field -> foir field mapping. */
+    fields: Record<string, string>;
+    /** Optional one-time bootstrap schema if the target model is missing. */
+    modelSeed?: ModelSeedInput;
+}
+interface IntegrationInput {
+    enabled?: boolean;
+    middleware: IntegrationMiddlewareInput;
+    credentials: IntegrationCredentialsInput;
+    sync: Record<string, IntegrationSyncMappingInput>;
+    /** Opaque middleware-specific settings — not validated by the CLI. */
+    settings?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+type ExtensionTarget = 'record' | 'model-list';
+interface ExtensionPlacementInput {
+    target: ExtensionTarget;
+    model: string;
+    tab: string;
+    title: string;
+    hints?: Record<string, unknown>;
+}
+interface ExtensionInput {
+    url: string;
+    placements: ExtensionPlacementInput[];
+    metadata?: Record<string, unknown>;
+}
 interface ApplyConfigInput {
     key: string;
     name: string;
@@ -181,6 +232,10 @@ interface ApplyConfigInput {
     authProviders?: ApplyConfigAuthProviderInput[];
     placements?: ApplyConfigPlacementInput[];
     apiKeys?: ApplyConfigApiKeyInput[];
+    /** Per-project integration declarations, keyed by integration name. */
+    integrations?: Record<string, IntegrationInput>;
+    /** Per-project extension declarations, keyed by extension name. */
+    extensions?: Record<string, ExtensionInput>;
     [key: string]: unknown;
 }
 /** Define a complete config manifest. */
@@ -203,5 +258,9 @@ declare function defineAuthProvider(provider: ApplyConfigAuthProviderInput): App
 declare function defineHook(hook: ApplyConfigHookInput): ApplyConfigHookInput;
 /** Define an editor placement (sidebar or main-editor tab). */
 declare function definePlacement(placement: ApplyConfigPlacementInput): ApplyConfigPlacementInput;
+/** Define an integration declaration. */
+declare function defineIntegration(integration: IntegrationInput): IntegrationInput;
+/** Define an extension declaration. */
+declare function defineExtensionDeclaration(extension: ExtensionInput): ExtensionInput;
 
-export { type ApplyConfigApiKeyInput, type ApplyConfigAuthProviderInput, type ApplyConfigHookInput, type ApplyConfigInput, type ApplyConfigModelInput, type ApplyConfigOperationInput, type ApplyConfigPlacementInput, type ApplyConfigScheduleInput, type ApplyConfigSegmentInput, type ExpressionPrecondition, type FieldDefinitionInput, type Precondition, type QuotaRule, type SegmentPrecondition, defineAuthProvider, defineConfig, defineExtension, defineField, defineHook, defineModel, defineOperation, definePlacement, defineSchedule, defineSegment };
+export { type ApplyConfigApiKeyInput, type ApplyConfigAuthProviderInput, type ApplyConfigHookInput, type ApplyConfigInput, type ApplyConfigModelInput, type ApplyConfigOperationInput, type ApplyConfigPlacementInput, type ApplyConfigScheduleInput, type ApplyConfigSegmentInput, type CredentialStrategy, type ExpressionPrecondition, type ExtensionInput, type ExtensionPlacementInput, type ExtensionTarget, type FieldDefinitionInput, type IntegrationCredentialsInput, type IntegrationInput, type IntegrationMiddlewareInput, type IntegrationSyncMappingInput, type ModelSeedFieldInput, type ModelSeedInput, type Precondition, type QuotaRule, type SegmentPrecondition, defineAuthProvider, defineConfig, defineExtension, defineExtensionDeclaration, defineField, defineHook, defineIntegration, defineModel, defineOperation, definePlacement, defineSchedule, defineSegment };

package/dist/lib/config-helpers.js

@@ -27,12 +27,20 @@ function defineHook(hook) {
 function definePlacement(placement) {
   return placement;
 }
+function defineIntegration(integration) {
+  return integration;
+}
+function defineExtensionDeclaration(extension) {
+  return extension;
+}
 export {
   defineAuthProvider,
   defineConfig,
   defineExtension,
+  defineExtensionDeclaration,
   defineField,
   defineHook,
+  defineIntegration,
   defineModel,
   defineOperation,
   definePlacement,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eide/foir-cli",
-  "version": "0.4.11",
+  "version": "0.4.14",
   "description": "Universal platform CLI for Foir platform",
   "type": "module",
   "publishConfig": {