@spectrabrain/eds 0.4.0 → 0.6.0

package/consumer/register-scripts.mjs

@@ -20,10 +20,9 @@ const legacyScripts = {
   "update:eds-agent-context": [legacyRunnerCommand],
   "generate:eds-tailwind": [legacyRunnerCommand],
 };
-const hookScripts = [
-  { name: "pretypecheck", target: "typecheck" },
-  { name: "prebuild", target: "build" },
-];
+const obsoleteDoctorHooks = new Set(["pretypecheck", "prebuild"]);
+const doctorPrefix = doctorCommand + " && ";
+const doctorLifecycleScripts = ["pretypecheck", "prebuild", "typecheck", "build"];
 
 export function writeConsumerPackageJson(packagePath, source, consumerPackage) {
   const trailingNewline = source.endsWith("\n") ? "\n" : "";
@@ -40,15 +39,22 @@ export function isCompatibleCommand(value, command) {
   return new RegExp("(^|[\\s&|;(])" + escaped + "($|[\\s&|;)])").test(value);
 }
 
+export function canUseConsumerScript(scripts, name, command, { willRegister = false } = {}) {
+  if (isCompatibleCommand(scripts[name], command)) {
+    return true;
+  }
+  return willRegister && (scripts[name] === undefined || legacyScripts[name]?.includes(scripts[name]) === true);
+}
+
 export function registerConsumerScripts(
   consumerRoot,
-  { log = console.log, dryRun = false, packageManager = detectPackageManager(consumerRoot) } = {},
+  { log = console.log, dryRun = false, logNoop = true, 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: [], syncRunCommand: null };
+  const result = { changed: false, added: [], migrated: [], removed: [], cleanedDoctorScripts: [], conflicts: [], syncRunCommand: null };
 
   for (const [name, command] of Object.entries(requiredScripts)) {
     if (isCompatibleCommand(scripts[name], command)) {
@@ -79,51 +85,47 @@ export function registerConsumerScripts(
     }
   }
 
-  const hookTargets = [];
-  for (const hook of hookScripts) {
-    if (scripts[hook.target] === undefined) {
-      continue;
-    }
-    hookTargets.push(hook.target);
-    if (isCompatibleCommand(scripts[hook.name], doctorCommand)) {
+  // Previous EDS versions ran Doctor as an npm lifecycle hook, or told Yarn Berry users to prefix these
+  // commands. Remove that automatic check while preserving any command that followed the Doctor prefix.
+  for (const name of doctorLifecycleScripts) {
+    if (obsoleteDoctorHooks.has(name) && scripts[name] === doctorCommand) {
+      delete scripts[name];
+      result.cleanedDoctorScripts.push(name);
       continue;
     }
-    if (scripts[hook.name] === undefined) {
-      scripts[hook.name] = doctorCommand;
-      result.added.push(hook.name);
-      continue;
+    if (typeof scripts[name] === "string" && scripts[name].startsWith(doctorPrefix)) {
+      const remainingCommand = scripts[name].slice(doctorPrefix.length).trimStart();
+      if (remainingCommand.length > 0) {
+        scripts[name] = remainingCommand;
+        result.cleanedDoctorScripts.push(name);
+      }
     }
-    result.skippedHooks.push(hook.name);
-    log(
-      `[EDS] ${hook.name} already runs ${JSON.stringify(scripts[hook.name])}; left unchanged. Change it to ` +
-        `${JSON.stringify(doctorCommand + " && " + scripts[hook.name])} so ${doctorCommand} gates ${hook.target}.`,
-    );
   }
 
-  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. The caller prints the next
-  // step: init runs sync right away, postinstall tells the consumer to run it.
+  result.changed = result.added.length > 0 || result.migrated.length > 0 || result.removed.length > 0 || result.cleanedDoctorScripts.length > 0;
+  // When sync:eds belongs to the consumer, point at the CLI instead of their script. The caller uses this when it
+  // cannot safely ensure that the package script has been registered.
   result.syncRunCommand = result.conflicts.includes(syncScriptName) ? cliCommand(packageManager, "sync") : runnerCommand(packageManager, syncScriptName);
+  const changedScripts = [
+    ...result.added,
+    ...result.migrated,
+    ...result.removed.map((name) => "removed " + name),
+    ...result.cleanedDoctorScripts.map((name) => "removed Doctor from " + name),
+  ];
   if (result.changed && dryRun) {
-    log("[EDS] would update package.json scripts: " + [...result.added, ...result.migrated, ...result.removed].join(", "));
+    log("[EDS] would update package.json scripts: " + changedScripts.join(", "));
   } else if (result.changed) {
     consumerPackage.scripts = scripts;
     writeConsumerPackageJson(packagePath, source, consumerPackage);
-    log("[EDS] Added the EDS scripts to package.json: " + [...result.added, ...result.migrated].join(", ") +
-      (result.removed.length > 0 ? " (removed " + result.removed.join(", ") + ")" : "") + ".");
-  } else if (result.conflicts.length === 0) {
+    log("[EDS] Updated package.json scripts: " + changedScripts.join(", ") + ".");
+    if (result.cleanedDoctorScripts.length > 0) {
+      log("[EDS] Doctor runs before committing; it is no longer attached to typecheck or build.");
+    }
+  } else if (result.conflicts.length === 0 && logNoop) {
     log("[EDS] The EDS scripts are already registered.");
   } else {
     log("[EDS] The EDS scripts were left unchanged.");
   }
 
-  // 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(
-      "[EDS] 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/sync.mjs

@@ -13,7 +13,7 @@ import {
 } from "./css-root.mjs";
 import { planTailwind } from "./generate-tailwind.mjs";
 import { cliCommand, createExitError, detectPackageManager, generatedCssRelativePath, normalizeEol, readPackageJson, resolvePackage, runnerCommand, toPosix } from "./paths.mjs";
-import { doctorCommand, doctorScriptName, isCompatibleCommand, writeConsumerPackageJson } from "./register-scripts.mjs";
+import { canUseConsumerScript, doctorCommand, doctorScriptName, isCompatibleCommand, registerConsumerScripts, syncCommand, syncScriptName, writeConsumerPackageJson } from "./register-scripts.mjs";
 import { planAgentContext, planClaudeImport, planDeliveryNotes, planGeminiImport } from "./update-agent-context.mjs";
 
 export const syncTargets = new Set(["tailwind", "agents"]);
@@ -31,9 +31,18 @@ export function describeMissingTailwindRoot(plans) {
     : "Tailwind CSS v3 detected (@tailwind directives in " + plans.tailwindV3File + "); " + skippedWiring + " " + tailwindV3Advice;
 }
 
-export function collectPlans({ consumerRoot, env = process.env }) {
+export function collectPlans({ consumerRoot, env = process.env, ensureScripts = false }) {
   const pkg = resolvePackage(consumerRoot);
   const packageManager = detectPackageManager(consumerRoot, env);
+  const scripts = readPackageJson(consumerRoot)?.scripts ?? {};
+  const commands = {
+    sync: canUseConsumerScript(scripts, syncScriptName, syncCommand, { willRegister: ensureScripts })
+      ? runnerCommand(packageManager, syncScriptName)
+      : cliCommand(packageManager, "sync"),
+    doctor: canUseConsumerScript(scripts, doctorScriptName, doctorCommand, { willRegister: ensureScripts })
+      ? runnerCommand(packageManager, doctorScriptName)
+      : cliCommand(packageManager, "doctor"),
+  };
   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).
@@ -44,7 +53,7 @@ export function collectPlans({ consumerRoot, env = process.env }) {
   const errors = [];
   let agents = null;
   try {
-    agents = planAgentContext({ consumerRoot, pkg, packageManager });
+    agents = planAgentContext({ consumerRoot, pkg, packageManager, commands });
   } catch (error) {
     errors.push(error);
   }
@@ -54,11 +63,11 @@ export function collectPlans({ consumerRoot, env = process.env }) {
   return { consumerRoot, pkg, packageManager, sources, root, tailwindV3File, tailwind, cssRoot, legacyImports, agents, claude, gemini, deliveryNotes, errors };
 }
 
-export function planSync({ consumerRoot, env = process.env, only = null }) {
+export function planSync({ consumerRoot, env = process.env, only = null, ensureScripts = true }) {
   if (only !== null && !syncTargets.has(only)) {
     throw createExitError("Unknown --only target: " + only + " (use tailwind or agents).", 2);
   }
-  const plans = collectPlans({ consumerRoot, env });
+  const plans = collectPlans({ consumerRoot, env, ensureScripts: ensureScripts && only === null });
   if (plans.errors.length > 0) {
     // Same wording as the doctor line, so the CONSUMER_AGENT.md table applies to both.
     plans.errors[0].message = "invalid: " + plans.errors[0].message;
@@ -83,7 +92,7 @@ export function planSync({ consumerRoot, env = process.env, only = null }) {
 }
 
 // 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.
+// later sync and doctor runs resolve the same root without the environment variable.
 function persistTailwindRoot(plan, { dryRun, log }) {
   if (plan.root?.source !== "env" || plan.only === "agents") {
     return false;
@@ -94,7 +103,7 @@ function persistTailwindRoot(plan, { dryRun, log }) {
   const existing = consumerPackage[consumerConfigField];
   if (existing !== undefined && (typeof existing !== "object" || existing === null || Array.isArray(existing))) {
     log("[EDS] package.json \"" + consumerConfigField + "\" is not an object, so " + tailwindRootEnvironmentVariable + " was not recorded. " +
-      "With several Tailwind CSS candidates, doctor and the pretypecheck/prebuild hooks exit 2 again. Check what uses the existing \"" +
+      "With several Tailwind CSS candidates, doctor and sync exit 2 again. Check what uses the existing \"" +
       consumerConfigField + "\" value and move it so \"" + consumerConfigField + "\" can be an object, or set " + tailwindRootEnvironmentVariable + " on every run.");
     return false;
   }
@@ -109,7 +118,7 @@ function persistTailwindRoot(plan, { dryRun, log }) {
   }
   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 + ".");
+  log("[EDS] wrote " + label + " to package.json; doctor and sync now use this Tailwind root without " + tailwindRootEnvironmentVariable + ".");
   return true;
 }
 
@@ -143,13 +152,17 @@ export function applySync(plan, { dryRun = false, log = console.log } = {}) {
     const doctorRun = isCompatibleCommand(scripts[doctorScriptName], doctorCommand)
       ? runnerCommand(plan.packageManager, doctorScriptName)
       : cliCommand(plan.packageManager, "doctor");
-    log("[EDS] Synced with " + version + ". Include the files written above in your change, then run " + doctorRun + ".");
+    log("[EDS] Synced with " + version + ". Include the files written above in your change; before committing, run " + doctorRun + ".");
   }
   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 });
+export function runSync({ consumerRoot, env = process.env, only = null, dryRun = false, ensureScripts = true, log = console.log }) {
+  const plan = planSync({ consumerRoot, env, only, ensureScripts });
+  // Keep script setup and cleanup in the same one-time task-start command, including package managers that skip postinstall.
+  if (ensureScripts && only === null) {
+    registerConsumerScripts(consumerRoot, { log, dryRun, logNoop: false, packageManager: plan.packageManager });
+  }
   applySync(plan, { dryRun, log });
   return 0;
 }

package/consumer/update-agent-context.mjs

@@ -17,12 +17,12 @@ export const geminiImportLine = "@./AGENTS.md";
 const importPattern = /^[ \t]*@(?:\.\.?\/)?AGENTS\.md[ \t]*$/m;
 const endMarkerText = "<!-- EDS:END -->";
 
-export function planAgentContext({ consumerRoot, pkg, packageManager = null }) {
+export function planAgentContext({ consumerRoot, pkg, packageManager = null, commands = null }) {
   const filePath = path.join(consumerRoot, "AGENTS.md");
   const before = readTextIfExists(filePath);
   // The block is rendered with the target file's dominant line ending; a new file uses LF.
   const eol = before === null ? "\n" : detectEol(before);
-  const block = withEol(renderBlock(readTemplateBlock(pkg.packageRoot), pkg.version, packageManager), eol);
+  const block = withEol(renderBlock(readTemplateBlock(pkg.packageRoot), pkg.version, packageManager, commands), eol);
   const located = before === null ? null : locateBlock(before);
   return {
     label: "agents",

package/consumer-postinstall.mjs

@@ -1,7 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { locateBlock, readBlockVersion } from "./consumer/managed-block.mjs";
+import { cliCommand, detectPackageManager, resolvePackage } from "./consumer/paths.mjs";
 import { registerConsumerScripts } from "./consumer/register-scripts.mjs";
+import { runSync } from "./consumer/sync.mjs";
 
 const packageRoot = path.dirname(fileURLToPath(import.meta.url));
 const consumerRoot = process.env.INIT_CWD;
@@ -12,7 +15,7 @@ if (!consumerRoot || path.resolve(consumerRoot) === packageRoot) {
 
 const consumerPackagePath = path.join(consumerRoot, "package.json");
 if (!fs.existsSync(consumerPackagePath)) {
-  console.log("[EDS] Consumer package.json was not found; run npx @spectrabrain/eds init in the package that depends on @spectrabrain/eds.");
+  console.log("[EDS] Consumer package.json was not found; the coding agent should run EDS setup in the app package that depends on EDS.");
   process.exit(0);
 }
 
@@ -26,35 +29,90 @@ function realpathOrNull(filePath) {
 
 const installedPath = realpathOrNull(path.join(consumerRoot, "node_modules", "@spectrabrain", "eds"));
 if (installedPath === null || installedPath !== realpathOrNull(packageRoot)) {
-  console.log("[EDS] Skipping consumer setup: this install is not the consumer's node_modules/@spectrabrain/eds. Run npx @spectrabrain/eds init in the package that depends on @spectrabrain/eds.");
+  console.log("[EDS] Skipping consumer setup: this is not the app package's direct EDS install. The coding agent should set up EDS in the app package that depends on it.");
   process.exit(0);
 }
 
-// pnpm rewrites the consumer package.json after dependency lifecycle scripts, so edits made here are lost.
-if (String(process.env.npm_config_user_agent ?? "").startsWith("pnpm/")) {
-  console.log("[EDS] pnpm discards package.json edits made during install; run pnpm exec eds init to register the EDS scripts.");
+let consumerPackage;
+try {
+  consumerPackage = JSON.parse(fs.readFileSync(consumerPackagePath, "utf8"));
+} catch (error) {
+  console.log("[EDS] Consumer package.json could not be parsed (" + error.message + "); the coding agent should run EDS setup after fixing it.");
   process.exit(0);
 }
 
-let consumerPackage;
+let packageManager;
+let packageJson;
 try {
-  consumerPackage = JSON.parse(fs.readFileSync(consumerPackagePath, "utf8"));
+  packageManager = detectPackageManager(consumerRoot);
+  packageJson = resolvePackage(consumerRoot);
 } catch (error) {
-  console.log("[EDS] Consumer package.json could not be parsed (" + error.message + "); run npx @spectrabrain/eds init after fixing it.");
+  console.log("[EDS] Consumer setup was skipped (" + (error instanceof Error ? error.message : String(error)) + ").");
   process.exit(0);
 }
 
-// A workspaces root hoists the package but is not the app that uses it: registering the scripts and hooks
-// there would make the root build look for src/styles/eds-tokens.css and AGENTS.md in the wrong place.
+const initCommand = cliCommand(packageManager, "init");
 if (consumerPackage.workspaces !== undefined) {
-  console.log("[EDS] Skipping consumer setup: package.json declares workspaces. Run npx @spectrabrain/eds init inside the app package that depends on @spectrabrain/eds.");
+  console.log("[EDS] Skipping consumer setup at the workspaces root. The coding agent should run " + initCommand + " inside the app package that depends on EDS.");
+  process.exit(0);
+}
+
+const agentsPath = path.join(consumerRoot, "AGENTS.md");
+let existingManagedBlock = null;
+let markerVersion = null;
+try {
+  if (fs.existsSync(agentsPath)) {
+    const block = locateBlock(fs.readFileSync(agentsPath, "utf8"));
+    existingManagedBlock = block?.block ?? null;
+    markerVersion = existingManagedBlock === null ? null : readBlockVersion(existingManagedBlock);
+  }
+} catch (error) {
+  console.log(
+    "[EDS] Initial sync was skipped (" + (error instanceof Error ? error.message : String(error)) + "); " +
+      "the coding agent should repair the EDS markers before syncing.",
+  );
   process.exit(0);
 }
 
-// The install must never fail because of this setup step; anything unexpected is reported and left to eds doctor.
+const pnpmInstall = String(process.env.npm_config_user_agent ?? "").startsWith("pnpm/");
+if (!pnpmInstall) {
+  try {
+    registerConsumerScripts(consumerRoot, { packageManager });
+  } catch (error) {
+    console.log("[EDS] Script maintenance was skipped (" + (error instanceof Error ? error.message : String(error)) + ").");
+  }
+}
+
+if (existingManagedBlock !== null && markerVersion === null) {
+  console.log(
+    "[EDS] The existing AGENTS.md EDS block has no version marker; scripts were maintained without changing files, and the coding agent will read the installed version's CHANGELOG.md actions and sync at the start of the next UI task.",
+  );
+  process.exit(0);
+}
+
+if (markerVersion !== null) {
+  if (markerVersion !== packageJson.version) {
+    console.log(
+      "[EDS] Installed EDS version " + packageJson.version + " differs from the AGENTS.md marker " + markerVersion + "; " +
+        "the coding agent will read the version's CHANGELOG.md actions and sync at the start of the next UI task.",
+    );
+  } else {
+    console.log("[EDS] The AGENTS.md version marker matches; the coding agent will check generated files with its next task-start sync.");
+  }
+  process.exit(0);
+}
+
+// pnpm restores package.json after dependency lifecycle scripts, so sync its initial managed files now but let the agent
+// register scripts with its first task-start sync. Other package managers keep both scripts and files.
 try {
-  const result = registerConsumerScripts(consumerRoot);
-  console.log("[EDS] Run " + result.syncRunCommand + " to finish setup.");
+  runSync({ consumerRoot, ensureScripts: false });
+  if (pnpmInstall) {
+    console.log("[EDS] pnpm leaves package.json scripts to the coding agent's first task-start sync.");
+  }
+  console.log("[EDS] Initial EDS sync is ready; the managed instructions tell the coding agent when to sync on later tasks.");
 } catch (error) {
-  console.log("[EDS] Consumer setup was skipped (" + (error instanceof Error ? error.message : String(error)) + "). Run npx @spectrabrain/eds init to register the EDS scripts.");
+  console.log(
+    "[EDS] Initial sync was skipped (" + (error instanceof Error ? error.message : String(error)) + "); " +
+      "the coding agent should resolve the finding and run " + cliCommand(packageManager, "sync") + ".",
+  );
 }

package/dist/components/Button/spec.json

@@ -1,6 +1,6 @@
 {
   "specVersion": 1,
-  "packageVersion": "0.4.0",
+  "packageVersion": "0.6.0",
   "name": "Button",
   "purpose": "사용자가 즉시 실행할 수 있는 행동과 탐색을 표현하는 인터랙티브 요소입니다.",
   "usageContexts": [