@spectrabrain/eds 0.0.4 → 0.1.1

package/consumer/init.mjs

@@ -0,0 +1,186 @@
+import fs from "node:fs";
+import path from "node:path";
+import { cliCommand, createExitError, detectPackageManager, installCommand, packageName, readPackageJson, resolvePackage, runnerCommand } from "./paths.mjs";
+import { registerConsumerScripts, syncScriptName, writeConsumerPackageJson } from "./register-scripts.mjs";
+import { runSync } from "./sync.mjs";
+
+export const ciTargets = new Set(["github", "gitlab"]);
+const allowScriptsField = "allowScripts";
+const minimumAllowScriptsNpmMajor = 12;
+// --no-allow-scripts-pin keeps the approval valid after EDS upgrades, like the name-only entry init writes.
+const approveCommand = "npm install-scripts approve --no-allow-scripts-pin " + packageName;
+
+const ciInstallCommands = {
+  npm: "npm ci",
+  pnpm: "pnpm install --frozen-lockfile",
+  yarn: "yarn install --frozen-lockfile",
+  bun: "bun install --frozen-lockfile",
+};
+
+function ciInstallCommand(packageManager) {
+  if (packageManager.name === "yarn" && packageManager.berry) {
+    return "yarn install --immutable";
+  }
+  return ciInstallCommands[packageManager.name];
+}
+
+// A CI job that fails when sync is out of date. It runs the EDS CLI directly with the repository's package
+// manager, so the consumer's own package.json scripts are not required.
+export function renderCiSnippet(target, packageManager) {
+  const install = ciInstallCommand(packageManager);
+  const doctor = cliCommand(packageManager, "doctor");
+  if (target === "github") {
+    const setup = packageManager.name === "pnpm"
+      ? ["      - uses: pnpm/action-setup@v4"]
+      : packageManager.name === "bun"
+        ? ["      - uses: oven-sh/setup-bun@v2"]
+        : [];
+    const cache = packageManager.name === "bun" ? [] : ["          cache: " + packageManager.name];
+    return [
+      "# .github/workflows/eds-doctor.yml",
+      "name: eds doctor",
+      "on: [push, pull_request]",
+      "jobs:",
+      "  eds-doctor:",
+      "    runs-on: ubuntu-latest",
+      "    steps:",
+      "      - uses: actions/checkout@v4",
+      ...setup,
+      "      - uses: actions/setup-node@v4",
+      "        with:",
+      "          node-version: 22",
+      ...cache,
+      "      - run: " + install,
+      "      - run: " + doctor,
+      "",
+    ].join("\n");
+  }
+  if (target === "gitlab") {
+    const before = packageManager.name === "pnpm"
+      ? ["    - corepack enable"]
+      : packageManager.name === "bun"
+        ? ["    - npm install -g bun"]
+        : [];
+    return [
+      "# .gitlab-ci.yml",
+      "eds-doctor:",
+      "  image: node:22",
+      "  stage: test",
+      "  script:",
+      ...before,
+      "    - " + install,
+      "    - " + doctor,
+      "",
+    ].join("\n");
+  }
+  throw createExitError("Unknown --print-ci target: " + target + " (use github or gitlab).", 2);
+}
+
+// npm 12+ blocks dependency install scripts unless package.json allows them. A name-only entry keeps
+// the EDS postinstall running on later installs and upgrades without re-approval.
+function writeAllowScripts(consumerRoot, { log, dryRun }) {
+  const packagePath = path.join(consumerRoot, "package.json");
+  const source = fs.readFileSync(packagePath, "utf8");
+  const consumerPackage = JSON.parse(source);
+  const existing = consumerPackage[allowScriptsField];
+  if (existing !== undefined && typeof existing !== "object") {
+    log("[EDS] package.json " + allowScriptsField + " is not an object; left unchanged. To approve the EDS postinstall, run " + approveCommand + ".");
+    return false;
+  }
+  const current = existing?.[packageName];
+  if (current !== undefined) {
+    log("[EDS] package.json " + allowScriptsField + "[\"" + packageName + "\"] is already " + JSON.stringify(current) + "; left unchanged.");
+    return false;
+  }
+  if (dryRun) {
+    log("[EDS] would write " + allowScriptsField + "[\"" + packageName + "\"] = true to package.json");
+    return false;
+  }
+  consumerPackage[allowScriptsField] = { ...(existing ?? {}), [packageName]: true };
+  writeConsumerPackageJson(packagePath, source, consumerPackage);
+  log("[EDS] wrote " + allowScriptsField + "[\"" + packageName + "\"] = true to package.json so npm " + minimumAllowScriptsNpmMajor + "+ runs the EDS postinstall on later installs.");
+  return true;
+}
+
+function printInstallScriptGuidance(consumerRoot, packageManager, { log, dryRun, allowScripts }) {
+  const { name, major, berry } = packageManager;
+  if (name === "npm") {
+    if (major !== null && major >= minimumAllowScriptsNpmMajor) {
+      if (allowScripts) {
+        writeAllowScripts(consumerRoot, { log, dryRun });
+      } else {
+        log("[EDS] --no-allow-scripts: not writing " + allowScriptsField + ". Later installs skip the EDS postinstall until someone runs " + approveCommand + ".");
+      }
+    } else if (major === null) {
+      log("[EDS] The npm version is unknown because init did not run through npm. If this project uses npm " + minimumAllowScriptsNpmMajor +
+        "+, run " + approveCommand + ", or rerun " + cliCommand(packageManager, "init") + " so init can write " + allowScriptsField + ".");
+    }
+    return;
+  }
+  // The postinstall only re-registers the scripts init has just written, so approving it is optional everywhere
+  // except npm 12+, where init records the approval itself.
+  if (name === "pnpm") {
+    log("[EDS] pnpm: the scripts are registered, so the EDS postinstall needs no build approval. After upgrading EDS, run " +
+      runnerCommand(packageManager, syncScriptName) + ".");
+    return;
+  }
+  if (name === "bun") {
+    log("[EDS] Optional (bun): to let the EDS postinstall re-register the scripts on later installs, add \"trustedDependencies\": [\"" +
+      packageName + "\"] to package.json. It replaces bun's default trusted list, so this is the project owner's decision.");
+    return;
+  }
+  if (name === "yarn" && berry) {
+    log("[EDS] Optional (Yarn 2+): to let the EDS postinstall re-register the scripts on later installs, keep enableScripts: true in .yarnrc.yml " +
+      "or add \"dependenciesMeta\": { \"" + packageName + "\": { \"built\": true } } to package.json.");
+  }
+}
+
+export function runInit({
+  consumerRoot,
+  env = process.env,
+  noSync = false,
+  dryRun = false,
+  allowScripts = true,
+  printCi = null,
+  log = console.log,
+}) {
+  const packageManager = detectPackageManager(consumerRoot, env);
+  if (printCi !== null) {
+    if (!ciTargets.has(printCi)) {
+      throw createExitError("Unknown --print-ci target: " + printCi + " (use github or gitlab).", 2);
+    }
+    log(renderCiSnippet(printCi, packageManager));
+    return 0;
+  }
+
+  if (!fs.existsSync(path.join(consumerRoot, "package.json"))) {
+    throw createExitError(
+      "No package.json in " + consumerRoot + "; run init in the package that depends on " + packageName + ".",
+      1,
+    );
+  }
+  // A workspace root or a parent folder can resolve a hoisted EDS; the scripts, hooks and AGENTS.md belong to the
+  // app package that declares it.
+  const consumerPackage = readPackageJson(consumerRoot);
+  const declared = ["dependencies", "devDependencies", "optionalDependencies"].some((field) => consumerPackage?.[field]?.[packageName] !== undefined);
+  if (!declared) {
+    throw createExitError(
+      "package.json in " + consumerRoot + " does not declare " + packageName + ". Run init in the app package that uses EDS, after " +
+        installCommand(packageManager) + " there.",
+      2,
+    );
+  }
+  try {
+    resolvePackage(consumerRoot);
+  } catch {
+    throw createExitError(packageName + " is declared but not installed; run " + installCommand(packageManager) + " first.", 1);
+  }
+
+  const registered = registerConsumerScripts(consumerRoot, { log, dryRun, packageManager });
+  printInstallScriptGuidance(consumerRoot, packageManager, { log, dryRun, allowScripts });
+  if (noSync) {
+    log("[EDS] Run " + registered.syncRunCommand + " to finish setup.");
+    return 0;
+  }
+  return runSync({ consumerRoot, env, dryRun, log });
+}

package/consumer/managed-block.mjs

@@ -0,0 +1,126 @@
+import fs from "node:fs";
+import path from "node:path";
+import { renderRunnerCommands } from "./paths.mjs";
+
+export const beginMarker = "<!-- EDS:BEGIN -->";
+export const endMarker = "<!-- EDS:END -->";
+export const versionPattern = /^<!-- EDS:VERSION (\S+) -->$/m;
+export const legacyVersionLabel = "pre-0.1.0";
+
+const fenceOpenPattern = /^[ \t]{0,3}(`{3,}|~{3,})/;
+
+export function readTemplateBlock(packageRoot) {
+  const guide = fs.readFileSync(path.join(packageRoot, "CONSUMER_AGENT.md"), "utf8");
+  const beginIndex = guide.indexOf(beginMarker);
+  const endIndex = beginIndex < 0 ? -1 : guide.indexOf(endMarker, beginIndex);
+  if (beginIndex < 0 || endIndex < beginIndex) {
+    throw new Error("CONSUMER_AGENT.md has an invalid managed block.");
+  }
+  return guide.slice(beginIndex, endIndex + endMarker.length);
+}
+
+// The template is written for npm; the rendered block uses the consumer's package-manager runner
+// (pnpm, yarn, bun run) so the commands an agent reads work in that repository.
+export function renderBlock(template, version, packageManager = null) {
+  const versionLine = "<!-- EDS:VERSION " + version + " -->";
+  const withoutVersion = template.replace(/^<!-- EDS:VERSION \S+ -->\r?\n/m, "");
+  if (!withoutVersion.startsWith(beginMarker)) {
+    throw new Error("CONSUMER_AGENT.md managed block must start with " + beginMarker + ".");
+  }
+  const body = renderRunnerCommands(withoutVersion.slice(beginMarker.length), packageManager);
+  return beginMarker + "\n" + versionLine + body;
+}
+
+export function readBlockVersion(block) {
+  return block.match(versionPattern)?.[1] ?? null;
+}
+
+// Replaces the inside of Markdown fenced code blocks (``` or ~~~) with spaces of the same length, so
+// markers quoted as examples are not treated as the real block while every index still maps to the
+// original text. An unclosed fence runs to the end of the file, as in CommonMark.
+export function maskFencedBlocks(text) {
+  const lines = text.split(/(\r?\n)/);
+  let fence = null;
+  const output = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const segment = lines[index];
+    if (index % 2 === 1) {
+      output.push(segment);
+      continue;
+    }
+    if (fence === null) {
+      const opened = segment.match(fenceOpenPattern);
+      if (opened) {
+        fence = opened[1];
+      }
+      output.push(segment);
+      continue;
+    }
+    const closing = segment.match(fenceOpenPattern);
+    if (closing && closing[1][0] === fence[0] && closing[1].length >= fence.length && segment.trim() === closing[1]) {
+      fence = null;
+      output.push(segment);
+      continue;
+    }
+    output.push(" ".repeat(segment.length));
+  }
+  return output.join("");
+}
+
+function findAll(text, marker) {
+  const positions = [];
+  let index = text.indexOf(marker);
+  while (index >= 0) {
+    positions.push(index);
+    index = text.indexOf(marker, index + marker.length);
+  }
+  return positions;
+}
+
+function lineNumberAt(text, index) {
+  return text.slice(0, index).split(/\r?\n/).length;
+}
+
+const markerFix = "Keep one " + beginMarker + " line with the " + endMarker + " line after it, delete the other marker lines, " +
+  "then run sync again (sync rewrites what is between them).";
+
+function describeLines(text, positions) {
+  const lines = positions.map((position) => lineNumberAt(text, position));
+  return lines.length === 0 ? "none" : (lines.length === 1 ? "line " : "lines ") + lines.join(", ");
+}
+
+export function locateBlock(existing) {
+  const masked = maskFencedBlocks(existing);
+  const begins = findAll(masked, beginMarker);
+  const ends = findAll(masked, endMarker);
+  if (begins.length !== ends.length || begins.length > 1) {
+    throw new Error(
+      "AGENTS.md must contain zero or one complete EDS managed block. Outside fenced code blocks it has " + beginMarker + " at " +
+        describeLines(existing, begins) + " and " + endMarker + " at " + describeLines(existing, ends) + ". " + markerFix,
+    );
+  }
+  if (begins.length === 0) {
+    return null;
+  }
+
+  const [start] = begins;
+  const [endIndex] = ends;
+  if (endIndex < start) {
+    throw new Error(
+      "AGENTS.md has an invalid EDS managed block: " + endMarker + " at line " + lineNumberAt(existing, endIndex) +
+        " comes before " + beginMarker + " at line " + lineNumberAt(existing, start) + ". " + markerFix,
+    );
+  }
+  const end = endIndex + endMarker.length;
+  return { start, end, block: existing.slice(start, end) };
+}
+
+// `block` must already use `eol`; the separators around it follow the same line ending.
+export function applyBlock(existing, block, eol = "\n") {
+  const located = existing === null ? null : locateBlock(existing);
+  if (located) {
+    return existing.slice(0, located.start) + block + existing.slice(located.end);
+  }
+  const trimmed = (existing ?? "").replace(/\s*$/, "");
+  return trimmed ? trimmed + eol + eol + block + eol : block + eol;
+}

package/consumer/paths.mjs

@@ -0,0 +1,266 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+export const packageName = "@spectrabrain/eds";
+export const generatedCssRelativePath = path.join("src", "styles", "eds-tokens.css");
+
+const excludedDirectories = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  ".git",
+  "storybook-static",
+  "coverage",
+]);
+const cssExtensions = new Set([".css"]);
+const scriptExtensions = new Set([".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".mts", ".cts"]);
+
+export function createExitError(message, exitCode) {
+  const error = new Error(message);
+  error.exitCode = exitCode;
+  return error;
+}
+
+export function resolvePackage(consumerRoot) {
+  const require = createRequire(path.join(consumerRoot, "package.json"));
+  let packageJsonPath;
+  try {
+    packageJsonPath = require.resolve(packageName + "/package.json");
+  } catch {
+    throw createExitError(packageName + " is not installed here; install it in this package first.", 2);
+  }
+
+  const packageRoot = path.dirname(packageJsonPath);
+  let packageJson;
+  try {
+    packageJson = readJson(packageJsonPath);
+  } catch (error) {
+    throw createExitError(packageName + "/package.json could not be read: " + error.message, 2);
+  }
+  return {
+    packageRoot,
+    packageJson,
+    version: String(packageJson.version ?? ""),
+    resolve(specifier) {
+      return require.resolve(packageName + "/" + specifier);
+    },
+  };
+}
+
+export function resolvePackageRoot(consumerRoot) {
+  return resolvePackage(consumerRoot).packageRoot;
+}
+
+export function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+export function readPackageJson(directory) {
+  const filePath = path.join(directory, "package.json");
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  return readJson(filePath);
+}
+
+export function readTextIfExists(filePath) {
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : null;
+}
+
+export function listFiles(directory, extensions) {
+  if (!fs.existsSync(directory)) {
+    return [];
+  }
+  const files = [];
+  const walk = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const entryPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (excludedDirectories.has(entry.name) || entry.name.startsWith(".")) {
+          continue;
+        }
+        walk(entryPath);
+        continue;
+      }
+      if (entry.isFile() && extensions.has(path.extname(entry.name))) {
+        files.push(entryPath);
+      }
+    }
+  };
+  walk(directory);
+  return files.sort();
+}
+
+export function listCssFiles(consumerRoot) {
+  return listFiles(consumerRoot, cssExtensions);
+}
+
+export function listScriptFiles(directory) {
+  return listFiles(directory, scriptExtensions);
+}
+
+export function toPosix(filePath) {
+  return filePath.split(path.sep).join("/");
+}
+
+export function relativeTo(consumerRoot, filePath) {
+  return toPosix(path.relative(consumerRoot, filePath));
+}
+
+export function relativeImportPath(fromFile, toFile) {
+  const relative = toPosix(path.relative(path.dirname(fromFile), toFile));
+  return relative.startsWith(".") ? relative : "./" + relative;
+}
+
+export function detectIndent(text) {
+  return text.match(/^([ \t]+)"/m)?.[1] ?? "  ";
+}
+
+export function detectEol(text) {
+  return text.includes("\r\n") ? "\r\n" : "\n";
+}
+
+// Re-renders LF (or mixed) text with the target file's dominant line ending.
+export function withEol(text, eol) {
+  return text.replace(/\r?\n/g, eol);
+}
+
+// Comparisons (doctor) treat CRLF and LF as equal so an autocrlf checkout is not reported as stale.
+export function normalizeEol(text) {
+  return text === null || text === undefined ? text : text.replace(/\r\n/g, "\n");
+}
+
+export function realpathOrNull(filePath) {
+  try {
+    return fs.realpathSync(filePath);
+  } catch {
+    return null;
+  }
+}
+
+const runnerPrefixes = {
+  npm: "npm run ",
+  pnpm: "pnpm ",
+  yarn: "yarn ",
+  bun: "bun run ",
+};
+const lockfileManagers = [
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+  ["package-lock.json", "npm"],
+  ["npm-shrinkwrap.json", "npm"],
+];
+const htmlExtensions = new Set([".html"]);
+
+export function parseUserAgent(userAgent) {
+  const match = String(userAgent ?? "").match(/^(npm|pnpm|yarn|bun)\/(\d+)(?:\.(\d+))?(?:\.(\d+))?(\S*)/);
+  if (!match) {
+    return null;
+  }
+  const [, name, major, minor, patch, rest] = match;
+  return { name, version: [major, minor ?? "0", patch ?? "0"].join(".") + rest, major: Number.parseInt(major, 10) };
+}
+
+function isYarnBerry(consumerRoot, major) {
+  if (major !== null) {
+    return major >= 2;
+  }
+  if (fs.existsSync(path.join(consumerRoot, ".yarnrc.yml"))) {
+    return true;
+  }
+  const lockfile = readTextIfExists(path.join(consumerRoot, "yarn.lock"));
+  return lockfile !== null && /^__metadata:/m.test(lockfile);
+}
+
+// The directory that holds .git at or above startDirectory, or null outside git.
+export function findGitRoot(startDirectory) {
+  for (let directory = path.resolve(startDirectory); ; ) {
+    if (fs.existsSync(path.join(directory, ".git"))) {
+      return directory;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) {
+      return null;
+    }
+    directory = parent;
+  }
+}
+
+// The nearest lockfile names the package manager: this directory, then its parents up to the git root, so a
+// workspace package resolves to the repository lockfile. Outside git only this directory counts, so a stray
+// lockfile in a parent folder is never picked up.
+export function findLockfile(startDirectory) {
+  const start = path.resolve(startDirectory);
+  const directories = [start];
+  for (let directory = start; !fs.existsSync(path.join(directory, ".git")); ) {
+    const parent = path.dirname(directory);
+    if (parent === directory) {
+      directories.length = 1;
+      break;
+    }
+    directories.push(parent);
+    directory = parent;
+  }
+  for (const directory of directories) {
+    const found = lockfileManagers.find(([fileName]) => fs.existsSync(path.join(directory, fileName)));
+    if (found) {
+      return { directory, fileName: found[0], name: found[1] };
+    }
+  }
+  return null;
+}
+
+// The lockfile decides; the runner in npm_config_user_agent (npm, npx, pnpm, yarn, bun) decides only without a
+// lockfile. `npx @spectrabrain/eds init` in a pnpm repository therefore still renders pnpm commands. The runner's
+// version is kept only when the runner is that same manager (npm 12+ allowScripts, Yarn 2+).
+export function detectPackageManager(consumerRoot, env = process.env) {
+  const fromAgent = parseUserAgent(env.npm_config_user_agent);
+  const lockfile = findLockfile(consumerRoot);
+  const name = lockfile?.name ?? fromAgent?.name ?? "npm";
+  const agent = fromAgent?.name === name ? fromAgent : null;
+  const major = agent?.major ?? null;
+  return {
+    name,
+    version: agent?.version ?? null,
+    major,
+    berry: name === "yarn" && isYarnBerry(lockfile?.directory ?? consumerRoot, major),
+    // Yarn Plug'n'Play writes .pnp.cjs (.pnp.js before Yarn 3) next to yarn.lock and installs no node_modules.
+    pnp: name === "yarn" && [".pnp.cjs", ".pnp.js"].some((fileName) => fs.existsSync(path.join(lockfile?.directory ?? consumerRoot, fileName))),
+    runner: runnerPrefixes[name],
+    source: lockfile ? "lockfile" : fromAgent ? "user-agent" : "default",
+  };
+}
+
+export function runnerCommand(packageManager, scriptName) {
+  return (packageManager?.runner ?? runnerPrefixes.npm) + scriptName;
+}
+
+// npx and bunx fall back to the registry when no local bin exists, and the unscoped registry name "eds" is an
+// unrelated package, so they always name @spectrabrain/eds. pnpm exec and yarn run only the local bin.
+const cliPrefixes = {
+  npm: "npx " + packageName,
+  pnpm: "pnpm exec eds",
+  yarn: "yarn eds",
+  bun: "bunx " + packageName,
+};
+const addPrefixes = { npm: "npm install", pnpm: "pnpm add", yarn: "yarn add", bun: "bun add" };
+
+export function cliCommand(packageManager, args) {
+  return (cliPrefixes[packageManager?.name] ?? cliPrefixes.npm) + " " + args;
+}
+
+export function installCommand(packageManager, names = [packageName]) {
+  return (addPrefixes[packageManager?.name] ?? addPrefixes.npm) + " " + names.join(" ");
+}
+
+export function renderRunnerCommands(text, packageManager) {
+  const runner = packageManager?.runner ?? runnerPrefixes.npm;
+  return runner === runnerPrefixes.npm ? text : text.replace(/\bnpm run /g, runner);
+}
+
+export function listHtmlFiles(consumerRoot) {
+  return listFiles(consumerRoot, htmlExtensions);
+}