@arjunkhera/atlas 0.3.44 → 0.3.45

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.3.44",
+  "version": "0.3.45",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, for any repository.",
   "author": {
     "name": "Arjun Khera"

package/door/cli.mjs

@@ -36,6 +36,7 @@ import { issuesCommand as testsIssues } from './lib/issues.mjs';
 import { changedCommand as testsChanged } from './lib/changed-tests.mjs';
 import { beforeCommand as testsBefore } from './lib/fails-before.mjs';
 import { upkeepCommand } from './lib/upkeep.mjs';
+import { gateCommand } from './lib/gate.mjs';
 import { judgeCommand } from './lib/judge.mjs';
 
 export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -124,6 +125,11 @@ const HELP = `atlas — the door into a repo's Atlas files
       --event <file>                   the GitHub pull request event; adds the item check
       --json                           print JSON
 
+  atlas gate apply --repo <owner/name> set the gate: two rulesets from atlas.yaml required_checks, and auto-merge
+      --root <repo>                    the checkout to read atlas.yaml from (default: this folder)
+      --dry-run                        print each call; change nothing
+      --off | --on                     break glass: turn both rulesets off, or back on
+
   atlas judge seal <tasks.md>          the fresh-agent test: check the judge's six candidates, print the seal and the three that run
   atlas judge brief <tasks.md> <id>    print the exact words for one run: the task, then the report form
   atlas judge run <tasks.md> <id> --out <dir>   one fresh agent does one sealed task, in a clean clone at the sealed commit
@@ -161,6 +167,7 @@ export const FLAGS = Object.freeze({
   view: { product: 'value', name: 'value', out: 'value' },
   tests: { root: 'optional', halves: 'value', evidence: 'value', 'guards-from': 'value', tests: 'value', 'dry-run': 'switch', run: 'value', own: 'value', base: 'value', head: 'value', list: 'value', side: 'value', old: 'value', new: 'value', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch', scenario: 'value', language: 'value' },
   upkeep: { root: 'optional', event: 'value', json: 'switch' },
+  gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch' },
   judge: { tasks: 'value', verdict: 'value', seal: 'value', runs: 'value', out: 'value', repo: 'value', budget: 'value', model: 'value' },
   install: { local: 'switch', from: 'value', 'skip-global': 'switch', yes: 'switch' },
   upgrade: { version: 'optional', yes: 'switch' },
@@ -371,6 +378,10 @@ function upkeepVerb(chosen) {
   return upkeepCommand({ what: chosen._[1], event: chosen.event, json: Boolean(chosen.json) }, rootOf(chosen), line);
 }
 
+function gateVerb(chosen) {
+  return gateCommand({ what: chosen._[1], repo: chosen.repo, root: rootOf(chosen), dryRun: Boolean(chosen['dry-run']), off: Boolean(chosen.off), on: Boolean(chosen.on) }, line);
+}
+
 function judgeVerb(chosen) {
   return judgeCommand({ what: chosen._[1], file: chosen._[2], task: chosen._[3], tasks: chosen.tasks, verdict: chosen.verdict, seal: chosen.seal, runs: chosen.runs, out: chosen.out, repo: chosen.repo, budget: chosen.budget, model: chosen.model }, line, PACKAGE_ROOT);
 }
@@ -408,6 +419,7 @@ export async function main(argv = process.argv.slice(2)) {
     case 'view': return viewCommand(chosen);
     case 'tests': return testsCommand(chosen);
     case 'upkeep': return upkeepVerb(chosen);
+    case 'gate': return gateVerb(chosen);
     case 'judge': return judgeVerb(chosen);
     default: throw new Error(`there is no verb "${command}". Run "atlas help".`);
   }

package/door/lib/gate.mjs

@@ -0,0 +1,193 @@
+// `atlas gate apply`: the setup command of the gate (roadmap R9, design
+// docs/design-docs/gate-apply/). The owner runs it with his own GitHub login.
+// It sets two rulesets from the repo's atlas.yaml and allows auto-merge:
+//   1. "atlas gate" on the default branch: a pull request with no approval,
+//      each required check from GitHub Actions, no force push, no delete;
+//   2. "atlas release tags" on v* tags: no update, no delete.
+// The bypass list stays empty. --off and --on are the break glass.
+//
+// The plan is built by pure functions, so a test reads it without GitHub. The
+// gh calls sit in one place, behind `gh`, which a test replaces.
+import { execFileSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { childEnvironment } from '../../work/lib/child-env.mjs';
+import { parseYaml } from '../../shape/check.mjs';
+
+export const BRANCH_RULESET = 'atlas gate';
+export const TAG_RULESET = 'atlas release tags';
+// The app that posts GitHub Actions check runs. A status that another app posts
+// under the same name does not count.
+export const ACTIONS_APP_ID = 15368;
+
+export class GateError extends Error {}
+
+// What the gate reads from atlas.yaml.
+export function gateFacts(root) {
+  const path = join(root, 'atlas.yaml');
+  if (!existsSync(path)) throw new GateError(`there is no atlas.yaml in ${root}. Nothing was changed.`);
+  const facts = parseYaml(readFileSync(path, 'utf8')) ?? {};
+  const checks = facts.required_checks;
+  if (!Array.isArray(checks) || checks.length === 0 || checks.some((name) => typeof name !== 'string' || !name.trim())) {
+    throw new GateError('atlas.yaml lists no required_checks. Nothing was changed.');
+  }
+  if (facts.up_to_date !== undefined && typeof facts.up_to_date !== 'boolean') throw new GateError('atlas.yaml up_to_date must be true or false. Nothing was changed.');
+  return { checks: [...checks], upToDate: facts.up_to_date === true };
+}
+
+// The two ruleset bodies, as the GitHub rulesets API takes them.
+export function rulesets({ checks, upToDate }, enforcement = 'active') {
+  return [
+    {
+      name: BRANCH_RULESET,
+      target: 'branch',
+      enforcement,
+      bypass_actors: [],
+      conditions: { ref_name: { include: ['~DEFAULT_BRANCH'], exclude: [] } },
+      rules: [
+        {
+          type: 'pull_request',
+          parameters: {
+            required_approving_review_count: 0,
+            dismiss_stale_reviews_on_push: false,
+            require_code_owner_review: false,
+            require_last_push_approval: false,
+            required_review_thread_resolution: false,
+          },
+        },
+        {
+          type: 'required_status_checks',
+          parameters: {
+            strict_required_status_checks_policy: upToDate,
+            required_status_checks: checks.map((context) => ({ context, integration_id: ACTIONS_APP_ID })),
+          },
+        },
+        { type: 'non_fast_forward' },
+        { type: 'deletion' },
+      ],
+    },
+    {
+      name: TAG_RULESET,
+      target: 'tag',
+      enforcement,
+      bypass_actors: [],
+      conditions: { ref_name: { include: ['refs/tags/v*'], exclude: [] } },
+      rules: [{ type: 'update' }, { type: 'deletion' }],
+    },
+  ];
+}
+
+// The calls of one run. `existing` is the list GitHub gives for the repo's
+// rulesets: [{ id, name }]. A ruleset that exists is updated, never doubled.
+// In a dry run, a ruleset that does not exist yet shows as <id>.
+export function plan({ repo, facts, existing = [], mode = 'apply', dryRun = false }) {
+  const ids = new Map(existing.map((ruleset) => [ruleset.name, ruleset.id]));
+  if (mode === 'off' || mode === 'on') {
+    const enforcement = mode === 'off' ? 'disabled' : 'active';
+    return [BRANCH_RULESET, TAG_RULESET].map((name) => {
+      if (!ids.has(name) && !dryRun) throw new GateError(`the repo has no ruleset "${name}". Run "atlas gate apply" first.`);
+      return { method: 'PUT', path: `repos/${repo}/rulesets/${ids.get(name) ?? '<id>'}`, name, body: { enforcement } };
+    });
+  }
+  const calls = rulesets(facts).map((body) => (ids.has(body.name)
+    ? { method: 'PUT', path: `repos/${repo}/rulesets/${ids.get(body.name)}`, name: body.name, body }
+    : { method: 'POST', path: `repos/${repo}/rulesets`, name: body.name, body }));
+  calls.push({ method: 'PATCH', path: `repos/${repo}`, name: 'allow auto-merge', body: { allow_auto_merge: true } });
+  return calls;
+}
+
+// One readable block for each call, for the dry run and the log.
+export function describe(call) {
+  const lines = [`${call.method.padEnd(6)} ${call.path}   ${call.name}`];
+  const body = call.body;
+  if (body.rules) {
+    const on = body.target === 'branch' ? `branch ${body.conditions.ref_name.include.join(', ')}` : `tag ${body.conditions.ref_name.include.join(', ')}`;
+    lines.push(`       ${on}, enforcement ${body.enforcement}, bypass ${body.bypass_actors.length ? body.bypass_actors.length : 'none'}`);
+    for (const rule of body.rules) {
+      if (rule.type === 'pull_request') lines.push(`       pull_request: ${rule.parameters.required_approving_review_count} approvals`);
+      else if (rule.type === 'required_status_checks') {
+        lines.push(`       required_status_checks (strict ${rule.parameters.strict_required_status_checks_policy}), from GitHub Actions (${ACTIONS_APP_ID}):`);
+        for (const check of rule.parameters.required_status_checks) lines.push(`         ${check.context}`);
+      } else lines.push(`       ${rule.type}`);
+    }
+  } else {
+    lines.push(`       ${Object.entries(body).map(([key, value]) => `${key} ${value}`).join(', ')}`);
+  }
+  return lines.join('\n');
+}
+
+// What a read-back must hold, compared key by key. Returns the differences.
+export function compare(wanted, got) {
+  const problems = [];
+  if (got.enforcement !== wanted.enforcement) problems.push(`${wanted.name}: enforcement is ${got.enforcement}, not ${wanted.enforcement}`);
+  if ((got.bypass_actors ?? []).length !== 0) problems.push(`${wanted.name}: the bypass list is not empty`);
+  if (JSON.stringify(got.conditions?.ref_name?.include ?? []) !== JSON.stringify(wanted.conditions.ref_name.include)) problems.push(`${wanted.name}: it holds for ${JSON.stringify(got.conditions?.ref_name?.include)}`);
+  for (const rule of wanted.rules) {
+    const found = (got.rules ?? []).find((each) => each.type === rule.type);
+    if (!found) { problems.push(`${wanted.name}: the rule ${rule.type} is missing`); continue; }
+    if (rule.type === 'pull_request' && found.parameters?.required_approving_review_count !== 0) problems.push(`${wanted.name}: pull_request asks for ${found.parameters?.required_approving_review_count} approvals`);
+    if (rule.type === 'required_status_checks') {
+      const key = (check) => `${check.context}|${check.integration_id}`;
+      const want = rule.parameters.required_status_checks.map(key).sort();
+      const have = (found.parameters?.required_status_checks ?? []).map(key).sort();
+      if (JSON.stringify(want) !== JSON.stringify(have)) problems.push(`${wanted.name}: the required checks are ${JSON.stringify(have)}, not ${JSON.stringify(want)}`);
+      if (Boolean(found.parameters?.strict_required_status_checks_policy) !== rule.parameters.strict_required_status_checks_policy) problems.push(`${wanted.name}: up to date is ${found.parameters?.strict_required_status_checks_policy}`);
+    }
+  }
+  return problems;
+}
+
+// The gh door. Each call is `gh api` with a JSON body on stdin.
+export function ghApi(method, path, body) {
+  const args = ['api', '--method', method, path, '-H', 'Accept: application/vnd.github+json'];
+  if (body !== undefined) args.push('--input', '-');
+  const out = execFileSync('gh', args, { encoding: 'utf8', input: body === undefined ? undefined : JSON.stringify(body), env: childEnvironment(), stdio: ['pipe', 'pipe', 'pipe'] });
+  return out.trim() ? JSON.parse(out) : null;
+}
+
+const explain = (error) => {
+  const text = `${error.stderr ?? ''}${error.message ?? ''}`;
+  if (/HTTP 403|Upgrade to GitHub Pro|403/.test(text)) return 'GitHub refused the ruleset (403). A private repo needs GitHub Pro for rulesets, and only a repo admin may set one.';
+  return text.trim().split('\n').slice(-3).join(' ');
+};
+
+// `atlas gate apply`. Returns the exit code.
+export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false }, line, gh = ghApi) {
+  if (what !== 'apply') throw new GateError(`there is no gate verb "${what ?? ''}". Use apply.`);
+  if (!repo || repo === true || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) throw new GateError('atlas gate apply needs --repo <owner/name>.');
+  if (off && on) throw new GateError('pick --off or --on, not both.');
+  const mode = off ? 'off' : on ? 'on' : 'apply';
+  const facts = mode === 'apply' ? gateFacts(root) : null;
+  if (dryRun) line('atlas gate apply: dry run, nothing changes.');
+  if (facts) line(`atlas.yaml read from ${root}: ${facts.checks.length} required check(s), up_to_date ${facts.upToDate}.`);
+  line(`GET    repos/${repo}/rulesets`);
+  let existing;
+  try { existing = gh('GET', `repos/${repo}/rulesets`) ?? []; } catch (error) {
+    if (!dryRun) { line(`atlas gate apply: ${explain(error)} Nothing was changed.`); return 1; }
+    line(`       (the read failed: ${explain(error)} The plan below assumes no ruleset exists.)`);
+    existing = [];
+  }
+  const calls = plan({ repo, facts, existing, mode, dryRun });
+  for (const call of calls) line(describe(call));
+  if (dryRun) return 0;
+  const written = [];
+  for (const call of calls) {
+    try { written.push({ call, answer: gh(call.method, call.path, call.body) }); } catch (error) {
+      line(`atlas gate apply: ${call.method} ${call.path} failed: ${explain(error)}`);
+      line(written.length ? `Done before the failure: ${written.map((each) => each.call.name).join(', ')}.` : 'Nothing was changed.');
+      return 1;
+    }
+  }
+  if (mode !== 'apply') { line(`atlas gate apply: both rulesets are ${mode === 'off' ? 'disabled' : 'active'}.`); return 0; }
+  const problems = [];
+  for (const wanted of rulesets(facts)) {
+    const id = written.find((each) => each.call.name === wanted.name)?.answer?.id ?? existing.find((ruleset) => ruleset.name === wanted.name)?.id;
+    const got = gh('GET', `repos/${repo}/rulesets/${id}`);
+    problems.push(...compare(wanted, got ?? {}));
+  }
+  const settings = gh('GET', `repos/${repo}`);
+  if (settings?.allow_auto_merge !== true) problems.push('the repo does not allow auto-merge');
+  if (problems.length) { for (const problem of problems) line(`  ✗ ${problem}`); line('atlas gate apply: the read-back differs. Look at the repo settings.'); return 1; }
+  line(`atlas gate apply: the gate is on for ${repo}. Read back: ${BRANCH_RULESET}, ${TAG_RULESET}, allow_auto_merge true.`);
+  return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.3.44",
+  "version": "0.3.45",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",

package/skills/lead/SKILL.md

@@ -105,6 +105,7 @@ set. A test keeps the two lists equal.
 | `atlas design` | `folder` to learn where designs live; `check` before you show a design; `build` to make its page |
 | `atlas view` | `build --product <id>` makes the project view page of one product, when the owner asks for it or after an Atlas release changes it. Publish it with only the grant the command prints |
 | `atlas upkeep` | `check` before you ask for a merge: the docs index, dead doc links, and the tracker item a pull request names. The daily upkeep run calls it on the main branch |
+| `atlas gate` | `apply` once per repo, by the owner on his Mac, after the repo's `required_checks` exist. `--dry-run` first. `--off` and `--on` are the break glass |
 | `atlas judge` | In the fresh-agent test only, as the `atlas:fresh-agent-test` skill says. `seal` after the pick, `brief` to read a sealed ask, `run` for each sealed task, `check` after the grade |
 
 A person merges every file that `atlas tooling` writes.