@arjunkhera/atlas 0.4.26 → 0.4.27

package/.claude-plugin/plugin.json

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

package/door/lib/pull-request.mjs

@@ -23,7 +23,7 @@ export const TOOLING_LABEL = 'atlas-helper';
 
 // The only files the tooling writer may write: the check, its workflow, and
 // the pull request template when the repo has none.
-export const TOOLING_PATHS = Object.freeze([CHECK_PATH, WORKFLOW_PATH, '.github/workflows/atlas-jobs.yml', '.github/pull_request_template.md']);
+export const TOOLING_PATHS = Object.freeze([CHECK_PATH, WORKFLOW_PATH, '.github/workflows/atlas-jobs.yml', '.github/workflows/atlas-upkeep.yml', '.github/pull_request_template.md']);
 // The only files the tooling writer may remove: the workflow of check versions
 // 1 to 5, which the gate workflow replaces (roadmap R7).
 export const TOOLING_REMOVALS = Object.freeze([OLD_WORKFLOW_PATH]);

package/door/lib/tooling.mjs

@@ -42,25 +42,34 @@ const oldWorkflow = (root) => existsSync(join(root, OLD_WORKFLOW_PATH));
 // repo backwards, and never replaces a hand edit at the same version.
 export const JOBS_PATH = '.github/workflows/atlas-jobs.yml';
 export const PACKAGE_JOBS_SOURCE = 'door/templates/atlas-jobs.yml';
+// The upkeep check on each pull request (roadmap R41). The same pin rule holds.
+// The Atlas repo keeps its own atlas-upkeep.yml, which runs the package of
+// master and has no pin, so the writer keeps it and Atlas runs one upkeep job.
+export const UPKEEP_PATH = '.github/workflows/atlas-upkeep.yml';
+export const PACKAGE_UPKEEP_SOURCE = 'door/templates/atlas-upkeep.yml';
+// The workflows the writer pins, in the order of its rows.
+const PINNED = Object.freeze([[JOBS_PATH, PACKAGE_JOBS_SOURCE], [UPKEEP_PATH, PACKAGE_UPKEEP_SOURCE]]);
 const VERSION_SLOT = '__ATLAS_VERSION__';
-export function packagedJobsWorkflow(packageRoot) {
-  const full = join(packageRoot, PACKAGE_JOBS_SOURCE);
+function packagedPinned(packageRoot, source) {
+  const full = join(packageRoot, source);
   return existsSync(full) ? readFileSync(full, 'utf8').split(VERSION_SLOT).join(packagePackageVersion(packageRoot)) : null;
 }
-const jobsPin = (text) => /@arjunkhera\/atlas@(\d+)\.(\d+)\.(\d+)\b/.exec(text)?.slice(1).map(Number) ?? null;
+export const packagedJobsWorkflow = (packageRoot) => packagedPinned(packageRoot, PACKAGE_JOBS_SOURCE);
+export const packagedUpkeepWorkflow = (packageRoot) => packagedPinned(packageRoot, PACKAGE_UPKEEP_SOURCE);
+const pinOf = (text) => /@arjunkhera\/atlas@(\d+)\.(\d+)\.(\d+)\b/.exec(text)?.slice(1).map(Number) ?? null;
 const older = (a, b) => { for (let i = 0; i < 3; i += 1) if (a[i] !== b[i]) return a[i] < b[i]; return false; };
-// written, refreshed, unchanged or kept: what the writer does with the watcher.
-function jobsState(root, packageRoot) {
-  const wanted = packagedJobsWorkflow(packageRoot);
+// written, refreshed, unchanged or kept: what the writer does with one pinned workflow.
+function pinnedState(root, packageRoot, path, source) {
+  const wanted = packagedPinned(packageRoot, source);
   if (wanted === null) return null;
-  const full = join(root, JOBS_PATH);
+  const full = join(root, path);
   if (!existsSync(full)) return 'written';
   const was = readFileSync(full, 'utf8');
   if (was === wanted) return 'unchanged';
-  const have = jobsPin(was);
-  return have && older(have, jobsPin(wanted)) ? 'refreshed' : 'kept';
+  const have = pinOf(was);
+  return have && older(have, pinOf(wanted)) ? 'refreshed' : 'kept';
 }
-const jobsNeedWrite = (root, packageRoot) => ['written', 'refreshed'].includes(jobsState(root, packageRoot));
+const pinnedNeedWrite = (root, packageRoot) => PINNED.some(([path, source]) => ['written', 'refreshed'].includes(pinnedState(root, packageRoot, path, source)));
 
 // The pull request template (roadmap R8). The writer puts it into a repo that
 // has none, and never replaces a template the repo keeps.
@@ -113,7 +122,7 @@ export function mayWrite(root, packageRoot, { replaceUnknown = false, workflowOn
     throw new ToolingRefusal(`this package's ${PACKAGE_CHECK_SOURCE} is ${pkg.row ? 'not the newest release' : 'in no release'} of the check, so it is not written into another repo. Use a released Atlas.`);
   }
   const now = status({ root, packageRoot });
-  if (now.state === 'current' && !workflowOnly && !templateMissing(root, packageRoot) && !jobsNeedWrite(root, packageRoot) && !oldWorkflow(root)) {
+  if (now.state === 'current' && !workflowOnly && !templateMissing(root, packageRoot) && !pinnedNeedWrite(root, packageRoot) && !oldWorkflow(root)) {
     throw new ToolingRefusal(`this repo's check is already current. ${readWorkflow(root) === WORKFLOW_TEMPLATE || workflowKept(root) ? 'Both files match the package, so there is nothing to write.' : 'Its workflow file differs from the package; pass --workflow to rewrite only that file.'}`, { current: true });
   }
   if (now.state === 'unknown' && !replaceUnknown && !own) {
@@ -145,16 +154,17 @@ export function write(root, packageRoot, { dryRun = false, replaceUnknown = fals
     if (!dryRun) rmSync(join(root, OLD_WORKFLOW_PATH));
     rows.push({ path: OLD_WORKFLOW_PATH, state: 'removed', sha256: null, was: sha256(was) });
   }
-  const jobs = workflowOnly ? null : jobsState(root, packageRoot);
-  if (jobs !== null) {
-    const contents = packagedJobsWorkflow(packageRoot);
-    const full = join(root, JOBS_PATH);
+  for (const [path, source] of workflowOnly ? [] : PINNED) {
+    const state = pinnedState(root, packageRoot, path, source);
+    if (state === null) continue;
+    const contents = packagedPinned(packageRoot, source);
+    const full = join(root, path);
     const was = existsSync(full) ? readFileSync(full, 'utf8') : null;
-    if ((jobs === 'written' || jobs === 'refreshed') && !dryRun) {
+    if ((state === 'written' || state === 'refreshed') && !dryRun) {
       mkdirSync(dirname(full), { recursive: true });
       writeFileSync(full, contents);
     }
-    rows.push({ path: JOBS_PATH, state: jobs, sha256: sha256(jobs === 'kept' ? was : contents), was: was === null ? null : sha256(was) });
+    rows.push({ path, state, sha256: sha256(state === 'kept' ? was : contents), was: was === null ? null : sha256(was) });
   }
   const template = workflowOnly ? null : packagedTemplate(packageRoot);
   if (template !== null) {
@@ -180,7 +190,7 @@ export function changes(root, packageRoot, { replaceUnknown = false, workflowOnl
   if (rows.every((row) => row.state === 'unchanged' || row.state === 'kept')) {
     throw new ToolingRefusal('this repo is already current: its Atlas files match the package, so there is nothing to open.', { current: true });
   }
-  const wanted = { ...packagedFiles(packageRoot), [JOBS_PATH]: packagedJobsWorkflow(packageRoot), [PR_TEMPLATE_PATH]: packagedTemplate(packageRoot) };
+  const wanted = { ...packagedFiles(packageRoot), [JOBS_PATH]: packagedJobsWorkflow(packageRoot), [UPKEEP_PATH]: packagedUpkeepWorkflow(packageRoot), [PR_TEMPLATE_PATH]: packagedTemplate(packageRoot) };
   return rows
     .filter((row) => row.state !== 'unchanged' && row.state !== 'kept')
     .map((row) => (row.state === 'removed' ? {
@@ -196,8 +206,8 @@ export function changes(root, packageRoot, { replaceUnknown = false, workflowOnl
           ? `copied byte for byte from ${PACKAGE_CHECK_SOURCE}, check version ${CHECK_VERSION}, in Atlas ${version}`
           : row.path === PR_TEMPLATE_PATH
             ? `copied from ${PACKAGE_TEMPLATE_SOURCE}, Atlas ${version}; the repo had no pull request template`
-            : row.path === JOBS_PATH
-              ? `written from ${PACKAGE_JOBS_SOURCE}, with its pin set to Atlas ${version}`
+            : row.path === JOBS_PATH || row.path === UPKEEP_PATH
+              ? `written from ${row.path === JOBS_PATH ? PACKAGE_JOBS_SOURCE : PACKAGE_UPKEEP_SOURCE}, with its pin set to Atlas ${version}`
               : `written from the WORKFLOW_TEMPLATE constant in ${PACKAGE_CHECK_SOURCE}, Atlas ${version}`,
       },
     }));

package/door/templates/atlas-upkeep.yml

@@ -0,0 +1,45 @@
+name: atlas-upkeep
+# The Atlas upkeep check on each pull request: plain code, no model and no
+# secret. `atlas tooling` wrote this file from the Atlas package; do not edit
+# it by hand. A newer Atlas moves the pin below when `atlas tooling pr` runs.
+#
+# It stops drift at its source: the docs index lists each doc, every doc link
+# resolves, each doc names its code, and the pull request names its tracker
+# item, or says "no item:" and a reason. A repo with no docs/ folder passes
+# the index part with one line.
+#
+# It runs a pinned Atlas release from npm, never code of the pull request. It
+# runs on pull_request, not pull_request_target, so it holds only a read token
+# and no secret, also for a pull request from a fork. npx runs outside the
+# checkout, so an .npmrc in the pull request cannot pick the registry.
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: atlas-upkeep-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  upkeep:
+    name: docs · upkeep check
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    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: Upkeep check
+        run: |
+          set -euo pipefail
+          cd "$RUNNER_TEMP"
+          npx --yes --ignore-scripts @arjunkhera/atlas@__ATLAS_VERSION__ upkeep check --root "$GITHUB_WORKSPACE" --event "$GITHUB_EVENT_PATH" | tee -a "$GITHUB_STEP_SUMMARY"

package/package.json

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