@arjunkhera/atlas 0.4.22 → 0.4.24

package/door/lib/jobs.mjs

@@ -25,6 +25,8 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseYaml } from '../../shape/check.mjs';
 import { api, apiBase, repoOk, openIssues, TOKEN_SHAPE, DEFAULT_BOT, DEFAULT_MAX } from './issues.mjs';
+import { checkGateFiles, checkGateAudit, checkGateErrors } from './gate-audit.mjs';
+import { commitAudit, ghApi } from './gate.mjs';
 
 export const JOBS_LABEL = 'atlas-job';
 export const HANDED_OVER = 'handed-over';
@@ -107,9 +109,16 @@ export async function checkRedMain({ repo, branch, env }) {
 
 // The check of each Atlas job, by its `when`. A job whose check is not built yet reads `none` and
 // says so in the notes; it never reads `found` from nothing.
-const CHECKS = { 'red-main': checkRedMain };
+// The gate jobs (roadmap R14) read GitHub through `gh`, which the Actions
+// runner holds; their token is the run's own GITHUB_TOKEN.
+const CHECKS = {
+  'red-main': checkRedMain,
+  'gate-files': ({ root, env, fetchImpl }) => checkGateFiles({ root, env, fetchImpl }),
+  'gate-audit': ({ repo, branch, gh }) => checkGateAudit({ repo, branch, gh, audit: commitAudit }),
+  'gate-errors': ({ repo, gh }) => checkGateErrors({ repo, gh }),
+};
 
-export async function jobsCheck({ root, repo, branch = null, env = process.env, jobs = atlasJobs() }) {
+export async function jobsCheck({ root, repo, branch = null, env = process.env, jobs = atlasJobs(), gh = ghApi, fetchImpl = fetch }) {
   const named = namedJobs(root);
   const notes = [];
   const ran = [];
@@ -123,7 +132,10 @@ export async function jobsCheck({ root, repo, branch = null, env = process.env,
     if (!check) { notes.push(`${id}: its check is not built yet`); ran.push({ job: id, state: 'none' }); continue; }
     try {
       if (!mainBranch) mainBranch = await defaultBranch({ repo, env });
-      const found = (await check({ repo, branch: mainBranch, env })).map((f) => ({ ...f, job: id }));
+      // A check gives its findings, or { findings, notes }.
+      const got = await check({ repo, branch: mainBranch, env, root, gh, fetchImpl });
+      const found = (Array.isArray(got) ? got : got.findings).map((f) => ({ ...f, job: id }));
+      for (const note of Array.isArray(got) ? [] : got.notes ?? []) notes.push(`${id}: ${String(note).slice(0, 300)}`);
       findings.push(...found);
       ran.push({ job: id, state: found.length ? 'found' : 'none' });
     } catch (error) {
@@ -194,13 +206,22 @@ export function jobIssue(finding) {
 export const handedOverStops = (now = Date.now()) => (issue) => (issue.labels ?? []).some((l) => (typeof l === 'string' ? l : l?.name) === HANDED_OVER)
   && Number.isFinite(Date.parse(issue.closed_at)) && now - Date.parse(issue.closed_at) <= HANDED_OVER_DAYS * DAY;
 
+// A job with `handed_over: ignored` never stops on a closed issue: anyone with
+// the shared login can close an issue, so a gate finding comes back while its
+// commit is in the window (roadmap R14).
+export const closedStopsFor = (jobs, now = Date.now()) => (issue) => {
+  const job = (issue.labels ?? []).map((l) => (typeof l === 'string' ? l : l?.name)).find((name) => String(name).startsWith('job:'));
+  if (job && jobs.get(job.slice(4))?.handed_over === 'ignored') return false;
+  return handedOverStops(now)(issue);
+};
+
 export async function fileJobs({ envelope, repo, dryRun = false, max = DEFAULT_MAX, bot = DEFAULT_BOT, env = process.env, line, now = Date.now(), jobs = atlasJobs() }) {
   const { findings, dropped } = typedFindings(envelope, jobs);
   if (dropped) line(`dropped ${dropped} finding(s) that are not typed, or that name no Atlas job`);
   if (envelope.state === 'broken') line('the check reads broken, so a check found nothing it can trust. The run ends red.');
   const list = findings.map((f) => ({ key: `${f.job}:${f.key}`, issue: jobIssue(f) }));
   const result = list.length
-    ? await openIssues({ findings: list, repo, dryRun, max, bot, env, line, label: JOBS_LABEL, closedStops: handedOverStops(now) })
+    ? await openIssues({ findings: list, repo, dryRun, max, bot, env, line, label: JOBS_LABEL, closedStops: closedStopsFor(jobs, now) })
     : (line('no finding: nothing to file.'), { opened: [], skipped: [], deferred: [], failed: [] });
   return { ...result, broken: envelope.state === 'broken' };
 }

package/door/templates/atlas-jobs.yml

@@ -5,7 +5,9 @@ name: atlas-jobs
 # It runs once a day from the default branch, and never on a pull request, so
 # a pull request cannot change what it runs. It has two jobs:
 #   check  reads the repo and the CI runs of the default branch. It holds only
-#          read permissions and the run's own token, and no repo secret.
+#          read permissions and the run's own token, and no repo secret. The
+#          gate jobs (gate-audit, gate-errors) also read pull requests and
+#          check runs, so the job reads those two as well.
 #   file   holds only issues write. It runs Atlas code on the JSON of the
 #          check job, and files one `atlas-job` issue for each new finding.
 # A job does nothing until atlas.yaml names it under `jobs: { atlas: [...] }`.
@@ -28,6 +30,8 @@ jobs:
     permissions:
       contents: read
       actions: read
+      pull-requests: read
+      checks: read
     outputs:
       findings: ${{ steps.check.outputs.findings }}
     steps:

package/door/workflows/atlas-gate-audit.yml

@@ -0,0 +1,128 @@
+name: atlas-gate-audit
+on:
+  push:
+    branches: [master]
+
+# The push audit of the advisory gate (roadmap R14, design
+# docs/design-docs/audit-job/). This plan gives the repo no rulesets, so
+# GitHub merges and takes pushes with no check. This workflow looks at each
+# commit that a push put on the main branch, along the first parent:
+#   1. A commit that no pull request merged is a push past the gate.
+#   2. A force push.
+#   3. A merge made before the required checks of its pull request were
+#      green. A check counts only from a run of the base file that defines it.
+#   4. A gate run that is not from the base copy of atlas-gate.yml.
+# Each finding opens one `atlas-job` issue, and the run ends red. It does not
+# undo the push.
+#
+# It runs the code of the pushed commit, so a push can edit it and hide. The
+# watcher (atlas-jobs.yml) runs the npm copy of Atlas once a day. It audits
+# the commits of the last two days again, and compares these files with the
+# latest release. A test keeps this file byte identical to
+# packages/atlas/door/workflows/atlas-gate-audit.yml.
+#
+# Two jobs, each with only what it needs:
+#   audit  read rights only. It writes the findings as job output.
+#   file   contents: read for the checkout, and issues: write. That is the
+#          only write right of this workflow.
+permissions: {}
+
+concurrency:
+  group: atlas-gate-audit-${{ github.sha }}
+  cancel-in-progress: false
+
+jobs:
+  audit:
+    name: gate · push audit
+    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pull-requests: read
+      checks: read
+      actions: read
+    outputs:
+      findings: ${{ steps.audit.outputs.findings }}
+    steps:
+      # actions/checkout v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+
+      - name: Audit each commit of this push
+        id: audit
+        env:
+          GH_TOKEN: ${{ github.token }}
+          BEFORE: ${{ github.event.before }}
+          AFTER: ${{ github.event.after }}
+          FORCED: ${{ github.event.forced }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -uo pipefail
+          out="$RUNNER_TEMP/findings.json"
+          # keep FILE [FROM]: add the findings of FROM to FILE, through Atlas code.
+          keep() { node --input-type=module -e 'import { keepFindings } from "./packages/atlas/door/lib/gate-audit.mjs"; import { readFileSync, existsSync } from "node:fs"; const [to, from] = process.argv.slice(1); const have = from && existsSync(from) ? JSON.parse(readFileSync(from, "utf8")) : { findings: [] }; keepFindings(to, have.findings ?? [], { broken: have.state === "broken" });' "$@"; }
+          keep "$out"
+          forced=()
+          if [ "$FORCED" = "true" ]; then forced=(--forced); fi
+          if [ -z "${BEFORE//0/}" ] || [ "$FORCED" = "true" ] || ! git cat-file -e "$BEFORE^{commit}" 2>/dev/null; then
+            commits="$AFTER"
+          else
+            commits=$(git rev-list --first-parent --reverse "$BEFORE..$AFTER")
+          fi
+          for sha in $commits; do
+            flag=()
+            if [ "$sha" = "$AFTER" ]; then flag=("${forced[@]}"); fi
+            # GitHub can take a moment to link a fresh merge to its pull
+            # request. So a "no pull request" answer gets one more read, with
+            # a fresh findings file.
+            if ! text=$(node packages/atlas/bin/atlas gate audit --repo "$REPO" --commit "$sha" "${flag[@]}" --findings "$out.$sha"); then
+              if grep -q '^RED PUSH' <<<"$text"; then
+                sleep 30
+                rm -f "$out.$sha"
+                text=$(node packages/atlas/bin/atlas gate audit --repo "$REPO" --commit "$sha" "${flag[@]}" --findings "$out.$sha")
+              fi
+            fi
+            printf '%s\n' "$text" | tee -a "$GITHUB_STEP_SUMMARY"
+            # A run that wrote no file stopped before it could: mark it broken.
+            if [ -s "$out.$sha" ]; then keep "$out" "$out.$sha"; else echo '{"jobs":1,"state":"broken","findings":[]}' > "$out.$sha"; keep "$out" "$out.$sha"; fi
+          done
+          echo "findings=$(base64 -w0 < "$out")" >> "$GITHUB_OUTPUT"
+
+  file:
+    name: gate · push audit issues
+    needs: audit
+    if: always() && needs.audit.outputs.findings != ''
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      # actions/checkout v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          persist-credentials: false
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+      - name: File one issue for each new finding
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          FINDINGS: ${{ needs.audit.outputs.findings }}
+        run: |
+          set -euo pipefail
+          printf '%s' "$FINDINGS" | base64 -d > "$RUNNER_TEMP/findings.json"
+          node packages/atlas/bin/atlas jobs file --findings "$RUNNER_TEMP/findings.json" --repo "$GITHUB_REPOSITORY" | tee -a "$GITHUB_STEP_SUMMARY"
+          state=$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).state' "$RUNNER_TEMP/findings.json")
+          if [ "$state" != "none" ]; then
+            echo "::error::the push audit found a break of the gate (state $state). Read the issues it opened."
+            exit 1
+          fi

package/door/workflows/atlas-gate.yml

@@ -0,0 +1,142 @@
+name: atlas-gate
+run-name: "gate #${{ github.event.pull_request.number }} at ${{ github.event.pull_request.head.sha }}"
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, edited, ready_for_review]
+
+# The gate (roadmap R6, design docs/design-docs/gate-check/). One job, named
+# `gate`, ends as success, or as failure with "owner: class" or "red: reason"
+# in its summary. It judges the pull request by the static rules: the
+# owner-only list, secrets of a known shape, head jobs named like a check, and
+# a test change for product code.
+#
+# It runs on pull_request_target, so GitHub runs this file as the base branch
+# holds it, with the base code. The head is fetched as git objects only and is
+# never checked out, built or run. atlas.yaml comes from the base side only.
+# The title of the run names the pull request and the head; `atlas gate ready`
+# reads it to pin the run (done line 8).
+#
+# The token can only read. No checkout keeps a credential: the one fetch of
+# the head takes the token for that command alone. The job writes two output
+# keys, `result` and `class`, each one word of a fixed set.
+#
+# The signed act (roadmap R72): the gate reads the comments of the pull
+# request, and a valid signature of the owner for this head turns "owner" into
+# success. The key comes from atlas/owner-signers on the base. A new comment
+# with a signed act reruns this run (atlas-gate-signed.yml).
+#
+# Report mode: the gate is not in required_checks yet. It joins the list after
+# the A1 exit test of the overhaul roadmap.
+#
+# The second job, `shape`, is the repo shape check from the base (roadmap R7,
+# design docs/design-docs/shape-check-from-base/). It is the job that
+# `atlas tooling` writes into every repo, word for word, and `atlas status`
+# compares it with the package.
+permissions:
+  contents: read
+  pull-requests: read
+  issues: read
+  checks: read
+  actions: read
+
+concurrency:
+  group: atlas-gate-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  gate:
+    name: gate
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      result: ${{ steps.check.outputs.result }}
+      class: ${{ steps.check.outputs.class }}
+    steps:
+      # actions/checkout v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+
+      - name: Fetch the head as objects only
+        env:
+          PR: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          header="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$TOKEN" | base64 -w0)"
+          git -c "http.https://github.com/.extraheader=$header" fetch --no-tags --no-recurse-submodules origin "+refs/pull/$PR/head:refs/atlas-gate/head"
+          got="$(git rev-parse --verify refs/atlas-gate/head^{commit})"
+          if [ "$got" != "$HEAD_SHA" ]; then
+            echo "::error::the fetched head is $got, not the head of the event $HEAD_SHA. Push again."
+            exit 1
+          fi
+
+      - name: Read the pull request text from the event
+        run: node -e 'const fs=require("fs");const e=JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH,"utf8"));fs.writeFileSync(process.env.RUNNER_TEMP+"/body.md",String(e.pull_request.body??""))'
+
+      - name: Gate check
+        id: check
+        env:
+          PR: ${{ github.event.pull_request.number }}
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          node packages/atlas/bin/atlas gate check --root . --repo "$GITHUB_REPOSITORY" --base "$GITHUB_SHA" --head "$HEAD_SHA" --pr "$PR" --base-ref "$BASE_REF" --body "$RUNNER_TEMP/body.md" --summary "$GITHUB_STEP_SUMMARY" --output "$GITHUB_OUTPUT"
+
+  shape:
+    name: gate · shape
+    runs-on: ubuntu-latest
+    # The check reads two trees and opens no network. It finishes in seconds
+    # on a small repo. The bound stops a runner being billed until someone
+    # kills it; a run that hits it is red.
+    timeout-minutes: 10
+    outputs:
+      result: ${{ steps.shape.outputs.result }}
+      class: ${{ steps.shape.outputs.class }}
+    steps:
+      # actions/checkout v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+      - name: Fetch the head as objects only
+        env:
+          PR: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          header="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$TOKEN" | base64 -w0)"
+          git -c "http.https://github.com/.extraheader=$header" fetch --no-tags --no-recurse-submodules origin "+refs/pull/$PR/head:refs/atlas-gate/head"
+          got="$(git rev-parse --verify refs/atlas-gate/head^{commit})"
+          if [ "$got" != "$HEAD_SHA" ]; then
+            echo "::error::the fetched head is $got, not the head of the event $HEAD_SHA. Push again."
+            exit 1
+          fi
+      - name: Shape check from the base
+        id: shape
+        env:
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+          if [ ! -f .github/atlas/check.mjs ]; then
+            echo "OWNER: first-run: the base has no .github/atlas/check.mjs, so the owner reads the first shape"
+            echo "result=owner" >> "$GITHUB_OUTPUT"
+            echo "class=first-run" >> "$GITHUB_OUTPUT"
+            exit 1
+          fi
+          node .github/atlas/check.mjs --gate --repo "$GITHUB_REPOSITORY" --base-commit "$GITHUB_SHA" --head-commit "$HEAD_SHA"

package/hooks/step-in.mjs

@@ -5,7 +5,8 @@
 // every test that reads the count.
 //
 // Its limits are the reason the package may ship it:
-// 1. A row holds the time, the session and the repos. It never holds the
+// 1. A row holds the time, the session and the repos, and `from: platform`
+//    when a platform sent the message (item f7391622). It never holds the
 //    text of the message.
 // 2. It makes no network call, reads no key and starts no program. It reads
 //    the hook input, atlas.yaml in the session folder or one level down, and
@@ -24,6 +25,11 @@ import { fileURLToPath } from 'node:url';
 const MAX_REPOS = 16;
 const REPO = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}\/[A-Za-z0-9_.-]{1,100}$/;
 const SESSION = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/;
+// Item f7391622: in a cloud project the platform also sends messages to the
+// session, such as a reminder, a relay or a pull request event. A message
+// that starts with one of these tags is the platform's.
+const PLATFORM_TAGS = ['wake', 'session-context', 'relay', 'coordinator-relay', 'system-reminder', 'task-notification'];
+const READ_BYTES = 65536;
 
 // The folder that the hook writes and the Atlas tools read. The tools keep
 // their own copy of the path, because these bytes are pinned.
@@ -52,13 +58,32 @@ export function reposOf(cwd) {
   return [...new Set(found.map((name) => repoOf(join(cwd, name, 'atlas.yaml'))).filter(Boolean))].slice(0, MAX_REPOS);
 }
 
+// Who sent one message, from its first bytes: 'owner' or 'platform'. The
+// text is read here and never kept.
+// 1. A <message> tag with trigger="true" and from="human" is the owner's. A
+//    cloud project wraps an owner message this way.
+// 2. A message that starts with a platform tag is the platform's.
+// 3. Any other message is the owner's, so an unknown shape counts high.
+export function senderOf(prompt) {
+  if (typeof prompt !== 'string') return 'owner';
+  const head = prompt.slice(0, READ_BYTES);
+  for (const match of head.matchAll(/<message\b([^>]*)>/g)) {
+    const attrs = match[1];
+    if (/\btrigger="true"/.test(attrs) && /\bfrom="human"/.test(attrs)) return 'owner';
+  }
+  const tag = /^\s*<([a-z][a-z-]*)[\s>]/.exec(head);
+  return tag && PLATFORM_TAGS.includes(tag[1]) ? 'platform' : 'owner';
+}
+
 // One message in, one row out, or null when no row is due.
 export function rowOf(input, { now = new Date(), id = randomUUID() } = {}) {
   const session = typeof input?.session_id === 'string' && SESSION.test(input.session_id) ? input.session_id : null;
   if (!session) return null;
   const repos = reposOf(input?.cwd);
   if (repos === null) return null;
-  return { v: 1, id, at: now.toISOString(), session, repos };
+  // A row with no sender is the owner's, as in the hook of 0.4.8, so only a
+  // platform message carries the key.
+  return { v: 1, id, at: now.toISOString(), session, repos, ...(senderOf(input?.prompt) === 'platform' ? { from: 'platform' } : {}) };
 }
 
 // The row goes to a file of its own, written under a temporary name and

package/package.json

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