@biffo/cli 0.308.2 → 0.309.0

package/_skeletons/plugin-template/registry-schema.json

@@ -330,6 +330,36 @@
       "type": "object",
       "additionalProperties": { "type": "string" },
       "description": "Python package dependencies (including biffo-plugin-sdk)."
+    },
+    "config": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "kind", "description"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$",
+            "description": "Config key, snake_case. Referenced by other manifest fields (e.g. chat_agents[].required_group) and used as the per-plugin, per-name lookup key the host resolves at runtime."
+          },
+          "kind": {
+            "enum": ["secret", "setting"],
+            "description": "'secret' — the instance supplies an SSM parameter PATH, never the credential itself. 'setting' — the instance supplies a literal value (a Cognito group name, a feature flag, a numeric limit). Never a value itself; this manifest declares only the NEED (biffo-template#1517)."
+          },
+          "required": {
+            "type": "boolean",
+            "default": true,
+            "description": "If true, `biffo plugin install` fails loudly when the instance supplies no value for this name, rather than installing an unconfigured plugin."
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "description": "What this need is for, shown to whoever installs the plugin so they know what to supply."
+          }
+        },
+        "additionalProperties": false
+      },
+      "description": "Named needs (a credential, a group name, a feature flag) this manifest declares that the INSTANCE must supply at install time — never values, only name/kind/required/description (biffo-template#1517). See ConfigDeclaration in biffo_plugin_sdk.plugin for the full mechanism."
     }
   },
   "additionalProperties": false

package/_skeletons/registry/registry-schema.json

@@ -330,6 +330,36 @@
       "type": "object",
       "additionalProperties": { "type": "string" },
       "description": "Python package dependencies (including biffo-plugin-sdk)."
+    },
+    "config": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "kind", "description"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$",
+            "description": "Config key, snake_case. Referenced by other manifest fields (e.g. chat_agents[].required_group) and used as the per-plugin, per-name lookup key the host resolves at runtime."
+          },
+          "kind": {
+            "enum": ["secret", "setting"],
+            "description": "'secret' — the instance supplies an SSM parameter PATH, never the credential itself. 'setting' — the instance supplies a literal value (a Cognito group name, a feature flag, a numeric limit). Never a value itself; this manifest declares only the NEED (biffo-template#1517)."
+          },
+          "required": {
+            "type": "boolean",
+            "default": true,
+            "description": "If true, `biffo plugin install` fails loudly when the instance supplies no value for this name, rather than installing an unconfigured plugin."
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "description": "What this need is for, shown to whoever installs the plugin so they know what to supply."
+          }
+        },
+        "additionalProperties": false
+      },
+      "description": "Named needs (a credential, a group name, a feature flag) this manifest declares that the INSTANCE must supply at install time — never values, only name/kind/required/description (biffo-template#1517). See ConfigDeclaration in biffo_plugin_sdk.plugin for the full mechanism."
     }
   },
   "additionalProperties": false

package/dist/index.js

@@ -8317,6 +8317,12 @@ var ChatAgentDeclarationSchema = z7.object({
   max_output_tokens: z7.number().int().positive().default(1024),
   timeout_seconds: z7.number().positive().default(20)
 }).strict();
+var ConfigDeclarationSchema = z7.object({
+  name: z7.string().regex(/^[a-z][a-z0-9_]*$/, "must be snake_case, e.g. image_provider_api_key"),
+  kind: z7.enum(["secret", "setting"]),
+  required: z7.boolean().default(true),
+  description: z7.string().min(1, "description is required so an installer knows what this need is for")
+}).strict();
 var PluginManifestSchema = z7.object({
   name: z7.string().regex(/^[a-z][a-z0-9-]*$/, "must be a lowercase kebab-case slug"),
   version: z7.string().regex(/^\d+\.\d+\.\d+$/, "must be a full semver, e.g. 1.2.3"),
@@ -8350,7 +8356,10 @@ var PluginManifestSchema = z7.object({
   // The plugin's tenant-scoped baseline-row seed (ADR-0005, biffo-template#1554).
   // Optional — a plugin with no baseline data omits this entirely, and
   // `biffo plugin install`/`upgrade` vendor nothing for it.
-  seed: SeedDeclarationSchema.optional()
+  seed: SeedDeclarationSchema.optional(),
+  // The needs this plugin declares the instance must supply (biffo-template#1517)
+  // — never values, only name/kind/required/description.
+  config: z7.array(ConfigDeclarationSchema).default([])
 }).superRefine((manifest, ctx) => {
   const tableNames = new Set(manifest.tables.map((t) => t.name));
   for (const route of manifest.api_routes) {
@@ -8371,6 +8380,27 @@ var PluginManifestSchema = z7.object({
       }
     }
   }
+  const configCounts = /* @__PURE__ */ new Map();
+  for (const c of manifest.config) configCounts.set(c.name, (configCounts.get(c.name) ?? 0) + 1);
+  for (const [name, count] of configCounts) {
+    if (count > 1) {
+      ctx.addIssue({
+        code: z7.ZodIssueCode.custom,
+        message: `Duplicate config declaration name '${name}'`
+      });
+    }
+  }
+  const settingNames = new Set(
+    manifest.config.filter((c) => c.kind === "setting").map((c) => c.name)
+  );
+  for (const agent of manifest.chat_agents) {
+    if (!settingNames.has(agent.required_group)) {
+      ctx.addIssue({
+        code: z7.ZodIssueCode.custom,
+        message: `chat_agents[key=${agent.key}].required_group '${agent.required_group}' must name a 'config' declaration with kind: "setting" on this same manifest \u2014 a literal Cognito group name is no longer accepted here (biffo-template#1517). Declared setting config names: ${[...settingNames].sort().join(", ") || "none"}`
+      });
+    }
+  }
 });
 function validateManifest(raw) {
   const result = PluginManifestSchema.safeParse(raw);
@@ -9046,7 +9076,7 @@ function printScopeSeamEntitlement(name) {
 }
 
 // src/commands/plugin-install.ts
-import { cpSync as cpSync5, existsSync as existsSync31, mkdirSync as mkdirSync11, readFileSync as readFileSync23, statSync as statSync7 } from "fs";
+import { cpSync as cpSync5, existsSync as existsSync31, mkdirSync as mkdirSync11, readFileSync as readFileSync23, statSync as statSync7, writeFileSync as writeFileSync12 } from "fs";
 import { join as join33, relative as relative4, resolve as resolve12 } from "path";
 import chalk15 from "chalk";
 import { Command as Command15 } from "commander";
@@ -9092,6 +9122,58 @@ var PluginMigrationsAdapter = class {
   }
 };
 
+// src/lib/plugin-config-resolution.ts
+function pluginConfigEnvNames(pluginName, configName) {
+  const prefix = `BIFFO_PLUGIN_${pluginName.toUpperCase().replace(/-/g, "_")}_${configName.toUpperCase()}`;
+  return { literalEnv: prefix, parameterEnv: `${prefix}_PARAMETER` };
+}
+function resolvePluginConfigSupply(pluginName, declarations, supplied) {
+  const resolved = [];
+  const missingRequired = [];
+  for (const decl of declarations) {
+    const raw = supplied[decl.name];
+    const value = raw?.trim();
+    if (!value) {
+      if (decl.required) {
+        missingRequired.push({ name: decl.name, kind: decl.kind, description: decl.description });
+      }
+      continue;
+    }
+    if (decl.kind === "secret" && !value.startsWith("/")) {
+      throw new Error(
+        `--config ${decl.name}=... must be an SSM parameter PATH starting with '/' for a 'secret' declaration (e.g. /myproject/dev/${pluginName}/${decl.name}) \u2014 never the credential itself. Store the credential in SSM first, then pass its parameter name here.`
+      );
+    }
+    const { literalEnv, parameterEnv } = pluginConfigEnvNames(pluginName, decl.name);
+    resolved.push({
+      name: decl.name,
+      kind: decl.kind,
+      description: decl.description,
+      value,
+      envName: decl.kind === "secret" ? parameterEnv : literalEnv
+    });
+  }
+  return { resolved, missingRequired };
+}
+function parseConfigOptionValues(entries) {
+  const record = {};
+  for (const entry of entries) {
+    const eq = entry.indexOf("=");
+    if (eq <= 0) {
+      throw new Error(`--config value '${entry}' must be of the form name=value`);
+    }
+    record[entry.slice(0, eq)] = entry.slice(eq + 1);
+  }
+  return record;
+}
+function missingRequiredConfigMessage(pluginName, missing) {
+  const lines = missing.map((m) => `  - ${m.name} (${m.kind}): ${m.description}`);
+  return `Plugin '${pluginName}' declares ${missing.length} required config value(s) with no supplied value:
+${lines.join("\n")}
+
+Supply each with --config <name>=<value> (repeatable) and re-run install. For a 'secret', pass the SSM parameter PATH holding the credential (create the parameter first, e.g. \`aws ssm put-parameter --type SecureString ...\`), never the credential itself.`;
+}
+
 // src/lib/plugin-provenance.ts
 import { existsSync as existsSync28, readFileSync as readFileSync21, writeFileSync as writeFileSync10 } from "fs";
 import { join as join29 } from "path";
@@ -9387,7 +9469,12 @@ var pluginInstallCommand = new Command15("install").description(
 ).argument("[target]", "Plugin name and minor version, e.g. rbac@1.0 (omit when using --local)").option(
   "--local <path>",
   "Install from a local, unpublished plugin directory instead of the registry"
-).option("--dry-run", "Resolve the plugin and print planned changes without modifying the repo").option("--cwd <path>", "Project root to install into (defaults to the current directory)").action(
+).option("--dry-run", "Resolve the plugin and print planned changes without modifying the repo").option("--cwd <path>", "Project root to install into (defaults to the current directory)").option(
+  "--config <name=value>",
+  "Supply an instance value for one manifest `config:` declaration (biffo-template#1517) \u2014 repeatable. For a 'secret' declaration, value must be an SSM parameter PATH, never the credential itself.",
+  (value, previous) => [...previous, value],
+  []
+).action(
   async (target, options) => {
     const cwd = options.cwd ? resolve12(options.cwd) : process.cwd();
     try {
@@ -9396,7 +9483,8 @@ var pluginInstallCommand = new Command15("install").description(
         {
           ...options.local ? { local: resolve12(options.local) } : {},
           dryRun: options.dryRun ?? false,
-          cwd
+          cwd,
+          config: parseConfigOptionValues(options.config)
         },
         {
           registry: new RegistryAdapter(),
@@ -9501,7 +9589,7 @@ async function runPluginInstall(target, options, deps) {
     );
   }
   if (options.dryRun) {
-    printDryRun4(entry, source, relTargetDir, inTreeSource);
+    printDryRun4(entry, source, relTargetDir, inTreeSource, options.config ?? {});
     return;
   }
   const isRepo = await deps.git.isGitRepo(options.cwd);
@@ -9531,6 +9619,14 @@ async function runPluginInstall(target, options, deps) {
     if (retiredShapeReasons.length > 0) {
       throw new Error(retiredFrontendShapeError(pluginName, retiredShapeReasons));
     }
+    const configSupply = resolvePluginConfigSupply(
+      pluginName,
+      manifest.config,
+      options.config ?? {}
+    );
+    if (configSupply.missingRequired.length > 0) {
+      throw new Error(missingRequiredConfigMessage(pluginName, configSupply.missingRequired));
+    }
     if (inTreeSource) {
       log.info(`${relTargetDir}/ is already in this checkout \u2014 installing in place.`);
     } else {
@@ -9589,6 +9685,31 @@ async function runPluginInstall(target, options, deps) {
     if (seedResult.vendored) {
       stagePaths.push(seedResult.stagedPath);
     }
+    if (manifest.config.length > 0) {
+      const configFilePath = join33(targetDir, "biffo.plugin-config.json");
+      writeFileSync12(
+        configFilePath,
+        JSON.stringify(
+          {
+            plugin: pluginName,
+            resolved: configSupply.resolved.map(({ name, kind, envName, value }) => ({
+              name,
+              kind,
+              env: envName,
+              // For a secret this is the SSM parameter PATH, not the credential.
+              value
+            }))
+          },
+          null,
+          2
+        ) + "\n",
+        "utf8"
+      );
+      stagePaths.push(relative4(options.cwd, configFilePath));
+      log.success(
+        `Recorded ${configSupply.resolved.length}/${manifest.config.length} declared config value(s) at ${relative4(options.cwd, configFilePath)}`
+      );
+    }
     const commitMessage = `feat(plugins): install ${pluginName}@${source.version}`;
     await deps.git.add(options.cwd, stagePaths);
     await deps.git.commit(options.cwd, commitMessage);
@@ -9599,10 +9720,28 @@ async function runPluginInstall(target, options, deps) {
     console.log(chalk15.dim(`    git push`));
     console.log(chalk15.dim(`    biffo deploy <environment> --app-only
 `));
+    printConfigWiringInstructions(pluginName, configSupply.resolved);
   } finally {
     source.cleanup();
   }
 }
+function printConfigWiringInstructions(pluginName, resolved) {
+  if (resolved.length === 0) return;
+  console.log(chalk15.bold(`  ${pluginName} needs these env vars on the shared plugin host:
+`));
+  const entries = {};
+  for (const r of resolved) entries[r.envName] = r.value;
+  console.log(chalk15.dim(`    ${JSON.stringify(entries, null, 2).split("\n").join("\n    ")}`));
+  console.log(
+    `
+  Add them to plugin_host_environment in infra/environments/<env>/plugin_host.auto.tfvars.json.`
+  );
+  if (resolved.some((r) => r.kind === "secret")) {
+    console.log(
+      "  At least one is a secret reference \u2014 grant the shared plugin host's execution role ssm:GetParameter (and kms:Decrypt if it's a SecureString on a customer-managed key) scoped to that parameter."
+    );
+  }
+}
 function parseManifestFile(path) {
   try {
     return JSON.parse(readFileSync23(path, "utf8"));
@@ -9610,7 +9749,7 @@ function parseManifestFile(path) {
     throw new Error(`Could not parse ${path} as JSON: ${err.message}`);
   }
 }
-function printDryRun4(entry, source, relTargetDir, inTreeSource) {
+function printDryRun4(entry, source, relTargetDir, inTreeSource, suppliedConfig = {}) {
   const name = entry ? entry.name : source.name;
   const version = entry ? entry.version : source.version;
   console.log(chalk15.bold("\n  Dry run \u2014 no changes will be made\n"));
@@ -9642,6 +9781,18 @@ function printDryRun4(entry, source, relTargetDir, inTreeSource) {
       `  Would vendor seed DDL into: ${pluginSeedImportDir(name)}/ (baseline_tables: ${source.manifest.seed.baseline_tables.join(", ") || "none declared"})`
     );
   }
+  if (source && source.manifest.config.length > 0) {
+    const { resolved, missingRequired } = resolvePluginConfigSupply(
+      name,
+      source.manifest.config,
+      suppliedConfig
+    );
+    console.log(`  Declares ${source.manifest.config.length} config need(s):`);
+    for (const c of source.manifest.config) {
+      const status = missingRequired.some((m) => m.name === c.name) ? "MISSING (would fail install)" : resolved.some((r) => r.name === c.name) ? "supplied" : "not supplied (optional)";
+      console.log(`    - ${c.name} (${c.kind}${c.required ? ", required" : ""}): ${status}`);
+    }
+  }
   console.log(`  Would commit:  feat(plugins): install ${name}@${version}
 `);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.308.2",
+  "version": "0.309.0",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",