@alfe.ai/integration-manifest 0.0.11 → 0.1.0

package/dist/index.d.ts

@@ -28,6 +28,10 @@ interface ConfigSchemaField {
   select_options?: SelectOption[];
   /** OAuth provider identifier for oauth_connect fields */
   oauth_provider?: string;
+  /** Force specific scope groups for OAuth (e.g. ["chat"]) — hides other scopes in the dashboard */
+  oauth_scopes?: string[];
+  /** Integration ID to patch on OAuth callback (when using a shared OAuth provider) */
+  oauth_integration_id?: string;
   /** If true, this field is not shown in the dashboard UI (install wizard or configure modal) */
   hidden?: boolean;
   /** Only show this field if another field has a truthy value (string) or matches a specific value (object) */
@@ -45,11 +49,39 @@ interface McpServerDeclaration {
   command: string;
   /** Arguments for the command */
   args?: string[];
-  /** Environment variables — supports {{config.KEY}} interpolation from config + secrets */
+  /**
+   * Environment variables. Two interpolation syntaxes are supported:
+   *
+   * - `{{config.KEY}}` — resolved from the integration's user-supplied
+   *   config + secrets via `resolveConfig()`. Existing behavior.
+   * - `{{credentials.<provider>.<field>}}` — resolved by the
+   *   `mcp-applier` via `AgentApiClient.get<Provider>Credentials()`.
+   *   `<provider>` is the OAuth provider key (`atlassian`, `github`,
+   *   `xero`, `notion`, `myob`, …); `<field>` is a top-level key on the
+   *   credentials response (`accessToken`, `clientId`, `cloudId`, …).
+   *   Used in conjunction with `requires_credentials` to signal the
+   *   precondition.
+   */
   env?: Record<string, string>;
   /** Working directory (optional) */
   cwd?: string;
-  /** If true, applier skips auto-application — a lifecycle hook manages this MCP server instead */
+  /**
+   * OAuth provider whose credentials this server requires. When set and
+   * the credentials are missing or 404, the applier logs and skips
+   * registration silently — same graceful no-op the `post_activate.mjs`
+   * hooks do today. Pair with `{{credentials.<provider>.<field>}}` env
+   * references; the explicit field is preferred over inferring from the
+   * presence of the interpolation pattern for clarity.
+   */
+  requires_credentials?: string;
+  /**
+   * @deprecated As of 2026-05-18 the `mcp-applier` handles every case
+   * end-to-end (config + credentials interpolation, requires_credentials
+   * skip-silently, manager.addServer with owner attribution). The
+   * legacy `OpenClawApplier.applyMcpServers` path has been deleted so
+   * the field is now accepted but completely ignored on parse. Drop
+   * from new manifests.
+   */
   hook_managed?: boolean;
 }
 interface CommandDeclaration {
@@ -257,6 +289,7 @@ declare const McpServerDeclarationSchema: z.ZodObject<{
   args: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
   env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
   cwd: z.ZodOptional<z.ZodString>;
+  requires_credentials: z.ZodOptional<z.ZodString>;
   hook_managed: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strip>;
 declare const CommandDeclarationSchema: z.ZodObject<{
@@ -397,6 +430,7 @@ declare const IntegrationManifestSchema: z.ZodObject<{
     args: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     cwd: z.ZodOptional<z.ZodString>;
+    requires_credentials: z.ZodOptional<z.ZodString>;
     hook_managed: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
   }, z.core.$strip>>>>;
   repository: z.ZodOptional<z.ZodURL>;
@@ -443,6 +477,14 @@ declare function buildConfigValidationSchema(configSchema: z.infer<typeof Config
 type ManifestSchemaType = z.infer<typeof IntegrationManifestSchema>;
 //#endregion
 //#region src/parser.d.ts
+/**
+ * Pluggable warn-sink for parse-time advisories. Defaults to the
+ * Node `console.warn` so the message lands in the right place
+ * regardless of which logger the caller uses; callers that want
+ * structured logs can override.
+ */
+type ParseWarner = (message: string, meta?: Record<string, unknown>) => void;
+declare function setParseWarner(warner: ParseWarner): void;
 declare class ManifestParseError extends Error {
   readonly issues?: {
     path: string;
@@ -569,4 +611,4 @@ declare function migrateConfig(currentConfig: Record<string, unknown>, diff: Con
   warnings: string[];
 };
 //#endregion
-export { type AgentRuntime, type CommandContext, type CommandDeclaration, CommandDeclarationSchema, type CommandHandlerFn, type CommandResult, 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 McpServerDeclaration, McpServerDeclarationSchema, 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 };
+export { type AgentRuntime, type CommandContext, type CommandDeclaration, CommandDeclarationSchema, type CommandHandlerFn, type CommandResult, 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 McpServerDeclaration, McpServerDeclarationSchema, type ParseWarner, 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, setParseWarner };

package/dist/index.js

@@ -65,6 +65,7 @@ const McpServerDeclarationSchema = z.object({
 	args: z.array(z.string()).optional().default([]),
 	env: z.record(z.string(), z.string()).optional(),
 	cwd: z.string().optional(),
+	requires_credentials: z.string().min(1).optional(),
 	hook_managed: z.boolean().optional().default(false)
 });
 const CommandDeclarationSchema = z.object({
@@ -217,6 +218,13 @@ function buildConfigValidationSchema(configSchema) {
 * and validates against the Zod schema. Returns a fully typed
 * IntegrationManifest or throws a descriptive error.
 */
+let parseWarner = (msg, meta) => {
+	if (meta && Object.keys(meta).length > 0) console.warn(`[integration-manifest] ${msg}`, meta);
+	else console.warn(`[integration-manifest] ${msg}`);
+};
+function setParseWarner(warner) {
+	parseWarner = warner;
+}
 var ManifestParseError = class extends Error {
 	constructor(message, issues) {
 		super(message);
@@ -248,7 +256,22 @@ function parseManifestString(yaml, overrides) {
 		}));
 		throw new ManifestParseError(`Invalid integration manifest:\n${issues.map((i) => `  ${i.path ? `${i.path}: ` : ""}${i.message}`).join("\n")}`, issues);
 	}
-	return result.data;
+	const manifest = result.data;
+	warnDeprecatedFields(manifest);
+	return manifest;
+}
+/**
+* Emit one-time-per-parse advisories for fields that pass schema
+* validation but are deprecated. The flag is accepted-but-ignored,
+* not rejected — the warn is the only signal manifest authors get
+* since the `@deprecated` JSDoc only surfaces in TS callers' IDEs.
+*/
+function warnDeprecatedFields(manifest) {
+	const hookManagedServers = manifest.mcp_servers.filter((s) => s.hook_managed === true).map((s) => s.id);
+	if (hookManagedServers.length > 0) parseWarner(`manifest "${manifest.id}" declares mcp_servers with deprecated hook_managed:true — drop the field, the mcp-applier handles every case end-to-end now`, {
+		integration: manifest.id,
+		servers: hookManagedServers
+	});
 }
 /**
 * Read and parse an alfe-integration.yaml file from disk.
@@ -398,4 +421,4 @@ function migrateConfig(currentConfig, diff) {
 	};
 }
 //#endregion
-export { CommandDeclarationSchema, ConfigFieldTypeSchema, ConfigSchemaFieldSchema, InstallTargetsSchema, IntegrationHooksSchema, IntegrationManifestSchema, ManifestParseError, McpServerDeclarationSchema, PluginInstallSchema, RuntimeInstallSchema, SelectOptionSchema, SkillInstallSchema, buildConfigValidationSchema, diffConfigSchemas, extractTemplateReferences, interpolateConfig, isRelativePath, migrateConfig, parseManifestFile, parseManifestString, resolveAssetUrl };
+export { CommandDeclarationSchema, ConfigFieldTypeSchema, ConfigSchemaFieldSchema, InstallTargetsSchema, IntegrationHooksSchema, IntegrationManifestSchema, ManifestParseError, McpServerDeclarationSchema, PluginInstallSchema, RuntimeInstallSchema, SelectOptionSchema, SkillInstallSchema, buildConfigValidationSchema, diffConfigSchemas, extractTemplateReferences, interpolateConfig, isRelativePath, migrateConfig, parseManifestFile, parseManifestString, resolveAssetUrl, setParseWarner };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/integration-manifest",
-  "version": "0.0.11",
+  "version": "0.1.0",
   "description": "Integration manifest schema, types, and parser for Alfe integration platform",
   "type": "module",
   "main": "./dist/index.js",