@arjunkhera/atlas 0.3.41 → 0.3.42

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -103,7 +103,7 @@ const HELP = `atlas — the door into a repo's Atlas files
       --evidence <dir>                 where the evidence files go; default <area>/test/evidence
       --scenario <id>                  run one scenario only
 
-  atlas tests rerun --root <area> --run <id>   list the scenario test files whose first attempt did not end well
+  atlas tests rerun --root <area> --run <id> [--language python]   list the scenario test files whose first attempt did not end well
       --tests <dir>                    the test folder of the area; default test. The test files are in <dir>/scenarios
       --evidence <dir>                 where the evidence files are; default <area>/test/evidence
 
@@ -146,7 +146,7 @@ export const FLAGS = Object.freeze({
   ste: { share: 'switch', terms: 'value' },
   design: { tracker: 'value', out: 'value', draft: 'switch', root: 'optional' },
   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', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch', scenario: 'value' },
+  tests: { root: 'optional', halves: 'value', evidence: 'value', 'guards-from': 'value', tests: 'value', 'dry-run': 'switch', run: 'value', own: 'value', base: 'value', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch', scenario: 'value', language: 'value' },
   upkeep: { root: 'optional', event: 'value', json: 'switch' },
   judge: { tasks: 'value', verdict: 'value', seal: 'value', runs: 'value', out: 'value', repo: 'value', budget: 'value', model: 'value' },
   install: { local: 'switch', from: 'value', 'skip-global': 'switch', yes: 'switch' },
@@ -347,7 +347,7 @@ async function testsCommand(chosen) {
   if (what === 'sweep') return testsSweep({ evidence: chosen.evidence, since: chosen.since, base: chosen.base, out: chosen.out, text: Boolean(chosen.text) }, root, line);
   if (what === 'covers') return testsCovers({ itemId: chosen._[2], evidence: chosen.evidence, json: Boolean(chosen.json) }, root, line);
   if (what === 'kept') return (await runKept({ root, evidenceDir: chosen.evidence, only: chosen.scenario ?? null, write: (text) => process.stdout.write(text) })).exit;
-  if (what === 'rerun') return testsRerun({ run: chosen.run, evidence: chosen.evidence, tests: chosen.tests }, root, line);
+  if (what === 'rerun') return testsRerun({ run: chosen.run, evidence: chosen.evidence, tests: chosen.tests, language: chosen.language ?? 'javascript' }, root, line);
   if (what === 'issues') return testsIssues({ findings: chosen.findings, repo: chosen.repo, max: chosen.max, bot: chosen.bot, dryRun: Boolean(chosen['dry-run']), args: [...chosen._, ...Object.values(chosen).filter((v) => typeof v === 'string')] }, line);
   throw new Error(`there is no tests verb "${what ?? ''}". Use check, write, proof, verdict, named, sweep, covers, kept, issues or rerun.`);
 }

package/door/kit-releases.json

@@ -44,6 +44,10 @@
     {
       "kit_sha256": "ea6dc64f5ae4b5caca925a9613c829f5738d16b21d2664434dada208027b60b6",
       "first_package": "0.3.38"
+    },
+    {
+      "kit_sha256": "8d6ae3c4dede74bafe292a992de3ef650e5c5566fb282081a9de23b8d30d9025",
+      "first_package": "0.3.39"
     }
   ]
 }

package/door/lib/tests.mjs

@@ -31,9 +31,12 @@ export class KitRefusal extends Error {
   constructor(message) { super(message); this.name = 'KitRefusal'; }
 }
 
+// Python bytecode (__pycache__) is never part of the kit: a dev tree that ran a
+// Python test may hold it, and it must not reach a repo.
 function filesUnder(dir, prefix = '') {
   const out = [];
   for (const name of readdirSync(dir).sort()) {
+    if (name === '__pycache__') continue;
     const full = join(dir, name);
     if (statSync(full).isDirectory()) out.push(...filesUnder(full, `${prefix}${name}/`));
     else out.push(`${prefix}${name}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.3.41",
+  "version": "0.3.42",
   "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/tests/SKILL.md

@@ -358,6 +358,31 @@ not counted, and the test passes.
 After the product is ready, a lost connection, a server exit or a time-out is
 `fail`. `blocked` is for a guard refusal, a start-up fault and the first-call check.
 
+### A test in Python
+
+Use the Python library when the runner of the area is Python. Its header,
+`test/atlas/contract.py`, holds a worked example.
+
+1. Name the file `test/scenarios/<name>_test.py`. List a Python runner in
+   `runner` of `tests.yaml`. `runner` may be a list, one runner for each
+   language.
+2. Before the import, set `sys.dont_write_bytecode = True`. Put
+   `test/atlas` on `sys.path`, and import `scenario` from `contract`.
+   Run Python with `-B`: the check refuses bytecode in the test folder.
+   Never run it with `-O`, which removes every assert.
+3. Decorate the body: `@scenario("../../scenarios/<name>.md", adapter=adapter)`.
+4. Write each check as a `with` block that holds an assert statement:
+   `with run.check("<scenario>/e1#<fingerprint>"):`. Use `run.gate` for a gate.
+   To keep a short proof, set `proof.value` in `with ... as proof:`.
+5. Use `run.not_exercised` and `run.wait_for`, in snake case.
+6. Give the driver of each way in through the adapter (`define_adapter`).
+   Build its child environment with `child_env`.
+
+The library reads the scenario through node, so the runner needs node and
+python3. It does not yet start an environment, give run secrets, repeat a
+run, ask a judge or ship drivers. Each of these ends `blocked`. Write such a
+scenario with `contract.mjs`.
+
 ### A model in the test
 
 A model makes a test vary and costs money. Three parts of the kit handle it.

package/tests/bridge.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// The bridge for a contract library in another language (design section 8.1).
+// A library in Python, say, must read a scenario exactly as the link check
+// reads it: the same parser, the same fingerprints, the same tests.yaml check
+// and the same guard comparison. So it does not parse the words itself. It
+// runs this file and reads one JSON object:
+//
+//   node bridge.mjs load <scenario.md>
+//   -> { root, file, environment, evidenceDir, guardRefusal, tests, envSpec, shippedDrivers, wayGuardParts,
+//        scenario: { id, title, file, sha256, method, fields, through, ways, repeat,
+//                    assertions: [{ id, fullId, kind, gate, ways, fp, names, line }],
+//                    tables: { T1: { name, kind, header, rows, fingerprint, cases } } } }
+//
+// `cases` is every case of a combination table (every combination, or a set
+// that holds every pair), so the other language need not make them again.
+// A fault in the scenario or in tests.yaml prints { error } and exits 1.
+// The environment and the folders come from the same variables as
+// contract.mjs: ATLAS_ENV, CI, ATLAS_EVIDENCE_DIR and ATLAS_GUARDS_FROM.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readTestsYaml, checkTestsYaml, compareGuardParts, resolveEnvironments, GUARD_PARTS } from './tests-yaml.mjs';
+import { SHIPPED_DRIVERS } from './drivers/index.mjs';
+import { readScenario, addFingerprints, combinations, pairs } from './scenario.mjs';
+
+function findRoot(file) {
+  let dir = dirname(file);
+  for (;;) {
+    if (existsSync(join(dir, 'atlas', 'tests.yaml'))) return dir;
+    const up = dirname(dir);
+    if (up === dir) throw new Error(`no atlas/tests.yaml above ${file}`);
+    dir = up;
+  }
+}
+
+export function loadForLibrary(path, env = process.env) {
+  const file = resolve(String(path));
+  const root = findRoot(file);
+  const yaml = readTestsYaml(join(root, 'atlas', 'tests.yaml'));
+  const findings = checkTestsYaml(yaml);
+  if (findings.length) throw new Error(`atlas/tests.yaml: ${findings.map((f) => `line ${f.line}: ${f.message}`).join('; ')}`);
+  const sc = readScenario(file);
+  if (sc.problems.length) throw new Error(`${path}: ${sc.problems.map((p) => `line ${p.line}: ${p.message}`).join('; ')}`);
+  const tests = yaml.value;
+  addFingerprints(sc, tests);
+  // The same rule as contract.mjs: a branch whose guard parts differ from the main branch copy is refused.
+  let guardRefusal = null;
+  if (env.ATLAS_GUARDS_FROM) {
+    try {
+      const changes = compareGuardParts(readFileSync(env.ATLAS_GUARDS_FROM, 'utf8'), yaml.value);
+      if (changes.length) guardRefusal = `the guard parts of atlas/tests.yaml differ from the main branch copy (${changes.map((c) => c.part).join(', ')}); the run is refused. A change to a guard part comes to the owner`;
+    } catch (error) {
+      guardRefusal = `ATLAS_GUARDS_FROM names a file that cannot be read as tests.yaml (${error.code ?? error.message}); the run is refused`;
+    }
+  }
+  const environment = env.ATLAS_ENV ?? (env.CI ? 'ci' : 'local');
+  const evidenceDir = env.ATLAS_EVIDENCE_DIR ?? join(root, 'test', 'evidence');
+  const tables = {};
+  for (const [name, t] of sc.tables) {
+    const cases = t.kind === 'combination' ? (t.cover === 'pair' ? pairs(t.dimensions) : combinations(t.dimensions)) : null;
+    tables[name] = { name, kind: t.kind, header: t.header ?? null, rows: t.rows ?? [], fingerprint: t.fingerprint, cases };
+  }
+  return {
+    root, file, environment, evidenceDir, guardRefusal, tests,
+    // What a library in another language must refuse until it has its own form of the guard.
+    shippedDrivers: SHIPPED_DRIVERS,
+    wayGuardParts: GUARD_PARTS.filter((p) => p.startsWith('ways-in.*.')).map((p) => p.slice('ways-in.*.'.length)),
+    envSpec: resolveEnvironments(tests.environments ?? {})[environment] ?? null,
+    scenario: {
+      id: sc.id, title: sc.title, file: sc.file, sha256: sc.sha256, method: sc.method,
+      names: [...new Set([...sc.start, ...sc.steps, ...sc.assertions].flatMap((x) => x.names ?? []))],
+      fields: sc.fields, through: sc.through, ways: sc.ways ?? sc.through, repeat: sc.repeat ?? null,
+      assertions: sc.assertions.map((a) => ({ id: a.id, fullId: a.fullId, kind: a.kind, gate: Boolean(a.gate), ways: a.ways ?? sc.through, fp: a.fp, names: a.names ?? [], line: a.line })),
+      tables,
+    },
+  };
+}
+
+export function main(argv, write = (text) => process.stdout.write(text)) {
+  const [verb, path] = argv;
+  if (verb !== 'load' || !path) { process.stderr.write('bridge: use "bridge.mjs load <scenario.md>"\n'); return 2; }
+  try {
+    write(`${JSON.stringify(loadForLibrary(path))}\n`);
+    return 0;
+  } catch (error) {
+    write(`${JSON.stringify({ error: error.message })}\n`);
+    return 1;
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = main(process.argv.slice(2));