@makerx/yoke 0.13.1 → 0.14.0

package/README.md

@@ -24,6 +24,7 @@ yoke sync --user   # ~/.claude/skills
 - `/pr` raises a PR with a short What/Why/(How) description.
 - `/review [number]` reviews a PR with Claude and Codex, combines their findings and offers to post them. [Configure](src/features/review/README.md#settings).
 - `/review-ci` makes CI review each PR, adding a workflow or switching the repo's existing LLM review workflow over, and helps set its variable and secret. [Details](src/features/review/README.md#ci).
+- `/review-ci-gate` blocks merging until the CI review passes, once its workflow is merged. [Details](src/features/review/README.md#merge-gate).
 
 ## CLI
 
@@ -31,6 +32,7 @@ yoke sync --user   # ~/.claude/skills
 yoke sync [--user] [--force]  # write yoke's skills
 yoke review [number]          # review a PR (used by /review)
 yoke review-ci                # add the CI review workflow (used by /review-ci)
+yoke review-ci-gate           # require the review / gate check on the default branch (used by /review-ci-gate)
 yoke review-gate <result>     # block merging until the PR's latest review succeeds (used by review.yml)
 yoke models                   # list each provider's models
 ```

package/dist/cli.js

@@ -7,7 +7,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@makerx/yoke",
-  version: "0.13.1",
+  version: "0.14.0",
   description: "Lean, user-invoked Claude Code skills for MakerX AI-assisted delivery, plus the CLI they call.",
   license: "MIT",
   author: "MakerX",
@@ -43,6 +43,7 @@ var package_default = {
   dependencies: {
     commander: "^15.0.0",
     "log-update": "^8.0.0",
+    yaml: "^2.9.1",
     zod: "^4.6.7"
   },
   devDependencies: {
@@ -54,8 +55,7 @@ var package_default = {
     "oxlint-tsgolint": "^7.0.2004",
     tsup: "^9.0.0",
     typescript: "^6.0.3",
-    vitest: "^5.0.5",
-    yaml: "^2.9.1"
+    vitest: "^5.0.5"
   },
   overrides: {
     minimatch: "^11.0.3"
@@ -159,6 +159,28 @@ function howToSet(key, placeholder = "<value>") {
   return `${ways.slice(0, -1).join(", ")} or ${ways.at(-1)}`;
 }
 
+// src/cliSettings.ts
+function addSettingOptions(command, keys) {
+  for (const key of keys) {
+    const flag = settingFlag(key);
+    if (flag) command.option(`${flag} <value>`, settingDescription(key));
+  }
+  return command;
+}
+function optionName(flag) {
+  return flag.slice(2).replace(/-(.)/g, (_, next) => next.toUpperCase());
+}
+function flagSettings(options, keys) {
+  const flags = {};
+  for (const key of keys) {
+    const flag = settingFlag(key);
+    const value = flag && options[optionName(flag)];
+    if (typeof value === "string") flags[key] = value;
+  }
+  return flags;
+}
+var settingsHelp = "\nEach setting falls back to its YOKE_* env var, then `yoke config set --user`; API keys come from env or config only. Run `yoke config` to see them all.";
+
 // src/features/config/userConfig.ts
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
@@ -548,6 +570,9 @@ async function discardPendingReview(pr2, review, exec2 = run) {
 async function githubGet(path, exec2 = run) {
   return JSON.parse(await exec2("gh", ["api", path]));
 }
+async function githubPost(path, body, exec2 = run) {
+  return JSON.parse(await exec2("gh", ["api", "--method", "POST", path, "--input", "-"], void 0, JSON.stringify(body)));
+}
 var github = {
   open: (pr2) => openPendingReview(pr2),
   add: (review, comment) => addReviewComment(review, comment),
@@ -761,21 +786,6 @@ function setupCommands(settings, workflow) {
     ...workflowSecrets(workflow).map((secret2) => `gh secret set ${secret2}`)
   ];
 }
-var gateRuleset = {
-  name: "yoke review",
-  target: "branch",
-  enforcement: "active",
-  conditions: { ref_name: { include: ["~DEFAULT_BRANCH"], exclude: [] } },
-  rules: [
-    {
-      type: "required_status_checks",
-      parameters: { strict_required_status_checks_policy: false, required_status_checks: [{ context: gateCheck }] }
-    }
-  ]
-};
-function rulesetCommand() {
-  return `echo ${shellQuote(JSON.stringify(gateRuleset))} | gh api --method POST 'repos/{owner}/{repo}/rulesets' --input -`;
-}
 var unknownRepo = "<owner>/<repo>";
 function githubRepo(cwd = process.cwd()) {
   try {
@@ -832,28 +842,242 @@ function reviewCiReport(outcome, settings, workflow, repo) {
     "",
     outcome === "printed" ? "Once the repo's review workflow runs this review, commit and push it; each PR opened from this repo then gets a review." : `Commit and push ${callerWorkflowPath}; each PR opened from this repo then gets a review.`,
     "",
-    `To block merging while the review fails, require the ${gateCheck} check on the default branch with:`,
-    `  ${rulesetCommand()}`,
-    "Run it only after this workflow is merged to the default branch, or pushes to open PRs get stuck waiting for a status."
+    `To block merging while the review fails, run /review-ci-gate once this workflow is merged to the default branch; it requires the ${gateCheck} check there.`
   ].join("\n");
 }
 
+// src/features/review/ciGate.ts
+import { z as z3 } from "zod";
+
+// src/features/review/ciGateCaller.ts
+import { parse } from "yaml";
+import { z as z2 } from "zod";
+var yokeRepo = "MakerXStudio/yoke";
+var localReviewWorkflow = "./.github/workflows/review.yml";
+var reviewWorkflowPrefix = reviewWorkflowRef.slice(0, reviewWorkflowRef.indexOf("@") + 1).toLowerCase();
+var workflowSchema = z2.looseObject({
+  on: z2.unknown().optional(),
+  permissions: z2.unknown().optional(),
+  jobs: z2.record(z2.string(), z2.looseObject({ uses: z2.unknown().optional(), permissions: z2.unknown().optional() }).nullable()).optional()
+});
+function parseWorkflow(content) {
+  try {
+    const result = workflowSchema.safeParse(parse(content));
+    return result.success ? result.data : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function callsReview(uses, repo) {
+  if (typeof uses !== "string") return false;
+  if (uses.toLowerCase().startsWith(reviewWorkflowPrefix)) return true;
+  return repo.toLowerCase() === yokeRepo.toLowerCase() && uses === localReviewWorkflow;
+}
+function listIncludes(value, item) {
+  return value === item || Array.isArray(value) && value.includes(item);
+}
+function pullRequestTrigger(on) {
+  if (typeof on !== "object" || on === null || Array.isArray(on) || !("pull_request" in on)) return void 0;
+  const trigger = on.pull_request;
+  return typeof trigger === "object" && trigger !== null && !Array.isArray(trigger) ? { ...trigger } : void 0;
+}
+function runsOnSynchronize(on) {
+  if (typeof on === "string" || Array.isArray(on)) return listIncludes(on, "pull_request");
+  if (typeof on !== "object" || on === null || !("pull_request" in on)) return false;
+  const trigger = pullRequestTrigger(on);
+  if (!trigger || !("types" in trigger)) return true;
+  return listIncludes(trigger.types, "synchronize");
+}
+function globMatches(pattern, branch) {
+  const source = pattern.split(/(\*\*|\*|\?)/).map((part) => ({ "**": ".*", "*": "[^/]*", "?": "." })[part] ?? part.replace(/[.+^${}()|[\]\\]/g, "\\$&")).join("");
+  return new RegExp(`^${source}$`).test(branch);
+}
+function patterns(value) {
+  if (typeof value === "string") return [value];
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function branchesInclude(value, branch) {
+  return patterns(value).reduce(
+    (included, pattern) => pattern.startsWith("!") ? included && !globMatches(pattern.slice(1), branch) : included || globMatches(pattern, branch),
+    false
+  );
+}
+function skipFilters(on, branch) {
+  const trigger = pullRequestTrigger(on);
+  if (!trigger) return [];
+  const filters = ["paths", "paths-ignore"].filter((key) => key in trigger);
+  if ("branches" in trigger && !branchesInclude(trigger.branches, branch)) filters.push("branches");
+  if ("branches-ignore" in trigger && patterns(trigger["branches-ignore"]).some((pattern) => globMatches(pattern, branch)))
+    filters.push("branches-ignore");
+  return filters;
+}
+function canReadActions(permissions) {
+  if (permissions === "read-all" || permissions === "write-all") return true;
+  if (typeof permissions !== "object" || permissions === null || !("actions" in permissions)) return false;
+  return permissions.actions === "read" || permissions.actions === "write";
+}
+function checkWorkflow(path, workflow, repo, branch) {
+  const jobs = Object.values(workflow.jobs ?? {}).filter((job) => job && callsReview(job.uses, repo));
+  if (jobs.length === 0) return void 0;
+  const problems2 = [];
+  if (!runsOnSynchronize(workflow.on)) problems2.push("lacks the `synchronize` type in its `pull_request` trigger");
+  if (!jobs.some((job) => canReadActions(job?.permissions ?? workflow.permissions)))
+    problems2.push("lacks `actions: read` in its permissions");
+  const filters = skipFilters(workflow.on, branch);
+  if (filters.length > 0)
+    problems2.push(
+      `skips some PRs to ${branch} through its \`pull_request\` ${filters.map((filter) => `\`${filter}\``).join(", ")} filter${filters.length > 1 ? "s" : ""}, so those PRs could never merge`
+    );
+  return { path, problems: problems2 };
+}
+function checkCallerWorkflows(files, repo, branch) {
+  const callers = files.flatMap(({ path, content }) => {
+    const workflow = parseWorkflow(content);
+    const check = workflow && checkWorkflow(path, workflow, repo, branch);
+    return check ? [check] : [];
+  });
+  return callers.find((caller) => caller.problems.length === 0) ?? callers[0];
+}
+
+// src/features/review/ciGate.ts
+var gateRuleset = {
+  name: "yoke review",
+  target: "branch",
+  enforcement: "active",
+  conditions: { ref_name: { include: ["~DEFAULT_BRANCH"], exclude: [] } },
+  rules: [
+    {
+      type: "required_status_checks",
+      parameters: { strict_required_status_checks_policy: false, required_status_checks: [{ context: gateCheck }] }
+    }
+  ]
+};
+var recentPrCount = 20;
+var repoSchema = z3.object({
+  full_name: z3.string(),
+  html_url: z3.string(),
+  default_branch: z3.string()
+});
+var branchRulesSchema = z3.array(
+  z3.object({
+    type: z3.string(),
+    ruleset_id: z3.number().optional(),
+    parameters: z3.object({ required_status_checks: z3.array(z3.object({ context: z3.string() })).optional() }).optional()
+  })
+);
+var directorySchema = z3.array(z3.object({ type: z3.string(), name: z3.string(), path: z3.string() }));
+var fileSchema = z3.object({ content: z3.string() });
+var pullsSchema = z3.array(z3.object({ head: z3.object({ sha: z3.string() }) }));
+var checkRunsSchema = z3.object({ total_count: z3.number() });
+var createdSchema = z3.object({ id: z3.number() });
+var rulesetsSchema = z3.array(z3.object({ id: z3.number(), name: z3.string(), enforcement: z3.string() }));
+var githubApi = { get: (path) => githubGet(path), post: (path, body) => githubPost(path, body) };
+async function getUnlessMissing(api, path) {
+  try {
+    return await api.get(path);
+  } catch (error) {
+    if (error instanceof ReviewError && error.message.includes("(HTTP 404)")) return void 0;
+    throw error;
+  }
+}
+async function workflowFiles(api, repo) {
+  const ref = `ref=${encodeURIComponent(repo.default_branch)}`;
+  const listing = await getUnlessMissing(api, `repos/${repo.full_name}/contents/.github/workflows?${ref}`);
+  if (listing === void 0) return [];
+  const files = directorySchema.parse(listing).filter((entry) => entry.type === "file" && /\.ya?ml$/.test(entry.name));
+  return Promise.all(
+    files.map(async ({ path }) => {
+      const { content } = fileSchema.parse(await api.get(`repos/${repo.full_name}/contents/${path}?${ref}`));
+      return { path, content: Buffer.from(content, "base64").toString("utf8") };
+    })
+  );
+}
+async function callerProblem(api, repo) {
+  const branch = repo.default_branch;
+  const caller = checkCallerWorkflows(await workflowFiles(api, repo), repo.full_name, branch);
+  if (!caller) return `No workflow on ${branch} calls yoke's review.yml. Run /review-ci, then merge its ${callerWorkflowPath} to ${branch}.`;
+  if (caller.problems.length > 0)
+    return `${caller.path} on ${branch} calls yoke's review.yml but ${caller.problems.join(" and ")}. Fix it and merge the change to ${branch}.`;
+  return void 0;
+}
+async function gateHasReported(api, repo) {
+  const pulls = pullsSchema.parse(
+    await api.get(`repos/${repo.full_name}/pulls?state=all&sort=updated&direction=desc&per_page=${recentPrCount}`)
+  );
+  for (const { head } of pulls) {
+    const runs = checkRunsSchema.parse(
+      await api.get(`repos/${repo.full_name}/commits/${head.sha}/check-runs?check_name=${encodeURIComponent(gateCheck)}&per_page=1`)
+    );
+    if (runs.total_count > 0) return true;
+  }
+  return false;
+}
+async function rulesetProblem(api, repo) {
+  const rulesets = rulesetsSchema.parse(await api.get(`repos/${repo.full_name}/rulesets?includes_parents=false&per_page=100`));
+  const existing = rulesets.find((ruleset) => ruleset.name === gateRuleset.name);
+  if (!existing) return void 0;
+  return `The "${gateRuleset.name}" ruleset already exists with enforcement \`${existing.enforcement}\` but doesn't require ${gateCheck} on ${repo.default_branch}: ${repo.html_url}/rules/${existing.id}. Set its enforcement to Active and its required check to ${gateCheck}, or delete it and run this again.`;
+}
+async function createRuleset(api, repo) {
+  try {
+    return await api.post(`repos/${repo.full_name}/rulesets`, gateRuleset);
+  } catch (error) {
+    if (error instanceof ReviewError && /\(HTTP 40[34]\)/.test(error.message))
+      throw new ReviewError(
+        `GitHub refused to add the "${gateRuleset.name}" ruleset to ${repo.full_name}: your gh user can't edit its repository rules. Ask a repo admin, or someone whose role can edit repository rules, to run \`yoke review-ci-gate\`.`
+      );
+    throw error;
+  }
+}
+async function problems(api, repo) {
+  const found = [];
+  const ruleset = await rulesetProblem(api, repo);
+  if (ruleset) found.push(ruleset);
+  const caller = await callerProblem(api, repo);
+  if (caller) found.push(caller);
+  if (!await gateHasReported(api, repo))
+    found.push(
+      `No ${gateCheck} check run on the ${recentPrCount} most recently updated PRs. Open or push to a PR so the gate reports, then run this again.`
+    );
+  return found;
+}
+async function enforceReviewGate(api = githubApi) {
+  const repo = repoSchema.parse(await api.get("repos/{owner}/{repo}"));
+  const branch = repo.default_branch;
+  const rules = branchRulesSchema.parse(await api.get(`repos/${repo.full_name}/rules/branches/${encodeURIComponent(branch)}`));
+  const existing = rules.find(
+    (rule) => rule.type === "required_status_checks" && rule.parameters?.required_status_checks?.some((check) => check.context === gateCheck)
+  );
+  if (existing) {
+    const where = existing.ruleset_id ? ` by ${repo.html_url}/rules/${existing.ruleset_id}` : "";
+    return { created: false, message: `${gateCheck} is already required on ${branch}${where}; nothing changed.` };
+  }
+  const found = await problems(api, repo);
+  if (found.length > 0)
+    throw new ReviewError([`Cannot require ${gateCheck} on ${branch} yet:`, ...found.map((problem) => `- ${problem}`)].join("\n"));
+  const { id } = createdSchema.parse(await createRuleset(api, repo));
+  return {
+    created: true,
+    message: `Added the "${gateRuleset.name}" ruleset, which blocks merging to ${branch} until ${gateCheck} passes: ${repo.html_url}/rules/${id}`
+  };
+}
+
 // src/features/review/gate.ts
 import { appendFileSync, readFileSync as readFileSync3 } from "fs";
 import { setTimeout } from "timers/promises";
-import { z as z2 } from "zod";
-var eventSchema = z2.object({
-  action: z2.string(),
-  pull_request: z2.object({
-    number: z2.number(),
-    head: z2.object({ ref: z2.string(), repo: z2.object({ full_name: z2.string() }).nullable() }),
-    user: z2.object({ type: z2.string() })
+import { z as z4 } from "zod";
+var eventSchema = z4.object({
+  action: z4.string(),
+  pull_request: z4.object({
+    number: z4.number(),
+    head: z4.object({ ref: z4.string(), repo: z4.object({ full_name: z4.string() }).nullable() }),
+    user: z4.object({ type: z4.string() })
   })
 });
-var runsSchema = z2.object({
-  workflow_runs: z2.array(z2.object({ id: z2.number(), run_number: z2.number(), pull_requests: z2.array(z2.object({ number: z2.number() })) }))
+var runsSchema = z4.object({
+  workflow_runs: z4.array(z4.object({ id: z4.number(), run_number: z4.number(), pull_requests: z4.array(z4.object({ number: z4.number() })) }))
 });
-var jobsSchema = z2.object({ jobs: z2.array(z2.object({ name: z2.string(), status: z2.string(), conclusion: z2.string().nullable() })) });
+var jobsSchema = z4.object({ jobs: z4.array(z4.object({ name: z4.string(), status: z4.string(), conclusion: z4.string().nullable() })) });
 var pollInterval = 3e4;
 var rerunHint = "Mark the PR as draft, then ready for review, to run the review again.";
 var firstRunHint = "Mark the PR as ready for review (from draft if it is not one) to run it.";
@@ -877,7 +1101,7 @@ function gateContext(env = process.env) {
   };
 }
 async function earlierRuns({ repo, runId, runNumber, event }, deps) {
-  const { workflow_id } = z2.object({ workflow_id: z2.number() }).parse(await deps.get(`repos/${repo}/actions/runs/${runId}`));
+  const { workflow_id } = z4.object({ workflow_id: z4.number() }).parse(await deps.get(`repos/${repo}/actions/runs/${runId}`));
   const query = new URLSearchParams({ event: "pull_request", branch: event.pull_request.head.ref, per_page: "100" });
   const { workflow_runs } = runsSchema.parse(await deps.get(`repos/${repo}/actions/workflows/${workflow_id}/runs?${query.toString()}`));
   return workflow_runs.filter((run2) => run2.run_number < runNumber && run2.pull_requests.some((pr2) => pr2.number === event.pull_request.number)).toSorted((a, b) => b.run_number - a.run_number).map((run2) => run2.id);
@@ -2129,8 +2353,8 @@ function slotsToRun(slots2) {
   return [...distinct.values()];
 }
 async function assertViable(slots2, check = checks) {
-  const problems = await Promise.all(slotsToRun(slots2).map((use) => slotProblem(use, check)));
-  const errors = problems.filter((problem) => problem !== void 0);
+  const problems2 = await Promise.all(slotsToRun(slots2).map((use) => slotProblem(use, check)));
+  const errors = problems2.filter((problem) => problem !== void 0);
   if (errors.length)
     throw new ReviewFailure("a reviewer could not run", ["Cannot review:", ...errors.map((error) => `- ${error}`)].join("\n"));
 }
@@ -2304,6 +2528,21 @@ If \`yoke\` is not found, run \`npm i -g @makerx/yoke\` and retry.
 `
 };
 
+// src/features/review/ciGateSkill.ts
+var reviewCiGateSkill = {
+  name: "review-ci-gate",
+  description: "Block merging to this repo's default branch until yoke's CI review passes, once its review workflow is merged.",
+  disableModelInvocation: true,
+  userLevel: true,
+  body: `
+Run \`yoke review-ci-gate\` and relay its output.
+
+If it fails, say what is missing and how to fix it, as it reports. Don't create the ruleset any other way.
+
+If \`yoke\` is not found, run \`npm i -g @makerx/yoke\`.
+`
+};
+
 // src/features/review/ciSkill.ts
 var reviewCiSkill = {
   name: "review-ci",
@@ -2338,7 +2577,7 @@ Never ask whether they are set for the organisation, and don't query org setting
 
 With Entra, check \`az ad app federated-credential list --id <client-id>\` and show the printed create command if the credential is missing.
 
-Finish with what changed and what's left: commit and push the workflow, then, only once it is merged to the default branch, run the printed \`gh api\` ruleset command requiring \`review / gate\`. Don't run it before then.
+Finish with what changed and what's left: commit and push the workflow, then, once it is merged to the default branch, run \`/review-ci-gate\` to require \`review / gate\` before merging.
 
 If \`yoke\` is not found, run \`npm i -g @makerx/yoke\`.
 `
@@ -2359,7 +2598,7 @@ If \`yoke\` is not found, run \`npm i -g @makerx/yoke\` and retry.
 };
 
 // src/features/sync/sync.ts
-var bundledSkills = [prSkill, reviewSkill, reviewCiSkill];
+var bundledSkills = [prSkill, reviewSkill, reviewCiSkill, reviewCiGateSkill];
 function skillsRoot(user, cwd = process.cwd(), home = homedir3()) {
   return join9(user ? home : cwd, ".claude", "skills");
 }
@@ -2404,26 +2643,6 @@ pr.command("raise").description("Validate a PR title and body, then create the P
   }
 });
 var providerKeys = settingKeys.filter((key) => !key.startsWith("review."));
-function addSettingOptions(command, keys) {
-  for (const key of keys) {
-    const flag = settingFlag(key);
-    if (flag) command.option(`${flag} <value>`, settingDescription(key));
-  }
-  return command;
-}
-function optionName(flag) {
-  return flag.slice(2).replace(/-(.)/g, (_, next) => next.toUpperCase());
-}
-function flagSettings(options, keys) {
-  const flags = {};
-  for (const key of keys) {
-    const flag = settingFlag(key);
-    const value = flag && options[optionName(flag)];
-    if (typeof value === "string") flags[key] = value;
-  }
-  return flags;
-}
-var settingsHelp = "\nEach setting falls back to its YOKE_* env var, then `yoke config set --user`; API keys come from env or config only. Run `yoke config` to see them all.";
 addSettingOptions(
   program.command("review").description("Review the current branch's PR, or PR <number>, with Claude and Codex in parallel, then combine their findings").argument("[number]", "PR number; reviewed without checking it out").option("--post", "post the findings to the PR as one review, reusing the saved review of the PR head when there is one").option("--force", "discard this PR head's cached reviews and run every pass again").option("--verbose", "print every step and each reviewer's tool calls as log lines instead of live spinners"),
   settingKeys
@@ -2464,6 +2683,15 @@ addSettingOptions(
     process.exitCode = 1;
   }
 });
+program.command("review-ci-gate").description(`Require the ${gateCheck} check on the default branch with a ruleset, once the CI review workflow is merged`).action(async () => {
+  try {
+    console.log((await enforceReviewGate()).message);
+  } catch (error) {
+    if (!(error instanceof ReviewError)) throw error;
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+});
 program.command("review-gate").description("Block merging until the latest review that ran for the PR succeeds; fork and bot PRs pass. Used by review.yml's gate job").argument("<result>", "result of the review job on this event: success, failure, cancelled or skipped").action(async (result) => {
   try {
     if (!await runReviewGate(result, console.log)) process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makerx/yoke",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Lean, user-invoked Claude Code skills for MakerX AI-assisted delivery, plus the CLI they call.",
   "license": "MIT",
   "author": "MakerX",
@@ -36,6 +36,7 @@
   "dependencies": {
     "commander": "^15.0.0",
     "log-update": "^8.0.0",
+    "yaml": "^2.9.1",
     "zod": "^4.6.7"
   },
   "devDependencies": {
@@ -47,8 +48,7 @@
     "oxlint-tsgolint": "^7.0.2004",
     "tsup": "^9.0.0",
     "typescript": "^6.0.3",
-    "vitest": "^5.0.5",
-    "yaml": "^2.9.1"
+    "vitest": "^5.0.5"
   },
   "overrides": {
     "minimatch": "^11.0.3"