create-agent-rig 0.4.0 → 0.5.0

package/packages/cli/dist/commands/upgrade.js

@@ -1,11 +1,12 @@
 import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { initInstallSet, projectNameFor } from './init.js';
+import { hookFilesReferencedIn } from '../lib/init-settings.js';
 import { loadHashHistory, presentInEveryRelease } from '../lib/history.js';
 import { agentOsInstallSet, agentOsLayerDirs } from '../lib/install-set.js';
 import { listTree } from '../lib/copy-tree.js';
 import { readManifest, sha256, writeManifest } from '../lib/manifest.js';
-import { resolveInside } from '../lib/safe-path.js';
+import { isSafeSubstitutionValue, resolveInside } from '../lib/safe-path.js';
 import { detokenizeContent, substituteFileName } from '../lib/substitute.js';
 import { TARGETS } from '../lib/targets.js';
 import { packageVersion } from '../lib/version.js';
@@ -13,6 +14,8 @@ import { packageVersion } from '../lib/version.js';
 export class UpgradeError extends Error {
 }
 const SETTINGS = '.claude/settings.json';
+const CODEX_HOOKS = '.codex/hooks.json';
+const WIRING_PATHS = new Set([SETTINGS, CODEX_HOOKS]);
 /** The universal layer's architecture group — installed by `create`, never by `init`. */
 const ARCHITECTURE_ONLY = [
     '.claude/rules/architecture.md',
@@ -130,6 +133,30 @@ function isReleasedVersion(history, rel, content, ctx) {
     const candidates = new Set([sha256(content), sha256(detokenizeContent(content, ctx))]);
     return known.hashes.some((hash) => candidates.has(hash));
 }
+/**
+ * Would writing `next` over `current` stop calling a hook that is still there?
+ *
+ * The one question the hash arms cannot answer. They prove the bytes belong to
+ * the rig; they do not prove the replacement wires the same hooks, and
+ * Wiring files have flavours that differ in exactly that. A hook file
+ * still on disk with nothing wired to it is the quiet failure
+ * `lib/init-settings.ts` names: the rules claim it is enforced and nothing ever
+ * calls it.
+ *
+ * Only hooks whose FILE is still present count. One the user deleted on purpose
+ * is not being silenced by this write — it was already gone.
+ */
+async function unwiresAnInstalledHook(repoDir, current, next) {
+    const nextHooks = hookFilesReferencedIn(next);
+    for (const hook of hookFilesReferencedIn(current)) {
+        if (nextHooks.has(hook))
+            continue;
+        const onDisk = resolveInside(repoDir, hook);
+        if (onDisk !== null && (await exists(onDisk)))
+            return true;
+    }
+    return false;
+}
 /**
  * What an upgrade would do, decided per file, writing nothing.
  *
@@ -146,11 +173,37 @@ export async function planUpgrade(repoDir, options = {}) {
         ? await detectInstall(repoDir)
         : { kind: manifest.kind, stacks: manifest.stacks, region: manifest.project.region };
     const kind = manifest?.kind ?? detected.kind;
-    const name = path.basename(path.resolve(repoDir));
-    // `init` slugs the directory name into something an operator can type (it
-    // ends up in the kill-switch filename); `create` validated it as an npm name
-    // at generation time, so there the basename is already the project name.
-    const bootstrapName = kind === 'init' ? projectNameFor(repoDir) : name;
+    // With no manifest to read, guess the name the rig's own files were written
+    // with — and each command wrote them differently, so the guess branches the
+    // same way:
+    //
+    // - `init` substitutes the **slug** and records the slug (`init.ts`,
+    //   `projectNameFor` in both places), so for an init rig the slug is not an
+    //   approximation, it is the value;
+    // - `create` substitutes the name it was **given**, having validated it — and
+    //   that validation accepts a trailing `-` or `.`, which `projectNameFor`
+    //   strips. So slugging a create rig renames it: `my-app.` became `my-app`,
+    //   stopped matching its own installed files, and returned four of them as
+    //   conflicts.
+    //
+    // The one case where the raw name cannot be kept is a directory the manifest
+    // reader would refuse — `My App` produced `{"name":"My App"}`, which
+    // `parseManifest` voids, so the manifest this command exists to write was
+    // written and immediately unreadable and every later run reported "no
+    // manifest here (a pre-0.4.0 rig)". The condition is that reader's own
+    // exported predicate, not a second copy of its rule.
+    //
+    // 🔴 All three branches were bought by a defect, and two of those defects
+    // were introduced by fixing the other — the mirror is easy to miss, because
+    // each fix looks total until the other kind is tried. Change nothing here
+    // without running the three sibling cases in `upgrade.test.ts`.
+    //
+    // ⚠ It is still the *directory's* name, so a renamed or cloned rig with no
+    // manifest bootstraps the new name and its substituted files come back as
+    // conflicts — kept and reported, never overwritten. Committing the manifest
+    // is what removes the guess, and that is unchanged from 0.4.0.
+    const rawName = path.basename(path.resolve(repoDir));
+    const bootstrapName = kind === 'init' || !isSafeSubstitutionValue(rawName) ? projectNameFor(repoDir) : rawName;
     const project = manifest?.project ?? {
         name: bootstrapName,
         scope: bootstrapName,
@@ -172,6 +225,7 @@ export async function planUpgrade(repoDir, options = {}) {
     const contents = new Map();
     const nextFiles = {};
     let wiring = null;
+    const wiringByPath = new Map();
     for (const file of files) {
         const current = await readIfPresent(repoDir, file.rel);
         const recorded = manifest?.files[file.rel];
@@ -202,36 +256,63 @@ export async function planUpgrade(repoDir, options = {}) {
             }
             continue;
         }
-        if (file.rel === SETTINGS) {
-            if (current === file.content) {
-                actions.push({ rel: file.rel, verdict: 'unchanged' });
-                nextFiles[file.rel] = sha256(file.content);
-            }
-            else {
-                // Same special case `init` makes: this file is a merge target, not a
-                // payload — replacing it can unwire hooks the user added themselves.
-                wiring = file.content;
-                actions.push({
-                    rel: file.rel,
-                    verdict: 'wiring',
-                    reason: 'never replaced — merge the entries below by hand',
-                });
-                if (recorded !== undefined)
-                    nextFiles[file.rel] = recorded;
-            }
-            continue;
-        }
+        // The two limits that keep wiring files' new replaceability from
+        // disarming the rig, both measured rather than reasoned about.
+        //
+        // 1. The released-hash fallback is not enough for THIS file. Every other
+        //    file has one flavour; this one has two — `create` wires all the hooks,
+        //    `init` wires only the ones it installs — and they share a history
+        //    entry. A manifest-less rig that ran `init` is recorded `kind: 'init'`,
+        //    so matching a released hash would write the narrow wiring over the
+        //    full one. The item asks for the manifest arm and says the rest is
+        //    reported, which is also the reading with no regression behind it.
+        // 2. Even the manifest arm is not enough on its own, because `kind` is
+        //    trusted from a file that travels in pull requests. So the decision is
+        //    gated on the wiring itself: if the replacement would stop calling a
+        //    hook still sitting in `.claude/hooks/`, it is handed over. That check
+        //    does not care which flavour anything claims to be.
+        const isWiring = WIRING_PATHS.has(file.rel);
+        const wouldUnwireAnInstalledHook = isWiring && (await unwiresAnInstalledHook(repoDir, current, file.content));
+        const vouched = isWiring
+            ? recorded !== undefined && sha256(current) === recorded
+            : (recorded !== undefined && sha256(current) === recorded) ||
+                isReleasedVersion(history, file.rel, current, ctx);
         if (current === file.content) {
             actions.push({ rel: file.rel, verdict: 'unchanged' });
             nextFiles[file.rel] = sha256(file.content);
         }
-        else if (recorded !== undefined && sha256(current) === recorded) {
-            actions.push({ rel: file.rel, verdict: 'update', templatePath: file.source });
+        else if (vouched && !wouldUnwireAnInstalledHook) {
+            actions.push({
+                rel: file.rel,
+                verdict: 'update',
+                templatePath: file.source,
+                // Every other replacement is routine; this one rewrites what calls the
+                // guards, so it says so rather than arriving as one more `~` line.
+                ...(isWiring ? { reason: 'the hook wiring, replaced — you never edited it' } : {}),
+            });
             nextFiles[file.rel] = sha256(file.content);
         }
-        else if (isReleasedVersion(history, file.rel, current, ctx)) {
-            actions.push({ rel: file.rel, verdict: 'update', templatePath: file.source });
-            nextFiles[file.rel] = sha256(file.content);
+        else if (isWiring) {
+            // Nothing vouches for these bytes, or replacing them would silence a hook
+            // that is still installed. Either way this is the one file whose conflict
+            // is a merge rather than a choice, so the released file is handed over.
+            wiring = file.content;
+            wiringByPath.set(file.rel, file.content);
+            actions.push({
+                rel: file.rel,
+                verdict: 'wiring',
+                // Say what was actually checked. This file no longer consults the
+                // released-hash table (see the limits above), so it cannot claim these
+                // bytes are not a release — only that the manifest does not vouch for
+                // them, which is the check that ran.
+                reason: wouldUnwireAnInstalledHook
+                    ? 'replacing it would stop calling a hook that is still installed — merge the entries below by hand'
+                    : recorded === undefined
+                        ? 'the manifest does not vouch for it — treated as yours, merge the entries below by hand'
+                        : 'edited since it was installed — merge the entries below by hand',
+            });
+            if (recorded !== undefined)
+                nextFiles[file.rel] = recorded;
         }
         else {
             actions.push({
@@ -263,6 +344,7 @@ export async function planUpgrade(repoDir, options = {}) {
         bootstrapped: manifest === null,
         actions,
         wiring,
+        wiringByPath,
         contents,
         manifest: {
             version: await packageVersion(),

package/packages/cli/dist/index.js

@@ -4,13 +4,14 @@ import { CreateError, createProject } from './commands/create.js';
 import { InitError, initFileContents, initProject, planInit } from './commands/init.js';
 import { UpgradeError, applyUpgrade, planUpgrade } from './commands/upgrade.js';
 import { makePalette } from './lib/colors.js';
+import { readManifest } from './lib/manifest.js';
 import { promptConfirm, promptTarget } from './lib/prompts.js';
 import { collectGovernance, renderSummary } from './lib/summary.js';
 import { DEFAULT_TARGET, TARGET_NAMES } from './lib/targets.js';
 import { packageVersion } from './lib/version.js';
 const USAGE = `Usage: create-agent-rig <dir> [options]
 
-Scaffolds a new project into <dir>: agent operating system (.claude/, CLAUDE.md)
+Scaffolds a new project into <dir>: a Claude Code + Codex agent operating system
 plus a runnable code skeleton. Refuses to write into a non-empty directory.
 
 Options
@@ -22,9 +23,12 @@ Options
   --version         print the version
   -h, --help        this text
 
-Also: create-agent-rig init [--dry-run] [--force]
+Also: create-agent-rig init [--dry-run]
   Install the process layer (rules, gates, stop rules — no architecture
-  assumptions) into the CURRENT existing repo. Refuses to clobber CLAUDE.md.
+  assumptions) into the CURRENT existing repo. Refuses to clobber CLAUDE.md
+  or AGENTS.md.
+  --force is deprecated: it refuses and points at upgrade, which refreshes a
+  rig file by file. It is removed in 0.6.
 
 Also: create-agent-rig upgrade [--dry-run] [--yes]
   Bring the rig in the CURRENT repo up to this version. Replaces the files it
@@ -44,10 +48,23 @@ async function runInit(rawArgs) {
     }
     const cwd = process.cwd();
     const dryRun = values['dry-run'] === true;
+    // `init` adopts a repo the rig knows nothing about. Run inside a rig `create`
+    // generated — reachable when its CLAUDE.md was deleted — it is the wrong
+    // command: it installs the process layer alone and never refreshes the stack
+    // overlays. Say so before anything is written, so it is visible on --dry-run
+    // too.
+    //
+    // It is a manifest read, so a pre-0.4.0 rig with no manifest gets no advisory
+    // even when it came from `create` — the same limit `recordInstall` carries,
+    // and stated in both places because either one alone reads as wider.
+    const existing = await readManifest(cwd);
     const plan = await planInit(cwd);
     process.stdout.write(`agent-rig init — process layer into ${cwd}\n\n` +
         plan.files.map((f) => `  + ${f.path}`).join('\n') +
         '\n');
+    if (existing?.kind === 'create') {
+        process.stdout.write(`\n!  This rig was created by create-agent-rig — \`init\` only fills gaps here; use \`upgrade\` to refresh.\n`);
+    }
     if (plan.conflicts.length > 0) {
         process.stdout.write(`\nAlready present (kept, not overwritten):\n` +
             plan.conflicts.map((c) => `  · ${c}`).join('\n') +
@@ -61,12 +78,15 @@ async function runInit(rawArgs) {
     process.stdout.write(`\nInstalled ${result.written.length} files` +
         (result.skipped.length ? `, kept ${result.skipped.length} existing` : '') +
         '.\n');
-    // The one kept file that silently disables everything else: without this
-    // wiring the hooks sit on disk and are never called, while the rules claim
-    // they are enforced. Say so loudly, and hand over the exact entries.
-    if (result.skipped.includes('.claude/settings.json')) {
-        const wiring = (await initFileContents(cwd)).get('.claude/settings.json') ?? '';
-        process.stdout.write(`\n!  .claude/settings.json already exists — it was kept, so the rig's hooks are NOT wired.\n` +
+    // A kept harness config silently disables that harness's enforcement: the
+    // hooks sit on disk and are never called, while the rules claim they are.
+    // Say so loudly, and hand over the exact entries for each affected harness.
+    const generated = await initFileContents(cwd);
+    for (const wiringPath of ['.claude/settings.json', '.codex/hooks.json']) {
+        if (!result.skipped.includes(wiringPath))
+            continue;
+        const wiring = generated.get(wiringPath) ?? '';
+        process.stdout.write(`\n!  ${wiringPath} already exists — it was kept, so the rig's hooks are NOT wired there.\n` +
             `   Until you merge these entries into it, nothing enforces the rules:\n\n` +
             wiring.replace(/^/gm, '   ') +
             '\n');
@@ -124,11 +144,15 @@ async function runUpgrade(rawArgs) {
     // The one thing this command will not do for you — printed with the plan,
     // because the dry run is where a reader decides whether there is work here,
     // and a report that mentions entries it never shows is not a plan.
-    if (plan.wiring !== null) {
-        process.stdout.write(`\n!  .claude/settings.json is never replaced — it is where your own hooks live.\n` +
-            `   This version wires them like this; merge in what is missing:\n\n` +
-            plan.wiring.replace(/^/gm, '   ') +
-            '\n');
+    if (plan.wiringByPath.size > 0) {
+        for (const [wiringPath, wiring] of plan.wiringByPath) {
+            process.stdout.write(`\n!  ${wiringPath} was handed over rather than replaced — the reason is\n` +
+                `   on its line above. It is hook wiring, so it is never overwritten\n` +
+                `   without proof the rig wrote those exact bytes.\n` +
+                `   This version wires it like this; merge in what is missing:\n\n` +
+                wiring.replace(/^/gm, '   ') +
+                '\n');
+        }
     }
     if (values['dry-run'] === true) {
         process.stdout.write('\nDry run — nothing written.\n');

package/packages/cli/dist/lib/copy-tree.js

@@ -25,8 +25,38 @@ function isBinary(buffer) {
 }
 export async function copyTree(srcDir, destDir, options = {}) {
     const ignore = new Set(options.ignore ?? DEFAULT_IGNORE);
+    const files = [];
     await mkdir(destDir, { recursive: true });
-    await copyDir(srcDir, destDir, '', { ...options, ignore });
+    await collectCopyTasks(srcDir, destDir, '', { ...options, ignore }, files);
+    await mapConcurrent(files, 16, ({ srcPath, destPath, relPath }) => copyFileEntry(srcPath, destPath, relPath, { ...options, ignore }));
+}
+/** Run independent async work through a bounded pool while preserving result order. */
+export async function mapConcurrent(items, limit, worker) {
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new RangeError('concurrency limit must be positive');
+    const results = new Array(items.length);
+    let next = 0;
+    let failed = false;
+    let firstError;
+    const run = async () => {
+        while (!failed && next < items.length) {
+            const index = next;
+            next += 1;
+            try {
+                results[index] = await worker(items[index]);
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    firstError = error;
+                }
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => run()));
+    if (failed)
+        throw firstError;
+    return results;
 }
 /**
  * The destination-relative file paths {@link copyTree} would produce — same
@@ -62,7 +92,7 @@ export async function listTreeEntries(srcDir, options = {}) {
     await walk(srcDir, '');
     return files;
 }
-async function copyDir(srcDir, destDir, relDir, options) {
+async function collectCopyTasks(srcDir, destDir, relDir, options, files) {
     const entries = await readdir(srcDir, { withFileTypes: true });
     for (const entry of entries) {
         if (options.ignore.has(entry.name))
@@ -73,10 +103,10 @@ async function copyDir(srcDir, destDir, relDir, options) {
         const relPath = path.join(relDir, entry.name);
         if (entry.isDirectory()) {
             await mkdir(destPath, { recursive: true });
-            await copyDir(srcPath, destPath, relPath, options);
+            await collectCopyTasks(srcPath, destPath, relPath, options, files);
         }
         else if (entry.isFile()) {
-            await copyFileEntry(srcPath, destPath, relPath, options);
+            files.push({ srcPath, destPath, relPath });
         }
         // Symlinks and other special entries are intentionally not copied:
         // templates are plain trees.
@@ -87,7 +117,7 @@ async function copyFileEntry(srcPath, destPath, relPath, options) {
         await copyFile(srcPath, destPath); // copyFile preserves the mode by itself
         return;
     }
-    const buffer = await readFile(srcPath);
+    const [buffer, { mode }] = await Promise.all([readFile(srcPath), stat(srcPath)]);
     if (isBinary(buffer)) {
         await writeFile(destPath, buffer);
     }
@@ -96,6 +126,5 @@ async function copyFileEntry(srcPath, destPath, relPath, options) {
     }
     // writeFile does NOT preserve permissions — restore them (chmod ignores umask),
     // otherwise executable template files (scripts, hooks) arrive non-executable.
-    const { mode } = await stat(srcPath);
     await chmod(destPath, mode & 0o777);
 }

package/packages/cli/dist/lib/init-settings.js

@@ -13,6 +13,18 @@
  */
 /** Matches the hook file a wired command runs, e.g. `.claude/hooks/guard-bash.mjs`. */
 const HOOK_REFERENCE = /\.claude\/hooks\/[A-Za-z0-9._-]+\.mjs/;
+/**
+ * Every hook file some command in this settings text would run.
+ *
+ * Deliberately a scan of the raw text rather than a walk of the parsed shape:
+ * the caller compares two settings files to ask whether one stops calling a
+ * hook the other called, and a shape this module does not understand must not
+ * make that question answer "nothing was wired". The same expression decides
+ * both, so the filter and the comparison cannot drift apart.
+ */
+export function hookFilesReferencedIn(settingsText) {
+    return new Set(settingsText.match(new RegExp(HOOK_REFERENCE, 'g')) ?? []);
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/packages/cli/dist/lib/install-set.js

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { listTreeEntries } from './copy-tree.js';
+import { listTreeEntries, mapConcurrent } from './copy-tree.js';
 import { substituteContent, substituteFileName } from './substitute.js';
 import { agentOsStackDir, agentOsUniversalDir } from '../templates.js';
 /**
@@ -34,13 +34,11 @@ export async function agentOsInstallSet(stacks, ctx) {
         const entries = await listTreeEntries(layer.dir, {
             transformName: (name) => substituteFileName(name, ctx),
         });
-        for (const entry of entries) {
-            files.push({
-                rel: entry.rel,
-                source: entry.source,
-                content: substituteContent(await readFile(entry.source, 'utf8'), ctx),
-            });
-        }
+        files.push(...(await mapConcurrent(entries, 16, async (entry) => ({
+            rel: entry.rel,
+            source: entry.source,
+            content: substituteContent(await readFile(entry.source, 'utf8'), ctx),
+        }))));
     }
     return files;
 }

package/packages/cli/dist/lib/manifest.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { isSafeSegment } from './safe-path.js';
+import { isSafeSubstitutionValue } from './safe-path.js';
 /**
  * The install manifest: what this rig installed, at which version, and the
  * hash each file had when it was written.
@@ -54,18 +54,30 @@ export function parseManifest(raw) {
         typeof project.region !== 'string') {
         return null;
     }
-    // Values, not just types. These are substituted into file names and joined
-    // into paths, and this file is committed — it reaches a maintainer's disk
-    // through a pull request. A name of `../..` would send every write out of
-    // the repository, so an unsafe value invalidates the whole manifest rather
-    // than being quietly corrected into something plausible.
-    if (!isSafeSegment(project.name) || !isSafeSegment(project.scope))
+    // Values, not just types. This file is committed, so it reaches a
+    // maintainer's disk through a pull request. A name of `../..` would send a
+    // write out of the repository — and `name` and `region` go further than
+    // paths: they are substituted into installed **files**, where a quote closes
+    // the string literal `stop-flag.mjs` embeds the name in, which `guard-bash`
+    // imports on every Bash call. (`scope` reaches no template today and a
+    // `stacks` entry names an overlay *directory*.) An unsafe value invalidates
+    // the whole manifest rather than being quietly corrected into something
+    // plausible.
+    //
+    // One check, not two: `isSafeSubstitutionValue` is strictly stronger than
+    // `isSafeSegment` here — its first character excludes `.`, and its class
+    // admits neither `/` nor `\` nor `\0` — so pairing them would leave a second
+    // predicate that can never fire, read as cover, and quietly stop being true
+    // if either one moves. `isSafeSegment` still guards every path segment at
+    // write time, in `resolveInside`.
+    if (!isSafeSubstitutionValue(project.name) || !isSafeSubstitutionValue(project.scope)) {
         return null;
-    if (project.region !== '' && !isSafeSegment(project.region))
+    }
+    if (project.region !== '' && !isSafeSubstitutionValue(project.region))
         return null;
     if (!Array.isArray(m.stacks) || m.stacks.some((s) => typeof s !== 'string'))
         return null;
-    if (m.stacks.some((s) => !isSafeSegment(s)))
+    if (m.stacks.some((s) => !isSafeSubstitutionValue(s)))
         return null;
     if (!isStringRecord(m.files))
         return null;

package/packages/cli/dist/lib/safe-path.js

@@ -16,6 +16,36 @@ export function isSafeSegment(value) {
         !value.includes('\\') &&
         !value.includes('\0'));
 }
+/**
+ * A value that can be substituted into an **installed file** without changing
+ * what that file means.
+ *
+ * 🔴 **Why this is not {@link isSafeSegment}, and why widening that one instead
+ * would be wrong.** `isSafeSegment` answers "can this steer a path", and it is
+ * what {@link resolveInside} holds every path segment to when an upgrade
+ * writes — `CLAUDE.md` and `.claude/rules/workflow.md` have to keep passing it,
+ * so it cannot become this whitelist. But `project.name` is substituted into
+ * `.claude/scripts/stop-flag.mjs` **inside a single-quoted JavaScript string
+ * literal**, and `guard-bash` imports that module on every Bash call. A value
+ * that steers no path at all still closes that quote: it reaches code
+ * execution in the hook process, and it silently disarms the kill switch,
+ * because the paths it computes stop pointing at `~/.claude/<name>-loop-STOP`.
+ * A brake that looks installed and is not is the worst of the two.
+ *
+ * So the rule is a whitelist, not a blacklist of the payloads anyone thought
+ * of. It costs nothing real: `create` already refuses anything outside this
+ * shape, and `projectNameFor` only ever emits `[a-z0-9._-]` — plus a leading
+ * `_`, which is why the first character allows it.
+ *
+ * One legitimate value it does reject on purpose: the **empty** region, which
+ * `init` writes to mean "no region". That carve-out belongs to the caller
+ * (`parseManifest`), not here — an empty string is exactly what a whitelist of
+ * substitutable characters should refuse, and folding "or empty" into this
+ * predicate would hand it to `name` and `scope` as well.
+ */
+export function isSafeSubstitutionValue(value) {
+    return /^[a-z0-9_][a-z0-9._-]*$/.test(value);
+}
 /**
  * `rel` resolved under `root`, or `null` when it would land anywhere else —
  * including an absolute path, an empty path, and the classic sibling