@arjunkhera/atlas 0.0.0 → 0.2.0

package/door/lib/pull-request.mjs

@@ -0,0 +1,115 @@
+// One helper change set becomes one pull request, with the fixed label and
+// per-change provenance.
+//
+// Milestone M2, slice L2 stage one. The frozen sentence: "Helper pull requests
+// carry the fixed label and per-change provenance." The rule behind it is R13
+// of the M2 design study's review panel.
+//
+// The body is built by a pure function, so a test reads it without GitHub. The
+// git and GitHub calls sit below it, in one place.
+import { execFileSync } from 'node:child_process';
+import { childEnvironment } from '../../work/lib/child-env.mjs';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { checkChanges, HELPER_LABEL, PROVENANCE_SOURCES } from './helpers.mjs';
+
+export { HELPER_LABEL, PROVENANCE_SOURCES };
+
+const escapeCell = (text) => String(text ?? '').replaceAll('|', '\\|').replaceAll('\n', ' ').trim();
+
+// One request may reach two helpers. "We now deploy prod on Fly" reaches Facts
+// and Procedures. It is still ONE pull request: design page D2's rule, carried
+// here (architecture section 5.1, rule 1).
+export function checkAll(groups) {
+  if (!Array.isArray(groups) || !groups.length) throw new Error('a pull request needs at least one helper group');
+  const seen = new Map();
+  for (const group of groups) {
+    const helper = checkChanges(group.helperId, group.changes);
+    if (seen.has(helper.id)) throw new Error(`the ${helper.id} helper appears twice; put its changes in one group`);
+    seen.set(helper.id, { helper, changes: group.changes });
+  }
+  return [...seen.values()].sort((a, b) => a.helper.file - b.helper.file);
+}
+
+// The pull request body. Every change is one row, and every row names where the
+// change came from. A reader can tell an owner decision from a guess without
+// opening the diff.
+export function provenanceBody({ helper, helpers, why, changes, groups, repo = null }) {
+  const parts = groups ?? [{ helper, changes }];
+  const named = (helpers ?? parts.map((group) => group.helper));
+  const lines = [
+    named.length === 1
+      ? `The \`${named[0].title}\` helper wrote this. It owns ${named[0].ownsText}.`
+      : `${named.length} helpers wrote this, and it is one pull request because it is one change:\n${named.map((one) => `- \`${one.title}\`, which owns ${one.ownsText}`).join('\n')}`,
+    '',
+    `**Why.** ${String(why ?? '').trim() || 'Not given.'}`,
+    '',
+    '## What changed, and where each change came from',
+    '',
+    '| File | Helper | Source | What the source says |',
+    '|---|---|---|---|',
+  ];
+  for (const group of parts) {
+    for (const change of group.changes) {
+      lines.push(`| \`${escapeCell(change.path)}\` | ${escapeCell(group.helper.title)} | ${escapeCell(change.provenance.source)} | ${escapeCell(change.provenance.detail)} |`);
+    }
+  }
+  lines.push(
+    '',
+    '## How to read this',
+    '',
+    `1. Every file above is instruction class. It steers agents, so a person merges it${repo ? ` in ${repo}` : ''}.`,
+    '2. An agent made every change. No person edited these files by hand.',
+    `3. "Source" is one of: ${PROVENANCE_SOURCES.join(', ')}.`,
+    '',
+    `Label: \`${HELPER_LABEL}\`. Authority: Arjunkhera/atlas, \Atlas amendment A1.6\`, section 5, slice L2 stage one.`,
+    '',
+  );
+  return lines.join('\n');
+}
+
+// Write a checked change set into a working tree. It writes files and nothing
+// else: no branch, no commit, no network. `open` below does the rest.
+export function applyChanges(root, helperId, changes) {
+  const helper = checkChanges(helperId, changes);
+  const written = [];
+  for (const change of changes) {
+    const path = join(root, change.path);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, change.contents);
+    written.push(change.path);
+  }
+  return { helper, written };
+}
+
+const run = (command, args, cwd) => execFileSync(command, args, { cwd, encoding: 'utf8', timeout: 120_000, maxBuffer: 8 * 1024 * 1024, env: childEnvironment() }).trim();
+
+// The whole pull request, live. Needs git and the GitHub command line.
+//
+// It never merges. A person merges every file a helper writes, because every
+// one of them steers agents.
+export function open({ root, helperId, changes, groups, why, branch, title, base = null, label = HELPER_LABEL, dryRun = false }) {
+  const wanted = groups ?? [{ helperId, changes }];
+  const checked = checkAll(wanted);
+  const all = checked.flatMap((group) => group.changes);
+  // A dry run writes nothing. The first version applied the changes and then
+  // printed "Nothing was pushed", which was true and misleading (acceptance
+  // review of batch 16, finding S3-5).
+  if (!dryRun) for (const group of checked) applyChanges(root, group.helper.id, group.changes);
+  const repo = (() => { try { return run('gh', ['repo', 'view', '--json', 'nameWithOwner', '--jq', '.nameWithOwner'], root); } catch { return null; } })();
+  const body = provenanceBody({ groups: checked, why, repo });
+  const onto = base ?? run('git', ['symbolic-ref', '--short', 'HEAD'], root);
+  const helper = checked[0].helper;
+  if (dryRun) return { helper, helpers: checked.map((group) => group.helper), repo, branch, title, body, base: onto, written: all.map((change) => change.path), opened: false };
+
+  run('git', ['checkout', '-b', branch], root);
+  run('git', ['add', '--', ...all.map((change) => change.path)], root);
+  run('git', ['commit', '-m', title, '-m', body], root);
+  run('git', ['push', '-u', 'origin', branch], root);
+  // A label that does not exist yet makes `gh pr create` fail, so it is made
+  // first. A label that already exists makes that call fail instead, and that
+  // failure is the expected one.
+  try { run('gh', ['label', 'create', label, '--description', 'Written by an Atlas helper. A person merges it.', '--color', 'C5A882'], root); } catch { /* it already exists */ }
+  const url = run('gh', ['pr', 'create', '--title', title, '--body', body, '--label', label, '--base', onto], root);
+  return { helper, helpers: checked.map((group) => group.helper), repo, branch, title, body, base: onto, written: all.map((change) => change.path), opened: true, url };
+}

package/door/lib/releases.mjs

@@ -0,0 +1,42 @@
+// The release list of the check: every copy of shape/check.mjs that a release
+// of Atlas has shipped, by fingerprint (row F11, amendment A1.9).
+//
+// An installed package has no git history, so "behind" cannot be decided by
+// git ancestry. This list decides it. The last entry is the check this package
+// ships. An earlier entry is a check an earlier release shipped.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { sha256 } from '../../shape/check.mjs';
+
+export const RELEASES_PATH = 'shape/releases.json';
+export const PACKAGE_CHECK_SOURCE = 'shape/check.mjs';
+
+export function readReleases(packageRoot) {
+  const list = JSON.parse(readFileSync(join(packageRoot, RELEASES_PATH), 'utf8'));
+  if (!Array.isArray(list.releases) || !list.releases.length) throw new Error(`${RELEASES_PATH} lists no release`);
+  for (const row of list.releases) {
+    if (!Number.isInteger(row.check_version) || !/^[0-9a-f]{64}$/.test(row.sha256 ?? '') || typeof row.first_package !== 'string') {
+      throw new Error(`${RELEASES_PATH} holds a malformed row: ${JSON.stringify(row)}`);
+    }
+  }
+  return list.releases;
+}
+
+export function packagePackageVersion(packageRoot) {
+  return JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version;
+}
+
+// Where one fingerprint sits in the list: the row, and whether it is the last.
+export function placeOf(releases, fingerprint) {
+  const index = releases.findIndex((row) => row.sha256 === fingerprint);
+  if (index < 0) return { row: null, latest: false };
+  return { row: releases[index], latest: index === releases.length - 1 };
+}
+
+// The check this package would put in a repo, and where it sits in the list.
+export function packagedCheck(packageRoot) {
+  const text = readFileSync(join(packageRoot, PACKAGE_CHECK_SOURCE), 'utf8');
+  const releases = readReleases(packageRoot);
+  const fingerprint = sha256(text);
+  return { text, sha256: fingerprint, releases, ...placeOf(releases, fingerprint) };
+}

package/door/lib/status.mjs

@@ -0,0 +1,47 @@
+// The session verb: is this repository's copy of the check current, behind,
+// unknown or missing?
+//
+// Milestone M2, slice L2 stage one, done line 2: "The session verb names a
+// stale copy by hash." Row F11 (amendment A1.9) changes how: the answer comes
+// from the release list the package carries, shape/releases.json, and never
+// from git history or the package version.
+//
+//   current  the copy's fingerprint is the last row of the list
+//   behind   the copy's fingerprint is an earlier row
+//   unknown  the fingerprint is in no row: edited by hand, or from elsewhere
+//   missing  the repo has no copy
+//
+// CI never makes this judgement. A check with no network cannot learn the
+// package's list. This runs in a session, with the package on disk.
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CHECK_PATH, checkStamps, sha256 } from '../../shape/check.mjs';
+import { packagedCheck, placeOf } from './releases.mjs';
+
+export const STATES = Object.freeze(['current', 'behind', 'unknown', 'missing']);
+
+export function status({ root, packageRoot }) {
+  const pkg = packagedCheck(packageRoot);
+  const latest = pkg.releases[pkg.releases.length - 1];
+  const packaged = { sha256: pkg.sha256, check_version: checkStamps(pkg.text).check_version, released: Boolean(pkg.row), latest: pkg.latest };
+  const full = join(root, CHECK_PATH);
+  if (!existsSync(full)) {
+    return { root, path: CHECK_PATH, state: 'missing', packaged, copy: null, why: `${CHECK_PATH} does not exist in this repo, so it runs no check of its own. "atlas tooling pr" adds it and its GitHub workflow.` };
+  }
+  const text = readFileSync(full, 'utf8');
+  const fingerprint = sha256(text);
+  const { row, latest: isLatest } = placeOf(pkg.releases, fingerprint);
+  const copy = { sha256: fingerprint, check_version: row?.check_version ?? checkStamps(text).check_version, first_package: row?.first_package ?? null };
+  if (row && isLatest) {
+    return { root, path: CHECK_PATH, state: 'current', packaged, copy, why: `the copy is check version ${row.check_version}, the newest one Atlas has released (first in Atlas ${row.first_package}).` };
+  }
+  if (row) {
+    return { root, path: CHECK_PATH, state: 'behind', packaged, copy, why: `the copy is check version ${row.check_version}, first released in Atlas ${row.first_package}. The newest is check version ${latest.check_version}, from Atlas ${latest.first_package}. "atlas tooling pr" refreshes it.` };
+  }
+  return { root, path: CHECK_PATH, state: 'unknown', packaged, copy, why: `the copy's fingerprint, sha256 ${fingerprint.slice(0, 12)}…, is in no release of the check. Someone edited it, or it came from an unreleased package. "atlas tooling pr --replace-unknown" shows the difference and replaces it.` };
+}
+
+// The same question across several repositories.
+export function statusMany(roots, packageRoot) {
+  return roots.map((root) => { try { return status({ root, packageRoot }); } catch (error) { return { root, state: 'unknown', why: error.message, packaged: null, copy: null }; } });
+}

package/door/lib/tooling.mjs

@@ -0,0 +1,119 @@
+// The tooling helper. It writes and refreshes the two files Atlas puts in a
+// repository, and it needs no model and no network to do it.
+//
+// Milestone M2, slice L2 stage one, done line 1: "The tooling helper writes
+// both files into a repository with no hand step."
+//
+// Both files come from the package: the check is copied byte for byte from
+// shape/check.mjs, and the workflow is written from the WORKFLOW_TEMPLATE
+// constant inside that same file. One place writes both, so they can never
+// disagree about the path.
+//
+// Row F11 (amendment A1.9): a refresh never moves a repo backwards and never
+// plants a check no release has shipped. It writes only when the repo's copy
+// is missing or behind, or unknown with --replace-unknown, and only a check
+// that is the newest row of the release list. The Atlas repo itself may take
+// its own unreleased check, because that is how a new check is made.
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { CHECK_PATH, WORKFLOW_PATH, WORKFLOW_TEMPLATE, CHECK_VERSION, sha256, parseYaml } from '../../shape/check.mjs';
+import { packagedCheck, packagePackageVersion, PACKAGE_CHECK_SOURCE } from './releases.mjs';
+import { status } from './status.mjs';
+
+export { CHECK_PATH, WORKFLOW_PATH, PACKAGE_CHECK_SOURCE };
+
+export class ToolingRefusal extends Error {
+  constructor(message, { current = false } = {}) { super(message); this.current = current; }
+}
+
+// What the package would put in a repository right now.
+export function packagedFiles(packageRoot) {
+  return {
+    [CHECK_PATH]: readFileSync(join(packageRoot, PACKAGE_CHECK_SOURCE), 'utf8'),
+    [WORKFLOW_PATH]: WORKFLOW_TEMPLATE,
+  };
+}
+
+// Is this repository the one the package is built from? Two things must
+// agree: the repo named in atlas.yaml, and the git remote of the checkout.
+// Either alone is one line anyone can write; the harm of a false claim stays
+// in that one repository.
+const githubName = (url) => /github\.com[/:]([^/]+\/[^/]+?)(?:\.git)?\/?$/.exec(String(url ?? '').trim())?.[1] ?? null;
+export function isPackageRepo(root, packageRoot) {
+  const own = githubName(JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).repository?.url);
+  const file = join(root, 'atlas.yaml');
+  if (!own || !existsSync(file)) return false;
+  let named = null;
+  try { named = parseYaml(readFileSync(file, 'utf8'))?.repo ?? null; } catch { return false; }
+  if (named !== own) return false;
+  try {
+    const remote = execFileSync('git', ['-C', root, 'config', '--get', 'remote.origin.url'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return githubName(remote) === own;
+  } catch { return false; }
+}
+
+// May the helper write into this repository? Returns nothing, or throws a
+// refusal that says what to do instead.
+const readWorkflow = (root) => { const full = join(root, WORKFLOW_PATH); return existsSync(full) ? readFileSync(full, 'utf8') : null; };
+
+export function mayWrite(root, packageRoot, { replaceUnknown = false, workflowOnly = false } = {}) {
+  const pkg = packagedCheck(packageRoot);
+  const own = isPackageRepo(root, packageRoot);
+  if (!pkg.latest && !own) {
+    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) {
+    throw new ToolingRefusal(`this repo's check is already current. ${readWorkflow(root) === WORKFLOW_TEMPLATE ? '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) {
+    throw new ToolingRefusal(`${now.why}`);
+  }
+  return now;
+}
+
+// Write both files into a repository. Returns one row per file saying whether
+// it was written new, refreshed, or already the same. Safe to run again.
+export function write(root, packageRoot, { dryRun = false, replaceUnknown = false, workflowOnly = false } = {}) {
+  const before = dryRun ? null : mayWrite(root, packageRoot, { replaceUnknown, workflowOnly });
+  const all = packagedFiles(packageRoot);
+  const wanted = workflowOnly ? { [WORKFLOW_PATH]: all[WORKFLOW_PATH] } : all;
+  const rows = [];
+  for (const [path, contents] of Object.entries(wanted)) {
+    const full = join(root, path);
+    const was = existsSync(full) ? readFileSync(full, 'utf8') : null;
+    const state = was === null ? 'written' : was === contents ? 'unchanged' : 'refreshed';
+    if (state !== 'unchanged' && !dryRun) {
+      mkdirSync(dirname(full), { recursive: true });
+      writeFileSync(full, contents);
+    }
+    rows.push({ path, state, sha256: sha256(contents), was: was === null ? null : sha256(was) });
+  }
+  if (!dryRun && rows.every((row) => row.state === 'unchanged')) {
+    throw new ToolingRefusal('this repo is already current: both files match the package, so there is nothing to write.', { current: true });
+  }
+  return { rows, version: packagePackageVersion(packageRoot), check_version: CHECK_VERSION, status: before?.state ?? null, changed: rows.some((row) => row.state !== 'unchanged') };
+}
+
+// The change set the pull request machinery takes, for the two files above.
+export function changes(root, packageRoot, { replaceUnknown = false, workflowOnly = false } = {}) {
+  mayWrite(root, packageRoot, { replaceUnknown, workflowOnly });
+  const { rows, version } = write(root, packageRoot, { dryRun: true, workflowOnly });
+  if (rows.every((row) => row.state === 'unchanged')) {
+    throw new ToolingRefusal('this repo is already current: both files match the package, so there is nothing to open.', { current: true });
+  }
+  const wanted = packagedFiles(packageRoot);
+  return rows
+    .filter((row) => row.state !== 'unchanged')
+    .map((row) => ({
+      path: row.path,
+      contents: wanted[row.path],
+      provenance: {
+        source: 'repo read',
+        detail: row.path === CHECK_PATH
+          ? `copied byte for byte from ${PACKAGE_CHECK_SOURCE}, check version ${CHECK_VERSION}, in Atlas ${version}`
+          : `written from the WORKFLOW_TEMPLATE constant in ${PACKAGE_CHECK_SOURCE}, Atlas ${version}`,
+      },
+    }));
+}

package/package.json

@@ -1,7 +1,28 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.0.0",
-  "description": "Placeholder. The first real release is 0.2.0.",
+  "version": "0.2.0",
+  "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
+  "type": "module",
   "license": "UNLICENSED",
-  "repository": {"type": "git", "url": "https://github.com/Arjunkhera/atlas.git"}
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Arjunkhera/atlas.git",
+    "directory": "packages/atlas"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "atlas": "bin/atlas"
+  },
+  "files": [
+    "bin/",
+    "door/",
+    "work/",
+    "shape/",
+    "skills/",
+    "agents/",
+    ".claude-plugin/",
+    ".mcp.json"
+  ]
 }