@biffo/cli 0.308.2 → 0.309.1

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

@@ -630,6 +630,7 @@ import { Command as Command3 } from "commander";
 // src/adapters/git/index.ts
 import { randomUUID } from "crypto";
 import { existsSync as existsSync6, mkdtempSync as mkdtempSync2, rmSync as rmSync2 } from "fs";
+import { readFile as readFile2, rm } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
 import { join as join6 } from "path";
 
@@ -1237,6 +1238,51 @@ var GitAdapter = class {
   async hasFleetWorktreeClaim(worktreePath) {
     return existsSync6(join6(worktreePath, ".fleet-worktree-claim"));
   }
+  /**
+   * Milliseconds since `worktreePath`'s `.fleet-worktree-claim` lock was
+   * written (biffo-template#1948), or `null` when there is no lock, or its
+   * `holder` file cannot be read and parsed.
+   *
+   * `bin/fleet.sh worktree-claim` (biffo-fleet) writes the holder token on
+   * line 1 and a UTC ISO-8601 timestamp (`now()`, i.e. `date -u
+   * +%Y-%m-%dT%H:%M:%SZ`) on line 2 — this reads that second line and diffs
+   * it against the current time. `null` is the fail-closed default for
+   * "cannot tell": `doctor-reaper.ts` treats it exactly like a live claim,
+   * never like a stale one, the same posture `hasFleetWorktreeClaim` already
+   * takes and fleet.sh's own comment on an unwritten holder file takes ("An
+   * unwritten holder is still a HELD lock").
+   */
+  async fleetWorktreeClaimAgeMs(worktreePath) {
+    try {
+      const raw = await readFile2(join6(worktreePath, ".fleet-worktree-claim", "holder"), "utf8");
+      const claimedAt = raw.split("\n")[1]?.trim();
+      if (!claimedAt) return null;
+      const claimedMs = Date.parse(claimedAt);
+      return Number.isNaN(claimedMs) ? null : Date.now() - claimedMs;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Removes a `.fleet-worktree-claim` lock directory outright (biffo-template#1948).
+   *
+   * Used only once `doctor --fix` has independently judged the lock stale —
+   * see `FLEET_CLAIM_STALE_AFTER_MS` in `lib/doctor-reaper.ts`. Needed because
+   * the lock directory is untracked: leaving it in place after deciding to
+   * disregard it would trip `hasUncommittedChanges`'s `git status
+   * --porcelain` and keep the worktree anyway, under the less specific
+   * `uncommitted-changes` reason, defeating the point of ignoring it.
+   *
+   * Best-effort — swallows any error, so a permissions problem or a
+   * concurrent release falls back to the existing `isDirty` keep path rather
+   * than crashing the whole `--fix` sweep.
+   */
+  async clearStaleFleetWorktreeClaim(worktreePath) {
+    try {
+      await rm(join6(worktreePath, ".fleet-worktree-claim"), { recursive: true, force: true });
+    } catch {
+    }
+  }
   /** Best-effort fetch of the tracking remote, so the ahead/behind check below
    * compares against reality rather than a stale local ref (#394). Never throws:
    * offline or a missing remote must not block an upgrade on its own — the
@@ -8317,6 +8363,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 +8402,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 +8426,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 +9122,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 +9168,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 +9515,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 +9529,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 +9635,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 +9665,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 +9731,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 +9766,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 +9795,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 +9827,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}
 `);
 }
@@ -16081,6 +16278,7 @@ function runDoctorChecks(facts) {
 }
 
 // src/lib/doctor-reaper.ts
+var FLEET_CLAIM_STALE_AFTER_MS = 4 * 60 * 60 * 1e3;
 function classifyReapCandidate(facts) {
   if (facts.hasFleetClaim) return { action: "keep", reason: "fleet-worktree-claimed" };
   if (facts.isDetached) return { action: "keep", reason: "detached-head" };
@@ -16108,12 +16306,23 @@ function findReapCandidates(branches, worktrees) {
 }
 async function reapCandidate(cwd, candidate, deps) {
   const { git, github } = deps;
-  const [current, isDirty, hasFleetClaim] = await Promise.all([
+  const [current, claimExists] = await Promise.all([
     git.currentBranch(candidate.worktreePath),
-    git.hasUncommittedChanges(candidate.worktreePath),
     git.hasFleetWorktreeClaim(candidate.worktreePath)
   ]);
   const isDetached = current === "HEAD" || current === "";
+  let hasFleetClaim = false;
+  let staleClaimCleared = false;
+  if (claimExists) {
+    const ageMs = await git.fleetWorktreeClaimAgeMs(candidate.worktreePath);
+    if (ageMs === null || ageMs < FLEET_CLAIM_STALE_AFTER_MS) {
+      hasFleetClaim = true;
+    } else {
+      await git.clearStaleFleetWorktreeClaim(candidate.worktreePath);
+      staleClaimCleared = true;
+    }
+  }
+  const isDirty = await git.hasUncommittedChanges(candidate.worktreePath);
   const prVerdict = isDetached || isDirty || hasFleetClaim ? "unknown" : await github.prVerdictForBranch(cwd, candidate.branch);
   let mergeContainsHead = true;
   if (prVerdict === "merged") {
@@ -16131,10 +16340,10 @@ async function reapCandidate(cwd, candidate, deps) {
     mergeContainsHead
   });
   if (verdict.action === "keep") {
-    return { candidate, verdict, worktreeRemoved: null };
+    return { candidate, verdict, worktreeRemoved: null, staleClaimCleared };
   }
   const worktreeRemoved = await git.removeWorktree(cwd, candidate.worktreePath);
-  return { candidate, verdict, worktreeRemoved };
+  return { candidate, verdict, worktreeRemoved, staleClaimCleared };
 }
 async function reapAll(cwd, branches, worktrees, currentBranch, deps) {
   const candidates = findReapCandidates(branches, worktrees).filter(
@@ -16335,28 +16544,36 @@ function printReapOutcomes(outcomes) {
   const kept = outcomes.filter((o) => o.verdict.action === "keep");
   const removed = attempted.filter((o) => o.worktreeRemoved === true);
   const failed = attempted.filter((o) => o.worktreeRemoved !== true);
+  const staleClaims = outcomes.filter((o) => o.staleClaimCleared);
   console.log("");
   for (const o of attempted) {
+    const staleNote = o.staleClaimCleared ? " (after clearing a stale fleet-worktree-claim lock)" : "";
     if (o.worktreeRemoved === true) {
-      console.log(chalk21.green(`  removed  ${o.candidate.worktreePath} (${o.candidate.branch})`));
+      console.log(
+        chalk21.green(`  removed  ${o.candidate.worktreePath} (${o.candidate.branch})${staleNote}`)
+      );
     } else {
       console.log(
         chalk21.red(
-          `  FAILED   ${o.candidate.worktreePath} (${o.candidate.branch}) \u2014 judged safe to remove but 'git worktree remove' did not succeed; left as-is`
+          `  FAILED   ${o.candidate.worktreePath} (${o.candidate.branch}) \u2014 judged safe to remove but 'git worktree remove' did not succeed; left as-is${staleNote}`
         )
       );
     }
   }
   for (const o of kept) {
     const reason = o.verdict.reason === void 0 ? "unknown" : KEEP_REASON_TEXT[o.verdict.reason];
+    const staleNote = o.staleClaimCleared ? " (its stale fleet-worktree-claim lock was cleared first)" : "";
     console.log(
-      chalk21.dim(`  kept     ${o.candidate.worktreePath} (${o.candidate.branch}) \u2014 ${reason}`)
+      chalk21.dim(
+        `  kept     ${o.candidate.worktreePath} (${o.candidate.branch}) \u2014 ${reason}${staleNote}`
+      )
     );
   }
+  const staleClaimNote = staleClaims.length > 0 ? ` (${String(staleClaims.length)} had a stale fleet-worktree-claim lock cleared)` : "";
   console.log(
     chalk21.dim(
       `
-  --fix: ${String(removed.length)} removed, ${String(failed.length)} failed, ${String(kept.length)} kept, of ${String(outcomes.length)} worktree(s) considered.
+  --fix: ${String(removed.length)} removed, ${String(failed.length)} failed, ${String(kept.length)} kept, of ${String(outcomes.length)} worktree(s) considered${staleClaimNote}.
 `
     )
   );

package/package.json

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