@spectrabrain/eds 0.0.3 → 0.1.0

package/consumer/css-root.mjs

@@ -0,0 +1,239 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  createExitError,
+  detectEol,
+  detectPackageManager,
+  generatedCssRelativePath,
+  listCssFiles,
+  listHtmlFiles,
+  listScriptFiles,
+  readPackageJson,
+  relativeImportPath,
+  relativeTo,
+  runnerCommand,
+  toPosix,
+} from "./paths.mjs";
+
+export const tailwindRootEnvironmentVariable = "EDS_TAILWIND_ROOT";
+// Consumer package.json: "eds": { "tailwindRoot": "src/index.css" }. Written by sync when the override is used.
+export const consumerConfigField = "eds";
+export const tailwindRootConfigKey = "tailwindRoot";
+export const stylesImportLine = '@import "@spectrabrain/eds/styles.css";';
+export const fontsImportLine = '@import "@spectrabrain/eds/fonts.css";';
+
+// Accepts the canonical `@import "tailwindcss";`, the granular `tailwindcss/theme.css` and
+// `tailwindcss/utilities.css` entries (Preflight opt-out) and the `@import url("tailwindcss")` form.
+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");
+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;
+const cssCommentPattern = /\/\*[\s\S]*?\*\//g;
+const pretendardPattern = /pretendard/i;
+const packageReferencePattern = /@spectrabrain\/eds\//;
+
+// Blanks `/* ... */` comments while keeping every index and line break, so a commented-out import is
+// neither a Tailwind root nor a satisfied EDS import, and match positions still apply to the original.
+export function stripCssComments(contents) {
+  return contents.replace(cssCommentPattern, (comment) => comment.replace(/[^\r\n]/g, " "));
+}
+
+function collectImports(contents, pattern) {
+  return [...contents.matchAll(pattern)].map((match) => match[1]);
+}
+
+function hasTailwindImport(contents) {
+  return tailwindImportPattern.test(stripCssComments(contents));
+}
+
+function readSources(consumerRoot) {
+  const generatedPath = path.join(consumerRoot, generatedCssRelativePath);
+  const css = listCssFiles(consumerRoot)
+    .filter((filePath) => filePath !== generatedPath)
+    .map((filePath) => ({ path: filePath, contents: fs.readFileSync(filePath, "utf8") }));
+  const scripts = listScriptFiles(consumerRoot)
+    .map((filePath) => ({ path: filePath, contents: fs.readFileSync(filePath, "utf8") }));
+  const html = listHtmlFiles(consumerRoot)
+    .map((filePath) => ({ path: filePath, contents: fs.readFileSync(filePath, "utf8") }));
+  return { generatedPath, css, scripts, html };
+}
+
+export function readConfiguredTailwindRoot(consumerRoot) {
+  const configured = readPackageJson(consumerRoot)?.[consumerConfigField]?.[tailwindRootConfigKey];
+  if (configured === undefined || configured === null) {
+    return null;
+  }
+  if (typeof configured !== "string" || configured.trim() === "") {
+    throw createExitError("package.json " + consumerConfigField + "." + tailwindRootConfigKey + " must be a relative path string, for example \"src/index.css\".", 2);
+  }
+  return configured;
+}
+
+function resolveExplicitRoot(consumerRoot, relative, { source, label, remedy }) {
+  const rootPath = path.resolve(consumerRoot, relative);
+  if (!fs.existsSync(rootPath) || !fs.statSync(rootPath).isFile()) {
+    throw createExitError(label + " does not point to an existing file: " + relative + ". " + remedy, 2);
+  }
+  const contents = fs.readFileSync(rootPath, "utf8");
+  const relativePath = relativeTo(consumerRoot, rootPath);
+  return {
+    path: rootPath,
+    relativePath,
+    contents,
+    source,
+    warning: hasTailwindImport(contents)
+      ? null
+      : relativePath + ' does not import "tailwindcss"; EDS imports will be inserted at the top of the file.',
+  };
+}
+
+// Resolution order: EDS_TAILWIND_ROOT, then package.json eds.tailwindRoot, then auto-detection.
+// Returns null when the consumer has no Tailwind root at all: sync then skips the Tailwind wiring.
+// Two or more candidates and an explicit path that does not exist still exit 2.
+export function findTailwindRoot(
+  consumerRoot,
+  env = process.env,
+  sources = readSources(consumerRoot),
+  packageManager = detectPackageManager(consumerRoot, env),
+) {
+  const override = env[tailwindRootEnvironmentVariable];
+  if (override) {
+    return resolveExplicitRoot(consumerRoot, override, {
+      source: "env",
+      label: tailwindRootEnvironmentVariable,
+      remedy: "Point it at the CSS file that imports tailwindcss.",
+    });
+  }
+
+  const configured = readConfiguredTailwindRoot(consumerRoot);
+  if (configured !== null) {
+    return resolveExplicitRoot(consumerRoot, toPosix(configured), {
+      source: "config",
+      label: "package.json " + consumerConfigField + "." + tailwindRootConfigKey,
+      remedy: "Update or remove that key, or run " + tailwindRootEnvironmentVariable + "=<file> " +
+        runnerCommand(packageManager, "sync:eds") + " once to record the new path.",
+    });
+  }
+
+  const candidates = sources.css.filter((file) => hasTailwindImport(file.contents));
+  if (candidates.length === 0) {
+    return null;
+  }
+  if (candidates.length > 1) {
+    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.",
+      2,
+    );
+  }
+
+  const [root] = candidates;
+  return { path: root.path, relativePath: relativeTo(consumerRoot, root.path), contents: root.contents, source: "detected", warning: null };
+}
+
+export function importsPackageFile(sources, fileName) {
+  const pattern = new RegExp("^@spectrabrain/eds/" + fileName.replace(".", "\\.") + "$");
+  const cssHit = sources.css.some((file) => collectImports(stripCssComments(file.contents), cssImportPattern).some((entry) => pattern.test(entry)));
+  const scriptHit = sources.scripts.some((file) => collectImports(file.contents, scriptImportPattern).some((entry) => pattern.test(entry)));
+  return cssHit || scriptHit;
+}
+
+// EDS text styles reference the font family "Pretendard" from fonts.css, so a consumer that opts out of
+// styles.css must import tokens.css, components.css and fonts.css. Returns the import lines still missing.
+export function planPackageImports(sources) {
+  const hasStyles = importsPackageFile(sources, "styles.css");
+  const hasTokensAndComponents = importsPackageFile(sources, "tokens.css") && importsPackageFile(sources, "components.css");
+  const hasFonts = importsPackageFile(sources, "fonts.css");
+  if (!hasStyles && !hasTokensAndComponents) {
+    return [stylesImportLine];
+  }
+  if (!hasStyles && !hasFonts) {
+    return [fontsImportLine];
+  }
+  return [];
+}
+
+// Files (other than the EDS imports themselves) that mention Pretendard: a CDN link, a second @font-face
+// or a font-family declaration. Reported by doctor as a note only.
+export function findPretendardReferences(consumerRoot, sources) {
+  return [...sources.html, ...sources.css]
+    .filter((file) => file.contents.split(/\r?\n/).some((line) => pretendardPattern.test(line) && !packageReferencePattern.test(line)))
+    .map((file) => relativeTo(consumerRoot, file.path));
+}
+
+function importsGeneratedFile(root, generatedPath) {
+  return collectImports(stripCssComments(root.contents), cssImportPattern).some((specifier) => {
+    if (!specifier.startsWith(".")) {
+      return false;
+    }
+    return path.resolve(path.dirname(root.path), specifier) === generatedPath;
+  });
+}
+
+// End index of the last Tailwind import line (comments ignored), or null. With granular imports the EDS
+// lines go after the last one so they follow both theme.css and utilities.css.
+function lastTailwindImportEnd(contents) {
+  let end = null;
+  for (const match of stripCssComments(contents).matchAll(tailwindImportPatternGlobal)) {
+    end = match.index + match[0].length;
+  }
+  return end;
+}
+
+export function planCssRootImports({ consumerRoot, root, sources }) {
+  const generatedPath = sources.generatedPath;
+  const generatedImportLine = '@import "' + relativeImportPath(root.path, generatedPath) + '";';
+  const missing = planPackageImports(sources);
+  if (!importsGeneratedFile(root, generatedPath)) {
+    missing.push(generatedImportLine);
+  }
+
+  const eol = detectEol(root.contents);
+  let after = root.contents;
+  if (missing.length > 0) {
+    const lineEnd = lastTailwindImportEnd(root.contents);
+    if (lineEnd !== null) {
+      const lineBreak = root.contents.slice(lineEnd, lineEnd + eol.length) === eol ? eol : "";
+      const inserted = missing.join(eol);
+      after = root.contents.slice(0, lineEnd) + eol + inserted + (lineBreak ? "" : eol) + root.contents.slice(lineEnd);
+    } else {
+      after = missing.join(eol) + eol + root.contents;
+    }
+  }
+
+  return {
+    label: "css-root",
+    path: root.path,
+    relativePath: relativeTo(consumerRoot, root.path),
+    before: root.contents,
+    after,
+    missing,
+  };
+}
+
+export function planLegacyJsImportCleanup({ consumerRoot }) {
+  const sourceDirectory = path.join(consumerRoot, "src");
+  return listScriptFiles(sourceDirectory).flatMap((filePath) => {
+    const before = fs.readFileSync(filePath, "utf8");
+    const after = before.replace(legacyGeneratedImportPattern, "");
+    if (after === before) {
+      return [];
+    }
+    return [{
+      label: "legacy-js-import",
+      path: filePath,
+      relativePath: relativeTo(consumerRoot, filePath),
+      before,
+      after,
+    }];
+  });
+}
+
+export { readSources };

package/consumer/doctor.mjs

@@ -0,0 +1,178 @@
+import { findPretendardReferences, planPackageImports, stylesImportLine, fontsImportLine } from "./css-root.mjs";
+import { readGeneratedVersion } from "./generate-tailwind.mjs";
+import { legacyVersionLabel } from "./managed-block.mjs";
+import { generatedCssRelativePath, normalizeEol, readJson, readPackageJson, runnerCommand, toPosix } from "./paths.mjs";
+import { doctorCommand, doctorScriptName, isCompatibleCommand, syncCommand, syncScriptName } from "./register-scripts.mjs";
+import { scanClassNames } from "./scan-classes.mjs";
+import { collectPlans, noTailwindNote } from "./sync.mjs";
+
+export const doctorEnvironmentVariable = "EDS_DOCTOR";
+
+const fontGuidance = {
+  [stylesImportLine]: "missing: @spectrabrain/eds/styles.css import in CSS or JS (or tokens.css + components.css + fonts.css); EDS text styles need the bundled Pretendard font",
+  [fontsImportLine]: "missing: @spectrabrain/eds/fonts.css import next to tokens.css and components.css; EDS text styles reference the font family \"Pretendard\" from fonts.css",
+};
+
+export function collectFindings({ consumerRoot, env = process.env }) {
+  const plans = collectPlans({ consumerRoot, env });
+  const installed = plans.pkg.version;
+  const generatedRelativePath = toPosix(generatedCssRelativePath);
+  const findings = [];
+  const notes = [];
+  let rawColors = null;
+
+  const scripts = readPackageJson(consumerRoot)?.scripts ?? {};
+  for (const [name, command] of [[syncScriptName, syncCommand], [doctorScriptName, doctorCommand]]) {
+    if (isCompatibleCommand(scripts[name], command)) {
+      continue;
+    }
+    findings.push(
+      scripts[name] === undefined
+        ? "scripts: " + name + " is not registered; run npx @spectrabrain/eds init"
+        : "scripts: " + name + " runs " + JSON.stringify(scripts[name]) + " instead of \"" + command +
+          "\"; rename that script and run npx @spectrabrain/eds init, or make it run \"" + command + "\"",
+    );
+  }
+  // The fix line may only point at sync:eds when that script really runs eds sync.
+  const syncRegistered = isCompatibleCommand(scripts[syncScriptName], syncCommand);
+
+  if (plans.root === null) {
+    notes.push(noTailwindNote);
+    // Without a Tailwind root, sync cannot insert the imports, so doctor states the requirement directly.
+    for (const line of planPackageImports(plans.sources)) {
+      findings.push(fontGuidance[line]);
+    }
+  } else {
+    if (plans.tailwind.before === null) {
+      findings.push("missing: " + generatedRelativePath);
+    } else if (normalizeEol(plans.tailwind.before) !== normalizeEol(plans.tailwind.after)) {
+      // Line endings are ignored: an autocrlf checkout of the LF generated file is not stale.
+      const generatedBy = readGeneratedVersion(plans.tailwind.before);
+      findings.push(
+        generatedBy === null
+          ? "stale: " + generatedRelativePath + " has no @spectrabrain/eds version header (installed " + installed + ")"
+          : generatedBy === installed
+            ? "stale: " + generatedRelativePath + " differs from the output of @spectrabrain/eds@" + installed
+            : "stale: " + generatedRelativePath + " was generated by @spectrabrain/eds@" + generatedBy + " (installed " + installed + ")",
+      );
+    }
+
+    for (const line of plans.cssRoot.missing) {
+      findings.push("missing: " + line + " in " + plans.cssRoot.relativePath);
+    }
+
+    for (const write of plans.legacyImports) {
+      findings.push("legacy: " + write.relativePath + " imports eds-tokens.css from JavaScript (Tailwind cannot compile it)");
+    }
+
+    // Tailwind drops a class no token backs without a word, so an unknown eds-* name is always a finding.
+    const classScan = scanClassNames({
+      consumerRoot,
+      manifest: readJson(plans.pkg.resolve("tokens.json")),
+      files: [...plans.sources.scripts, ...plans.sources.css, ...plans.sources.html],
+    });
+    for (const hit of classScan.unknown) {
+      findings.push("unknown: " + hit.location + " " + hit.className + " is not a public EDS class; check tokens.json or " + generatedRelativePath);
+    }
+    rawColors = classScan.raw;
+  }
+
+  for (const filePath of findPretendardReferences(consumerRoot, plans.sources)) {
+    notes.push(filePath + " references Pretendard outside @spectrabrain/eds; EDS text styles use the bundled font, so the extra font source can be removed.");
+  }
+
+  for (const error of plans.errors) {
+    findings.push("invalid: " + error.message);
+  }
+  if (plans.agents) {
+    if (plans.agents.existingBlock === null) {
+      findings.push("missing: AGENTS.md managed block");
+    } else if (normalizeEol(plans.agents.existingBlock) !== normalizeEol(plans.agents.block)) {
+      const blockVersion = plans.agents.existingVersion ?? legacyVersionLabel;
+      findings.push(
+        blockVersion === installed
+          ? "stale: AGENTS.md managed block differs from @spectrabrain/eds@" + installed
+          : "stale: AGENTS.md managed block is for " + blockVersion + " (installed " + installed + ")",
+      );
+    }
+  }
+
+  if (plans.claude && normalizeEol(plans.claude.before) !== normalizeEol(plans.claude.after)) {
+    findings.push("missing: @AGENTS.md import in CLAUDE.md");
+  }
+  if (plans.gemini && normalizeEol(plans.gemini.before) !== normalizeEol(plans.gemini.after)) {
+    findings.push("missing: @./AGENTS.md import in GEMINI.md");
+  }
+
+  return { plans, findings, notes, installed, generatedRelativePath, syncRegistered, rawColors };
+}
+
+const rawColorLineLimit = 40;
+
+// --scan lists the classes that bypass the EDS tokens. It never changes the exit code: legacy code may keep them.
+function logRawColors(rawColors, log) {
+  if (rawColors === null) {
+    log("[EDS] scan: skipped (no Tailwind root)");
+    return;
+  }
+  if (rawColors.length === 0) {
+    log("[EDS] scan: no raw color classes found");
+    return;
+  }
+  const files = new Set(rawColors.map((hit) => hit.location.split(":")[0]));
+  log(
+    "[EDS] scan: " + rawColors.length + " raw color class" + (rawColors.length === 1 ? "" : "es") + " in " + files.size +
+      " file" + (files.size === 1 ? "" : "s") + " bypass the EDS tokens (informational; prefer text-eds-fg-*, bg-eds-bg-*, border-eds-stroke-*)",
+  );
+  for (const hit of rawColors.slice(0, rawColorLineLimit)) {
+    log("[EDS] raw: " + hit.location + " " + hit.className);
+  }
+  if (rawColors.length > rawColorLineLimit) {
+    log("[EDS] raw: … " + (rawColors.length - rawColorLineLimit) + " more");
+  }
+}
+
+export function runDoctor({ consumerRoot, env = process.env, warn = false, scan = false, log = console.log }) {
+  const mode = env[doctorEnvironmentVariable];
+  if (mode === "off") {
+    return 0;
+  }
+  const downgrade = warn || mode === "warn";
+
+  let result;
+  try {
+    result = collectFindings({ consumerRoot, env });
+  } catch (error) {
+    log("[EDS] " + error.message);
+    if (error.exitCode === 2) {
+      return downgrade ? 0 : 2;
+    }
+    throw error;
+  }
+
+  for (const note of result.notes) {
+    log("[EDS] note: " + note);
+  }
+  if (scan) {
+    logRawColors(result.rawColors, log);
+  }
+
+  if (result.findings.length === 0) {
+    const syncedPaths = result.plans.root === null
+      ? ["AGENTS.md"]
+      : [result.plans.root.relativePath, result.generatedRelativePath, "AGENTS.md"];
+    log("[EDS] synced with @spectrabrain/eds@" + result.installed + ": " + syncedPaths.join(", "));
+    return 0;
+  }
+
+  for (const finding of result.findings) {
+    log("[EDS] " + finding);
+  }
+  const fixCommand = result.syncRegistered ? runnerCommand(result.plans.packageManager, syncScriptName) : "npx eds sync";
+  log(
+    "[EDS] Run " + fixCommand + " to fix. (" +
+      doctorEnvironmentVariable + "=warn or eds doctor --warn downgrades this to a warning.)",
+  );
+  log("[EDS] Then read the AGENTS.md managed block and QUICKSTART.md in the package root before UI work.");
+  return downgrade ? 0 : 1;
+}

package/consumer/generate-tailwind.mjs

@@ -0,0 +1,83 @@
+import path from "node:path";
+import { generatedCssRelativePath, readJson, readTextIfExists, relativeTo } from "./paths.mjs";
+
+const propertyNames = [
+  "fontFamily",
+  "fontWeight",
+  "fontSize",
+  "lineHeight",
+  "letterSpacing",
+];
+
+export const fontSansStyleName = "body1";
+export function renderTailwindCss(manifest, version) {
+  const tokens = Object.keys(manifest.tokens ?? {});
+  const colorNames = tokens.filter((name) => name.startsWith("color-"));
+  const typography = new Map();
+
+  for (const name of tokens.filter((entry) => entry.startsWith("typography-"))) {
+    const match = name.match(/^typography-(.+)-(fontFamily|fontWeight|fontSize|lineHeight|letterSpacing)$/);
+    if (!match) {
+      throw new Error(`Unsupported typography token name: ${name}`);
+    }
+
+    const [, styleName, propertyName] = match;
+    const properties = typography.get(styleName) ?? new Set();
+    properties.add(propertyName);
+    typography.set(styleName, properties);
+  }
+
+  for (const [styleName, properties] of typography) {
+    for (const propertyName of propertyNames) {
+      if (!properties.has(propertyName)) {
+        throw new Error(`Typography preset ${styleName} is missing ${propertyName}.`);
+      }
+    }
+  }
+
+  if (!typography.has(fontSansStyleName)) {
+    throw new Error(`Typography preset ${fontSansStyleName} is required for --font-sans.`);
+  }
+
+  const colorAliases = colorNames
+    .map((name) => `  --color-eds-${name.slice("color-".length)}: var(--eds-${name});`)
+    .join("\n");
+  // Last line of the @theme block: Tailwind's default font family becomes the EDS body font.
+  const fontSans = `  --font-sans: var(--eds-typography-${fontSansStyleName}-fontFamily);`;
+  const typographyUtilities = [...typography.keys()].sort().map((styleName) => [
+    `@utility eds-typography-${styleName} {`,
+    `  font-family: var(--eds-typography-${styleName}-fontFamily);`,
+    `  font-weight: var(--eds-typography-${styleName}-fontWeight);`,
+    `  font-size: var(--eds-typography-${styleName}-fontSize);`,
+    `  line-height: var(--eds-typography-${styleName}-lineHeight);`,
+    `  letter-spacing: var(--eds-typography-${styleName}-letterSpacing);`,
+    `}`,
+  ].join("\n")).join("\n\n");
+
+  return [
+    `/* Generated from @spectrabrain/eds@${version}. Do not edit manually. */`,
+    "@theme inline {",
+    colorAliases,
+    fontSans,
+    "}",
+    "",
+    typographyUtilities,
+    "",
+  ].join("\n");
+}
+
+export function readGeneratedVersion(contents) {
+  return contents.match(/^\/\* Generated from @spectrabrain\/eds@(\S+)\. Do not edit manually\. \*\//m)?.[1] ?? null;
+}
+
+export function planTailwind({ consumerRoot, pkg }) {
+  const manifest = readJson(pkg.resolve("tokens.json"));
+  const filePath = path.join(consumerRoot, generatedCssRelativePath);
+  return {
+    label: "tailwind",
+    path: filePath,
+    relativePath: relativeTo(consumerRoot, filePath),
+    before: readTextIfExists(filePath),
+    after: renderTailwindCss(manifest, pkg.version),
+  };
+}

package/consumer/init.mjs

@@ -0,0 +1,172 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createExitError, detectPackageManager, packageName, 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;
+
+const installCommands = {
+  npm: "npm ci",
+  pnpm: "pnpm install --frozen-lockfile",
+  yarn: "yarn install --frozen-lockfile",
+  bun: "bun install --frozen-lockfile",
+};
+
+function installCommand(packageManager) {
+  if (packageManager.name === "yarn" && packageManager.berry) {
+    return "yarn install --immutable";
+  }
+  return installCommands[packageManager.name];
+}
+
+// A CI job that fails when sync is out of date. It runs `npx eds doctor` so the consumer's own
+// package.json scripts are not required.
+export function renderCiSnippet(target, packageManager) {
+  const install = installCommand(packageManager);
+  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: npx eds 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,
+      "    - npx eds 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; approve the postinstall manually with npm install-scripts approve --no-allow-scripts-pin " + packageName + ".");
+    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 you run npm install-scripts approve " + packageName + ".");
+      }
+    } else if (major === null) {
+      log("[EDS] npm " + minimumAllowScriptsNpmMajor + "+ blocks dependency install scripts by default; run npm install-scripts approve --no-allow-scripts-pin " + packageName + " there, or rerun init with npm so it can write " + allowScriptsField + ".");
+    }
+    return;
+  }
+  if (name === "pnpm") {
+    log("[EDS] pnpm blocks dependency build scripts by default. Run pnpm approve-builds and select " + packageName + ", or add to package.json:");
+    log("  \"pnpm\": { \"onlyBuiltDependencies\": [\"" + packageName + "\"] }");
+    log("[EDS] Without it, rerun " + runnerCommand(packageManager, syncScriptName) + " (or npx eds init) after each install.");
+    return;
+  }
+  if (name === "bun") {
+    log("[EDS] bun runs dependency lifecycle scripts only for trustedDependencies. Add to package.json:");
+    log("  \"trustedDependencies\": [\"" + packageName + "\"]");
+    log("[EDS] Note: setting trustedDependencies replaces bun's default trusted list; include any other package whose install scripts you rely on.");
+    return;
+  }
+  if (name === "yarn" && berry) {
+    log("[EDS] Yarn 2+ skips dependency install scripts when enableScripts is false. To run the EDS postinstall, keep enableScripts: true in .yarnrc.yml, or add to package.json:");
+    log("  \"dependenciesMeta\": { \"" + packageName + "\": { \"built\": true } }");
+    log("[EDS] Otherwise rerun " + runnerCommand(packageManager, syncScriptName) + " (or npx eds init) after each install.");
+  }
+}
+
+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 npx " + packageName + " init from the consumer root.",
+      1,
+    );
+  }
+  try {
+    resolvePackage(consumerRoot);
+  } catch {
+    throw createExitError(packageName + " is not installed here; run npm install " + packageName + " first.", 1);
+  }
+
+  registerConsumerScripts(consumerRoot, { log, dryRun, packageManager });
+  printInstallScriptGuidance(consumerRoot, packageManager, { log, dryRun, allowScripts });
+  if (noSync) {
+    log("[EDS] Scripts registered. Run " + runnerCommand(packageManager, syncScriptName) + " to finish setup.");
+    return 0;
+  }
+  return runSync({ consumerRoot, env, dryRun, log });
+}