@makerx/yoke 0.10.0 → 0.12.0

package/README.md

@@ -23,15 +23,15 @@ 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` adds a workflow that reviews each PR in CI and helps set its variable and secret. [Details](src/features/review/README.md#ci).
+- `/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).
 
 ## CLI
 
 ```bash
-yoke sync [--user]      # 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 models             # list each provider's models
+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 models                   # list each provider's models
 ```
 
 ## Configuration

package/dist/cli.js

@@ -7,7 +7,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@makerx/yoke",
-  version: "0.10.0",
+  version: "0.12.0",
   description: "Lean, user-invoked Claude Code skills for MakerX AI-assisted delivery, plus the CLI they call.",
   license: "MIT",
   author: "MakerX",
@@ -756,11 +756,15 @@ function repoRoot(cwd = process.cwd()) {
     throw new ReviewError("Not in a git repository; run `yoke review-ci` from the repo to review.");
   }
 }
-function writeCallerWorkflow(root, content, force) {
+var editInPlaceMessage = [
+  `${callerWorkflowPath} already exists and differs from yoke's version, so it was left as it is.`,
+  "Edit it in place to run yoke's review, keeping its provider, models and names. `yoke review-ci --print` shows yoke's version without saving it."
+].join("\n");
+function writeCallerWorkflow(root, content) {
   const path = join3(root, callerWorkflowPath);
   if (existsSync2(path)) {
     if (readFileSync2(path, "utf8") === content) return "unchanged";
-    if (!force) throw new ReviewError(`${callerWorkflowPath} already exists and differs; pass --force to overwrite it.`);
+    throw new ReviewError(editInPlaceMessage);
   }
   mkdirSync2(dirname2(path), { recursive: true });
   writeFileSync2(path, content);
@@ -770,7 +774,7 @@ function entraSetup({ clientId, environment }, repo) {
   const credential = federatedCredential(repo, environment);
   return [
     "",
-    `Instead of REVIEW_CI_API_KEY, the job signs in to Foundry as Entra app ${clientId} with its GitHub OIDC token. On that app, create a federated credential with:`,
+    `Instead of an API key, the review signs in to Foundry as Entra app ${clientId}. So that the app trusts this repo's review runs, add a federated credential to it with:`,
     `  issuer:   ${credential.issuer}`,
     `  audience: ${credential.audience}`,
     `  subject:  ${credential.subject}`,
@@ -780,17 +784,28 @@ function entraSetup({ clientId, environment }, repo) {
     ...environment ? [`The job runs in the ${environment} environment; create it on the repo if it does not exist.`] : []
   ];
 }
+function reportHeading(outcome, workflow) {
+  if (outcome === "printed")
+    return [`yoke's version of ${callerWorkflowPath}, not saved to the repo:`, "", renderCallerWorkflow(workflow).trimEnd()];
+  if (outcome === "unchanged") return [`${callerWorkflowPath} already matches yoke's version; nothing changed.`];
+  return [`Added ${callerWorkflowPath}, which reviews each PR opened from this repo.`];
+}
+function variableAndSecretSetup(settings, workflow) {
+  const hasSecret = workflowSecrets(workflow).length > 0;
+  return [
+    hasSecret ? `The review reads the model server's address from the repo variable ${baseUrlVariable} and its API key from the secret ${apiKeySecret}. Set them with:` : `The review reads the model server's address from the repo variable ${baseUrlVariable}. Set it with:`,
+    ...setupCommands(settings, workflow).map((command) => `  ${command}`),
+    ...hasSecret ? [`Skip the secret if ${apiKeySecret} is already set for your organisation.`] : []
+  ];
+}
 function reviewCiReport(outcome, settings, workflow, repo) {
-  const action = outcome === "wrote" ? "wrote" : "kept";
-  const reads = [`variable ${baseUrlVariable}`, ...workflowSecrets(workflow).map((secret2) => `secret ${secret2}`)];
   return [
-    `${action} ${callerWorkflowPath}`,
+    ...reportHeading(outcome, workflow),
     "",
-    `The workflow reads ${reads.join(" and ")}. Set ${reads.length > 1 ? "them" : "it"} on the repo (or the org) with:`,
-    ...setupCommands(settings, workflow).map((command) => `  ${command}`),
+    ...variableAndSecretSetup(settings, workflow),
     ...workflow.entra ? entraSetup(workflow.entra, repo()) : [],
     "",
-    "Commit and push the workflow; each PR opened from this repo then gets a review."
+    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.`
   ].join("\n");
 }
 
@@ -2185,23 +2200,38 @@ If \`yoke\` is not found, run \`npm i -g @makerx/yoke\` and retry.
 // src/features/review/ciSkill.ts
 var reviewCiSkill = {
   name: "review-ci",
-  description: "Add yoke's adversarial PR review workflow to this repo and set the variable and secret it needs.",
+  description: "Add yoke's adversarial PR review workflow to this repo, or switch its existing LLM review workflow to it, and set the variable and secret it needs.",
   disableModelInvocation: true,
   userLevel: true,
   body: `
-Run \`yoke review-ci $ARGUMENTS\`. If it reports that a model is required, run \`yoke models\` to list what the provider serves, ask the user which model each reviewer should run, and rerun with \`--reviewer-1-model\` and \`--reviewer-2-model\`. If it reports the workflow already exists and differs, show the user the difference and ask before rerunning with \`--force\`.
+Read \`.github/workflows/\`, recent review runs (\`gh run list\`, \`gh run view --log\`) and \`yoke config list\` before asking anything. Only ask what they don't answer, in plain words about the repo, not flags.
 
-With \`--provider foundry\`, if the Foundry resource has local (API key) auth disabled or the user prefers Entra, rerun with \`--azure-client-id\` and \`--azure-tenant-id\` of the Entra app the job signs in as, plus \`--environment\` if the job should run in a GitHub environment. Ask the user for these values; don't guess them.
+## Workflow
 
-Then set the variable and secret it printed. Run \`gh variable list\` and \`gh secret list\` first; if one is missing, ask whether it is already set at the org level before setting it on the repo.
-- \`REVIEW_CI_BASE_URL\` is a variable, not a secret: confirm the URL with the user and run the printed \`gh variable set\` command.
-- \`REVIEW_CI_API_KEY\` must never enter this conversation: ask the user to run \`gh secret set REVIEW_CI_API_KEY\` in their own terminal, outside this session, and paste the key at its prompt. With Entra auth there is no API key to set.
+A workflow is an LLM review if it has a model review PRs, whatever tool it uses.
 
-With Entra auth, show the user the federated credential it printed (issuer, audience, subject) and the \`az ad app federated-credential create\` command, and ask whether to run it or whether they will add the credential in the Azure portal. The app also needs the Cognitive Services User role on the Foundry resource, and the environment, if given, must exist on the repo.
+- **None:** run \`yoke review-ci $ARGUMENTS\`.
+- **One, not yoke's:** run \`yoke review-ci $ARGUMENTS --print\` with its provider and models, then edit that file in place to run yoke's review. Keep its name, triggers, provider, models, base URL, variable and secret names.
+- **Already yoke's** (calls MakerXStudio/yoke's \`review.yml\`, or \`./.github/workflows/review.yml\` in yoke itself): compare with \`--print\` and add only what is missing.
 
-Finish by running \`gh variable list\` and \`gh secret list\` and telling the user to commit and push the workflow file.
+Never ask whether to overwrite a workflow. If \`review-pr.yml\` exists and differs, edit it in place.
 
-If \`yoke\` is not found, run \`npm i -g @makerx/yoke\` and retry.
+If no workflow or setting names the models, ask which model each reviewer runs. For LiteLLM, offer \`yoke models\`. For Foundry, ask for deployment names.
+
+For Foundry with Entra, reuse the client and tenant IDs from the existing workflow; ask only if none is there.
+
+## Variable and secret
+
+Never ask whether they are set for the organisation, and don't query org settings.
+
+- \`REVIEW_CI_BASE_URL\` not in \`gh variable list\`: set it on the repo with the base URL from the workflow or the printed command.
+- \`REVIEW_CI_API_KEY\` not in \`gh secret list\`: tell the user to run \`gh secret set REVIEW_CI_API_KEY\` in their own terminal, and to skip it if the secret is already set for the organisation. Never take the key in this conversation.
+
+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.
+
+If \`yoke\` is not found, run \`npm i -g @makerx/yoke\`.
 `
 };
 
@@ -2227,12 +2257,12 @@ function skillsRoot(user, cwd = process.cwd(), home = homedir3()) {
 function isOwnedByUser(skillFile) {
   return existsSync8(skillFile) && !readFileSync8(skillFile, "utf8").includes(ownerMarker);
 }
-function syncSkills(destination, userDestination, skills = bundledSkills) {
+function syncSkills(destination, userDestination, force = false, skills = bundledSkills) {
   const result = { written: [], skipped: [] };
   for (const skill of skills) {
     const target = join9(skill.userLevel ? userDestination : destination, skill.name);
     const skillFile = join9(target, "SKILL.md");
-    if (isOwnedByUser(skillFile)) {
+    if (!force && isOwnedByUser(skillFile)) {
       result.skipped.push(target);
       continue;
     }
@@ -2246,13 +2276,13 @@ function syncSkills(destination, userDestination, skills = bundledSkills) {
 // src/cli.ts
 var { version } = package_default;
 var program = new Command("yoke").description("Lean Claude Code skills and the CLI they call.").version(version);
-program.command("sync").description("Write yoke's skills into this repo's .claude/skills, or ~/.claude/skills with --user").option("--user", "write to ~/.claude/skills instead, for every repo").action((options) => {
+program.command("sync").description("Write yoke's skills into this repo's .claude/skills, or ~/.claude/skills with --user").option("--user", "write to ~/.claude/skills instead, for every repo").option("--force", "overwrite same-named skills that yoke didn't write").action((options) => {
   const user = options.user ?? false;
   const cwd = process.cwd();
   const display = (path) => path.startsWith(cwd) ? relative(cwd, path) : path;
-  const { written, skipped } = syncSkills(skillsRoot(user), skillsRoot(true));
+  const { written, skipped } = syncSkills(skillsRoot(user), skillsRoot(true), options.force ?? false);
   for (const file of written) console.log(`wrote ${display(file)}`);
-  for (const dir of skipped) console.log(`skipped ${display(dir)} (your own skill; delete it to take yoke's)`);
+  for (const dir of skipped) console.log(`skipped ${display(dir)} (not yoke's skill; rerun with --force to overwrite it)`);
 });
 var pr = program.command("pr").description("Pull request commands");
 pr.command("raise").description("Validate a PR title and body, then create the PR with gh").requiredOption("--title <title>", "single-line PR title").requiredOption("--body <body>", "PR body with ## What, ## Why and optionally ## How").option("--base <branch>", "base branch (defaults to the repo default)").option("--no-draft", "create a ready-for-review PR instead of a draft").addHelpText("after", raiseGuide).action((options) => {
@@ -2310,14 +2340,14 @@ addSettingOptions(
   ).option("--provider <provider>", "litellm or foundry; every slot uses it in CI. Default: review.reviewer1.provider, else litellm").option(
     "--azure-client-id <id>",
     "Entra app (client) ID to sign in to Foundry with GitHub OIDC instead of an API key; needs --provider foundry"
-  ).option("--azure-tenant-id <id>", "Entra tenant ID of that app").option("--environment <name>", "GitHub environment the review job runs in, matching the app's federated credential subject").option("--force", `overwrite an existing ${callerWorkflowPath} that differs`),
+  ).option("--azure-tenant-id <id>", "Entra tenant ID of that app").option("--environment <name>", "GitHub environment the review job runs in, matching the app's federated credential subject").option("--print", `print the workflow and setup commands without writing ${callerWorkflowPath}`),
   ciKeys
 ).addHelpText("after", settingsHelp).action((options) => {
   try {
     const settings = resolveSettings(flagSettings(options, ciKeys), process.env, readUserConfig(userConfigPath()));
     const workflow = callerWorkflow(settings, options.provider, options);
     const root = repoRoot();
-    const outcome = writeCallerWorkflow(root, renderCallerWorkflow(workflow), options.force ?? false);
+    const outcome = options.print ? "printed" : writeCallerWorkflow(root, renderCallerWorkflow(workflow));
     console.log(reviewCiReport(outcome, settings, workflow, () => githubRepo(root)));
   } catch (error) {
     if (!(error instanceof ReviewError || error instanceof ConfigError)) throw error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makerx/yoke",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Lean, user-invoked Claude Code skills for MakerX AI-assisted delivery, plus the CLI they call.",
   "license": "MIT",
   "author": "MakerX",