@spectrabrain/eds 0.1.0 → 0.1.1

package/consumer/align.mjs

@@ -0,0 +1,401 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  analyzeFrontend,
+  checkBackendPackage,
+  classifyChangedPaths,
+  declaredDependencies,
+  detectFramework,
+  findFrontendPackages,
+  hashFile,
+  parseJsonc,
+  summarizeStructure,
+  walkFiles,
+} from "./align-analysis.mjs";
+import { countFindings, packageManagerCommands, renderNotes, renderPlan } from "./align-plan.mjs";
+import { alignDirectory, conventionsFileName, planFileName, rootLockfiles, stateFileName, stateSchemaVersion, templatesDirectoryName } from "./align-rules.mjs";
+import { cliCommand, createExitError, detectPackageManager, generatedCssRelativePath, installCommand, packageName, readPackageJson, resolvePackage, toPosix } from "./paths.mjs";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const templatesRoot = path.join(packageRoot, "consumer", "align", "templates");
+const notesFileName = "NOTES.md";
+const findingLimitPerKind = 40;
+const placeholderPattern = /\{\{eds\.(\w+)\}\}/g;
+
+function git(cwd, args) {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 });
+  } catch {
+    return null;
+  }
+}
+
+function gitPaths(cwd, args) {
+  return (git(cwd, args) ?? "").split("\0").filter(Boolean);
+}
+
+function readState(statePath, shown = (relativePath) => relativePath) {
+  if (!fs.existsSync(statePath)) {
+    return null;
+  }
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+  } catch (error) {
+    throw createExitError(toPosix(statePath) + " could not be read (" + error.message + "); delete " + shown(alignDirectory) + " and run eds align again.", 2);
+  }
+  if (state?.schemaVersion !== stateSchemaVersion) {
+    throw createExitError(toPosix(statePath) + " was written by another eds align version; delete " + shown(alignDirectory) + " and run eds align again.", 2);
+  }
+  return state;
+}
+
+// The frontend package: --frontend, the current directory when it holds a plan or declares react, or the only
+// React package below it.
+function resolveFrontendDirectory(consumerRoot, frontendOption) {
+  if (frontendOption) {
+    const directory = path.resolve(consumerRoot, frontendOption);
+    if (!fs.existsSync(path.join(directory, "package.json"))) {
+      throw createExitError("--frontend " + frontendOption + " has no package.json.", 2);
+    }
+    return directory;
+  }
+  if (fs.existsSync(path.join(consumerRoot, alignDirectory, stateFileName))) {
+    return consumerRoot;
+  }
+  const own = readPackageJson(consumerRoot);
+  if (own !== null && declaredDependencies(own).has("react")) {
+    return consumerRoot;
+  }
+  const candidates = findFrontendPackages(consumerRoot).filter((candidate) => candidate !== ".");
+  if (candidates.length === 1) {
+    return path.join(consumerRoot, candidates[0]);
+  }
+  throw createExitError(
+    candidates.length === 0
+      ? "No package here or below declares react; run eds align inside the frontend package."
+      : "Several React packages (" + candidates.join(", ") + "); rerun with --frontend <dir>.",
+    2,
+  );
+}
+
+// Tracked changes against a commit plus untracked files, as repository-relative paths.
+function changedSince(gitRoot, commit) {
+  return [
+    ...gitPaths(gitRoot, ["diff", "--name-only", "-z", "--no-renames", commit]),
+    ...gitPaths(gitRoot, ["ls-files", "--others", "--exclude-standard", "-z"]),
+  ];
+}
+
+function readStrictOption(packageDirectory) {
+  for (const name of ["tsconfig.json", "tsconfig.app.json"]) {
+    const filePath = path.join(packageDirectory, name);
+    if (!fs.existsSync(filePath)) {
+      continue;
+    }
+    try {
+      if (parseJsonc(fs.readFileSync(filePath, "utf8")).compilerOptions?.strict === true) {
+        return true;
+      }
+    } catch {
+      // An unparsable tsconfig is reported by the check; the template keeps the EVA default.
+    }
+  }
+  return false;
+}
+
+function joinPosix(...parts) {
+  const joined = path.posix.join(...parts.filter((part) => part !== "" && part !== "."));
+  return joined === "" ? "." : joined;
+}
+
+// Templates rendered with this repository's paths. Keys are target paths relative to the frontend package.
+export function renderTemplates({ app, protectedInside, packageJson, viteMajor, strict }) {
+  const eslintFileName = packageJson.type === "module" ? "eslint.config.js" : "eslint.config.mjs";
+  const viteTemplate = viteMajor !== null && viteMajor >= 8 ? "vite.config.rolldown.ts" : "vite.config.babel.ts";
+  const values = {
+    srcDir: app.srcDir,
+    strict: String(strict),
+    eslintIgnores: ["dist", "coverage", ".eds", ...protectedInside].map((entry) => JSON.stringify(entry)).join(", "),
+    prettierIgnores: [
+      "dist",
+      "coverage",
+      ".eds",
+      joinPosix(app.appDir, "public/mockServiceWorker.js"),
+      toPosix(generatedCssRelativePath),
+      "*.md",
+      ...rootLockfiles,
+      ...protectedInside,
+    ].join("\n"),
+  };
+  const rendered = new Map();
+  for (const templatePath of walkFiles(templatesRoot)) {
+    let target;
+    if (templatePath === "vite.config.babel.ts" || templatePath === "vite.config.rolldown.ts") {
+      if (templatePath !== viteTemplate) continue;
+      target = "vite.config.ts";
+    } else if (templatePath === "eslint.config.js") {
+      target = eslintFileName;
+    } else if (templatePath === "prettierrc.json" || templatePath === "prettierignore") {
+      target = "." + templatePath;
+    } else if (templatePath === "env.mock") {
+      target = joinPosix(app.appDir, ".env.mock");
+    } else if (templatePath.startsWith("src/")) {
+      target = joinPosix(app.srcDir, templatePath.slice("src/".length));
+    } else if (templatePath.startsWith("public/")) {
+      target = joinPosix(app.appDir, templatePath);
+    } else {
+      target = templatePath;
+    }
+    const contents = fs.readFileSync(path.join(templatesRoot, templatePath), "utf8").replace(placeholderPattern, (match, name) => {
+      if (!Object.prototype.hasOwnProperty.call(values, name)) {
+        throw new Error("Unknown template placeholder " + match + " in " + templatePath);
+      }
+      return values[name];
+    });
+    rendered.set(target, contents);
+  }
+  return rendered;
+}
+
+function logFindings(findings, log) {
+  const shown = new Map();
+  const hidden = new Map();
+  for (const finding of findings) {
+    const key = finding.level + " " + finding.kind;
+    const count = shown.get(key) ?? 0;
+    if (count >= findingLimitPerKind) {
+      hidden.set(key, (hidden.get(key) ?? 0) + 1);
+      continue;
+    }
+    shown.set(key, count + 1);
+    log("[EDS] " + (finding.level === "warning" ? "warning " : "") + finding.kind + ": " + finding.message);
+  }
+  for (const [key, count] of hidden) {
+    log("[EDS] … " + count + " more " + key + " findings (fix the ones above and run the check again)");
+  }
+}
+
+// The rules file as an agent reaches it from the frontend package: through node_modules (the frontend's own or a hoisted
+// one up to the git root) when EDS is installed there, else the resolved package directory (pnpm store, linked install).
+function conventionsPathFrom(packageDirectory, gitRoot, packageRoot) {
+  for (let directory = packageDirectory; ; directory = path.dirname(directory)) {
+    const candidate = path.join(directory, "node_modules", packageName, conventionsFileName);
+    if (fs.existsSync(candidate)) {
+      return toPosix(path.relative(packageDirectory, candidate));
+    }
+    if (directory === gitRoot || path.dirname(directory) === directory) {
+      break;
+    }
+  }
+  return toPosix(path.join(path.relative(packageDirectory, packageRoot), conventionsFileName));
+}
+
+function verificationCommands(commands) {
+  return ["format:check", "lint", "typecheck", "build", "eds:doctor"].map((script) => commands.run(script)).join(", ");
+}
+
+function locateFrontend({ consumerRoot, frontend }) {
+  const packageDirectory = fs.realpathSync(resolveFrontendDirectory(consumerRoot, frontend));
+  const packageJson = readPackageJson(packageDirectory);
+  const framework = detectFramework(declaredDependencies(packageJson));
+  if (framework.unsupported !== null) {
+    throw createExitError(
+      framework.unsupported + " found: moving it to Vite is a framework migration, not alignment. eds align supports Vite + React single-page apps.",
+      2,
+    );
+  }
+  if (!framework.vite || !framework.react) {
+    throw createExitError("eds align needs a Vite + React app; " + toPosix(path.join(packageDirectory, "package.json")) + " must declare vite and react.", 2);
+  }
+  const topLevel = git(packageDirectory, ["rev-parse", "--show-toplevel"]);
+  const gitRoot = topLevel === null ? null : fs.realpathSync(topLevel.trim());
+  const packageRelative = gitRoot === null ? "" : toPosix(path.relative(gitRoot, packageDirectory));
+  return { packageDirectory, packageJson, gitRoot, packageRelative };
+}
+
+function requireGit(gitRoot) {
+  if (gitRoot === null) {
+    throw createExitError(
+      "eds align needs git: the base commit is how --check proves the backend did not change. Ask the user to create a git repository at " +
+        "the project root (the directory that holds both frontend and backend) with a .gitignore covering node_modules, build output and " +
+        ".env files, commit everything once, then rerun eds align.",
+      2,
+    );
+  }
+}
+
+export function runAlign({ consumerRoot, env = process.env, check = false, frontend = null, dryRun = false, log = console.log }) {
+  const located = locateFrontend({ consumerRoot, frontend });
+  // Paths in the output are relative to the current directory, which differs from the frontend package with --frontend.
+  const fromCwd = toPosix(path.relative(consumerRoot, located.packageDirectory));
+  const shown = (relativePath) => (fromCwd === "" ? relativePath : fromCwd + "/" + relativePath);
+  // With --frontend the rerun hint keeps the flag, or the check could not locate the package again.
+  const frontendFlag = frontend ? " --frontend " + frontend : "";
+  return check ? runCheck({ ...located, env, log, shown, frontendFlag }) : runPlan({ ...located, env, dryRun, log, fromCwd, shown });
+}
+
+function runPlan({ packageDirectory, packageJson, gitRoot, packageRelative, env, dryRun, log, fromCwd, shown }) {
+  requireGit(gitRoot);
+  let pkg;
+  try {
+    pkg = resolvePackage(packageDirectory);
+  } catch {
+    throw createExitError("Install " + packageName + " in " + (packageRelative || ".") + " first (" + installCommand(detectPackageManager(packageDirectory, env)) + "), then run eds align there.", 2);
+  }
+  if (fs.realpathSync(pkg.packageRoot) !== fs.realpathSync(packageRoot)) {
+    log("[EDS] note: this is eds from " + toPosix(packageRoot) + ", but the frontend has " + packageName + "@" + pkg.version + " installed; run its own CLI (" + cliCommand(detectPackageManager(packageDirectory, env), "align") + ") so the plan matches the installed documents.");
+  }
+  const packageManager = detectPackageManager(packageDirectory, env);
+  const alignPath = path.join(packageDirectory, alignDirectory);
+  const alignRelative = packageRelative === "" ? alignDirectory : packageRelative + "/" + alignDirectory;
+  const previous = readState(path.join(alignPath, stateFileName), shown);
+
+  const analysis = analyzeFrontend({ packageDirectory, gitRoot, protectedInfo: previous?.protected ?? null });
+  let base;
+  let baseline;
+  if (previous !== null) {
+    base = previous.git.base;
+    baseline = previous.git.baseline;
+  } else {
+    base = git(gitRoot, ["rev-parse", "--verify", "HEAD"])?.trim() ?? null;
+    if (!base) {
+      throw createExitError("The repository has no commit yet, so --check has no base. Ask the user to commit the current files once " +
+        "(with a .gitignore covering node_modules, build output and .env files), then rerun eds align.", 2);
+    }
+    // Uncommitted changes that already exist are the baseline. Only paths the check guards are recorded:
+    // everything else inside the frontend package may change freely.
+    baseline = {};
+    const guarded = (relativePath) =>
+      analysis.protectedInfo.repository.some((entry) => relativePath === entry || relativePath.startsWith(entry + "/")) ||
+      (packageRelative !== "" && relativePath !== packageRelative && !relativePath.startsWith(packageRelative + "/"));
+    for (const relativePath of changedSince(gitRoot, "HEAD")) {
+      if (relativePath !== alignRelative && !relativePath.startsWith(alignRelative + "/") && guarded(relativePath)) {
+        baseline[relativePath] = hashFile(path.join(gitRoot, relativePath));
+      }
+    }
+  }
+
+  analysis.structure = summarizeStructure(analysis.allFiles);
+  const templates = renderTemplates({
+    app: analysis.app,
+    protectedInside: analysis.protectedInfo.inside,
+    packageJson,
+    viteMajor: analysis.majors.vite,
+    strict: readStrictOption(packageDirectory),
+  });
+  const createdAt = previous?.createdAt ?? new Date().toISOString();
+  const frontendState = { packageRelative, appDir: analysis.app.appDir, srcDir: analysis.app.srcDir };
+  const state = {
+    schemaVersion: stateSchemaVersion,
+    createdBy: packageName + "@" + pkg.version,
+    createdAt,
+    frontend: frontendState,
+    git: { base, baseline },
+    protected: analysis.protectedInfo,
+  };
+  const plan = renderPlan({
+    version: pkg.version,
+    createdAt,
+    base,
+    packageManager,
+    frontend: frontendState,
+    analysis,
+    templates: [...templates.keys()],
+    alignLabel: alignDirectory,
+    conventionsPath: conventionsPathFrom(packageDirectory, gitRoot, pkg.packageRoot),
+  });
+  const counts = countFindings(analysis.findings);
+
+  log("[EDS] align: frontend " + (packageRelative || ".") + " (Vite " + (analysis.majors.vite ?? "?") + ", React " + (analysis.majors.react ?? "?") +
+    ", " + packageManager.name + "), sources " + analysis.app.srcDir);
+  const protectedList = analysis.protectedInfo.repository;
+  log("[EDS] align: protected paths: " + (protectedList.length > 0 ? protectedList.join(", ") : "none detected") +
+    (packageRelative === "" ? "" : ", plus everything outside " + packageRelative));
+  log("[EDS] align: " + counts.errors + " " + plural(counts.errors, "error") + (counts.errorSummary ? " (" + counts.errorSummary + ")" : "") + ", " +
+    counts.warnings + " " + plural(counts.warnings, "warning") + " to resolve");
+  if (previous !== null) {
+    log("[EDS] align: kept the base commit " + base.slice(0, 12) + " from " + createdAt.slice(0, 10) + "; delete " + shown(alignDirectory) + " to start over.");
+  }
+  const planPath = path.join(alignPath, planFileName);
+  if (dryRun) {
+    const notesExist = fs.existsSync(path.join(alignPath, notesFileName));
+    log("[EDS] would write " + shown(alignDirectory + "/" + planFileName) + ", " + (notesExist ? "" : shown(alignDirectory + "/" + notesFileName) + ", ") +
+      shown(alignDirectory + "/" + stateFileName) + " and " + templates.size + " templates in " + shown(alignDirectory + "/" + templatesDirectoryName));
+    return 0;
+  }
+
+  const templatesPath = path.join(alignPath, templatesDirectoryName);
+  fs.rmSync(templatesPath, { recursive: true, force: true });
+  fs.mkdirSync(alignPath, { recursive: true });
+  // The directory ignores itself, so the plan never lands in a commit or in the base comparison.
+  fs.writeFileSync(path.join(alignPath, ".gitignore"), "*\n");
+  fs.writeFileSync(path.join(alignPath, stateFileName), JSON.stringify(state, null, 2) + "\n");
+  fs.writeFileSync(planPath, plan);
+  const notesPath = path.join(alignPath, notesFileName);
+  if (!fs.existsSync(notesPath)) {
+    fs.writeFileSync(notesPath, renderNotes());
+  }
+  for (const [target, contents] of templates) {
+    const targetPath = path.join(templatesPath, target);
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, contents);
+  }
+  const commands = packageManagerCommands(packageManager);
+  log("[EDS] wrote " + shown(alignDirectory + "/" + planFileName) + ", " + notesFileName + ", " + stateFileName + " and " + templates.size + " templates (base " + base.slice(0, 12) + ")");
+  log("[EDS] Next: " + (fromCwd === "" ? "" : "cd " + fromCwd + ", then ") + "follow " + alignDirectory + "/" + planFileName + " step by step; " +
+    commands.eds("align --check") + " verifies each step" + (fromCwd === "" ? "." : " (run every PLAN.md command from " + fromCwd + ")."));
+  return 0;
+}
+
+// With a plan, the check also proves that no protected or out-of-package file changed since its base commit.
+// Without one (after step 8 removed .eds/align), it checks the conventions only.
+function runCheck({ packageDirectory, gitRoot, packageRelative, env, log, shown, frontendFlag = "" }) {
+  const state = readState(path.join(packageDirectory, alignDirectory, stateFileName), shown);
+  const commands = packageManagerCommands(detectPackageManager(packageDirectory, env));
+  const findings = [];
+  let analysis;
+  if (state === null) {
+    log("[EDS] note: no " + shown(alignDirectory + "/" + stateFileName) + ": checking the conventions only (the protected-path check needs the base commit of eds align).");
+    analysis = analyzeFrontend({ packageDirectory, gitRoot: gitRoot ?? packageDirectory });
+  } else {
+    requireGit(gitRoot);
+    if (git(gitRoot, ["cat-file", "-e", state.git.base + "^{commit}"]) === null) {
+      throw createExitError("The base commit " + state.git.base.slice(0, 12) + " is not in this repository; delete " + shown(alignDirectory) + " and run eds align again.", 2);
+    }
+    const alignRelative = packageRelative === "" ? alignDirectory : packageRelative + "/" + alignDirectory;
+    findings.push(...classifyChangedPaths({
+      changed: changedSince(gitRoot, state.git.base),
+      baseline: state.git.baseline ?? {},
+      hashOf: (relativePath) => hashFile(path.join(gitRoot, relativePath)),
+      packageRelative,
+      protectedPaths: state.protected.repository ?? [],
+      alignRelative,
+      base: state.git.base,
+    }));
+    analysis = analyzeFrontend({ packageDirectory, gitRoot, protectedInfo: state.protected });
+    findings.push(...checkBackendPackage({ packageJson: analysis.packageJson, state }));
+  }
+  findings.push(...analysis.findings);
+  const counts = countFindings(findings);
+  const since = state === null ? "" : " since " + state.git.base.slice(0, 12);
+  logFindings(findings, log);
+  if (counts.errors === 0) {
+    log("[EDS] align: " + analysis.app.srcDir + " follows the EVA frontend conventions" +
+      (state === null ? "" : ", and no protected or out-of-package file changed" + since) +
+      (counts.warnings > 0 ? " (" + counts.warnings + " " + plural(counts.warnings, "warning") + ": fix them or record why)" : "") + ".");
+    log("[EDS] Also required: " + verificationCommands(commands) + " (each must exit 0, and eds:doctor must print [EDS] synced with)" +
+      (state === null ? "." : ", then step 8 of " + shown(alignDirectory + "/" + planFileName) + "."));
+    return 0;
+  }
+  log("[EDS] align: " + counts.errors + " " + plural(counts.errors, "error") + " (" + counts.errorSummary + "), " + counts.warnings + " " +
+    plural(counts.warnings, "warning") + since + ". Fix the errors and run " + commands.eds("align --check" + frontendFlag) + " again" +
+    (state === null ? "." : "; " + shown(alignDirectory + "/" + planFileName) + " maps each kind to a step, and protected, outside and backend-* errors mean revert that change."));
+  return 1;
+}
+
+function plural(count, word) {
+  return count === 1 ? word : word + "s";
+}

package/consumer/cli.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { runAlign } from "./align.mjs";
 import { runDoctor } from "./doctor.mjs";
 import { runInit } from "./init.mjs";
 import { runSync } from "./sync.mjs";
@@ -7,21 +8,27 @@ const usage = [
   "Usage: eds <command> [options]",
   "",
   "Commands:",
-  "  init      Register sync:eds, eds:doctor and doctor hooks in package.json, approve the postinstall",
-  "            for the detected package manager (npm 12+ writes allowScripts; others print steps), then run sync",
+  "  init      Register sync:eds and eds:doctor, plus pretypecheck/prebuild (eds doctor) when typecheck/build exist,",
+  "            write allowScripts on npm 12+, then run sync. Run it in the package that declares @spectrabrain/eds",
   "  sync      Generate src/styles/eds-tokens.css, wire the Tailwind root CSS and update AGENTS.md",
-  "            and the @AGENTS.md import in CLAUDE.md and GEMINI.md when they exist (without a Tailwind root only those change)",
+  "            and the @AGENTS.md import in CLAUDE.md (or .claude/CLAUDE.md) and GEMINI.md when they exist",
+  "            (without a Tailwind root only those change); notes say when an agent may not load the block",
   "  doctor    Check whether sync is up to date, the EDS font is imported and every eds-* class in the sources",
   "            is a public token (exit 1 when something is off)",
+  "  align     One-time reorganization of a Vite + React frontend into the EVA conventions (FRONTEND_CONVENTIONS.md):",
+  "            write .eds/align/PLAN.md, the steps an AI agent follows, plus templates; source files are not changed",
   "",
   "Options:",
   "  --only tailwind|agents     sync: apply only that part",
-  "  --dry-run                  Print the files sync or init would write without writing them",
+  "  --dry-run                  Print the files sync, init or align would write without writing them",
   "  --no-sync                  init: register scripts only",
   "  --no-allow-scripts         init: do not write allowScripts to package.json on npm 12+",
-  "  --print-ci github|gitlab   init: print a CI job that runs npx eds doctor, then exit",
+  "  --print-ci github|gitlab   init: print a CI job that runs eds doctor with this repository's package manager",
   "  --warn                     doctor: report findings but exit 0 (same as EDS_DOCTOR=warn)",
   "  --scan                     doctor: also list Tailwind palette and arbitrary color classes that bypass the EDS tokens",
+  "  --check                    align: check the conventions and that no backend or out-of-package file changed since",
+  "                             the plan's base commit (exit 1 when something is off)",
+  "  --frontend <dir>           align: the frontend package when the current directory is not it",
   "  --help                     Show this message",
   "",
   "Environment:",
@@ -30,55 +37,97 @@ const usage = [
   "  EDS_DOCTOR=warn|off               Downgrade or silence doctor failures",
 ].join("\n");
 
+const commands = ["init", "sync", "doctor", "align"];
+// The commands each option applies to. An option given to another command stops the CLI instead of being ignored,
+// so `eds sync --check` never writes files while looking like a check.
+const optionCommands = {
+  "--only": ["sync"],
+  "--dry-run": ["sync", "init", "align"],
+  "--no-sync": ["init"],
+  "--no-allow-scripts": ["init"],
+  "--print-ci": ["init"],
+  "--warn": ["doctor"],
+  "--scan": ["doctor"],
+  "--check": ["align"],
+  "--frontend": ["align"],
+};
+const valueOptions = new Set(["--only", "--print-ci", "--frontend"]);
+
+function usageError(message) {
+  // The bare `npx eds` could fetch an unrelated registry package, so the hint names the scoped package.
+  const error = new Error(message + " Run npx @spectrabrain/eds --help (or your package runner's eds --help) for the commands and options.");
+  error.exitCode = 2;
+  return error;
+}
+
 function parseArguments(argv) {
-  const [command, ...rest] = argv;
-  const options = { only: null, dryRun: false, noSync: false, allowScripts: true, printCi: null, warn: false, scan: false, help: false };
+  const [first, ...rest] = argv;
+  const command = first === "help" ? "--help" : first;
+  const options = {
+    only: null,
+    dryRun: false,
+    noSync: false,
+    allowScripts: true,
+    printCi: null,
+    warn: false,
+    scan: false,
+    check: false,
+    frontend: null,
+    help: false,
+  };
   for (let index = 0; index < rest.length; index += 1) {
     const argument = rest[index];
-    if (argument === "--dry-run") {
-      options.dryRun = true;
-    } else if (argument === "--no-sync") {
-      options.noSync = true;
-    } else if (argument === "--no-allow-scripts") {
-      options.allowScripts = false;
-    } else if (argument === "--warn") {
-      options.warn = true;
-    } else if (argument === "--scan") {
-      options.scan = true;
-    } else if (argument === "--help" || argument === "-h") {
+    // pnpm and yarn pass the `--` of `pnpm eds:doctor -- --scan` through to the CLI.
+    if (argument === "--") {
+      continue;
+    }
+    if (argument === "--help" || argument === "-h") {
       options.help = true;
-    } else if (argument === "--only") {
-      index += 1;
-      options.only = rest[index] ?? "";
-    } else if (argument.startsWith("--only=")) {
-      options.only = argument.slice("--only=".length);
-    } else if (argument === "--print-ci") {
+      continue;
+    }
+    const [name, inlineValue] = argument.startsWith("--") && argument.includes("=")
+      ? [argument.slice(0, argument.indexOf("=")), argument.slice(argument.indexOf("=") + 1)]
+      : [argument, null];
+    if (optionCommands[name] === undefined) {
+      throw usageError("Unknown option: " + argument + ".");
+    }
+    if (commands.includes(command) && !optionCommands[name].includes(command)) {
+      throw usageError(name + " is not an option of eds " + command + " (it applies to " + optionCommands[name].join(", ") + ").");
+    }
+    let value = inlineValue;
+    if (valueOptions.has(name) && value === null) {
       index += 1;
-      options.printCi = rest[index] ?? "";
-    } else if (argument.startsWith("--print-ci=")) {
-      options.printCi = argument.slice("--print-ci=".length);
-    } else {
-      throw new Error("Unknown option: " + argument);
+      value = rest[index] ?? "";
     }
+    // A value option given nothing, or followed by another option, would silently read that option as its value.
+    if (valueOptions.has(name) && (value === "" || value.startsWith("--"))) {
+      throw usageError(name + " needs a value.");
+    }
+    if (name === "--only") options.only = value;
+    else if (name === "--print-ci") options.printCi = value;
+    else if (name === "--frontend") options.frontend = value;
+    else if (name === "--dry-run") options.dryRun = true;
+    else if (name === "--no-sync") options.noSync = true;
+    else if (name === "--no-allow-scripts") options.allowScripts = false;
+    else if (name === "--warn") options.warn = true;
+    else if (name === "--scan") options.scan = true;
+    else if (name === "--check") options.check = true;
   }
   return { command, options };
 }
 
 async function main() {
   const consumerRoot = process.cwd();
-  let parsed;
-  try {
-    parsed = parseArguments(process.argv.slice(2));
-  } catch (error) {
-    console.error(error.message + "\n\n" + usage);
-    return 2;
-  }
-  const { command, options } = parsed;
+  const { command, options } = parseArguments(process.argv.slice(2));
 
   if (command === "--help" || command === "-h" || options.help) {
     console.log(usage);
     return 0;
   }
+  if (command === undefined) {
+    console.error("[EDS] Missing command (" + commands.join(", ") + ").\n\n" + usage);
+    return 2;
+  }
   if (command === "sync") {
     return runSync({ consumerRoot, only: options.only, dryRun: options.dryRun });
   }
@@ -94,9 +143,10 @@ async function main() {
       printCi: options.printCi,
     });
   }
-
-  console.error((command ? "Unknown command: " + command + "\n\n" : "") + usage);
-  return 2;
+  if (command === "align") {
+    return runAlign({ consumerRoot, check: options.check, frontend: options.frontend, dryRun: options.dryRun });
+  }
+  throw usageError("Unknown command: " + command + " (use " + commands.join(", ") + ").");
 }
 
 try {

package/consumer/css-root.mjs

@@ -28,6 +28,8 @@ const tailwindSpecifier = "tailwindcss(?:\\/(?:theme|utilities)(?:\\.css)?)?";
 const tailwindImportSource = "^[ \\t]*@import\\s+(?:url\\(\\s*)?[\"']" + tailwindSpecifier + "[\"']\\s*\\)?[^;]*;[^\\r\\n]*";
 const tailwindImportPattern = new RegExp(tailwindImportSource, "m");
 const tailwindImportPatternGlobal = new RegExp(tailwindImportSource, "gm");
+// Tailwind CSS v3 roots use @tailwind directives instead of @import "tailwindcss"; EDS wiring needs v4.
+const tailwindV3DirectivePattern = /^[ \t]*@tailwind\s+(?:base|components|utilities|variants|screens)\b/m;
 const cssImportPattern = /^[ \t]*@import\s+(?:url\()?["']([^"']+)["']/gm;
 const scriptImportPattern = /^[ \t]*import\s+["']([^"']+)["']/gm;
 const legacyGeneratedImportPattern = /^[ \t]*import\s+["'][^"']*eds-tokens\.css["'];?[ \t]*(?:\r?\n|$)/gm;
@@ -49,6 +51,19 @@ function hasTailwindImport(contents) {
   return tailwindImportPattern.test(stripCssComments(contents));
 }
 
+function hasTailwindV3Directive(contents) {
+  return tailwindV3DirectivePattern.test(stripCssComments(contents));
+}
+
+export const tailwindV3Advice = "EDS Tailwind wiring needs Tailwind CSS v4. Import @spectrabrain/eds/styles.css in the app entry and use " +
+  "var(--eds-*) or cssVar() for tokens; ask the user before upgrading to Tailwind CSS v4.";
+
+// The first CSS file that still uses Tailwind CSS v3 @tailwind directives, or null.
+export function findTailwindV3File(consumerRoot, sources) {
+  const file = sources.css.find((candidate) => hasTailwindV3Directive(candidate.contents) && !hasTailwindImport(candidate.contents));
+  return file ? relativeTo(consumerRoot, file.path) : null;
+}
+
 function readSources(consumerRoot) {
   const generatedPath = path.join(consumerRoot, generatedCssRelativePath);
   const css = listCssFiles(consumerRoot)
@@ -79,6 +94,12 @@ function resolveExplicitRoot(consumerRoot, relative, { source, label, remedy })
   }
   const contents = fs.readFileSync(rootPath, "utf8");
   const relativePath = relativeTo(consumerRoot, rootPath);
+  if (hasTailwindV3Directive(contents) && !hasTailwindImport(contents)) {
+    throw createExitError(
+      label + " points to " + relativePath + ", which uses Tailwind CSS v3 @tailwind directives. Remove that setting. " + tailwindV3Advice,
+      2,
+    );
+  }
   return {
     path: rootPath,
     relativePath,
@@ -126,10 +147,9 @@ export function findTailwindRoot(
     const found = candidates.map((file) => relativeTo(consumerRoot, file.path));
     throw createExitError(
       "Could not identify one Tailwind root CSS file (found " + found.length + ": " + found.join(", ") + "). " +
-        "Set " + tailwindRootEnvironmentVariable + ", for example " +
-        tailwindRootEnvironmentVariable + "=src/index.css " + runnerCommand(packageManager, "sync:eds") + ". " +
-        "sync records the choice in package.json as \"" + consumerConfigField + "\": { \"" + tailwindRootConfigKey +
-        "\": \"src/index.css\" } so doctor and the hooks reuse it.",
+        "Ask the user which of these is the app's Tailwind root, then run " + tailwindRootEnvironmentVariable + "=<that file> " +
+        runnerCommand(packageManager, "sync:eds") + " once. sync records the choice in package.json as \"" + consumerConfigField +
+        "\": { \"" + tailwindRootConfigKey + "\": \"<that file>\" } so doctor and the hooks reuse it.",
       2,
     );
   }