@alfe.ai/integration-manifest 0.0.1

package/README.md

@@ -0,0 +1,97 @@
+# @alfe.ai/integration-manifest
+
+Type definitions, Zod validation schemas, and YAML parsing for Alfe integration manifests.
+
+## What It Does
+
+Defines the schema and types for integration manifests (`alfe-integration.yaml`) — the standard format describing what an integration provides (capabilities, config fields, install targets, hooks, marketplace metadata, etc.).
+
+Used by `services/integrations` to validate and parse integration configurations, by frontend apps to render integration setup UIs, and by the CLI for manifest validation.
+
+## Key Files
+
+```
+src/
+├── index.ts          # Public re-exports
+├── types.ts          # Manifest type definitions (IntegrationManifest, state, health reports)
+├── schema.ts         # Zod validation schemas + buildConfigValidationSchema()
+├── parser.ts         # YAML parsing and validation (parseManifestString, parseManifestFile)
+├── schema.test.ts    # Schema tests
+└── parser.test.ts    # Parser tests
+```
+
+## Example Manifest
+
+```yaml
+# alfe-integration.yaml
+id: discord
+name: Alfe Discord
+version: 1.0.0
+description: Discord bot integration for Alfe agents
+author: alfe
+license: MIT
+depends_on: []
+min_gateway_version: 1.0.0
+
+installs:
+  skills:
+    - path: skills/discord-notify
+  plugins:
+    - package: "@alfe.ai/openclaw-discord"
+
+config_schema:
+  - key: bot_token
+    type: secret
+    label: "Discord Bot Token"
+    description: "Bot token from Discord Developer Portal"
+    required: true
+  - key: guild_id
+    type: string
+    label: "Guild ID"
+    required: false
+
+capabilities:
+  - discord.send_message
+  - discord.receive_message
+
+hooks:
+  post_install: scripts/post-install.sh
+  health_check: scripts/health.sh
+```
+
+Only `id`, `name`, `version`, `description`, and `author` are required — everything else has sensible defaults.
+
+## Usage
+
+```typescript
+import {
+  type IntegrationManifest,
+  parseManifestFile,
+  parseManifestString,
+  IntegrationManifestSchema,
+  buildConfigValidationSchema,
+} from '@alfe.ai/integration-manifest';
+
+// Parse and validate a manifest file
+const manifest = parseManifestFile('./alfe-integration.yaml');
+
+// Or parse a raw YAML string
+const manifest = parseManifestString(yamlString);
+
+// Build a Zod schema from a manifest's config_schema to validate user config
+const configSchema = buildConfigValidationSchema(manifest.config_schema);
+const result = configSchema.safeParse(userProvidedConfig);
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm --filter @alfe.ai/integration-manifest build
+pnpm --filter @alfe.ai/integration-manifest test
+```
+
+## Dependencies
+
+- `yaml` — YAML parsing
+- `zod` — Schema validation

package/dist/index.d.ts

@@ -0,0 +1,453 @@
+import { z } from "zod";
+
+//#region src/types.d.ts
+
+/**
+ * TypeScript types for the Alfe integration manifest (`alfe-integration.yaml`).
+ *
+ * These are the canonical types used by all packages that interact with
+ * integration manifests -- registry, lifecycle manager, CLI, etc.
+ */
+type ConfigFieldType = 'secret' | 'string' | 'number' | 'boolean' | 'enum' | 'select' | 'multi_select' | 'oauth_connect' | 'phone_number_picker';
+interface SelectOption {
+  value: string;
+  label: string;
+}
+interface ConfigSchemaField {
+  key: string;
+  type: ConfigFieldType;
+  label: string;
+  description?: string;
+  required: boolean;
+  default?: string | number | boolean;
+  /** Who can mutate this field at runtime. Default: 'admin' */
+  editable: 'admin' | 'agent';
+  /** Only used when type === 'enum' */
+  options?: string[];
+  /** Structured options for select/multi_select fields */
+  select_options?: SelectOption[];
+  /** OAuth provider identifier for oauth_connect fields */
+  oauth_provider?: string;
+  /** Only show this field if another field has a truthy value (string) or matches a specific value (object) */
+  depends_on_field?: string | {
+    key: string;
+    value: string | number | boolean;
+  };
+  /** Only show this field if a specific integration is installed */
+  depends_on_integration?: string;
+}
+interface SkillInstall {
+  /** Relative path within the integration repo to the skill directory */
+  path: string;
+}
+interface PluginInstall {
+  /** npm package name to install */
+  package: string;
+}
+type AgentRuntime = 'openclaw' | 'nanoclaw' | (string & {});
+interface RuntimeInstall {
+  plugins?: PluginInstall[];
+  skills?: SkillInstall[];
+  /** Deep-merged into the runtime's agent config on activation */
+  config?: Record<string, unknown>;
+}
+interface InstallTargets {
+  /** Universal skills — applied to all runtimes */
+  skills?: SkillInstall[];
+  /** Universal plugins — applied to all runtimes */
+  plugins?: PluginInstall[];
+  /** Per-runtime installs */
+  runtimes?: Record<AgentRuntime, RuntimeInstall>;
+}
+interface IntegrationHooks {
+  pre_install?: string;
+  post_install?: string;
+  pre_uninstall?: string;
+  post_uninstall?: string;
+  health_check?: string;
+}
+interface IntegrationPricingPlan {
+  name: string;
+  price: number;
+  currency?: string;
+  interval?: 'month' | 'year';
+}
+interface IntegrationPricing {
+  type: 'free' | 'paid';
+  /** Single price (shorthand for integrations with one plan) */
+  price?: number;
+  currency?: string;
+  interval?: 'month' | 'year';
+  /** Multiple plans/tiers (e.g., starter, growth, scale) */
+  plans?: Record<string, IntegrationPricingPlan>;
+}
+interface IntegrationAuthor {
+  name: string;
+  url?: string;
+}
+interface IntegrationManifest {
+  id: string;
+  name: string;
+  version: string;
+  description: string;
+  /** Simple author string (legacy) or structured author object */
+  author: string | IntegrationAuthor;
+  license: string;
+  depends_on: string[];
+  min_gateway_version: string;
+  installs: InstallTargets;
+  config_schema: ConfigSchemaField[];
+  capabilities: string[];
+  hooks: IntegrationHooks;
+  /**
+   * Agent runtimes this integration supports.
+   * If omitted or empty, the integration is considered universal (all runtimes).
+   * Example: ['openclaw'] means this integration only works with OpenClaw.
+   */
+  supported_agents?: AgentRuntime[];
+  /** Marketplace metadata */
+  publisherId?: string;
+  icon?: string;
+  pricing?: IntegrationPricing;
+  preview_images?: string[];
+  /** Long-form features list for the detail view */
+  features?: string[];
+}
+interface PublishedVersion {
+  version: string;
+  commit_hash: string;
+  changelog?: string;
+  published_at: string;
+}
+interface PublishedIntegration {
+  manifest: IntegrationManifest;
+  versions: PublishedVersion[];
+  /** Resolved asset URLs baked at publish time */
+  resolved_assets: {
+    icon?: string;
+    preview_images?: string[];
+  };
+}
+type IntegrationStatus = 'installing' | 'installed' | 'configured' | 'active' | 'error';
+interface IntegrationStateEntry {
+  status: IntegrationStatus;
+  version: string;
+  installedAt: string;
+  config: Record<string, unknown>;
+  error?: string;
+}
+interface IntegrationsStateFile {
+  version: number;
+  integrations: Record<string, IntegrationStateEntry>;
+}
+interface HealthCheckResult {
+  id: string;
+  name?: string;
+  healthy: boolean;
+  status: IntegrationStatus;
+  version?: string;
+  message?: string;
+  stdout?: string;
+  stderr?: string;
+}
+interface HealthReport {
+  overall: boolean;
+  results: HealthCheckResult[];
+  checkedAt: string;
+}
+//#endregion
+//#region src/schema.d.ts
+declare const ConfigFieldTypeSchema: z.ZodEnum<{
+  string: "string";
+  number: "number";
+  boolean: "boolean";
+  secret: "secret";
+  enum: "enum";
+  select: "select";
+  multi_select: "multi_select";
+  oauth_connect: "oauth_connect";
+  phone_number_picker: "phone_number_picker";
+}>;
+/** Structured option for select/multi_select fields */
+declare const SelectOptionSchema: z.ZodObject<{
+  value: z.ZodString;
+  label: z.ZodString;
+}, z.core.$strip>;
+declare const ConfigSchemaFieldSchema: z.ZodObject<{
+  key: z.ZodString;
+  type: z.ZodEnum<{
+    string: "string";
+    number: "number";
+    boolean: "boolean";
+    secret: "secret";
+    enum: "enum";
+    select: "select";
+    multi_select: "multi_select";
+    oauth_connect: "oauth_connect";
+    phone_number_picker: "phone_number_picker";
+  }>;
+  label: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  required: z.ZodDefault<z.ZodBoolean>;
+  default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+  editable: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+    admin: "admin";
+    agent: "agent";
+  }>>>;
+  options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  select_options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+  }, z.core.$strip>>>;
+  oauth_provider: z.ZodOptional<z.ZodString>;
+  depends_on_field: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    key: z.ZodString;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+  }, z.core.$strip>]>>;
+  depends_on_integration: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const SkillInstallSchema: z.ZodObject<{
+  path: z.ZodString;
+}, z.core.$strip>;
+declare const PluginInstallSchema: z.ZodObject<{
+  package: z.ZodString;
+}, z.core.$strip>;
+/** Per-runtime install overrides */
+declare const RuntimeInstallSchema: z.ZodObject<{
+  skills: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+    path: z.ZodString;
+  }, z.core.$strip>>>>;
+  plugins: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+    package: z.ZodString;
+  }, z.core.$strip>>>>;
+  config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const InstallTargetsSchema: z.ZodObject<{
+  skills: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+    path: z.ZodString;
+  }, z.core.$strip>>>>;
+  plugins: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+    package: z.ZodString;
+  }, z.core.$strip>>>>;
+  runtimes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+    skills: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+      path: z.ZodString;
+    }, z.core.$strip>>>>;
+    plugins: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+      package: z.ZodString;
+    }, z.core.$strip>>>>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>>>;
+}, z.core.$strip>;
+declare const IntegrationHooksSchema: z.ZodObject<{
+  pre_install: z.ZodOptional<z.ZodString>;
+  post_install: z.ZodOptional<z.ZodString>;
+  pre_uninstall: z.ZodOptional<z.ZodString>;
+  post_uninstall: z.ZodOptional<z.ZodString>;
+  health_check: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const IntegrationManifestSchema: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  version: z.ZodString;
+  description: z.ZodString;
+  author: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    name: z.ZodString;
+    url: z.ZodOptional<z.ZodURL>;
+  }, z.core.$strip>]>;
+  license: z.ZodDefault<z.ZodString>;
+  depends_on: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+  min_gateway_version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+  installs: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+    skills: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+      path: z.ZodString;
+    }, z.core.$strip>>>>;
+    plugins: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+      package: z.ZodString;
+    }, z.core.$strip>>>>;
+    runtimes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+      skills: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+      }, z.core.$strip>>>>;
+      plugins: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        package: z.ZodString;
+      }, z.core.$strip>>>>;
+      config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+  }, z.core.$strip>>>;
+  config_schema: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodEnum<{
+      string: "string";
+      number: "number";
+      boolean: "boolean";
+      secret: "secret";
+      enum: "enum";
+      select: "select";
+      multi_select: "multi_select";
+      oauth_connect: "oauth_connect";
+      phone_number_picker: "phone_number_picker";
+    }>;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    editable: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+      admin: "admin";
+      agent: "agent";
+    }>>>;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    select_options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      value: z.ZodString;
+      label: z.ZodString;
+    }, z.core.$strip>>>;
+    oauth_provider: z.ZodOptional<z.ZodString>;
+    depends_on_field: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+      key: z.ZodString;
+      value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, z.core.$strip>]>>;
+    depends_on_integration: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>>;
+  capabilities: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+  hooks: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+    pre_install: z.ZodOptional<z.ZodString>;
+    post_install: z.ZodOptional<z.ZodString>;
+    pre_uninstall: z.ZodOptional<z.ZodString>;
+    post_uninstall: z.ZodOptional<z.ZodString>;
+    health_check: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  supported_agents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  publisherId: z.ZodOptional<z.ZodString>;
+  icon: z.ZodOptional<z.ZodString>;
+  pricing: z.ZodOptional<z.ZodObject<{
+    type: z.ZodEnum<{
+      free: "free";
+      paid: "paid";
+    }>;
+    price: z.ZodOptional<z.ZodNumber>;
+    currency: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    interval: z.ZodOptional<z.ZodEnum<{
+      month: "month";
+      year: "year";
+    }>>;
+    plans: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+      name: z.ZodString;
+      price: z.ZodNumber;
+      currency: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+      interval: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        month: "month";
+        year: "year";
+      }>>>;
+    }, z.core.$strip>>>;
+  }, z.core.$strip>>;
+  preview_images: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  features: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Validate user-provided config values against a manifest's config_schema.
+ * Returns a Zod schema dynamically built from the manifest's config_schema.
+ */
+declare function buildConfigValidationSchema(configSchema: z.infer<typeof ConfigSchemaFieldSchema>[]): z.ZodObject<Record<string, z.ZodType>>;
+type ManifestSchemaType = z.infer<typeof IntegrationManifestSchema>;
+//#endregion
+//#region src/parser.d.ts
+declare class ManifestParseError extends Error {
+  readonly issues?: {
+    path: string;
+    message: string;
+  }[] | undefined;
+  constructor(message: string, issues?: {
+    path: string;
+    message: string;
+  }[] | undefined);
+}
+/**
+ * Parse a raw YAML string into a validated IntegrationManifest.
+ */
+declare function parseManifestString(yaml: string): IntegrationManifest;
+/**
+ * Read and parse an alfe-integration.yaml file from disk.
+ */
+declare function parseManifestFile(filePath: string): IntegrationManifest;
+//#endregion
+//#region src/assets.d.ts
+/**
+ * Asset URL resolution for integration manifests.
+ *
+ * At publish time, relative asset paths (icons, preview images) are resolved
+ * to absolute raw GitHub content URLs. Already-absolute URLs pass through unchanged.
+ */
+/**
+ * Check whether a path is relative (not a fully qualified URL).
+ */
+declare function isRelativePath(path: string): boolean;
+/**
+ * Resolve a relative asset path to a raw GitHub content URL.
+ * Absolute URLs are returned unchanged.
+ *
+ * @param assetPath - The path from the manifest (e.g. "./assets/icon.png")
+ * @param repoUrl - GitHub repo URL (e.g. "https://github.com/org/repo")
+ * @param commitHash - The commit hash to pin the URL to
+ * @param subdir - Subdirectory within the repo where the manifest lives (e.g. "integrations/voice")
+ */
+declare function resolveAssetUrl(assetPath: string, repoUrl: string, commitHash: string, subdir: string): string;
+//#endregion
+//#region src/interpolation.d.ts
+/**
+ * Variable interpolation engine for integration configs.
+ *
+ * Supports templates like `{{integration.slack.oauth_token}}` that reference
+ * config values from other installed integrations.
+ *
+ * - Single-pass replacement (no recursive resolution — prevents circular refs)
+ * - Unresolved templates are left as-is (graceful degradation)
+ */
+interface InterpolationContext {
+  /** Map of integrationId → config key-value pairs */
+  integrations: Partial<Record<string, Record<string, unknown>>>;
+}
+/**
+ * Interpolate template variables in a config object.
+ * Only string values are interpolated; other types pass through unchanged.
+ */
+declare function interpolateConfig(config: Record<string, unknown>, ctx: InterpolationContext): Record<string, unknown>;
+/**
+ * Extract all template references from a config object.
+ * Useful for dependency analysis and validation.
+ */
+declare function extractTemplateReferences(config: Record<string, unknown>): {
+  integrationId: string;
+  field: string;
+}[];
+//#endregion
+//#region src/migration.d.ts
+interface ConfigSchemaDiff {
+  added: ConfigSchemaField[];
+  removed: ConfigSchemaField[];
+  changed: {
+    field: string;
+    oldSchema: ConfigSchemaField;
+    newSchema: ConfigSchemaField;
+    /** True when the type changed (existing value likely invalid) */
+    breaking: boolean;
+  }[];
+  unchanged: ConfigSchemaField[];
+}
+/**
+ * Diff two config schemas to determine what changed between versions.
+ */
+declare function diffConfigSchemas(oldSchema: ConfigSchemaField[], newSchema: ConfigSchemaField[]): ConfigSchemaDiff;
+/**
+ * Migrate existing config values forward based on a schema diff.
+ *
+ * - Carries forward values for unchanged and non-breaking changed fields
+ * - Applies defaults for new fields when available
+ * - Drops removed fields
+ * - Generates warnings for new required fields without defaults and breaking changes
+ */
+declare function migrateConfig(currentConfig: Record<string, unknown>, diff: ConfigSchemaDiff): {
+  config: Record<string, unknown>;
+  warnings: string[];
+};
+//#endregion
+export { type AgentRuntime, type ConfigFieldType, ConfigFieldTypeSchema, type ConfigSchemaDiff, type ConfigSchemaField, ConfigSchemaFieldSchema, type HealthCheckResult, type HealthReport, type InstallTargets, InstallTargetsSchema, type IntegrationHooks, IntegrationHooksSchema, type IntegrationManifest, IntegrationManifestSchema, type IntegrationPricing, type IntegrationPricingPlan, type IntegrationStateEntry, type IntegrationStatus, type IntegrationsStateFile, type InterpolationContext, ManifestParseError, type ManifestSchemaType, type PluginInstall, PluginInstallSchema, type PublishedIntegration, type PublishedVersion, type RuntimeInstall, RuntimeInstallSchema, type SelectOption, SelectOptionSchema, type SkillInstall, SkillInstallSchema, buildConfigValidationSchema, diffConfigSchemas, extractTemplateReferences, interpolateConfig, isRelativePath, migrateConfig, parseManifestFile, parseManifestString, resolveAssetUrl };

package/dist/index.js

@@ -0,0 +1,366 @@
+import { z } from "zod";
+import { readFileSync } from "node:fs";
+import { parse } from "yaml";
+//#region src/schema.ts
+/**
+* Zod validation schema for the Alfe integration manifest.
+*
+* Validates the parsed YAML structure against the expected format.
+* Used by the parser and by the lifecycle manager to ensure manifest
+* correctness before installation.
+*/
+const ConfigFieldTypeSchema = z.enum([
+	"secret",
+	"string",
+	"number",
+	"boolean",
+	"enum",
+	"select",
+	"multi_select",
+	"oauth_connect",
+	"phone_number_picker"
+]);
+/** Structured option for select/multi_select fields */
+const SelectOptionSchema = z.object({
+	value: z.string().min(1),
+	label: z.string().min(1)
+});
+const ConfigSchemaFieldSchema = z.object({
+	key: z.string().min(1, "Config key must not be empty"),
+	type: ConfigFieldTypeSchema,
+	label: z.string().min(1, "Config label must not be empty"),
+	description: z.string().optional(),
+	required: z.boolean().default(false),
+	default: z.union([
+		z.string(),
+		z.number(),
+		z.boolean()
+	]).optional(),
+	editable: z.enum(["admin", "agent"]).optional().default("admin"),
+	options: z.array(z.string()).optional(),
+	select_options: z.array(SelectOptionSchema).optional(),
+	oauth_provider: z.string().optional(),
+	depends_on_field: z.union([z.string(), z.object({
+		key: z.string().min(1),
+		value: z.union([
+			z.string(),
+			z.number(),
+			z.boolean()
+		])
+	})]).optional(),
+	depends_on_integration: z.string().optional()
+}).refine((field) => {
+	if (field.type === "enum") return field.options !== void 0 && field.options.length > 0;
+	return true;
+}, { message: "Enum fields must have at least one option" }).refine((field) => {
+	if (field.type === "select" || field.type === "multi_select") return field.select_options !== void 0 && field.select_options.length > 0;
+	return true;
+}, { message: "Select/multi_select fields must have at least one option in select_options" }).refine((field) => {
+	if (field.type === "oauth_connect") return field.oauth_provider !== void 0 && field.oauth_provider.length > 0;
+	return true;
+}, { message: "oauth_connect fields must specify an oauth_provider" });
+const SkillInstallSchema = z.object({ path: z.string().min(1, "Skill path must not be empty") });
+const PluginInstallSchema = z.object({ package: z.string().min(1, "Plugin package name must not be empty") });
+/** Per-runtime install overrides */
+const RuntimeInstallSchema = z.object({
+	skills: z.array(SkillInstallSchema).optional().default([]),
+	plugins: z.array(PluginInstallSchema).optional().default([]),
+	config: z.record(z.string(), z.unknown()).optional()
+});
+/** Runtime key: lowercase alphanumeric + hyphens */
+const RuntimeKeySchema = z.string().regex(/^[a-z0-9][a-z0-9-]*$/, "Runtime key must be lowercase alphanumeric with hyphens");
+const InstallTargetsSchema = z.object({
+	skills: z.array(SkillInstallSchema).optional().default([]),
+	plugins: z.array(PluginInstallSchema).optional().default([]),
+	runtimes: z.record(RuntimeKeySchema, RuntimeInstallSchema).optional()
+});
+const IntegrationHooksSchema = z.object({
+	pre_install: z.string().optional(),
+	post_install: z.string().optional(),
+	pre_uninstall: z.string().optional(),
+	post_uninstall: z.string().optional(),
+	health_check: z.string().optional()
+});
+const IntegrationPricingPlanSchema = z.object({
+	name: z.string().min(1),
+	price: z.number().positive(),
+	currency: z.string().length(3).optional().default("USD"),
+	interval: z.enum(["month", "year"]).optional().default("month")
+});
+const IntegrationPricingSchema = z.object({
+	type: z.enum(["free", "paid"]),
+	price: z.number().positive().optional(),
+	currency: z.string().length(3).optional().default("USD"),
+	interval: z.enum(["month", "year"]).optional(),
+	plans: z.record(z.string(), IntegrationPricingPlanSchema).optional()
+}).refine((pricing) => {
+	if (pricing.type === "paid") {
+		const hasSinglePrice = pricing.price !== void 0 && pricing.price > 0;
+		const hasPlans = pricing.plans !== void 0 && Object.keys(pricing.plans).length > 0;
+		return hasSinglePrice || hasPlans;
+	}
+	return true;
+}, { message: "Paid integrations must have a positive price or at least one plan" });
+const IntegrationAuthorSchema = z.union([z.string().min(1, "Author must not be empty"), z.object({
+	name: z.string().min(1, "Author name must not be empty"),
+	url: z.url().optional()
+})]);
+const SemverSchema = z.string().regex(/^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/, "Must be a valid semver version (e.g. 1.0.0)");
+const IntegrationManifestSchema = z.object({
+	id: z.string().min(1, "Integration id must not be empty").regex(/^[a-z0-9][a-z0-9-]*$/, "id must be lowercase alphanumeric with hyphens"),
+	name: z.string().min(1, "Integration name must not be empty"),
+	version: SemverSchema,
+	description: z.string().min(1, "Description must not be empty"),
+	author: IntegrationAuthorSchema,
+	license: z.string().default("MIT"),
+	depends_on: z.array(z.string()).optional().default([]),
+	min_gateway_version: SemverSchema.optional().default("0.1.0"),
+	installs: InstallTargetsSchema.optional().default({
+		skills: [],
+		plugins: []
+	}),
+	config_schema: z.array(ConfigSchemaFieldSchema).optional().default([]),
+	capabilities: z.array(z.string()).optional().default([]),
+	hooks: IntegrationHooksSchema.optional().default({}),
+	supported_agents: z.array(RuntimeKeySchema).optional(),
+	publisherId: z.string().optional(),
+	icon: z.string().optional(),
+	pricing: IntegrationPricingSchema.optional(),
+	preview_images: z.array(z.string()).optional(),
+	features: z.array(z.string()).optional()
+});
+/**
+* Validate user-provided config values against a manifest's config_schema.
+* Returns a Zod schema dynamically built from the manifest's config_schema.
+*/
+function buildConfigValidationSchema(configSchema) {
+	const shape = {};
+	for (const field of configSchema) {
+		let fieldSchema;
+		switch (field.type) {
+			case "secret":
+			case "string":
+				fieldSchema = z.string();
+				break;
+			case "enum":
+				fieldSchema = z.string();
+				if (field.options) fieldSchema = z.enum(field.options);
+				break;
+			case "select":
+				fieldSchema = z.string();
+				if (field.select_options) {
+					const values = field.select_options.map((o) => o.value);
+					fieldSchema = z.enum(values);
+				}
+				break;
+			case "multi_select":
+				if (field.select_options) {
+					const values = field.select_options.map((o) => o.value);
+					fieldSchema = z.array(z.enum(values));
+				} else fieldSchema = z.array(z.string());
+				break;
+			case "oauth_connect":
+				fieldSchema = z.string();
+				break;
+			case "phone_number_picker":
+				fieldSchema = z.string();
+				break;
+			case "number":
+				fieldSchema = z.number();
+				break;
+			case "boolean":
+				fieldSchema = z.boolean();
+				break;
+			default: fieldSchema = z.unknown();
+		}
+		if (!field.required) fieldSchema = fieldSchema.optional();
+		shape[field.key] = fieldSchema;
+	}
+	return z.object(shape);
+}
+//#endregion
+//#region src/parser.ts
+/**
+* YAML parser for Alfe integration manifests.
+*
+* Reads an alfe-integration.yaml file or raw YAML string, parses it,
+* and validates against the Zod schema. Returns a fully typed
+* IntegrationManifest or throws a descriptive error.
+*/
+var ManifestParseError = class extends Error {
+	constructor(message, issues) {
+		super(message);
+		this.issues = issues;
+		this.name = "ManifestParseError";
+	}
+};
+/**
+* Parse a raw YAML string into a validated IntegrationManifest.
+*/
+function parseManifestString(yaml) {
+	let raw;
+	try {
+		raw = parse(yaml);
+	} catch (err) {
+		throw new ManifestParseError(`Invalid YAML: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (typeof raw !== "object" || raw === null) throw new ManifestParseError("Manifest must be a YAML object");
+	const result = IntegrationManifestSchema.safeParse(raw);
+	if (!result.success) {
+		const issues = result.error.issues.map((i) => ({
+			path: i.path.join("."),
+			message: i.message
+		}));
+		throw new ManifestParseError(`Invalid integration manifest:\n${issues.map((i) => `  ${i.path ? `${i.path}: ` : ""}${i.message}`).join("\n")}`, issues);
+	}
+	return result.data;
+}
+/**
+* Read and parse an alfe-integration.yaml file from disk.
+*/
+function parseManifestFile(filePath) {
+	let content;
+	try {
+		content = readFileSync(filePath, "utf-8");
+	} catch (err) {
+		throw new ManifestParseError(`Failed to read manifest file: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	return parseManifestString(content);
+}
+//#endregion
+//#region src/assets.ts
+/**
+* Asset URL resolution for integration manifests.
+*
+* At publish time, relative asset paths (icons, preview images) are resolved
+* to absolute raw GitHub content URLs. Already-absolute URLs pass through unchanged.
+*/
+/**
+* Check whether a path is relative (not a fully qualified URL).
+*/
+function isRelativePath(path) {
+	try {
+		new URL(path);
+		return false;
+	} catch {
+		return true;
+	}
+}
+/**
+* Resolve a relative asset path to a raw GitHub content URL.
+* Absolute URLs are returned unchanged.
+*
+* @param assetPath - The path from the manifest (e.g. "./assets/icon.png")
+* @param repoUrl - GitHub repo URL (e.g. "https://github.com/org/repo")
+* @param commitHash - The commit hash to pin the URL to
+* @param subdir - Subdirectory within the repo where the manifest lives (e.g. "integrations/voice")
+*/
+function resolveAssetUrl(assetPath, repoUrl, commitHash, subdir) {
+	if (!isRelativePath(assetPath)) return assetPath;
+	const repoMatch = /^https?:\/\/github\.com\/([^/]+)\/([^/]+)/.exec(repoUrl);
+	if (!repoMatch) return assetPath;
+	const [, owner, repo] = repoMatch;
+	const normalizedPath = assetPath.replace(/^\.\//, "");
+	return `https://raw.githubusercontent.com/${owner}/${repo}/${commitHash}/${subdir ? `${subdir.replace(/\/$/, "")}/${normalizedPath}` : normalizedPath}`;
+}
+//#endregion
+//#region src/interpolation.ts
+/**
+* Variable interpolation engine for integration configs.
+*
+* Supports templates like `{{integration.slack.oauth_token}}` that reference
+* config values from other installed integrations.
+*
+* - Single-pass replacement (no recursive resolution — prevents circular refs)
+* - Unresolved templates are left as-is (graceful degradation)
+*/
+const TEMPLATE_RE = /\{\{integration\.([a-z0-9-]+)\.([a-z0-9_]+)\}\}/g;
+/**
+* Interpolate template variables in a config object.
+* Only string values are interpolated; other types pass through unchanged.
+*/
+function interpolateConfig(config, ctx) {
+	const result = {};
+	for (const [key, value] of Object.entries(config)) if (typeof value === "string") result[key] = value.replace(TEMPLATE_RE, (_match, integrationId, field) => {
+		const integrationConfig = ctx.integrations[integrationId];
+		if (!integrationConfig) return _match;
+		const resolved = integrationConfig[field];
+		if (resolved == null) return _match;
+		return typeof resolved === "string" ? resolved : JSON.stringify(resolved);
+	});
+	else result[key] = value;
+	return result;
+}
+/**
+* Extract all template references from a config object.
+* Useful for dependency analysis and validation.
+*/
+function extractTemplateReferences(config) {
+	const refs = [];
+	for (const value of Object.values(config)) {
+		if (typeof value !== "string") continue;
+		let match;
+		const re = new RegExp(TEMPLATE_RE.source, TEMPLATE_RE.flags);
+		while ((match = re.exec(value)) !== null) refs.push({
+			integrationId: match[1],
+			field: match[2]
+		});
+	}
+	return refs;
+}
+//#endregion
+//#region src/migration.ts
+/**
+* Diff two config schemas to determine what changed between versions.
+*/
+function diffConfigSchemas(oldSchema, newSchema) {
+	const oldMap = new Map(oldSchema.map((f) => [f.key, f]));
+	const newMap = new Map(newSchema.map((f) => [f.key, f]));
+	const added = [];
+	const removed = [];
+	const changed = [];
+	const unchanged = [];
+	for (const [key, newField] of newMap) {
+		const oldField = oldMap.get(key);
+		if (!oldField) added.push(newField);
+		else if (JSON.stringify(oldField) === JSON.stringify(newField)) unchanged.push(newField);
+		else changed.push({
+			field: key,
+			oldSchema: oldField,
+			newSchema: newField,
+			breaking: oldField.type !== newField.type
+		});
+	}
+	for (const [key, oldField] of oldMap) if (!newMap.has(key)) removed.push(oldField);
+	return {
+		added,
+		removed,
+		changed,
+		unchanged
+	};
+}
+/**
+* Migrate existing config values forward based on a schema diff.
+*
+* - Carries forward values for unchanged and non-breaking changed fields
+* - Applies defaults for new fields when available
+* - Drops removed fields
+* - Generates warnings for new required fields without defaults and breaking changes
+*/
+function migrateConfig(currentConfig, diff) {
+	const config = {};
+	const warnings = [];
+	for (const field of diff.unchanged) if (field.key in currentConfig) config[field.key] = currentConfig[field.key];
+	for (const change of diff.changed) if (change.breaking) {
+		if (change.newSchema.default !== void 0) config[change.field] = change.newSchema.default;
+		warnings.push(`Field "${change.field}" type changed from "${change.oldSchema.type}" to "${change.newSchema.type}" — value reset`);
+	} else if (change.field in currentConfig) config[change.field] = currentConfig[change.field];
+	for (const field of diff.added) if (field.default !== void 0) config[field.key] = field.default;
+	else if (field.required) warnings.push(`New required field "${field.key}" has no default — user input needed`);
+	return {
+		config,
+		warnings
+	};
+}
+//#endregion
+export { ConfigFieldTypeSchema, ConfigSchemaFieldSchema, InstallTargetsSchema, IntegrationHooksSchema, IntegrationManifestSchema, ManifestParseError, PluginInstallSchema, RuntimeInstallSchema, SelectOptionSchema, SkillInstallSchema, buildConfigValidationSchema, diffConfigSchemas, extractTemplateReferences, interpolateConfig, isRelativePath, migrateConfig, parseManifestFile, parseManifestString, resolveAssetUrl };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@alfe.ai/integration-manifest",
+  "version": "0.0.1",
+  "description": "Integration manifest schema, types, and parser for Alfe integration platform",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "yaml": "^2.7.0",
+    "zod": "^4.0.5"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  }
+}