@biffo/cli 0.164.0 → 0.166.0

package/dist/index.js

@@ -1506,6 +1506,70 @@ var GitHubAdapter = class {
     }
     log.success("Branch protection configured on dev, staging, and main");
   }
+  /**
+   * Protect a single branch with caller-supplied required checks (#803).
+   *
+   * `configureBranchProtection` above exists for **deployable** repos and
+   * protects `dev`, `staging` and `main` with `DEFAULT_STATUS_CHECKS` — the
+   * core workflow's job names. Neither is right for a plugin repo:
+   *
+   * - A plugin repo is **non-deployable** and has `dev` only (AGENTS.md §2).
+   *   Reusing the deployable path would demand two branches it should not have,
+   *   and `waitForBranch` would hang on them for two minutes each before
+   *   failing.
+   * - Its checks are its own CI's job names (`Lint`, `Type Check`, `Test`, …),
+   *   not the core workflow's. Requiring a context that is never reported
+   *   blocks every PR for ever, on a branch whose CI is entirely green.
+   *
+   * `statusChecks` must be non-empty. Protection that requires nothing is worse
+   * than none: it reads as configured while gating on nothing, so callers that
+   * could not determine the contexts must not silently land here.
+   */
+  async protectSingleBranch(org, repo, branch, statusChecks, protectionIntervalMs = 3e3) {
+    if (statusChecks.length === 0) {
+      throw new Error(
+        `Refusing to protect ${org}/${repo}@${branch} with no required status checks \u2014 that reads as protected while gating on nothing. Determine the workflow's job contexts first.`
+      );
+    }
+    log.info(`Waiting for ${branch} branch to be ready...`);
+    await this.waitForBranch(org, repo, branch);
+    log.info(`Configuring branch protection on ${branch}...`);
+    const params = {
+      owner: org,
+      repo,
+      branch,
+      required_status_checks: { strict: true, contexts: statusChecks },
+      enforce_admins: false,
+      required_pull_request_reviews: {
+        required_approving_review_count: 0,
+        dismiss_stale_reviews: false
+      },
+      restrictions: null,
+      required_linear_history: true,
+      allow_force_pushes: false,
+      allow_deletions: false
+    };
+    const deadline = Date.now() + 3e4;
+    while (true) {
+      try {
+        await this.octokit.repos.updateBranchProtection(params);
+        break;
+      } catch (err) {
+        const status = err.status;
+        if (status === 403) {
+          log.warn(`Branch protection unavailable for ${org}/${repo}: ${err.message}`);
+          log.warn("  Add it later via GitHub once the plan allows it, or make the repo public.");
+          return;
+        }
+        if (status !== 404 || Date.now() >= deadline) throw err;
+        log.info("Branch protection endpoint not yet ready, retrying...");
+        await new Promise((resolve18) => setTimeout(resolve18, protectionIntervalMs));
+      }
+    }
+    log.success(
+      `Branch protection configured on ${branch} (${statusChecks.length} required check(s))`
+    );
+  }
   async createEnvironments(config) {
     const { org, repo } = config.source_control.config;
     for (const env of config.environments) {
@@ -6370,6 +6434,50 @@ import { fileURLToPath as fileURLToPath5 } from "url";
 import chalk13 from "chalk";
 import { Command as Command13 } from "commander";
 
+// src/lib/workflow-check-contexts.ts
+function unquote(value) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length > 1 || trimmed.startsWith("'") && trimmed.endsWith("'") && trimmed.length > 1) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+function workflowCheckContexts(workflow) {
+  const lines = workflow.split("\n");
+  const jobsIndex = lines.findIndex((line) => /^jobs:\s*(#.*)?$/.test(line));
+  if (jobsIndex === -1) return [];
+  const contexts = [];
+  let currentJobId = null;
+  let currentJobIndent = 0;
+  let currentName = null;
+  const flush = () => {
+    if (currentJobId !== null) contexts.push(currentName ?? currentJobId);
+    currentJobId = null;
+    currentName = null;
+  };
+  for (const line of lines.slice(jobsIndex + 1)) {
+    if (line.trim() === "" || /^\s*#/.test(line)) continue;
+    if (!/^\s/.test(line)) break;
+    const jobMatch = /^(\s+)([A-Za-z0-9_-]+):\s*(#.*)?$/.exec(line);
+    if (jobMatch?.[1] !== void 0 && jobMatch[2] !== void 0) {
+      const indent = jobMatch[1].length;
+      if (currentJobId === null || indent === currentJobIndent) {
+        flush();
+        currentJobId = jobMatch[2];
+        currentJobIndent = indent;
+        continue;
+      }
+    }
+    if (currentJobId === null) continue;
+    const nameMatch = /^(\s+)name:\s*(.+?)\s*$/.exec(line);
+    if (nameMatch?.[1] !== void 0 && nameMatch[2] !== void 0 && nameMatch[1].length === currentJobIndent + 2 && currentName === null) {
+      currentName = unquote(nameMatch[2]);
+    }
+  }
+  flush();
+  return contexts;
+}
+
 // src/lib/plugin-locations.ts
 import { existsSync as existsSync21, readdirSync as readdirSync10 } from "fs";
 import { join as join21 } from "path";
@@ -6661,7 +6769,8 @@ function applySubstitutions(text, names) {
   return out;
 }
 var BINARY_EXTENSIONS = /\.(png|jpe?g|gif|ico|woff2?|ttf|zip|gz)$/i;
-function scaffoldPlugin(skeletonRoot, destDir, names) {
+function scaffoldPlugin(skeletonRoot, destDir, names, options = {}) {
+  const layout = options.layout ?? "in-tree";
   if (!existsSync22(skeletonRoot)) {
     throw new Error(`Plugin skeleton not found at ${skeletonRoot}`);
   }
@@ -6678,7 +6787,7 @@ function scaffoldPlugin(skeletonRoot, destDir, names) {
       (a, b) => a.name.localeCompare(b.name)
     )) {
       if (NEVER_COPY.has(entry.name)) continue;
-      if (relDir === "" && entry.name in STANDALONE_ONLY_ENTRIES) {
+      if (layout === "in-tree" && relDir === "" && entry.name in STANDALONE_ONLY_ENTRIES) {
         skipped.push({ entry: entry.name, reason: STANDALONE_ONLY_ENTRIES[entry.name] });
         continue;
       }
@@ -6724,6 +6833,12 @@ function findSkeletonRoot(startDir, skeleton) {
 var pluginCreateCommand = new Command13("create").description("Scaffold a new plugin from the Biffo plugin skeleton: biffo plugin create <name>").argument("<name>", "Plugin name \u2014 lowercase kebab-case, e.g. acme-crm").option(
   "--first-party",
   "Scaffold into the template-owned services/_plugins/ carve-out. Only valid in the biffo-template repo itself \u2014 see notes."
+).option(
+  "--standalone",
+  "Scaffold a standalone plugin repo (ADR-0003 section 2) into ./biffo-plugin-<name>/ instead of into this checkout, keeping its own CI/CD workflows"
+).option(
+  "--org <org>",
+  "With --standalone, also create the GitHub repo under this org (or user), push, and protect dev"
 ).option(
   "--skeleton <path>",
   "Path to the plugin skeleton (defaults to _skeletons/plugin-template)"
@@ -6735,12 +6850,18 @@ var pluginCreateCommand = new Command13("create").description("Scaffold a new pl
         name,
         {
           firstParty: options.firstParty ?? false,
+          standalone: options.standalone ?? false,
+          ...options.org ? { org: options.org } : {},
           ...options.skeleton ? { skeletonRoot: resolve11(options.skeleton) } : {},
           dryRun: options.dryRun ?? false,
           commit: options.commit !== false,
           cwd
         },
-        { git: new GitAdapter() }
+        {
+          git: new GitAdapter(),
+          makeGitHub: (token) => new GitHubAdapter(token),
+          resolveToken: resolveGithubToken3
+        }
       );
     } catch (err) {
       log.error(err.message);
@@ -6750,6 +6871,15 @@ var pluginCreateCommand = new Command13("create").description("Scaffold a new pl
 );
 async function runPluginCreate(name, options, deps) {
   const names = deriveNames(name);
+  if (options.standalone) {
+    if (options.firstParty) {
+      throw new Error(
+        "--standalone and --first-party are opposites: --first-party authors a plugin *inside* the template at services/_plugins/, while --standalone authors one in its own repository (ADR-0003 section 2). Pick one."
+      );
+    }
+    await runStandaloneCreate(names, options, deps);
+    return;
+  }
   const isInstance = existsSync23(join23(options.cwd, INSTANCE_CORE_FILE));
   if (options.firstParty && isInstance) {
     throw new Error(
@@ -6808,6 +6938,128 @@ async function runPluginCreate(name, options, deps) {
   }
   printNextSteps(names, relDir, channel);
 }
+async function runStandaloneCreate(names, options, deps) {
+  const destDir = join23(options.cwd, names.dist);
+  if (existsSync23(destDir)) {
+    throw new Error(`${names.dist}/ already exists. Choose a different name, or remove it first.`);
+  }
+  const skeletonRoot = resolveSkeletonRoot(options);
+  if (options.dryRun) {
+    console.log(chalk13.bold("\n  Dry run \u2014 no changes will be made\n"));
+    console.log(`  Plugin:          ${names.slug}`);
+    console.log("  Channel:         standalone repo");
+    console.log(`  Would scaffold:  ${names.dist}/`);
+    console.log(`  From skeleton:   ${skeletonRoot}`);
+    console.log(`  Python package:  ${names.pkg}   (dist: ${names.dist})`);
+    console.log("  Would git init:  yes, on branch dev, with an initial commit\n");
+    return;
+  }
+  const { files } = scaffoldPlugin(skeletonRoot, destDir, names, { layout: "standalone" });
+  restorePackagedDotfiles(destDir);
+  log.success(`Scaffolded ${String(files.length)} file(s) into ${names.dist}/`);
+  const manifest = validateManifest(
+    JSON.parse(readFileSync17(join23(destDir, "biffo.plugin.json"), "utf8"))
+  );
+  if (manifest.name !== names.slug) {
+    throw new Error(
+      `Scaffolded manifest declares name '${manifest.name}', expected '${names.slug}'. The skeleton's manifest name may have diverged from 'example-plugin'.`
+    );
+  }
+  log.success(
+    `Manifest valid \u2014 ${String(manifest.tables.length)} table(s), ${String(manifest.api_routes.length)} route(s)`
+  );
+  if (options.commit) {
+    await deps.git.init(destDir);
+    await deps.git.add(destDir, ["."]);
+    await deps.git.commit(destDir, `feat: scaffold ${names.slug} plugin`);
+    log.success(`Initialised a git repo on dev with an initial commit`);
+  }
+  if (options.org !== void 0 && options.org !== "") {
+    if (!options.commit) {
+      throw new Error(
+        "--org needs a commit to push. Drop --no-commit, or create the repo yourself using the steps printed by a --no-commit run."
+      );
+    }
+    await createAndPushStandaloneRepo(options.org, names, destDir, deps);
+    return;
+  }
+  printStandaloneNextSteps(names, minorOf(manifest.version));
+}
+async function createAndPushStandaloneRepo(org, names, destDir, deps) {
+  if (deps.makeGitHub === void 0 || deps.resolveToken === void 0) {
+    throw new Error("No GitHub adapter available \u2014 cannot create a repository.");
+  }
+  const token = await deps.resolveToken();
+  const github = deps.makeGitHub(token);
+  const cloneUrl = await github.createEmptyRepo(org, names.dist, `${names.slug} \u2014 a Biffo plugin`);
+  await deps.git.addRemote(destDir, "origin", cloneUrl);
+  await deps.git.push(destDir, "dev", { token });
+  log.success(`Pushed dev to ${org}/${names.dist}`);
+  await github.setDefaultBranch(org, names.dist, "dev");
+  const ciPath = join23(destDir, ".github", "workflows", "ci.yml");
+  const contexts = existsSync23(ciPath) ? workflowCheckContexts(readFileSync17(ciPath, "utf8")) : [];
+  if (contexts.length === 0) {
+    log.warn(
+      `Could not determine required status checks from ${ciPath} \u2014 skipping branch protection. Configure it manually on dev once you know the CI job names.`
+    );
+  } else {
+    await github.protectSingleBranch(org, names.dist, "dev", contexts);
+  }
+  printStandaloneRemoteNextSteps(names, org);
+}
+function printStandaloneRemoteNextSteps(names, org) {
+  console.log(chalk13.bold("\n  Standalone plugin repo created!\n"));
+  console.log(`  https://github.com/${org}/${names.dist}  (dev, protected)
+`);
+  console.log("  Next:");
+  console.log(chalk13.dim(`    1. cd ${names.dist} && edit biffo.plugin.json`));
+  console.log(
+    chalk13.dim("    2. Add it to the registry so it appears in the plugin store \u2014 either set")
+  );
+  console.log(
+    chalk13.dim(
+      "       REGISTRY_PUBLISH_TOKEN on the repo, or add it to the registry\u2019s sources.json"
+    )
+  );
+  console.log(
+    chalk13.dim(`    3. Consumers install it with: biffo plugin install ${names.slug}@<minor>
+`)
+  );
+}
+function minorOf(version) {
+  const match = /^(\d+)\.(\d+)/.exec(version);
+  return match ? `${match[1]}.${match[2]}` : version;
+}
+function printStandaloneNextSteps(names, minor) {
+  console.log(chalk13.bold("\n  Standalone plugin repo scaffolded!\n"));
+  console.log(`  ${names.dist}/ is a complete plugin repository: manifest, example table and`);
+  console.log("  routes, terraform/ module, and its own CI, release and registry workflows.\n");
+  console.log("  Next:");
+  console.log(chalk13.dim(`    1. cd ${names.dist} && edit biffo.plugin.json`));
+  console.log(
+    chalk13.dim("    2. Create the repo \u2014 plugin repos are dev-only (AGENTS.md section 2):")
+  );
+  console.log(chalk13.dim(`         gh repo create <org>/${names.dist} --private --source=. --push`));
+  console.log(
+    chalk13.dim("         gh api -X PATCH repos/<org>/" + names.dist + " -f default_branch=dev")
+  );
+  console.log(chalk13.dim("    3. Publish it to the registry so it appears in the plugin store:"));
+  console.log(chalk13.dim("         see .github/workflows/publish-registry.yml in the new repo"));
+  console.log(
+    chalk13.dim(`    4. Consumers install it with: biffo plugin install ${names.slug}@${minor}
+`)
+  );
+}
+function resolveSkeletonRoot(options) {
+  const here = dirname8(fileURLToPath5(import.meta.url));
+  const skeletonRoot = options.skeletonRoot ?? findSkeletonRoot(here, "plugin-template") ?? join23(options.cwd, "_skeletons", "plugin-template");
+  if (!existsSync23(skeletonRoot)) {
+    throw new Error(
+      `Could not find the plugin skeleton (_skeletons/plugin-template/). Pass --skeleton <path> to point at it explicitly.`
+    );
+  }
+  return skeletonRoot;
+}
 function printDryRun3(names, relDir, skeletonRoot, channel) {
   console.log(chalk13.bold("\n  Dry run \u2014 no changes will be made\n"));
   console.log(`  Plugin:          ${names.slug}`);

package/package.json

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