@arjunkhera/atlas 0.4.21 → 0.4.22

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -141,6 +141,7 @@ const HELP = `atlas — the door into a repo's Atlas files
 
   atlas upkeep check --root <repo>     the upkeep check: the docs index, dead doc links, the code each doc names, and in a pull request its tracker item
   atlas upkeep replay --root <repo>    what the doc-sources rule would have asked of the last merges; writes nothing
+  atlas upkeep procedures --root <repo>  run the procedure steps marked atlas-run; --base <ref> runs only the procedures a change touches
       --last <n>                       how many merges on the first-parent line; default 30
       --event <file>                   the GitHub pull request event; adds the item check
       --json                           print JSON
@@ -214,7 +215,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' },
   jobs: { root: 'optional', repo: 'value', branch: 'value', out: 'value', findings: 'value', max: 'value', 'dry-run': 'switch' },
-  upkeep: { root: 'optional', event: 'value', json: 'switch', last: 'value' },
+  upkeep: { root: 'optional', event: 'value', json: 'switch', last: 'value', base: 'value' },
   gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value', base: 'value', 'base-ref': 'value', head: 'value', body: 'value', json: 'switch', summary: 'value', output: 'value', days: 'value', branch: 'value' },
   approve: { repo: 'value', root: 'optional', key: 'value', provider: 'value', yes: 'switch', out: 'value', file: 'value', signers: 'value', commit: 'value', item: 'value', card: 'value', words: 'value', pr: 'value', head: 'value', decision: 'value', check: 'value' },
   judge: { tasks: 'value', verdict: 'value', seal: 'value', runs: 'value', out: 'value', repo: 'value', budget: 'value', model: 'value' },
@@ -461,7 +462,7 @@ function jobsVerb(chosen) {
 }
 
 function upkeepVerb(chosen) {
-  return upkeepCommand({ what: chosen._[1], event: chosen.event, json: Boolean(chosen.json), last: chosen.last }, rootOf(chosen), line);
+  return upkeepCommand({ what: chosen._[1], event: chosen.event, json: Boolean(chosen.json), last: chosen.last, base: chosen.base }, rootOf(chosen), line);
 }
 
 function gateVerb(chosen) {

package/door/lib/procedure-steps.mjs

@@ -0,0 +1,122 @@
+// CI runs the procedures (roadmap R40, item 38b2a0fe). Target design 4.6: CI
+// runs each procedure step that a clean machine can run.
+//
+// A procedure marks such a step with a fenced block whose info string holds
+// the tag `atlas-run`:
+//
+//   ```sh atlas-run
+//   npm test
+//   ```
+//
+// A step that needs what a clean machine does not have names it after the
+// tag: `atlas-run needs=secret/NPM_TOKEN` or `atlas-run needs=device/macos`.
+// Such a step is listed as "not run here", never as passed.
+//
+// `atlas upkeep procedures` runs the marked steps of each procedure that
+// atlas.yaml `procedures:` names. With --base, it runs only the procedures a
+// pull request changes: its own folder, or a path its `sources:` names. Each
+// block runs in bash, from the repo root, with `set -euo pipefail`. It reads
+// no repo kind, so a repo with no deploy target uses it unchanged.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fenceOpens, fenceCloses } from './markdown.mjs';
+import { docUnits, covers, changedPaths } from './doc-sources.mjs';
+
+export const TAG = 'atlas-run';
+const SHELLS = new Set(['sh', 'bash', 'shell']);
+const NEEDS = new Set(['secret', 'device', 'network']);
+// The bound on one block. A step that runs longer is a failure. It sits
+// below the 10 minutes of the CI job, so the step fails with a reason.
+export const STEP_TIMEOUT_MS = 8 * 60 * 1000;
+
+// Line 1: the marked steps of one procedure text. Each step is one fenced
+// block. `problems` holds a tag that cannot run as written.
+export function markedSteps(text) {
+  const steps = [];
+  const problems = [];
+  const lines = String(text ?? '').split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    const mark = fenceOpens(lines[i]);
+    if (!mark) continue;
+    const info = lines[i].trim().slice(mark.length).trim().split(/\s+/).filter(Boolean);
+    const start = i;
+    const body = [];
+    for (i += 1; i < lines.length && !fenceCloses(lines[i], mark); i += 1) body.push(lines[i]);
+    if (!info.includes(TAG)) continue;
+    const line = start + 1;
+    const lang = info[0] === TAG ? null : info[0];
+    if (!SHELLS.has(lang)) { problems.push({ line, why: `the block is tagged ${TAG} but its language is ${lang ?? 'missing'}; use sh or bash` }); continue; }
+    if (i >= lines.length) { problems.push({ line, why: 'the block never closes' }); continue; }
+    const needs = [];
+    let bad = null;
+    for (const word of info.slice(info.indexOf(TAG) + 1)) {
+      const m = /^needs=(.+)$/.exec(word);
+      if (!m) { bad = `"${word}" after ${TAG} is not needs=<kind>/<name>`; break; }
+      for (const one of m[1].split(',')) {
+        const [kind, name] = one.split('/');
+        if (!NEEDS.has(kind) || !name) { bad = `"${one}" is not one of ${[...NEEDS].map((k) => `${k}/<name>`).join(', ')}`; break; }
+        needs.push({ kind, name });
+      }
+      if (bad) break;
+    }
+    if (bad) { problems.push({ line, why: bad }); continue; }
+    const script = body.join('\n').trim();
+    if (!script) { problems.push({ line, why: 'the block is empty' }); continue; }
+    steps.push({ line, script, needs });
+  }
+  return { steps, problems };
+}
+
+// The procedures to run. With `changed`, only those a pull request changes:
+// a path in the procedure's folder, or a path its `sources:` names.
+export function proceduresToRun(root, changed = null) {
+  const units = docUnits(root).filter((one) => one.kind === 'procedure');
+  if (changed === null) return units;
+  return units.filter((one) => changed.some((path) => path.startsWith(`${one.unit}/`)
+    || (one.named?.sources ?? []).some((source) => covers(root, source, path))));
+}
+
+const needsText = (needs) => needs.map((one) => `${one.kind} ${one.name}`).join(', ');
+
+// Line 2 and line 3: run each marked step of each chosen procedure. A step
+// that needs a secret, a device or the network is "not run here".
+export function runProcedures(root, { base = null, run = runStep } = {}) {
+  const changed = base === null ? null : changedPaths(root, `${base}...HEAD`);
+  const chosen = proceduresToRun(root, changed);
+  const rows = [];
+  for (const unit of chosen) {
+    const { steps, problems } = markedSteps(readFileSync(join(root, unit.where), 'utf8'));
+    for (const one of problems) rows.push({ procedure: unit.unit, where: `${unit.where}:${one.line}`, state: 'bad tag', why: one.why });
+    if (!steps.length && !problems.length) rows.push({ procedure: unit.unit, where: unit.where, state: 'no step', why: `it marks no step with ${TAG}` });
+    for (const step of steps) {
+      const where = `${unit.where}:${step.line}`;
+      if (step.needs.length) { rows.push({ procedure: unit.unit, where, state: 'not run here', why: `needs ${needsText(step.needs)}` }); continue; }
+      const result = run(root, step.script);
+      rows.push({ procedure: unit.unit, where, state: result.ok ? 'passed' : 'failed', why: result.why, tail: result.tail });
+    }
+  }
+  const red = rows.filter((row) => row.state === 'failed' || row.state === 'bad tag');
+  return { procedures: chosen.map((one) => one.unit), all: changed === null, rows, green: red.length === 0 };
+}
+
+export function runStep(root, script) {
+  const out = spawnSync('bash', ['-c', `set -euo pipefail\n${script}`], { cwd: root, encoding: 'utf8', timeout: STEP_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024 });
+  const tail = `${out.stdout ?? ''}${out.stderr ?? ''}`.trimEnd().split('\n').slice(-20).join('\n');
+  if (out.error?.code === 'ETIMEDOUT') return { ok: false, why: `it ran past ${STEP_TIMEOUT_MS / 60000} minutes`, tail };
+  if (out.error) return { ok: false, why: out.error.message, tail };
+  return out.status === 0 ? { ok: true, why: 'exit 0', tail } : { ok: false, why: `exit ${out.status ?? out.signal}`, tail };
+}
+
+// `atlas upkeep procedures`.
+export function proceduresCommand({ base = null, json = false }, root, line) {
+  const out = runProcedures(root, { base });
+  if (json) { process.stdout.write(`${JSON.stringify(out, null, 2)}\n`); return out.green ? 0 : 1; }
+  line(`procedures: ${out.procedures.length} to run${out.all ? '' : ` (the ones this change touches, from ${base})`}${out.procedures.length ? `: ${out.procedures.join(', ')}` : ''}`);
+  for (const row of out.rows) {
+    line(`  ${row.state.padEnd(12)} ${row.where}  ${row.why}`);
+    if (row.state === 'failed' && row.tail) for (const one of row.tail.split('\n')) line(`      | ${one}`);
+  }
+  line(`procedure steps: ${out.green ? 'GREEN' : 'RED'}`);
+  return out.green ? 0 : 1;
+}

package/door/lib/upkeep.mjs

@@ -23,6 +23,7 @@ import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
 import { join, dirname, posix, resolve } from 'node:path';
 import { listChanged } from './changed-tests.mjs';
 import { docSourceFindings, replay } from './doc-sources.mjs';
+import { proceduresCommand } from './procedure-steps.mjs';
 
 // R39 line 4 gates only after the replay of line 3. The replay of the last 30
 // merges (atlas#225): rule "file" pulled in 81 docs over 24 merges, 58 not
@@ -246,9 +247,10 @@ export function upkeepCheck(root, { event = null } = {}) {
   return { green: findings.length === 0, findings, notes: sources.notes, index, dead, item, text, sources };
 }
 
-export function upkeepCommand({ what, event: eventFile, json = false, last }, root, line) {
+export function upkeepCommand({ what, event: eventFile, json = false, last, base }, root, line) {
   if (what === 'replay') return replayCommand({ last, json }, root, line);
-  if (what !== 'check') throw new Error(`there is no upkeep verb "${what ?? ''}". Use atlas upkeep check, or atlas upkeep replay.`);
+  if (what === 'procedures') return proceduresCommand({ base: base ?? null, json }, root, line);
+  if (what !== 'check') throw new Error(`there is no upkeep verb "${what ?? ''}". Use atlas upkeep check, atlas upkeep replay or atlas upkeep procedures.`);
   let event = null;
   if (eventFile !== undefined) {
     try { event = JSON.parse(readFileSync(resolve(eventFile), 'utf8')); } catch (error) { throw new Error(`cannot read the event file ${eventFile}: ${error.message}`); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.21",
+  "version": "0.4.22",
   "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

@@ -110,7 +110,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 jobs` | The `atlas-jobs` workflow calls `check`, then `file`, once a day. A session calls it only to see what the watcher would file: `check`, then `file --dry-run` |
-| `atlas upkeep` | `check` before you ask for a merge. It reads the docs index, dead doc links, the code each doc names, and the tracker item of a pull request. The daily upkeep run calls it on the main branch. `replay` before the doc-sources rule changes how it gates |
+| `atlas upkeep` | `check` before you ask for a merge. It reads the docs index, dead doc links, the code each doc names, and the tracker item of a pull request. The daily upkeep run calls it on the main branch. `replay` before the doc-sources rule changes how it gates. `procedures` runs the procedure steps tagged `atlas-run`; CI runs it with `--base` on each pull request |
 | `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. On a plan with no rulesets it reports advisory mode. `ready` before each merge, `check` in the `atlas-gate` workflow, `replay` before a change to the owner-only list. `audit` in the daily upkeep run, and with `--commit` in the push job of a repo that has one |
 | `atlas approve` | Never from a session. Only the owner runs it, on his Mac, with his key's touch. When the gate says "owner" for a pull request, ask him once for the signed act: name each pull request, its class and its cause. Put the owner pull requests of one day in one ask, so one touch signs them. `act`, `verify` and `key-check` work the same way |
 | `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 |

package/skills/repo-skills/SKILL.md

@@ -27,19 +27,24 @@ the form the repo already uses for that kind of thing.
    deploy. A rule says how to judge a change. They have different approval
    rules, so split a skill that holds both.
 4. **Write the header Atlas reads,** for a skill file. It names the type,
-   the commands and files, and the code it covers. It says how CI runs
-   it, if CI can. Today the Atlas check reads only `name` and
-   `description`, and finds the skill when `procedures` in `atlas.yaml`
-   names it. Later upkeep checks read the other keys, so keep each true.
-5. **Keep it to this repo.** A step that holds how to work in general
+   the commands and files, and the code it covers in `sources:`. The
+   Atlas check finds the skill when `procedures` in `atlas.yaml` names
+   it. `atlas upkeep check` reads `sources:`.
+5. **Tag each step a clean machine can run.** Put its commands in a
+   fenced block. Open it with ```` ```sh atlas-run ````. CI runs each
+   such block when a pull request changes the skill or its sources. A
+   step that needs a secret, a device or the network gets
+   `needs=secret/<name>`, `needs=device/<name>` or `needs=network/<name>`
+   after the tag. CI lists it as "not run here".
+6. **Keep it to this repo.** A step that holds how to work in general
    belongs in Atlas. Do not put it here. Propose it to Atlas with the
    `atlas:feedback` skill.
-6. **Follow the repo's own rules.** Read its entry file first. Some repos
+7. **Follow the repo's own rules.** Read its entry file first. Some repos
    ask for one area folder for each change, or a status file updated
    when the state changes. Keep to them.
-7. **Prove the steps once.** Ask the `atlas:verifier` crew to run them in
+8. **Prove the steps once.** Ask the `atlas:verifier` crew to run them in
    a fresh worktree, before you ask for the merge.
-8. **Write the pull request text.** Say what you found, what you kept,
+9. **Write the pull request text.** Say what you found, what you kept,
    and the gap you closed.
 
 ## The header of a skill file
@@ -51,9 +56,8 @@ description: <when to use it, in one or two sentences>
 type: task            # or rule
 names:                # each command and file the steps name
   - <command or path>
-covers:               # the code this skill describes
+sources:              # the code this skill describes
   - <path>
-ci: <how CI runs it, or "cannot run in CI">
 ---
 ```