@spectrabrain/eds 0.0.3 → 0.1.0

package/consumer/managed-block.mjs

@@ -0,0 +1,120 @@
+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;
+}
+
+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) {
+    const first = begins[0] ?? ends[0];
+    throw new Error(
+      "AGENTS.md must contain zero or one complete EDS managed block. Found " + begins.length + " " + beginMarker +
+        " and " + ends.length + " " + endMarker + " marker" + (begins.length + ends.length === 1 ? "" : "s") +
+        " outside fenced code blocks" + (first === undefined ? "" : ", first at line " + lineNumberAt(existing, first)) + ".",
+    );
+  }
+  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) + ".",
+    );
+  }
+  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,211 @@
+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 (run npm install).", 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);
+}
+
+export function detectPackageManager(consumerRoot, env = process.env) {
+  const fromAgent = parseUserAgent(env.npm_config_user_agent);
+  let name = fromAgent?.name ?? null;
+  let source = fromAgent ? "user-agent" : "lockfile";
+  if (name === null) {
+    name = lockfileManagers.find(([fileName]) => fs.existsSync(path.join(consumerRoot, fileName)))?.[1] ?? null;
+  }
+  if (name === null) {
+    name = "npm";
+    source = "default";
+  }
+  const major = fromAgent?.major ?? null;
+  return {
+    name,
+    version: fromAgent?.version ?? null,
+    major,
+    berry: name === "yarn" && isYarnBerry(consumerRoot, major),
+    runner: runnerPrefixes[name],
+    source,
+  };
+}
+
+export function runnerCommand(packageManager, scriptName) {
+  return (packageManager?.runner ?? runnerPrefixes.npm) + scriptName;
+}
+
+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);
+}

package/consumer/register-scripts.mjs

@@ -0,0 +1,124 @@
+import fs from "node:fs";
+import path from "node:path";
+import { detectIndent, detectPackageManager, runnerCommand } from "./paths.mjs";
+
+export const syncCommand = "eds sync";
+export const doctorCommand = "eds doctor";
+export const syncScriptName = "sync:eds";
+export const doctorScriptName = "eds:doctor";
+
+const legacyRunnerCommand = "node --input-type=module -e \"import('@spectrabrain/eds/consumer-sync.mjs')\"";
+const requiredScripts = {
+  [syncScriptName]: syncCommand,
+  [doctorScriptName]: doctorCommand,
+};
+const legacyScripts = {
+  [syncScriptName]: [
+    "npm run update:eds-agent-context && npm run generate:eds-tailwind",
+    "npm run update:eds-agent-context && npm run generate-eds-tailwind",
+  ],
+  "update:eds-agent-context": [legacyRunnerCommand],
+  "generate:eds-tailwind": [legacyRunnerCommand],
+};
+const hookScripts = [
+  { name: "pretypecheck", target: "typecheck" },
+  { name: "prebuild", target: "build" },
+];
+
+export function writeConsumerPackageJson(packagePath, source, consumerPackage) {
+  const trailingNewline = source.endsWith("\n") ? "\n" : "";
+  fs.writeFileSync(packagePath, JSON.stringify(consumerPackage, null, detectIndent(source)) + trailingNewline);
+}
+
+// A consumer may wrap the EDS command (for example `cross-env EDS_DOCTOR=warn eds doctor`). Any script that
+// still runs the EDS command counts as registered; only scripts that do not run it are reported.
+export function isCompatibleCommand(value, command) {
+  if (typeof value !== "string") {
+    return false;
+  }
+  const escaped = command.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp("(^|[\\s&|;(])" + escaped + "($|[\\s&|;)])").test(value);
+}
+
+export function registerConsumerScripts(
+  consumerRoot,
+  { log = console.log, dryRun = false, packageManager = detectPackageManager(consumerRoot) } = {},
+) {
+  const packagePath = path.join(consumerRoot, "package.json");
+  const source = fs.readFileSync(packagePath, "utf8");
+  const consumerPackage = JSON.parse(source);
+  const scripts = { ...(consumerPackage.scripts ?? {}) };
+  const result = { changed: false, added: [], migrated: [], removed: [], skippedHooks: [], conflicts: [] };
+
+  for (const [name, command] of Object.entries(requiredScripts)) {
+    if (isCompatibleCommand(scripts[name], command)) {
+      continue;
+    }
+    if (scripts[name] === undefined) {
+      scripts[name] = command;
+      result.added.push(name);
+      continue;
+    }
+    if (legacyScripts[name]?.includes(scripts[name])) {
+      scripts[name] = command;
+      result.migrated.push(name);
+      continue;
+    }
+    // Never fail the install over a consumer-owned script: leave it alone and let doctor report it.
+    result.conflicts.push(name);
+    log(
+      `[EVA Design System] Consumer script ${name} already exists with a different command (${JSON.stringify(scripts[name])}); ` +
+        `left unchanged. eds doctor reports it until the script runs "${command}".`,
+    );
+  }
+
+  for (const [name, commands] of Object.entries(legacyScripts)) {
+    if (requiredScripts[name] === undefined && commands.includes(scripts[name])) {
+      delete scripts[name];
+      result.removed.push(name);
+    }
+  }
+
+  const hookTargets = [];
+  for (const hook of hookScripts) {
+    if (scripts[hook.target] === undefined) {
+      continue;
+    }
+    hookTargets.push(hook.target);
+    if (isCompatibleCommand(scripts[hook.name], doctorCommand)) {
+      continue;
+    }
+    if (scripts[hook.name] === undefined) {
+      scripts[hook.name] = doctorCommand;
+      result.added.push(hook.name);
+      continue;
+    }
+    result.skippedHooks.push(hook.name);
+    log(`[EVA Design System] ${hook.name} is already defined; add "${doctorCommand}" to it manually.`);
+  }
+
+  result.changed = result.added.length > 0 || result.migrated.length > 0 || result.removed.length > 0;
+  // When sync:eds belongs to the consumer, point at the CLI instead of their script.
+  const syncRunCommand = result.conflicts.includes(syncScriptName) ? "npx eds sync" : runnerCommand(packageManager, syncScriptName);
+  if (result.changed && dryRun) {
+    log("[EVA Design System] would update package.json scripts: " + [...result.added, ...result.migrated, ...result.removed].join(", "));
+  } else if (result.changed) {
+    consumerPackage.scripts = scripts;
+    writeConsumerPackageJson(packagePath, source, consumerPackage);
+    log("[EVA Design System] Added consumer setup scripts. Run " + syncRunCommand + ".");
+  } else if (result.conflicts.length === 0) {
+    log("[EVA Design System] Consumer setup scripts are already registered. Run " + syncRunCommand + ".");
+  } else {
+    log("[EVA Design System] Consumer setup scripts were left unchanged. Run " + syncRunCommand + ".");
+  }
+
+  // Yarn berry (2+) does not run pre/post lifecycle hooks, so the doctor gate must be inlined by the consumer.
+  if (packageManager?.name === "yarn" && packageManager.berry && hookTargets.length > 0) {
+    log(
+      "[EVA Design System] Yarn 2+ does not run pretypecheck/prebuild hooks. Prepend \"" + doctorCommand +
+        " && \" to your " + hookTargets.join(" and ") + " script" + (hookTargets.length > 1 ? "s" : "") +
+        " to keep the doctor gate (this tool does not edit them).",
+    );
+  }
+  return result;
+}

package/consumer/scan-classes.mjs

@@ -0,0 +1,70 @@
+import { relativeTo } from "./paths.mjs";
+
+// Tailwind utilities that take a color. A class such as hover:bg-eds-bg-brand-primary/80 is one token here.
+const colorUtility = "(?:text|bg|border|ring|outline|fill|stroke|decoration|divide|from|to|via|accent|caret|shadow|placeholder|inset-ring)";
+const variantPrefix = "(?:[a-z0-9-]+:)*";
+const boundaryBefore = "(?<![\\w-])";
+const boundaryAfter = "(?![\\w-])";
+const opacity = "(?:/[0-9]{1,3})?";
+
+const edsColorClass = new RegExp(boundaryBefore + variantPrefix + colorUtility + "-eds-([a-z0-9-]+)" + opacity + boundaryAfter, "g");
+const edsTypographyClass = new RegExp(boundaryBefore + variantPrefix + "eds-typography-([a-z0-9-]+)" + boundaryAfter, "g");
+const rawColorClass = new RegExp(
+  boundaryBefore + variantPrefix + colorUtility +
+    "-(?:(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-[0-9]{2,3}|white|black|\\[(?:#|rgba?\\(|hsla?\\(|oklch\\(|oklab\\(|color\\()[^\\]]*\\])" +
+    opacity + boundaryAfter,
+  "g",
+);
+
+// The public class names are derived exactly like eds sync derives the Tailwind aliases from tokens.json.
+export function publicClassNames(manifest) {
+  const colors = new Set();
+  const typography = new Set();
+  for (const name of Object.keys(manifest.tokens ?? {})) {
+    if (name.startsWith("color-")) {
+      colors.add("eds-" + name.slice("color-".length));
+      continue;
+    }
+    const match = name.match(/^typography-(.+)-(?:fontFamily|fontWeight|fontSize|lineHeight|letterSpacing)$/);
+    if (match) {
+      typography.add(match[1]);
+    }
+  }
+  return { colors, typography };
+}
+
+// files: [{ path, contents }] as readSources() lists them (the generated eds-tokens.css is not among them).
+// unknown: eds-* classes that no public token backs (always a mistake, Tailwind silently drops them).
+// raw: Tailwind palette, white/black and arbitrary color classes that bypass the EDS tokens (informational).
+export function scanClassNames({ consumerRoot, manifest, files }) {
+  const { colors, typography } = publicClassNames(manifest);
+  const unknown = [];
+  const raw = [];
+  for (const file of files) {
+    const relativePath = relativeTo(consumerRoot, file.path);
+    file.contents.split(/\r?\n/).forEach((line, index) => {
+      const location = relativePath + ":" + (index + 1);
+      for (const match of line.matchAll(edsColorClass)) {
+        // "bg-eds-bg-" + name is composed at runtime; the scan cannot judge it.
+        if (match[1].endsWith("-")) {
+          continue;
+        }
+        if (!colors.has("eds-" + match[1])) {
+          unknown.push({ location, className: match[0] });
+        }
+      }
+      for (const match of line.matchAll(edsTypographyClass)) {
+        if (match[1].endsWith("-")) {
+          continue;
+        }
+        if (!typography.has(match[1])) {
+          unknown.push({ location, className: match[0] });
+        }
+      }
+      for (const match of line.matchAll(rawColorClass)) {
+        raw.push({ location, className: match[0] });
+      }
+    });
+  }
+  return { unknown, raw };
+}

package/consumer/sync.mjs

@@ -0,0 +1,133 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  consumerConfigField,
+  findTailwindRoot,
+  planCssRootImports,
+  planLegacyJsImportCleanup,
+  readSources,
+  tailwindRootConfigKey,
+  tailwindRootEnvironmentVariable,
+} from "./css-root.mjs";
+import { planTailwind } from "./generate-tailwind.mjs";
+import { createExitError, detectPackageManager, generatedCssRelativePath, normalizeEol, resolvePackage, toPosix } from "./paths.mjs";
+import { writeConsumerPackageJson } from "./register-scripts.mjs";
+import { planAgentContext, planClaudeImport, planGeminiImport } from "./update-agent-context.mjs";
+
+export const syncTargets = new Set(["tailwind", "agents"]);
+export const noTailwindNote =
+  "No Tailwind root CSS found (no @import \"tailwindcss\"); skipped " + toPosix(generatedCssRelativePath) +
+  " and the CSS imports. Set " + tailwindRootEnvironmentVariable + "=<file> once to wire Tailwind; sync records it in package.json " +
+  consumerConfigField + "." + tailwindRootConfigKey + ".";
+
+export function collectPlans({ consumerRoot, env = process.env }) {
+  const pkg = resolvePackage(consumerRoot);
+  const packageManager = detectPackageManager(consumerRoot, env);
+  const sources = readSources(consumerRoot);
+  const root = findTailwindRoot(consumerRoot, env, sources, packageManager);
+  // No Tailwind root: the Tailwind wiring is skipped entirely (no generated CSS, no root edits).
+  const tailwind = root === null ? null : planTailwind({ consumerRoot, pkg });
+  const cssRoot = root === null ? null : planCssRootImports({ consumerRoot, root, sources });
+  const legacyImports = root === null ? [] : planLegacyJsImportCleanup({ consumerRoot });
+  const errors = [];
+  let agents = null;
+  try {
+    agents = planAgentContext({ consumerRoot, pkg, packageManager });
+  } catch (error) {
+    errors.push(error);
+  }
+  const claude = planClaudeImport({ consumerRoot });
+  const gemini = planGeminiImport({ consumerRoot });
+  return { consumerRoot, pkg, packageManager, sources, root, tailwind, cssRoot, legacyImports, agents, claude, gemini, errors };
+}
+
+export function planSync({ consumerRoot, env = process.env, only = null }) {
+  if (only !== null && !syncTargets.has(only)) {
+    throw createExitError("Unknown --only target: " + only + " (use tailwind or agents).", 2);
+  }
+  const plans = collectPlans({ consumerRoot, env });
+  if (plans.errors.length > 0) {
+    throw plans.errors[0];
+  }
+
+  const writes = [];
+  if ((only === null || only === "tailwind") && plans.root !== null) {
+    writes.push(plans.tailwind, plans.cssRoot, ...plans.legacyImports);
+  }
+  if (only === null || only === "agents") {
+    writes.push(plans.agents);
+    if (plans.claude) {
+      writes.push(plans.claude);
+    }
+    if (plans.gemini) {
+      writes.push(plans.gemini);
+    }
+  }
+  // Like doctor, an EOL-only difference (an autocrlf checkout of the LF generated CSS) is already synced.
+  return { ...plans, only, writes: writes.filter((write) => normalizeEol(write.before) !== normalizeEol(write.after)) };
+}
+
+// EDS_TAILWIND_ROOT is a one-time choice: sync records it as package.json "eds": { "tailwindRoot" } so
+// doctor and the pretypecheck/prebuild hooks resolve the same root without the environment variable.
+function persistTailwindRoot(plan, { dryRun, log }) {
+  if (plan.root?.source !== "env" || plan.only === "agents") {
+    return false;
+  }
+  const packagePath = path.join(plan.consumerRoot, "package.json");
+  const source = fs.readFileSync(packagePath, "utf8");
+  const consumerPackage = JSON.parse(source);
+  const existing = consumerPackage[consumerConfigField];
+  if (existing !== undefined && (typeof existing !== "object" || existing === null || Array.isArray(existing))) {
+    log("[EDS] package.json " + consumerConfigField + " is not an object; " + tailwindRootEnvironmentVariable + " was not recorded there.");
+    return false;
+  }
+  const value = plan.root.relativePath;
+  const label = consumerConfigField + "." + tailwindRootConfigKey + " = " + JSON.stringify(value);
+  if (existing?.[tailwindRootConfigKey] === value) {
+    return false;
+  }
+  if (dryRun) {
+    log("[EDS] would write " + label + " to package.json");
+    return false;
+  }
+  consumerPackage[consumerConfigField] = { ...(existing ?? {}), [tailwindRootConfigKey]: value };
+  writeConsumerPackageJson(packagePath, source, consumerPackage);
+  log("[EDS] wrote " + label + " to package.json; doctor, sync and the hooks now use this Tailwind root without " + tailwindRootEnvironmentVariable + ".");
+  return true;
+}
+
+export function applySync(plan, { dryRun = false, log = console.log } = {}) {
+  const version = "@spectrabrain/eds@" + plan.pkg.version;
+  if (plan.root === null && plan.only !== "agents") {
+    log("[EDS] " + noTailwindNote);
+  } else if (plan.root?.warning) {
+    log("[EDS] " + plan.root.warning);
+  }
+  persistTailwindRoot(plan, { dryRun, log });
+  if (plan.writes.length === 0) {
+    log("[EDS] Already synced with " + version + ".");
+    return [];
+  }
+  for (const write of plan.writes) {
+    if (dryRun) {
+      log("[EDS] would write " + write.relativePath);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(write.path), { recursive: true });
+    fs.writeFileSync(write.path, write.after);
+    log("[EDS] wrote " + write.relativePath);
+  }
+  if (!dryRun) {
+    log(
+      "[EDS] Synced with " + version + ". Review the diff (AGENTS.md, CSS imports, " + toPosix(generatedCssRelativePath) +
+        ") before committing; the AGENTS.md block lists the rules.",
+    );
+  }
+  return plan.writes.map((write) => write.relativePath);
+}
+
+export function runSync({ consumerRoot, env = process.env, only = null, dryRun = false, log = console.log }) {
+  const plan = planSync({ consumerRoot, env, only });
+  applySync(plan, { dryRun, log });
+  return 0;
+}