@runeditrun/rer 0.0.0-stage → 0.1.1

package/cli/transfers.mjs

@@ -0,0 +1,33 @@
+import {localDependencyLinks} from './dependency-doctor.mjs';
+import { contained } from './project.mjs';
+import { missing, refuse } from './errors.mjs';
+import { locateExport, locateImport } from './archive-path.mjs';
+export async function transfer(project, options, signal, custody) {
+ const direction = options.verb, file = direction === 'export' ? options.output : options.input;
+ if (!file) throw missing(`Provide --${direction === 'export' ? 'output' : 'input'} FILE.`);
+ if (direction === 'import' && !options.yes) throw refuse('Import requires explicit --yes confirmation.');
+ const target = options.target ?? 'local', api = project.adapter.portability;
+ if(direction==='import' && options.legacyV1) {
+  if(!options.acknowledgeUnverifiedMetadata)throw refuse('Legacy v1 recovery requires --acknowledge-unverified-metadata: source identity, erasure metadata and other manifest metadata cannot be authenticated. See modules/portability/README.md#backup-only-v1-recovery.');
+  if(!options.output)throw missing('Legacy v1 recovery requires --output FILE for the new v2 backup.');
+  if(target!=='local'||options.platform==='container'||api?.legacyRecovery!==true)throw refuse('Legacy v1 recovery is supported only by the local Workers portability adapter in an empty isolated installation.');
+ }else if(direction==='import' && (options.acknowledgeUnverifiedMetadata||options.output))throw refuse('--acknowledge-unverified-metadata and import --output require --legacy-v1.');
+ if (!api || typeof api[direction] !== 'function' || (target === 'remote' && api.remote !== true)) throw refuse(`Complete ${target} ${direction} is unsupported: the reviewed portability API and binding policy must be adopted first.`);
+ const located = direction === 'export' ? await locateExport(project.root, file) : await locateImport(project.root, file), path = located.path;
+ const legacyOutput = options.legacyV1 ? await locateExport(project.root, options.output) : undefined;
+ const legacyRecovery=legacyOutput?{output:legacyOutput.path,acknowledged:options.acknowledgeUnverifiedMetadata}:undefined;
+ const sessionFile = options.sessionFile ? await contained(project.root, options.sessionFile, { privateFile: true }) : undefined;
+ if(options.journal && legacyRecovery)throw refuse('--journal requires normal v2 import; legacy v1 metadata cannot authenticate a later-journal recovery.');
+ if (options.journal && (direction !== 'import' || target !== 'local')) throw refuse('--journal applies to a local import only.');
+ // A later archive of the same installation carries its latest erasure journal.
+ const journal = options.journal ? await contained(project.root, options.journal, { privateFile: true }) : undefined;
+ await project.adapter.prepareData?.(project.root, custody.store, signal);
+ // Only now can the seed's Vite configuration load in a checkout that never built.
+ await located.unserved(); await legacyOutput?.unserved();
+ const result=await api[direction]({ root: project.root, target, path, journal, origin: options.origin, sessionFile, signal, platform:options.platform, legacyRecovery, ...custody });
+ if(direction==='import' && target==='local' && (await localDependencyLinks(project.root)).some(link=>link.needs_relink)) {
+  custody.store.report('Imported provider links need fresh approval. Run rer setup with RER_LINK_TOKEN_FILE to re-link this installation.');
+  return {...result,needsRelink:true,nextCommand:'rer setup'};
+ }
+ return result;
+}

package/cli/version.mjs

@@ -0,0 +1,36 @@
+// The rer CLI version: one source (global/package.json in Base) for the npm
+// package, `rer --version` and the version a vendored copy records. A commit
+// tagged rer-v<version> is that version; any other commit stamps
+// <version>-dev.g<sha8>, which sorts below the release.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageName = '@runeditrun/rer';
+const readJson = path => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; } };
+
+export function stampedVersion(base, version, revision = 'HEAD') {
+ const git = args => execFileSync('git', ['-C', base, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+ if (git(['tag', '--points-at', revision]).split('\n').includes(`rer-v${version}`)) return version;
+ return `${version}-dev.g${git(['rev-parse', '--short=8', revision])}`;
+}
+
+// The version of the rer source at `root`: a packed @runeditrun/rer carries it
+// in its package.json; a Base checkout derives it from its version source and
+// Git. undefined for a source tree without the version source.
+export function cliVersion(root) {
+ const packed = readJson(join(root, 'package.json'));
+ if (packed?.name === packageName) return packed.version;
+ const source = readJson(join(root, 'global/package.json'));
+ return source ? stampedVersion(root, source.version) : undefined;
+}
+
+// The version a vendored copy recorded (scripts/base-cli/inventory.json), else
+// the version of the rer source this file belongs to. undefined for a vendored
+// copy too old to record one.
+export function runningVersion() {
+ const vendored = readJson(new URL('../inventory.json', import.meta.url));
+ if (vendored) return vendored.cliVersion;
+ return cliVersion(fileURLToPath(new URL('..', import.meta.url)));
+}

package/composition/git-source.mjs

@@ -0,0 +1,111 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+export const sha256 = (bytes) =>
+  createHash("sha256").update(bytes).digest("hex");
+export function git(repo, args) {
+  return execFileSync("git", ["--no-replace-objects", "-C", repo, ...args], {
+    maxBuffer: 128 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+export function commit(repo, ref = "HEAD") {
+  if (typeof ref !== "string" || ref.startsWith("-"))
+    throw new Error("Invalid Git ref");
+  const sha = git(repo, ["rev-parse", "--verify", `${ref}^{commit}`])
+    .toString()
+    .trim();
+  if (!/^[a-f0-9]{40}$/.test(sha)) throw new Error("Expected SHA-1 Git commit");
+  return sha;
+}
+export function safePath(path) {
+  if (
+    typeof path !== "string" ||
+    !path ||
+    path.includes("\\") ||
+    /[\x00-\x1f\x7f]/.test(path) ||
+    path.split("/").some((p) => !p || p === "." || p === "..")
+  )
+    throw new Error(`Unsafe source or target: ${path}`);
+  if (
+    path
+      .split("/")
+      .some(
+        (p) =>
+          [
+            ".git",
+            ".seed",
+            ".worktrees",
+            "node_modules",
+            "dist",
+            ".output",
+            ".wrangler",
+            ".tanstack",
+            "test-results",
+            "playwright-report",
+            "coverage",
+            ".DS_Store",
+          ].includes(p) ||
+          /^\.env|^\.dev\.vars|\.(pem|key|p12|pfx|tsbuildinfo)$/.test(p),
+      ) ||
+    /(^|\/)(wrangler\.toml|wrangler\.local\.jsonc?|composition\.lock\.json)$/.test(
+      path,
+    )
+  )
+    throw new Error(`State or secret is not source: ${path}`);
+  return path;
+}
+export function tree(repo, sha) {
+  return git(repo, ["ls-tree", "-rz", "--full-tree", sha])
+    .toString()
+    .split("\0")
+    .filter(Boolean)
+    .map((line) => {
+      const tab = line.indexOf("\t");
+      const header = line.slice(0, tab),
+        path = line.slice(tab + 1);
+      const [mode, type, oid] = header.split(" ");
+      return { path, mode, type, oid };
+    });
+}
+export function blob(repo, sha, path) {
+  safePath(path);
+  return git(repo, ["show", `${sha}:${path}`]);
+}
+export function json(repo, sha, path) {
+  return JSON.parse(blob(repo, sha, path));
+}
+// Base's verification belongs in Base, rather than in each adopting seed.
+export function testSource(path) {
+  return path.split('/').some(part => ['test', 'tests', 'fixtures'].includes(part)) ||
+    /(?:\.test\.[^/]+|(?:^|\/)test-manifest-support\.mjs$|(?:^|\/)(?:test-fixture|[^/]+-fixture)\.(?:mjs|cjs)$|(?:^|\/)(?:tests|test_[^/]+|[^/]*_tests)\.py|(?:^|\/)browser-(?:check|output)\.mjs)$/.test(path);
+}
+export function select(repo, sha, source, { includeTests = true } = {}) {
+  safePath(source);
+  const entries = tree(repo, sha).filter(
+    (e) => (e.path === source || e.path.startsWith(`${source}/`)) &&
+      (includeTests || !testSource(e.path)),
+  );
+  if (!entries.length) throw new Error(`Missing source: ${source}`);
+  return entries.map((e) => {
+    safePath(e.path);
+    if (e.type !== "blob" || !["100644", "100755"].includes(e.mode))
+      throw new Error(`Unsafe source mode: ${e.path}`);
+    return {
+      path: e.path,
+      relative: e.path === source ? "" : e.path.slice(source.length + 1),
+      bytes: git(repo, ["cat-file", "blob", e.oid]),
+      mode: e.mode === "100755" ? 0o755 : 0o644,
+    };
+  });
+}
+export function familyManifest(repo, sha) {
+  const data = json(repo, sha, "family.json");
+  // Bootstrap validates only what is needed to locate immutable tooling.
+  // The pinned exporter owns the complete schema and compatibility rules.
+  if (
+    typeof data?.base?.commit !== "string" ||
+    !/^[a-f0-9]{40}$/.test(data.base.commit)
+  )
+    throw new Error("family.json needs an immutable base commit");
+  return data;
+}

package/edition-authoring/files.mjs

@@ -0,0 +1,81 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+export const hash = value => crypto.createHash('sha256').update(value).digest('hex');
+export const json = value => JSON.stringify(value, null, 2) + '\n';
+const environment = {...process.env, GIT_NO_REPLACE_OBJECTS: '1'};
+export function git(root, ...args) {
+  return execFileSync('git', ['-C', root, ...args], {env: environment, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe']}).trim();
+}
+// Raw Git output, for committed source bytes. The limit fails explicitly rather than truncating.
+function output(root, args, input) {
+  try {
+    return execFileSync('git', ['-C', root, ...args], {env: environment, input, maxBuffer: 64 * 1024 * 1024, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe']});
+  } catch (error) {
+    if (error.code === 'ENOBUFS') throw Error('Git source output exceeds the 64 MiB acquisition limit');
+    throw error;
+  }
+}
+export const raw = (root, ...args) => output(root, args);
+export const batch = (root, input, ...args) => output(root, args, input);
+export function safe(name) {
+  if (typeof name !== 'string' || !name || name.includes('\\') || /[\x00-\x1f\x7f]/.test(name) || path.posix.isAbsolute(name) || name.split('/').some(p => !p || p === '.' || p === '..' || p === '.git')) {
+    throw Error(`Unsafe path: ${name}`);
+  }
+  return name;
+}
+export function noLinks(root, relative) {
+  let current = root;
+  for (const part of relative.split('/')) {
+    current = path.join(current, part);
+    let stat;
+    try { stat = fs.lstatSync(current); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (stat?.isSymbolicLink()) throw Error('Symlink in destination path');
+  }
+}
+export function tracked(root, allowMissing = false) {
+  const result = Object.create(null);
+  for (const name of git(root, 'ls-files', '-z').split('\0').filter(Boolean)) {
+    safe(name);
+    if (name === 'sources.lock.json' || name.startsWith('.edition/')) continue;
+    noLinks(root, name);
+    if (allowMissing && !fs.existsSync(path.join(root, name))) continue;
+    const stat = fs.statSync(path.join(root, name));
+    if (!stat.isFile()) throw Error(`Unsupported tracked source: ${name}`);
+    result[name] = {data: fs.readFileSync(path.join(root, name)).toString('base64'), executable: !!(stat.mode & 0o111)};
+  }
+  return result;
+}
+export const digest = files => hash(json(files));
+// Base's test, fixture and browser-check sources, which portable copies leave out.
+// Composition pins its tooling alone, so composition/git-source.mjs keeps its own copy.
+export function testSource(path) {
+  return path.split('/').some(part => ['test', 'tests', 'fixtures'].includes(part)) ||
+    /(?:\.test\.[^/]+|(?:^|\/)test-manifest-support\.mjs$|(?:^|\/)(?:test-fixture|[^/]+-fixture)\.(?:mjs|cjs)$|(?:^|\/)(?:tests|test_[^/]+|[^/]*_tests)\.py|(?:^|\/)browser-(?:check|output)\.mjs)$/.test(path);
+}
+export function writeTree(root, files) {
+  // Validate the complete destination set before writing any selected source.
+  for (const name of Object.keys(files)) {
+    safe(name); noLinks(root, name);
+    if (fs.existsSync(path.join(root, name))) throw Error(`Source destination already exists: ${name}`);
+  }
+  for (const [name, value] of Object.entries(files)) {
+    const target = path.join(root, name);
+    fs.mkdirSync(path.dirname(target), {recursive: true});
+    fs.writeFileSync(target, Buffer.from(value.data, 'base64'), {mode: value.executable ? 0o755 : 0o644, flag: 'wx'});
+  }
+}
+export function fresh(destination, root) {
+  let absolute = path.resolve(destination);
+  let parent = path.dirname(absolute);
+  let tail = path.basename(absolute);
+  while (!fs.existsSync(parent)) {
+    tail = path.join(path.basename(parent), tail);
+    parent = path.dirname(parent);
+  }
+  absolute = path.join(fs.realpathSync(parent), tail);
+  if (absolute === root || absolute.startsWith(root + path.sep) || fs.existsSync(absolute)) throw Error('Output must be absent and outside edition');
+  return absolute;
+}

package/edition-authoring/manifest.mjs

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {safe} from './files.mjs';
+export const VERSION = '1.1.0';
+const identity = /^[a-zA-Z0-9][a-zA-Z0-9._-]*\/[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+export function origin(value) {
+  if (!value || typeof value.repository !== 'string' || !value.repository || value.repository.startsWith('-') || (!value.projection && !/^[a-f0-9]{40}$/.test(value.revision))) {
+    throw Error('Source requires repository and immutable full commit');
+  }
+  if (value.projection) {
+    const p = value.projection;
+    if (value.revision !== undefined || p.schemaVersion !== 1 || !/^[a-f0-9]{64}$/.test(p.originalSha256) || !/^[a-f0-9]{64}$/.test(p.recipeSha256) || Object.keys(p).sort().join(',') !== 'originalSha256,recipeSha256,schemaVersion') throw Error('Invalid public projection identity');
+  }
+  if (value.paths) {
+    if (!Array.isArray(value.paths) || !value.paths.length) throw Error('Origin paths must be nonempty');
+    value.paths.forEach(safe);
+  }
+  if (value.path !== undefined && value.path !== '.') safe(value.path);
+}
+export function manifest(root) {
+  const recipe = JSON.parse(fs.readFileSync(path.join(root, 'edition.json'), 'utf8'));
+  if (recipe.schemaVersion !== 1 || !identity.test(recipe.id)) throw Error('Invalid edition identity/schema');
+  if (recipe.toolchain?.id !== 'runeditrun/edition-authoring' || recipe.toolchain.version !== VERSION) throw Error('Unsupported independently pinned toolchain');
+  if (recipe.parent) origin(recipe.parent);
+  if (!Array.isArray(recipe.components)) throw Error('Components required');
+  const ids = new Set();
+  const paths = [];
+  let foundations = 0;
+  for (const component of recipe.components) {
+    if (!identity.test(component.id) || ids.has(component.id)) throw Error('Duplicate/invalid publisher-qualified component');
+    ids.add(component.id);
+    if (!['edition', 'module', 'family', 'foundation'].includes(component.role)) throw Error('Invalid component role');
+    if (component.role === 'foundation') foundations++;
+    const selected = component.source;
+    if (selected?.kind === 'local') {
+      if (!Array.isArray(selected.paths) || !selected.paths.length) throw Error('Local source paths required');
+      selected.paths.forEach(p => paths.push(safe(p)));
+      if (selected.origin) origin(selected.origin);
+      for (const mapping of selected.mappings || []) {
+        safe(mapping.path); safe(mapping.originPath);
+        if (!selected.origin || !selected.paths.some(p => mapping.path === p || mapping.path.startsWith(p + '/'))) {
+          throw Error('Mapping outside local source or missing origin');
+        }
+      }
+    } else if (selected?.kind === 'git') {
+      origin(selected);
+      paths.push(safe(selected.destination));
+      if (selected.workspace && !path.isAbsolute(selected.workspace)) throw Error('Workspace must be an explicit absolute checkout');
+    } else throw Error('Unknown source kind');
+  }
+  for (const component of recipe.components) {
+    for (const required of component.requires || []) if (!ids.has(required)) throw Error(`Missing selected dependency: ${required}`);
+    for (const conflict of component.conflicts || []) if (ids.has(conflict)) throw Error(`Conflicting selected component: ${conflict}`);
+  }
+  if (foundations > 1) throw Error('Select one runtime foundation');
+  for (let i = 0; i < paths.length; i++) {
+    if (paths[i] === 'edition.json' || paths[i] === 'sources.lock.json' || paths[i].startsWith('.edition')) throw Error('Reserved source destination');
+    for (let j = 0; j < i; j++) {
+      if (paths[i] === paths[j] || paths[i].startsWith(paths[j] + '/') || paths[j].startsWith(paths[i] + '/')) {
+        throw Error(`Colliding source paths: ${paths[i]} and ${paths[j]}`);
+      }
+    }
+  }
+  return recipe;
+}

package/global/README.md

@@ -0,0 +1,158 @@
+# rer
+
+`rer` is the Run Edit Run command. Install it once, then run `rer <verb>` in any
+Run Edit Run checkout: every verb runs that checkout's own pinned copy, so a
+checkout always gets the behaviour it was built and tested with.
+
+## Install
+
+Any one of these leaves `rer` on your PATH:
+
+```sh
+npx -y @runeditrun/rer cli install                # user install in ~/.local/share/rer, launcher ~/.local/bin/rer
+curl -fsSL https://runeditrun.com/install.sh | sh  # the same user install, without npm
+npm install -g @runeditrun/rer                    # npm's own global layout
+```
+
+`install.sh` is the file at the root of this package. It reads the version, the
+tarball and its sha512 integrity from the npm registry (`npm_config_registry`,
+default `https://registry.npmjs.org`; `RER_VERSION=X` pins an exact version,
+otherwise the latest), checks the download's integrity, file count and size,
+refuses archives with absolute paths, `..` entries, links or devices, then runs
+the package's own `rer cli install`. A failed or refused download leaves the
+version you had selected.
+
+No installer edits shell profiles. When `~/.local/bin` is not on your PATH, the
+install prints the exact line to add for your shell. The launcher runs `node` from
+PATH, so a Node upgrade does not break it. A re-run with the same build changes
+nothing; a different build is installed beside the current one, the previous one
+is kept and older ones are removed. It refuses to replace a `~/.local/bin/rer`
+that it did not write.
+
+`rer --version` prints this rer's version; inside a checkout a second line
+names the version the checkout pins, or says that its vendored copy is
+unversioned (exported before copies recorded one).
+
+`rer cli status` shows the version, the digest of the installed contents, the
+install channel (`npx`, `script` or `npm-global`), the launcher, the install root
+and every other `rer` on PATH. `rer cli uninstall` removes the launcher and the
+install root it runs only; `~/.rer` (servers, jobs, Node runtimes) is untouched.
+An npm global `rer` prints its `npm uninstall -g` command and leaves a user
+install in place.
+
+### Requirements
+
+- macOS or Linux, on x64 or arm64. WSL2 counts as Linux.
+- Node 22 or later on PATH; `rer` stops with one line naming the minimum on an
+  older Node.
+- For `install.sh`: `curl` and `tar`.
+- For `rer dev` in a checkout: the checkout's own package manager (pnpm for
+  Run Edit Run seeds).
+
+Not supported: native Windows (`install.sh` and `rer` say to use WSL2), and
+`OPERATIONS.json` version 1 projects.
+
+## Update
+
+```sh
+rer update               # the latest published version
+rer update --version X   # exactly X
+```
+
+`rer update` follows the way `rer` was installed. A user install (`npx` or
+`install.sh`) downloads the version from the registry, checks it as `install.sh`
+does and switches to it atomically, keeping the previous version and the same
+channel; a damaged or mismatched download leaves the current version selected.
+It says "already current" when the registry's version has the same contents. A
+development build (`<version>-dev.g<sha8>`) moves to the release once that
+version is published, and a different build of the same version counts as an
+update. An npm global install runs `npm install -g @runeditrun/rer@X` for its own
+prefix; when npm fails (for example, a prefix only root can write), `rer update`
+exits non-zero with npm's message and the exact command to run.
+
+In a terminal, `rer` checks the registry at most once a day and prints one line
+when a newer version is published. It never prints in `--json` output or when
+output is not a terminal, never delays a command by more than about 1.5 seconds,
+and `RER_NO_UPDATE_CHECK=1` turns it off.
+
+## Launch a checkout
+
+```sh
+rer dev
+```
+
+In a first-party checkout this is the whole launch. It installs dependencies when
+`node_modules` is missing, incomplete (no `node_modules/.modules.yaml`, or an
+install a launch started did not finish) or older than the lockfile, sets up a local owner
+(`owner@<checkout-name>.test`) on the first free port from 8787 when the checkout
+has never been set up (`--port N` picks the port), fills any setup answer the
+seed declares a `localDefault` for in `rer-setup.json` (a literal, a generated
+secret kept only in the checkout's private settings, or the chosen local
+origin), starts the app and prints:
+
+```
+RER_READY http://127.0.0.1:8787
+RER_SIGNED_IN owner@cradle.test
+RER_OPEN http://127.0.0.1:8787/__dev/key#...
+```
+
+or `RER_SIGN_IN <outbox>` for a seed that signs in through its development outbox.
+It never prompts and never re-runs setup on a checkout that is already set up. A
+setup a launch started that was stopped or failed is run again by the next
+`rer dev`, keeping the owner and origin it saved, unless a setup has finished
+there since (for example your own `rer setup`). A checkout whose pin reports it is
+not set up (`rer describe`'s `local.prepared`) but that already holds an owner
+(`local.ownerSaved`, for example when a newer manifest requires another setting)
+finishes setup keeping that owner and origin. A required setup answer with no value and no
+`localDefault` stops the launch with exit 3 and setup's message naming it.
+
+Inside a checkout `rer` acts on the nearest `OPERATIONS.json` at or above the
+working directory; `--cwd DIR` names the project root itself, exactly as
+`node scripts/rer.mjs` reads it.
+
+Without a terminal (an agent's shell tool) it returns as soon as the app is ready
+and leaves it running, printing the server's private log path; in a terminal it
+stays in the foreground and Ctrl-C stops it. `--detach` and `--foreground`
+override the choice, and `--json` prints `progress` events and the ready event. A
+first launch can take minutes: it prints a progress line at least every 30
+seconds, and if the calling command is killed the launch carries on; run
+`rer dev` again to reattach. A second `rer dev` reprints the ready lines.
+`rer dev --stop` stops the server, or a launch still preparing (which then
+reports that it was stopped), waits until every process they started has
+exited and says what it stopped; if any is still running it exits non-zero
+naming their PIDs.
+
+Servers started through `rer` (`rer dev`, `rer preview`) get a 10-server limit and a 12-hour idle timeout
+unless you set `RER_SERVER_LIMIT`, `RER_SERVER_IDLE_SECONDS` or `--idle-timeout`.
+`rer` supplies them only to checkouts whose pinned copy applies lower defaults
+or does not report its own (`rer describe` reports `defaults`), so a current
+checkout never records a limit you did not set.
+A start is never refused for machine load alone unless `RER_SERVERS_LOAD_THRESHOLD`
+or `RER_JOBS_LOAD_THRESHOLD` is set; memory and disk guards stay.
+
+## Find what to launch
+
+```sh
+rer list [DIR] [--json]
+```
+
+lists the checkouts in a folder, newest change first, with their profile
+(`first-party`, `independent` or `unsupported`), whether `rer dev` can launch
+them, whether they are set up, and their running URL.
+
+Independent projects (an `OPERATIONS.json` version 2 without a seed contract) run
+their declared commands with `rer <verb> [-- args]`; zero-setup launching does not
+apply to them. `OPERATIONS.json` version 1 is not supported.
+
+## Verbs
+
+In a checkout, every verb runs that checkout's own pinned `rer`; `rer VERB --help`
+there lists its flags:
+
+`install`, `setup`, `dev`, `preview`, `build`, `verify`, `reset --yes`, `deploy`,
+`export`, `import`, `outbox`, `doctor`, `describe`, `check`, `release`.
+
+Anywhere: `rer list [DIR]`, `rer cli status|install|uninstall`, `rer update`,
+`rer --version` and `rer --help`.
+
+Licence: MIT.

package/global/checkout.mjs

@@ -0,0 +1,72 @@
+// Find the project an invocation acts on: the nearest OPERATIONS.json at or
+// above the working directory, or exactly --cwd DIR. Then pick whose code runs it.
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { ownRoot, packageName } from './package-info.mjs';
+
+// The value of --cwd among the wrapper flags (never after a -- separator).
+function cwdFlag(args) {
+ for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--') return undefined;
+  if (args[i] === '--cwd') return { index: i + 1, value: args[i + 1] };
+ }
+ return undefined;
+}
+
+export function descriptorProfile(file) {
+ let descriptor;
+ try { descriptor = JSON.parse(readFileSync(file, 'utf8')); } catch { return { profile: 'unreadable' }; }
+ if (descriptor?.version === 2) return { profile: descriptor.seedContract ? 'first-party' : 'independent' };
+ return { profile: 'unsupported', version: descriptor?.version };
+}
+
+const projectRoot = directory => { try { return statSync(join(directory, 'OPERATIONS.json')).isFile() ? realpathSync(directory) : undefined; } catch { return undefined; } };
+
+// --cwd names the project root itself, as the pinned dispatcher reads it: no
+// upward search. When it names no project, the dispatcher of the checkout
+// around the working directory (else this package's own) receives it
+// unchanged, as an absolute path, and refuses it with its own message.
+export function locate(argv) {
+ const flag = cwdFlag(argv.slice(1)), args = [...argv];
+ if (flag?.value !== undefined) {
+  // A value the dispatcher's parser rejects (empty, or another flag) reaches it as given.
+  const usable = flag.value.trim() && !flag.value.startsWith('--'), named = resolve(process.cwd(), flag.value), root = usable ? projectRoot(named) : undefined;
+  if (root) { args[flag.index + 1] = root; return { root, args, ...descriptorProfile(join(root, 'OPERATIONS.json')) }; }
+  if (usable) args[flag.index + 1] = named;
+  const near = around(process.cwd());
+  return { root: near && ['first-party', 'independent'].includes(descriptorProfile(join(near, 'OPERATIONS.json')).profile) ? near : undefined, args, profile: 'refused' };
+ }
+ const root = around(process.cwd());
+ return { root, args, ...(root ? descriptorProfile(join(root, 'OPERATIONS.json')) : { profile: 'none' }) };
+}
+
+// The nearest project root at or above a directory.
+function around(start) {
+ for (let directory = start; ; directory = dirname(directory)) {
+  const root = projectRoot(directory);
+  if (root) return root;
+  if (dirname(directory) === directory) return undefined;
+ }
+}
+
+export function unsupportedMessage(root, version) {
+ return `${join(root, 'OPERATIONS.json')} is an OPERATIONS version ${version ?? '(none)'} descriptor, which rer does not run. Use the commands that project documents, or move it to OPERATIONS version 2.`;
+}
+
+function declaresPackage(root) {
+ try {
+  const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+  return Boolean(manifest.dependencies?.[packageName] ?? manifest.devDependencies?.[packageName]);
+ } catch { return false; }
+}
+
+// 1. the checkout's own pinned package, 2. its vendored scripts/rer.mjs,
+// 3. this package's bundled dispatcher.
+export function dispatcher(root) {
+ if (root && declaresPackage(root)) {
+  const pinned = join(root, 'node_modules', packageName);
+  if (existsSync(join(pinned, 'global/rer.mjs')) && realpathSync(pinned) !== ownRoot) return { mode: 'package', entry: join(realpathSync(pinned), 'global/rer.mjs') };
+ }
+ if (root && existsSync(join(root, 'scripts/rer.mjs'))) return { mode: 'vendored', entry: join(root, 'scripts/rer.mjs') };
+ return { mode: 'bundled', entry: join(ownRoot, 'bin/rer.mjs') };
+}

package/global/cli/command.mjs

@@ -0,0 +1,13 @@
+// rer cli status|install|uninstall
+const usage = 'Usage: rer cli status [--json] | rer cli install | rer cli uninstall\n';
+
+export async function cliCommand(args) {
+ const [action, ...flags] = args;
+ if (!action || ['--help', '-h'].includes(action)) { process.stdout.write(usage); return 0; }
+ const allowed = action === 'status' ? ['--json'] : [];
+ const unknown = flags.find(flag => !allowed.includes(flag));
+ if (!['status', 'install', 'uninstall'].includes(action) || unknown !== undefined) { process.stderr.write(`Unsupported: rer cli ${args.join(' ')}\n${usage}`); return 2; }
+ if (action === 'status') return (await import('./status.mjs')).status({ json: flags.includes('--json') });
+ if (action === 'install') return (await import('./install.mjs')).install();
+ return (await import('./uninstall.mjs')).uninstall();
+}

package/global/cli/install.mjs

@@ -0,0 +1,75 @@
+// rer cli install: copy the running package's own bytes into an immutable
+// version directory, switch `current` atomically, keep the previous version,
+// prune older ones and write the launcher. Never edits shell profiles.
+import { randomUUID } from 'node:crypto';
+import { chmod, cp, mkdir, readdir, readlink, rename, rm, symlink, writeFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { ownManifest, ownRoot, packageDigest, packageFileList } from '../package-info.mjs';
+import { installRecord, launcherOwner, launcherScript, layout } from './layout.mjs';
+
+async function readLink(path) { try { return await readlink(path); } catch (error) { if (['ENOENT', 'EINVAL'].includes(error.code)) return undefined; throw error; } }
+
+// Files read-only (immutable by intent); directories stay removable for pruning.
+async function freeze(root) {
+ for (const path of await packageFileList(root)) await chmod(join(root, path), path.endsWith('global/rer.mjs') || path === 'bin/rer.mjs' ? 0o555 : 0o444);
+}
+
+async function copyVersion(paths, name) {
+ const staging = join(paths.versions, `.staging-${randomUUID()}`);
+ await mkdir(paths.versions, { recursive: true });
+ try {
+  await cp(ownRoot, staging, { recursive: true });
+  await freeze(staging);
+  await rename(staging, join(paths.versions, name));
+ } finally { await rm(staging, { recursive: true, force: true }); }
+}
+
+async function switchCurrent(paths, name) {
+ const temporary = `${paths.current}.${randomUUID()}`;
+ await symlink(join('versions', name), temporary);
+ await rename(temporary, paths.current);
+}
+
+async function writeLauncher(paths) {
+ await mkdir(paths.bin, { recursive: true });
+ const temporary = `${paths.launcher}.${randomUUID()}`;
+ await writeFile(temporary, launcherScript(paths.data), { mode: 0o755 });
+ await rename(temporary, paths.launcher);
+}
+
+export function pathAdvice(paths, env = process.env) {
+ const entries = (env.PATH ?? '').split(':').filter(Boolean).map(entry => resolve(entry));
+ if (entries.includes(resolve(paths.bin))) return undefined;
+ const shell = basename(env.SHELL ?? '');
+ if (shell === 'fish') return `${paths.bin} is not on your PATH. Run this once in fish, then open a new terminal:\n  fish_add_path $HOME/.local/bin`;
+ const profile = shell === 'zsh' ? '~/.zshrc' : shell === 'bash' ? (process.platform === 'darwin' ? '~/.bash_profile' : '~/.bashrc') : '~/.profile';
+ return `${paths.bin} is not on your PATH. Add this line to ${profile}, then open a new terminal:\n  export PATH="$HOME/.local/bin:$PATH"`;
+}
+
+export async function install() {
+ const paths = layout(), manifest = ownManifest(), digest = await packageDigest(ownRoot);
+ const name = `${manifest.version}-${digest.slice(0, 8)}`, channel = process.env.RER_INSTALL_CHANNEL === 'script' ? 'script' : 'npx';
+ const launcher = await launcherOwner(paths.launcher);
+ if (launcher.state === 'foreign') {
+  process.stderr.write(`rer cli install: ${paths.launcher} already exists and was not written by rer cli install (it may be the unrelated npm package "rer"). Nothing was changed. Remove or rename it, then run the install again.\n`);
+  return 4;
+ }
+ const record = await installRecord(paths), current = await readLink(paths.current);
+ const script = launcherScript(paths.data);
+ let present = false;
+ try { present = await packageDigest(join(paths.versions, name)) === digest; } catch (error) { if (error.code !== 'ENOENT') throw error; }
+ const advice = pathAdvice(paths);
+ if (present && current === join('versions', name) && launcher.text === script && record?.channel === channel) {
+  process.stdout.write(`rer ${manifest.version} is already current (${join(paths.versions, name)}). Nothing changed.\n${advice ? advice + '\n' : ''}`);
+  return 0;
+ }
+ if (!present) { await rm(join(paths.versions, name), { recursive: true, force: true }); await copyVersion(paths, name); }
+ const previousName = current?.startsWith('versions/') && current !== join('versions', name) ? current.slice('versions/'.length) : record?.previous;
+ if (current !== join('versions', name)) await switchCurrent(paths, name);
+ const keep = new Set([name, previousName].filter(Boolean));
+ for (const entry of await readdir(paths.versions)) if (!keep.has(entry) && !entry.startsWith('.staging-')) await rm(join(paths.versions, entry), { recursive: true, force: true });
+ await writeFile(paths.record, JSON.stringify({ channel, previous: previousName && keep.has(previousName) ? previousName : null }, null, 2) + '\n', { mode: 0o644 });
+ if (launcher.text !== script) await writeLauncher(paths);
+ process.stdout.write(`Installed rer ${manifest.version} in ${join(paths.versions, name)}.\n${paths.launcher} runs it.${previousName ? ` The previous version (${previousName}) is kept.` : ''}\n${advice ? advice + '\n' : ''}`);
+ return 0;
+}