@arjunkhera/atlas 0.4.24 → 0.4.25

package/.claude-plugin/plugin.json

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

package/door/jobs/npm-release.yaml

@@ -0,0 +1,24 @@
+# An Atlas job (the routines design, records part). A job does nothing until a
+# repo names it in its atlas.yaml, with the npm packages it publishes:
+#
+#   jobs:
+#     atlas: [npm-release]
+#     npm: ['@scope/name']
+#
+# It fits a repo that publishes to npm through a release.yml on master that
+# keeps the Atlas release record, as Atlas does. A service, a schema repo or a
+# repo that publishes nothing does not name it.
+#
+# The check is Atlas code (door/lib/jobs.mjs). Each version that npm got in the
+# last 2 days must have the proof that `atlas upgrade` asks for: a successful
+# push run of release.yml on a master commit that recorded that version with
+# the sha256 of its tarball. A branch can publish before any merge (the gate
+# probes, P7), so a version with no such run is a finding. `problem` is a
+# code: no-tag, not-on-master, never-tip or no-record. Only a person can act
+# on it (deprecate the version on npm), so the job may only report.
+title: Each new npm version was published by a release run on master
+when: daily
+needs: []
+act: atlas:npm-release
+may: report
+fields: [package, version, problem, commit]

package/door/lib/install.mjs

@@ -218,12 +218,13 @@ export const recordName = (version, sha256) => `atlas-release-${version}-${sha25
 // commit must once have been the tip of master. A tag that a person made or
 // moved finds no record, so the upgrade refuses. With no sha256 (a loaded
 // copy has no tarball), any record of this version counts, and the byte
-// compare of every file does the rest.
+// compare of every file does the rest. A refusal carries a `code` too, for
+// the npm-release job of the watcher (jobs.mjs).
 export function findRelease({ gh, repo, version, sha256 }) {
   const commit = tagCommit(gh, repo, version);
-  if (!commit) return { problem: `no tag v${version} names a commit` };
-  if (!onMaster(gh, repo, commit)) return { problem: `the tag v${version} names commit ${commit.slice(0, 12)}, which is not on master` };
-  if (!wasTip(gh, repo, commit)) return { problem: `the tag v${version} names commit ${commit.slice(0, 12)}, which was never the tip of master through a merge or a push` };
+  if (!commit) return { code: 'no-tag', problem: `no tag v${version} names a commit` };
+  if (!onMaster(gh, repo, commit)) return { code: 'not-on-master', commit, problem: `the tag v${version} names commit ${commit.slice(0, 12)}, which is not on master` };
+  if (!wasTip(gh, repo, commit)) return { code: 'never-tip', commit, problem: `the tag v${version} names commit ${commit.slice(0, 12)}, which was never the tip of master through a merge or a push` };
   const runs = gh(['api', '--method', 'GET', `repos/${repo}/actions/workflows/release.yml/runs?event=push&status=success&head_sha=${commit}&per_page=100`]).workflow_runs ?? [];
   const prefix = recordName(version, '');
   const named = (name) => (sha256 ? name === recordName(version, sha256) : name.startsWith(prefix) && /^[0-9a-f]{64}$/.test(name.slice(prefix.length)));
@@ -234,7 +235,7 @@ export function findRelease({ gh, repo, version, sha256 }) {
     const artifacts = gh(['api', '--method', 'GET', `repos/${repo}/actions/runs/${run.id}/artifacts?per_page=100`]).artifacts ?? [];
     if (artifacts.some((artifact) => named(artifact.name ?? ''))) return { run, commit };
   }
-  return { problem: `no successful release run on master commit ${commit.slice(0, 12)} recorded ${version}${sha256 ? ' with this tarball' : ''}` };
+  return { code: 'no-record', commit, problem: `no successful release run on master commit ${commit.slice(0, 12)} recorded ${version}${sha256 ? ' with this tarball' : ''}` };
 }
 
 // The blob ids that the version files of the tarball must have: the files of

package/door/lib/jobs.mjs

@@ -24,7 +24,9 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseYaml } from '../../shape/check.mjs';
+import { createHash } from 'node:crypto';
 import { api, apiBase, repoOk, openIssues, TOKEN_SHAPE, DEFAULT_BOT, DEFAULT_MAX } from './issues.mjs';
+import { findRelease, sha512Integrity } from './install.mjs';
 import { checkGateFiles, checkGateAudit, checkGateErrors } from './gate-audit.mjs';
 import { commitAudit, ghApi } from './gate.mjs';
 
@@ -107,7 +109,100 @@ export async function checkRedMain({ repo, branch, env }) {
   return findings;
 }
 
-// The check of each Atlas job, by its `when`. A job whose check is not built yet reads `none` and
+// ---------------------------------------------------------------- the check of npm-release
+
+// A branch of the repo can run its own release.yml and publish to npm before any merge (the gate
+// probes, P7). So each version that npm got in the last NPM_DAYS days must have the proof that
+// `atlas upgrade` asks for: a successful push run of release.yml on a master commit that recorded
+// this version with the sha256 of this exact tarball (findRelease, install.mjs). The watcher runs
+// once a day, so two days cover one missed run. A longer window reaches versions from before the
+// release record existed (Atlas 0.4.0), and the tip proof reads only the newest 100 changes of master.
+export const NPM_DAYS = 2;
+export const NPM_MAX = 50;
+const PACKAGE = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+
+// The npm packages that atlas.yaml names under `jobs: { npm: [...] }`.
+export function npmPackages(root) {
+  const facts = parseYaml(readFileSync(join(root, 'atlas.yaml'), 'utf8')) ?? {};
+  const named = facts.jobs?.npm;
+  if (!Array.isArray(named) || !named.length) throw new Error('atlas.yaml names no package under jobs.npm');
+  const bad = named.map(String).find((name) => !PACKAGE.test(name));
+  if (bad !== undefined) throw new Error('jobs.npm in atlas.yaml holds a name that is not an npm package name');
+  return named.map(String);
+}
+
+// https, or http for this machine only (a test uses a fake registry on 127.0.0.1).
+function registryBase(env) {
+  const text = String(env.NPM_REGISTRY_URL || 'https://registry.npmjs.org');
+  let url;
+  try { url = new URL(text); } catch { throw usage('NPM_REGISTRY_URL is not a URL'); }
+  const local = url.hostname === '127.0.0.1' || url.hostname === 'localhost';
+  if (!(url.protocol === 'https:' || (url.protocol === 'http:' && local))) throw usage('NPM_REGISTRY_URL must be https (http is allowed only for 127.0.0.1 or localhost)');
+  return url;
+}
+
+// findRelease reads GitHub through a sync `gh`. Here each read is a fetch, so the proof runs again
+// after each read it asked for, until it needs none. Every read is a GET, and the same path gives the
+// same answer, so a replay changes nothing.
+export async function replayRelease({ base, key, repo, version, sha256 }) {
+  const answers = new Map();
+  for (let round = 0; round < 50; round += 1) {
+    try {
+      return findRelease({
+        repo, version, sha256,
+        gh: (args) => {
+          const path = `/${args.at(-1)}`;
+          if (!answers.has(path)) throw Object.assign(new Error('a read is still to come'), { need: path });
+          const answer = answers.get(path);
+          if (answer instanceof Error) throw answer;
+          return answer;
+        },
+      });
+    } catch (error) {
+      if (!error.need) throw error;
+      const r = await api(base, key, 'GET', error.need);
+      if (r.status === 404) answers.set(error.need, Object.assign(new Error('Not Found'), { stderr: 'HTTP 404' }));
+      else if (!r.ok) throw new Error(`GitHub answered ${r.status} when the release of ${version} was read`);
+      else answers.set(error.need, r.data);
+    }
+  }
+  throw new Error(`the release of ${version} needed more than 50 reads`);
+}
+
+export async function checkNpmRelease({ repo, env, root, now = Date.now(), fetchImpl = fetch }) {
+  const base = apiBase(env);
+  const key = env.GITHUB_TOKEN || '';
+  if (!key) throw usage('there is no token: set GITHUB_TOKEN in the environment');
+  const registry = registryBase(env);
+  const findings = [];
+  for (const name of npmPackages(root)) {
+    const response = await fetchImpl(new URL(name.replace('/', '%2F'), `${registry.href.replace(/\/?$/, '/')}`));
+    if (!response.ok) throw new Error(`npm answered ${response.status} when ${name} was read`);
+    const doc = await response.json();
+    // A broken answer must read broken, never none: each version needs a publish time.
+    const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+    if (!object(doc?.versions) || !object(doc?.time)) throw new Error(`npm sent no versions and times for ${name}`);
+    if (Object.keys(doc.versions).some((version) => !Number.isFinite(Date.parse(doc.time[version])))) throw new Error(`npm sent a version of ${name} with no publish time`);
+    const recent = Object.keys(doc.versions).filter((version) => now - Date.parse(doc.time[version]) <= NPM_DAYS * DAY);
+    if (recent.length > NPM_MAX) throw new Error(`npm holds ${recent.length} versions of ${name} from the last ${NPM_DAYS} days, more than ${NPM_MAX}`);
+    for (const version of recent.sort()) {
+      if (!VALUE.test(version)) throw new Error(`npm holds a version of ${name} that is not a plain version`);
+      const dist = doc.versions[version].dist ?? {};
+      const tarball = new URL(String(dist.tarball ?? ''), registry);
+      if (tarball.origin !== registry.origin) throw new Error(`the tarball of ${name}@${version} is not on the registry`);
+      const got = await fetchImpl(tarball);
+      if (!got.ok) throw new Error(`npm answered ${got.status} when the tarball of ${name}@${version} was read`);
+      const bytes = Buffer.from(await got.arrayBuffer());
+      if (sha512Integrity(bytes) !== dist.integrity) throw new Error(`the tarball of ${name}@${version} does not match the integrity npm records`);
+      const release = await replayRelease({ base, key, repo, version, sha256: createHash('sha256').update(bytes).digest('hex') });
+      if (!release.problem) continue;
+      findings.push({ job: 'npm-release', key: `${name}@${version}`, package: name, version, problem: release.code, ...(release.commit ? { commit: release.commit } : {}) });
+    }
+  }
+  return findings;
+}
+
+// The check of each Atlas job, by its id, else 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.
 // The gate jobs (roadmap R14) read GitHub through `gh`, which the Actions
 // runner holds; their token is the run's own GITHUB_TOKEN.
@@ -116,6 +211,7 @@ const CHECKS = {
   '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 }),
+  'npm-release': checkNpmRelease,
 };
 
 export async function jobsCheck({ root, repo, branch = null, env = process.env, jobs = atlasJobs(), gh = ghApi, fetchImpl = fetch }) {
@@ -128,7 +224,7 @@ export async function jobsCheck({ root, repo, branch = null, env = process.env,
   for (const id of named) {
     const job = jobs.get(id);
     if (!job) { notes.push(`${JOB_ID.test(id) ? id : '(a bad id)'}: no Atlas job has this id`); continue; }
-    const check = CHECKS[job.when];
+    const check = CHECKS[job.id] ?? CHECKS[job.when];
     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 });

package/package.json

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