@contentful/experience-design-system-cli 2.34.5-dev-build-d42cd1ad.0 → 2.34.5-dev-build-4bbbf2f0.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.34.5-dev-build-d42cd1ad.0",
+  "version": "2.34.5-dev-build-4bbbf2f0.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",

package/dist/src/analyze/composition/interchange-schema.d.ts

@@ -1,17 +1,11 @@
 /**
  * The CLI-owned composition interchange format (spec T1).
  *
- * Two views of the same data:
- *  - `InterchangeMap` — the human-authored / on-disk `{ version, groups }`
- *    shape (parent → children), consumed by the composition-map option.
- *    `--composition-map` consumes and the resolver can emit.
- *  - `CompositionEdge[]` — the flat internal runtime view, one edge per
- *    parent→child relationship, carrying optional `slot` (T7), `confidence`,
- *    and `provenance`. Easier to merge/dedupe across sources (T2).
- *
- * This module owns both shapes and the converters between them.
+ * `CompositionEdge[]` is the flat internal runtime view, one edge per
+ * parent→child relationship, carrying optional `slot` (T7), `confidence`,
+ * and `provenance`. It is easier to merge and dedupe across sources (T2).
  */
-export type EdgeProvenance = 'user' | 'typed-slot' | 'structural' | 'manifest' | 'doc' | `adapter:${string}` | 'agent';
+export type EdgeProvenance = 'typed-slot' | 'structural' | 'manifest' | 'doc' | `adapter:${string}` | 'agent';
 export type CompositionEdge = {
     parent: string;
     child: string;
@@ -21,17 +15,3 @@ export type CompositionEdge = {
     confidence?: number;
     provenance: EdgeProvenance;
 };
-export type InterchangeMap = {
-    version: 1;
-    groups: Record<string, string[]>;
-};
-export type ValidateResult = {
-    valid: true;
-    map: InterchangeMap;
-} | {
-    valid: false;
-    errors: string[];
-};
-export declare function validateInterchangeMap(input: unknown): ValidateResult;
-export declare function groupsToEdges(map: InterchangeMap, provenance: EdgeProvenance): CompositionEdge[];
-export declare function edgesToGroups(edges: CompositionEdge[]): InterchangeMap;

package/dist/src/analyze/composition/resolve-mapping-cli.d.ts

@@ -1,18 +1,7 @@
-import { type InterchangeMap } from './interchange-schema.js';
 export type CompositionCliOptions = {
-    /** `--composition-map <path>` — hand-authored interchange file. */
-    compositionMap?: string;
     /** `--composition-refresh` — force edge emission to run even over resolved residue. */
     compositionRefresh?: boolean;
 };
-export type LoadUserMapResult = {
-    ok: true;
-    map: InterchangeMap;
-} | {
-    ok: false;
-    error: string;
-};
-export declare function loadUserMap(path: string): Promise<LoadUserMapResult>;
 export type ResolvedCompositionSources = {
     forceAgent: boolean;
 };

package/dist/src/analyze/composition/resolve-mapping.d.ts

@@ -1,9 +1,8 @@
 import type { RawComponentDefinition } from '../../types.js';
-import { type CompositionEdge, type InterchangeMap } from './interchange-schema.js';
+import type { CompositionEdge } from './interchange-schema.js';
 import { type EdgeConflict } from './merge-edges.js';
 export type ResolveMappingResult = {
     components: RawComponentDefinition[];
-    userMap?: InterchangeMap;
     edges: CompositionEdge[];
     conflicts: EdgeConflict[];
     warnings: string[];
@@ -11,9 +10,9 @@ export type ResolveMappingResult = {
 /**
  * Orchestrate composition-edge acquisition and enrichment.
  *
- * Sources by rank: user map (1) > typed-slot / "code slots" (2) > structural
- * usage evidence (3) > manifest (4) > doc (5) > adapter-resolved / extraEdges
- * (6) > edge-emitting agent (7). Manifest/doc edges are computed deterministically outside
+ * Sources by rank: typed-slot / "code slots" (2) > structural usage evidence
+ * (3) > manifest (4) > doc (5) > adapter-resolved / extraEdges (6) >
+ * edge-emitting agent (7). Manifest/doc edges are computed deterministically outside
  * this function (see manifest-doc-evidence.ts) and joined via `extraEdges`.
  * ALL sources — including the code slots already on the incoming components —
  * are fed into one ranked merge and unioned; non-conflicting edges from every
@@ -28,7 +27,6 @@ export type ResolveMappingResult = {
  */
 export declare function resolveMapping(input: {
     components: RawComponentDefinition[];
-    userMap?: InterchangeMap;
     forceAgent?: boolean;
     files: Array<{
         path: string;
@@ -55,7 +53,7 @@ export declare function resolveMapping(input: {
     /**
      * Pre-resolved edges from an external source (e.g. manifest or documentation)
      * path). They join the ranked merge at their own provenance rank alongside
-     * code slots and the user map.
+     * code slots and other automatic mapping sources.
      */
     extraEdges?: CompositionEdge[];
 }): Promise<ResolveMappingResult>;

package/dist/src/credentials-store.d.ts

@@ -7,7 +7,7 @@ export type ExperiencesCredentials = {
     agentModel?: string;
     /** Feature 8: persisted custom prompt path for `generate components`. */
     generatePromptPath?: string;
-    /** Write JSONL trace of every command decision to ~/.contentful/experience-design-system-cli/debug/. */
+    /** Feature: default debug-mode (writes JSONL trace of every decision) for all commands. */
     debug?: boolean;
     /** Print plain text with no color; an exported NO_COLOR still wins. */
     noColor?: boolean;

package/dist/src/import/composition-options.d.ts

@@ -1,9 +1,7 @@
 export type CompositionOptionInput = {
-    compositionMap?: string;
     prompt?: string[];
 };
 export type CompositionForwardingOptions = {
-    compositionMap?: string;
     promptOverrides?: string[];
 };
 export declare function buildCompositionForwardingOptions(options: CompositionOptionInput): CompositionForwardingOptions;

package/dist/src/index.js

@@ -1184,6 +1184,17 @@ function initDebugLogger(opts) {
 function getDebugLogger() {
   return singleton ?? new NoopDebugLogger();
 }
+function resolveDebugMode(opts, configDebug) {
+  if (opts.debug !== void 0) return opts.debug;
+  const env = process.env["EDSI_DEBUG"];
+  if (env !== void 0 && env !== "") {
+    const v = env.toLowerCase();
+    if (v === "1" || v === "true" || v === "yes" || v === "on") return true;
+    if (v === "0" || v === "false" || v === "no" || v === "off") return false;
+  }
+  if (configDebug !== void 0) return configDebug;
+  return false;
+}
 function printDebugBanner(logger, phase) {
   if (!logger.enabled || !logger.path) return;
   const prefix = phase === "start" ? "\x1B[92m[debug]\x1B[0m " : "\x1B[92m[debug]\x1B[0m ";
@@ -7521,7 +7532,7 @@ function buildApplyOutput(operation, spaceId, environmentId, host) {
   };
 }
 function registerApplyCommand(program) {
-  const applyCmd = program.command("apply").description("Write component types and design tokens to Contentful ExO").argument("<file>", "CDF file containing all component and design token definitions");
+  const applyCmd = program.command("apply").description("Write component types and design tokens to Contentful ExO").helpOption(false).argument("<file>", "CDF file containing all component and design token definitions");
   applyCmd.action(async (file) => {
     const isTTY = getInteractiveTerminalSupport().supported;
     const inputs = await resolveSharedInputsOrDie(file);
@@ -8571,16 +8582,17 @@ ${defaultDiagnostics.map((diagnostic) => `  ${diagnostic}`).join("\n")}
         );
       }
     }
+    const buildMapPrompt = () => buildPrompt({
+      skill: "map-tokens",
+      mode: "autonomous",
+      generatedCdf,
+      tokenTree,
+      componentSourceRefs,
+      outDir: process.cwd(),
+      existingTokensInline
+    });
     if (opts.printPrompt) {
-      const prompt2 = await buildPrompt({
-        skill: "map-tokens",
-        mode: "autonomous",
-        generatedCdf,
-        tokenTree,
-        componentSourceRefs,
-        outDir: process.cwd(),
-        existingTokensInline
-      });
+      const prompt2 = await buildMapPrompt();
       process.stdout.write(prompt2 + "\n");
       await exitWithAnalytics(0);
       return;
@@ -8624,15 +8636,7 @@ Install it, choose another agent with --agent, or use --print-prompt to run the
       );
     }
     const stepId = createStep(db, sessionId2, "map tokens", { agent, model: model ?? "" });
-    const prompt = await buildPrompt({
-      skill: "map-tokens",
-      mode: "autonomous",
-      generatedCdf,
-      tokenTree,
-      componentSourceRefs,
-      outDir: process.cwd(),
-      existingTokensInline
-    });
+    const prompt = await buildMapPrompt();
     const invoker2 = createLocalCliAgentInvoker();
     const result = await invoker2.invoke({ agent, model, prompt, timeoutMs: DEFAULT_TIMEOUT_MS2 });
     if (result.timedOut || result.exitCode !== 0) {
@@ -8710,19 +8714,6 @@ var init_path_utils = __esm({
   }
 });
 
-// packages/experience-design-system-cli/src/import/composition-options.ts
-function buildCompositionForwardingOptions(options) {
-  return {
-    ...options.compositionMap ? { compositionMap: options.compositionMap } : {},
-    ...options.prompt && options.prompt.length > 0 ? { promptOverrides: options.prompt } : {}
-  };
-}
-var init_composition_options = __esm({
-  "packages/experience-design-system-cli/src/import/composition-options.ts"() {
-    "use strict";
-  }
-});
-
 // packages/experience-design-system-cli/src/analyze/select/tui/theme.ts
 var PALETTE;
 var init_theme = __esm({
@@ -28273,86 +28264,63 @@ var init_WizardApp = __esm({
 
 // packages/experience-design-system-cli/src/import/command.ts
 function registerImportCommand(program) {
-  const cmd = program.command("import").description("Run the full pipeline: analyze \u2192 select \u2192 generate \u2192 push").option("--project <path>", "Path to the project root to analyze", ".");
-  addAgentModelOptions(cmd, {
-    agentDescription: 'Agent to use for generate components (overrides credentials.json; falls back to "claude")',
-    modelDescription: "Model to use for generate components (defaults to a lightweight per-agent model; override with EDS_AGENT_MODEL_<AGENT>)"
-  }).option(
-    "--raw-tokens <path>",
-    "Path to a raw token source file (SCSS, CSS variables, JS/TS, Style Dictionary, etc.) to classify and import alongside components. Bypasses the interactive token prompt."
-  ).option(
-    "--skip-map-tokens",
-    "Skip agentic token restrictions while still resolving deterministic token-default paths"
-  ).option("--no-cache", "Re-run all steps even if output already exists");
-  cmd.option("--composition-map <path>", "Consume a hand-authored parent\u2192children interchange map").option(
+  program.command("import").description("Run the full pipeline: analyze \u2192 select \u2192 generate \u2192 push").option("--project <path>", "Path to the project root to analyze", ".").option("--tokens <path>", "Path to a raw token source file to import alongside components").option("--agent <name>", 'Agent to use for generation (overrides credentials.json; falls back to "claude")').option(
     "--prompt <stage=value>",
     "Override a stage prompt (repeatable). value is a file path or literal text, e.g. --prompt composition=./p.md",
     (v, acc) => [...acc, v],
     []
-  ).action(
-    async (opts) => {
-      const interactiveTerminalSupported = getInteractiveTerminalSupport().supported;
-      if (opts.rawTokens !== void 0) {
-        const { access: access9 } = await import("node:fs/promises");
-        try {
-          await access9(normalizePath(opts.rawTokens));
-        } catch {
-          process.stderr.write(`Error: --raw-tokens: file not found: ${opts.rawTokens}
-`);
-          process.exit(1);
-          return;
-        }
-      }
-      if (!interactiveTerminalSupported) {
-        requireInteractiveTerminal({
-          alternative: "run experiences import in an interactive terminal"
-        });
-      }
-      {
-        const { render: render5 } = await import("ink");
-        const { createElement: createElement6 } = await import("react");
-        const { WizardApp: WizardApp2 } = await Promise.resolve().then(() => (init_WizardApp(), WizardApp_exports));
-        const creds = await readExperiencesCredentials();
-        const resolvedAgent = opts.agent || creds.agent || "claude";
-        const resolvedModel = opts.model || creds.agentModel || void 0;
-        if (opts.bedrock && !(isAgentName(resolvedAgent) && agentSupportsBedrock(resolvedAgent))) {
-          process.stderr.write(`Error: --bedrock is not supported for --agent ${resolvedAgent}
+  ).option("--no-cache", "Re-run all steps even if output already exists").action(async (opts) => {
+    const interactiveTerminalSupported = getInteractiveTerminalSupport().supported;
+    if (opts.tokens !== void 0) {
+      const { access: access9 } = await import("node:fs/promises");
+      try {
+        await access9(normalizePath(opts.tokens));
+      } catch {
+        process.stderr.write(`Error: --tokens: file not found: ${opts.tokens}
 `);
-          process.exit(1);
-        }
-        const { waitUntilExit } = render5(
-          createElement6(WizardApp2, {
-            initialSpaceId: creds.spaceId,
-            initialEnvironmentId: creds.environmentId || "master",
-            initialCmaToken: creds.cmaToken,
-            initialHost: toConfiguredHost(creds.host) ?? DEFAULT_CONFIGURED_HOST,
-            initialAgent: resolvedAgent,
-            ...resolvedModel ? { initialModel: resolvedModel } : {},
-            ...opts.bedrock ? { bedrock: true } : {},
-            initialProjectPath: opts.project !== "." ? normalizePath(opts.project) : void 0,
-            ...buildCompositionForwardingOptions(opts),
-            noCache: opts.cache === false,
-            skipMapTokens: opts.skipMapTokens ?? false,
-            livePreview: true,
-            generatePromptPath: creds.generatePromptPath,
-            ...opts.rawTokens ? { initialRawTokensPath: normalizePath(opts.rawTokens) } : {}
-          })
-        );
-        await waitUntilExit();
+        process.exit(1);
         return;
       }
     }
-  );
+    if (!interactiveTerminalSupported) {
+      requireInteractiveTerminal({
+        alternative: "run experiences import in an interactive terminal"
+      });
+    }
+    {
+      const { render: render5 } = await import("ink");
+      const { createElement: createElement6 } = await import("react");
+      const { WizardApp: WizardApp2 } = await Promise.resolve().then(() => (init_WizardApp(), WizardApp_exports));
+      const creds = await readExperiencesCredentials();
+      const resolvedAgent = opts.agent || creds.agent || "claude";
+      const resolvedModel = creds.agentModel || void 0;
+      const { waitUntilExit } = render5(
+        createElement6(WizardApp2, {
+          initialSpaceId: creds.spaceId,
+          initialEnvironmentId: creds.environmentId || "master",
+          initialCmaToken: creds.cmaToken,
+          initialHost: toConfiguredHost(creds.host) ?? DEFAULT_CONFIGURED_HOST,
+          initialAgent: resolvedAgent,
+          ...resolvedModel ? { initialModel: resolvedModel } : {},
+          initialProjectPath: opts.project !== "." ? normalizePath(opts.project) : void 0,
+          ...opts.prompt && opts.prompt.length > 0 ? { promptOverrides: opts.prompt } : {},
+          noCache: opts.cache === false,
+          livePreview: true,
+          generatePromptPath: creds.generatePromptPath,
+          ...opts.tokens ? { initialRawTokensPath: normalizePath(opts.tokens) } : {}
+        })
+      );
+      await waitUntilExit();
+      return;
+    }
+  });
 }
 var init_command6 = __esm({
   "packages/experience-design-system-cli/src/import/command.ts"() {
     "use strict";
-    init_src();
     init_path_utils();
-    init_agent_model_options();
     init_credentials_store();
     init_host_utils();
-    init_composition_options();
     init_terminal_capabilities();
   }
 });
@@ -28659,7 +28627,7 @@ var init_checks2 = __esm({
 });
 
 // packages/experience-design-system-cli/src/doctor/command.ts
-async function runChecks(opts) {
+async function runChecks() {
   const pkgRoot = findPkgRoot();
   const results = [];
   const record = (name, passed, required = true) => {
@@ -28668,13 +28636,11 @@ async function runChecks(opts) {
   };
   if (record("Node.js version", await reportNode())) {
     const pnpmOk = record("pnpm", await reportPnpm(pkgRoot));
-    if (opts.skipBuild) {
-      info("\nSkipping install + build (--skip-build)");
-    } else if (pnpmOk && record("dependencies", await reportDependencies(pkgRoot))) {
+    if (pnpmOk && record("dependencies", await reportDependencies(pkgRoot))) {
       record("build", await reportBuild(pkgRoot));
     }
   }
-  if (!opts.skipAgent) record("coding agent", await reportAgent(), false);
+  record("coding agent", await reportAgent(), false);
   return results;
 }
 function printSummary(results) {
@@ -28714,13 +28680,13 @@ ${c.red(c.bold(`\u2717 ${requiredFailed} required check${requiredFailed === 1 ?
 `);
   return 1;
 }
-async function runDoctor(opts) {
+async function runDoctor() {
   process.stderr.write(`${c.bold("experiences doctor")} \u2014 checking your environment
 `);
-  process.exitCode = printSummary(await runChecks(opts));
+  process.exitCode = printSummary(await runChecks());
 }
 function registerDoctorCommand(program) {
-  program.command("doctor").description("Check prerequisites so experiences import runs without errors").option("--skip-build", "Skip the pnpm install + build step (useful if already built)").option("--skip-agent", "Skip the coding agent check").action((opts) => runDoctor(opts));
+  program.command("doctor").description("Check prerequisites so experiences import runs without errors").helpOption(false).action(() => runDoctor());
 }
 var init_command7 = __esm({
   "packages/experience-design-system-cli/src/doctor/command.ts"() {
@@ -29860,7 +29826,7 @@ async function runSetup(opts) {
   process.exit(finished.exitCode);
 }
 function registerSetupCommand(program) {
-  program.command("setup").description("Interactive setup: installs prerequisites and configures credentials for experiences import").option("--skip-build", "Skip the pnpm install + build step").option("--skip-agent", "Skip the coding agent check").option("--skip-credentials", "Skip the Contentful credentials step").option("--skip-optional", "Skip optional quality-of-life extras").action((opts) => runSetup(opts));
+  program.command("setup").description("Interactive setup: installs prerequisites and configures credentials for experiences import").helpOption(false).action(() => runSetup({}));
 }
 var SETUP_REQUIRES_TTY_MESSAGE;
 var init_command8 = __esm({
@@ -29872,57 +29838,14 @@ var init_command8 = __esm({
   }
 });
 
-// packages/experience-design-system-cli/src/analyze/composition/interchange-schema.ts
-function validateInterchangeMap(input) {
-  const errors = [];
-  if (typeof input !== "object" || input === null || Array.isArray(input)) {
-    return { valid: false, errors: ["interchange map must be a JSON object"] };
-  }
-  const obj = input;
-  if (obj.version !== 1) {
-    errors.push(`unsupported interchange version: expected 1, got ${JSON.stringify(obj.version)}`);
-  }
-  if (typeof obj.groups !== "object" || obj.groups === null || Array.isArray(obj.groups)) {
-    errors.push("interchange map must have a `groups` object");
-    return { valid: false, errors };
-  }
-  const groups = obj.groups;
-  for (const [parent, children] of Object.entries(groups)) {
-    if (!Array.isArray(children) || !children.every((c2) => typeof c2 === "string")) {
-      errors.push(`groups["${parent}"] must be an array of strings`);
-    }
-  }
-  if (errors.length > 0) return { valid: false, errors };
-  return { valid: true, map: { version: 1, groups } };
-}
-function groupsToEdges(map, provenance) {
-  const seen = /* @__PURE__ */ new Set();
-  const edges = [];
-  for (const [parent, children] of Object.entries(map.groups)) {
-    for (const child of children) {
-      const key = `${parent}::${child}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-      edges.push({ parent, child, provenance });
-    }
-  }
-  return edges;
-}
-var init_interchange_schema = __esm({
-  "packages/experience-design-system-cli/src/analyze/composition/interchange-schema.ts"() {
-    "use strict";
-  }
-});
-
 // packages/experience-design-system-cli/src/analyze/composition/merge-edges.ts
 function rank(p) {
-  if (p === "user") return 1;
-  if (p === "typed-slot") return 2;
-  if (p === "structural") return 3;
-  if (p === "manifest") return 4;
-  if (p === "doc") return 5;
-  if (p.startsWith("adapter:")) return 6;
-  return 7;
+  if (p === "typed-slot") return 1;
+  if (p === "structural") return 2;
+  if (p === "manifest") return 3;
+  if (p === "doc") return 4;
+  if (p.startsWith("adapter:")) return 5;
+  return 6;
 }
 function mergeEdges(all) {
   const byKey = /* @__PURE__ */ new Map();
@@ -30028,7 +29951,7 @@ function applyMapping(components, edges) {
     }))
   }));
   const byName = new Map(cloned.map((c2) => [c2.name, c2]));
-  const isHighTrust = (p) => p === "user" || p === "typed-slot" || p.startsWith("adapter:");
+  const isHighTrust = (p) => p === "typed-slot" || p.startsWith("adapter:");
   const addAllowed = (slot, child) => {
     const set = new Set(slot.allowedComponents ?? []);
     set.add(child);
@@ -30127,7 +30050,6 @@ async function resolveMapping(input) {
       }
     }
   }
-  if (input.userMap) collected.push(...groupsToEdges(input.userMap, "user"));
   if (input.extraEdges) {
     collected.push(...input.extraEdges);
   }
@@ -30175,7 +30097,6 @@ ${f.content}`).join("\n\n");
 var init_resolve_mapping = __esm({
   "packages/experience-design-system-cli/src/analyze/composition/resolve-mapping.ts"() {
     "use strict";
-    init_interchange_schema();
     init_merge_edges();
     init_parse_map_edges();
     init_apply_mapping();
@@ -30184,24 +30105,6 @@ var init_resolve_mapping = __esm({
 });
 
 // packages/experience-design-system-cli/src/analyze/composition/resolve-mapping-cli.ts
-import { readFile as readFile18 } from "node:fs/promises";
-async function loadUserMap(path) {
-  let text;
-  try {
-    text = await readFile18(path, "utf8");
-  } catch {
-    return { ok: false, error: `--composition-map: file not found: ${path}` };
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(text);
-  } catch {
-    return { ok: false, error: `--composition-map: not valid JSON: ${path}` };
-  }
-  const result = validateInterchangeMap(parsed);
-  if (!result.valid) return { ok: false, error: `--composition-map: ${result.errors.join("; ")}` };
-  return { ok: true, map: result.map };
-}
 function resolveCompositionSources(opts) {
   return {
     forceAgent: !!opts.compositionRefresh
@@ -30210,7 +30113,6 @@ function resolveCompositionSources(opts) {
 var init_resolve_mapping_cli = __esm({
   "packages/experience-design-system-cli/src/analyze/composition/resolve-mapping-cli.ts"() {
     "use strict";
-    init_interchange_schema();
   }
 });
 
@@ -30372,7 +30274,7 @@ var init_manifest_doc_evidence = __esm({
 });
 
 // packages/experience-design-system-cli/src/analyze/extract-command.ts
-import { mkdir as mkdir6, readdir as readdir3, readFile as readFile19, stat as stat6 } from "node:fs/promises";
+import { mkdir as mkdir6, readdir as readdir3, readFile as readFile18, stat as stat6 } from "node:fs/promises";
 import { isAbsolute as isAbsolute2, join as join25, relative as relative2, resolve as resolve19 } from "node:path";
 function isDenylistedNoiseFile(name) {
   return DENYLISTED_EXACT_FILE_NAMES.has(name) || DENYLISTED_FILE_NAME_PATTERNS.some((pattern) => pattern.test(name));
@@ -30439,7 +30341,7 @@ async function readCandidateFiles(components, extraFiles = []) {
   await Promise.all(
     [...paths].map(async (p) => {
       try {
-        const content = await readFile19(p, "utf8");
+        const content = await readFile18(p, "utf8");
         out.push({ path: p, content });
       } catch {
       }
@@ -30452,7 +30354,7 @@ function registerInternalExtractCommand(program) {
     "--resolve-unreachable <mode>",
     "Retry pass for unresolved Svelte Props types: 'auto' (default), 'always', or 'never'",
     "auto"
-  ).option("--composition-refresh", "Force the mapping agent to run even where deterministic sources answered").option("--composition-map <path>", "Consume a hand-authored parent\u2192children interchange map").option(
+  ).option("--composition-refresh", "Force the mapping agent to run even where deterministic sources answered").option(
     "--prompt <stage=value>",
     "Override a stage prompt (repeatable). value is a file path or literal text, e.g. --prompt composition=./p.md",
     (v, acc) => [...acc, v],
@@ -30568,16 +30470,6 @@ function registerInternalExtractCommand(program) {
     let validatedComponents = validateExtractedComponents(filteredComponents);
     {
       const sources = resolveCompositionSources(opts);
-      let userMap;
-      if (opts.compositionMap) {
-        const loaded = await loadUserMap(opts.compositionMap);
-        if (!loaded.ok) {
-          process.stderr.write(`Error: ${loaded.error}
-`);
-          process.exit(1);
-        }
-        userMap = loaded.map;
-      }
       const { overrides: promptOverrides, errors: promptErrors } = parsePromptOverrides(opts.prompt ?? []);
       for (const err of promptErrors) {
         process.stderr.write(`Error: ${err}
@@ -30639,7 +30531,6 @@ function registerInternalExtractCommand(program) {
         });
         const result = await resolveMapping({
           components: validatedComponents,
-          ...userMap ? { userMap } : {},
           ...extraEdges.length > 0 ? { extraEdges } : {},
           forceAgent: sources.forceAgent,
           files: promptFiles,
@@ -30780,14 +30671,14 @@ var init_extract_command = __esm({
 });
 
 // packages/experience-design-system-cli/src/lib/debug-preamble.ts
-async function beginCommand(command) {
+async function beginCommand(command, opts) {
   let configDebug;
   try {
     const creds = await readExperiencesCredentials();
     configDebug = creds.debug;
   } catch {
   }
-  const enabled = configDebug ?? false;
+  const enabled = resolveDebugMode(opts, configDebug);
   const logger = initDebugLogger({ enabled, command });
   if (logger.enabled) {
     printDebugBanner(logger, "start");
@@ -30846,7 +30737,7 @@ function resolveBedrockFromAncestors(actionCommand) {
   return false;
 }
 function registerImportV2Command(program) {
-  program.command("importv2").description("Launch the v2 import").action(async () => {
+  program.command("importv2").description("Launch the v2 import TUI (experience-design-system-cli-v2)").helpOption(false).action(async () => {
     const v2Path = join26(
       dirname13(fileURLToPath4(import.meta.url)),
       "..",
@@ -30864,7 +30755,7 @@ function registerImportV2Command(program) {
   });
 }
 function registerBuildCommand(program) {
-  program.command("build").description("Rebuild from source and re-link exo/experiences binaries to this build").action(async () => {
+  program.command("build").description("Rebuild from source and re-link exo/experiences binaries to this build").helpOption(false).action(async () => {
     const pkgRoot = resolve20(dirname13(fileURLToPath4(import.meta.url)), "..", "..");
     process.stderr.write("\u2699  Building from source...\n");
     const { exitCode } = await runBuild({
@@ -30874,18 +30765,34 @@ function registerBuildCommand(program) {
     process.exit(exitCode);
   });
 }
+function configureRootHelpOrder(program) {
+  const order = ["build", "help", "import", "apply", "importv2", "setup", "doctor"];
+  const rank2 = new Map(order.map((name, index) => [name, index]));
+  program.configureHelp({
+    visibleCommands(command) {
+      const internals = command;
+      const visible = command.commands.filter((entry) => !entry._hidden);
+      const helpCommand = internals._getHelpCommand?.();
+      if (helpCommand && !helpCommand._hidden) visible.push(helpCommand);
+      if (command !== program) return visible;
+      return visible.sort((a, b) => (rank2.get(a.name()) ?? order.length) - (rank2.get(b.name()) ?? order.length));
+    }
+  });
+}
 function createProgram() {
   const program = new Command().name("experience-design-system-cli").description("Static analysis, validation, generation, and import of Contentful design system artifacts").version(pkg3.version, "--version", "Print version number");
   registerInternalGenerateCommand(program);
   registerInternalExtractCommand(program);
   registerPrintCommand(program);
   registerMapTokensCommand(program);
-  registerApplyCommand(program);
+  registerBuildCommand(program);
+  program.helpCommand("help [command]", "display help for command");
   registerImportCommand(program);
+  registerApplyCommand(program);
   registerImportV2Command(program);
-  registerDoctorCommand(program);
   registerSetupCommand(program);
-  registerBuildCommand(program);
+  registerDoctorCommand(program);
+  configureRootHelpOrder(program);
   program.hook("preAction", async (_thisCommand, actionCommand) => {
     if (resolveBedrockFromAncestors(actionCommand)) {
       process.env.EDS_BEDROCK = "1";
@@ -30896,7 +30803,7 @@ function createProgram() {
     const { analyticsDisabled } = await readExperiencesCredentials();
     setPersistedAnalyticsDisabled(analyticsDisabled ?? false);
     noteCommandStart(commandChain);
-    await beginCommand(commandChain);
+    await beginCommand(commandChain, {});
   });
   program.hook("postAction", async () => {
     await completeActiveCommand();

package/dist/src/lib/debug-logger.d.ts

@@ -25,6 +25,17 @@ export declare function initDebugLogger(opts: InitDebugLoggerOptions): DebugLogg
 export declare function getDebugLogger(): DebugLogger;
 /** Test-only: reset the singleton. */
 export declare function __resetDebugLoggerForTest(): void;
+/**
+ * Resolve effective debug-mode setting from three sources.
+ *
+ * Precedence (highest first):
+ *   1. `EDSI_DEBUG` env var (truthy: 1, true, yes, on)
+ *   2. Persisted `debug` field in credentials.json
+ *   4. Default: OFF
+ */
+export declare function resolveDebugMode(opts: {
+    debug?: boolean;
+}, configDebug?: boolean): boolean;
 /**
  * Emit the bright-green "debug logs at <path>" banner to stderr.
  * No-op when debug is disabled or stderr is not a TTY-friendly stream.

package/dist/src/lib/debug-preamble.d.ts

@@ -1,6 +1,14 @@
 import { type DebugLogger } from './debug-logger.js';
 /**
- * Initialize the debug logger from persisted credentials.
- * Debug mode can only be configured via setup preferences;
+ * Preamble every top-level command action should call before doing work.
+ *
+ * Resolves the effective debug decision (flag > env > persisted config),
+ * initializes the singleton, and prints the bright-green start banner.
+ * Registers a process-exit handler that prints the end banner once.
+ *
+ * Returns the logger so the caller can emit events without a second import.
+ * When debug is disabled, the returned logger is a no-op.
  */
-export declare function beginCommand(command: string): Promise<DebugLogger>;
+export declare function beginCommand(command: string, opts: {
+    debug?: boolean;
+}): Promise<DebugLogger>;

package/dist/src/program.d.ts

@@ -16,9 +16,9 @@ export declare function runBuild(opts: {
     exitCode: number;
 }>;
 /**
- * Walks `actionCommand` and its ancestors for a truthy `--bedrock`.
- * --bedrock is registered per-subcommand, so a root-level or
- * subcommand-level setting can each carry it.
+ * Walks `actionCommand` and its ancestors for a truthy `--bedrock`. --bedrock
+ * is registered per-subcommand, so a
+ * root-level or subcommand-level setting can each carry it.
  */
 export declare function resolveBedrockFromAncestors(actionCommand: Command): boolean;
 export declare function createProgram(): Command;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.34.5-dev-build-d42cd1ad.0",
+  "version": "2.34.5-dev-build-4bbbf2f0.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -41,8 +41,8 @@
     "svelte": "^5.56.4",
     "ts-morph": "^27.0.2",
     "typescript": "^5.9.3",
-    "@contentful/experience-design-system-cli-v2": "2.34.5-dev-build-d42cd1ad.0",
-    "@contentful/experience-design-system-types": "2.34.5-dev-build-d42cd1ad.0"
+    "@contentful/experience-design-system-cli-v2": "2.34.5-dev-build-4bbbf2f0.0",
+    "@contentful/experience-design-system-types": "2.34.5-dev-build-4bbbf2f0.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.4",
@@ -54,9 +54,9 @@
     "ink-testing-library": "^4.0.0",
     "typescript-eslint": "^8.67.0",
     "vitest": "^4.0.16",
-    "@contentful/experience-design-system-client": "2.34.5-dev-build-d42cd1ad.0",
-    "@contentful/experience-design-system-generation": "2.34.5-dev-build-d42cd1ad.0",
-    "@contentful/experience-design-system-extraction": "2.34.5-dev-build-d42cd1ad.0"
+    "@contentful/experience-design-system-client": "2.34.5-dev-build-4bbbf2f0.0",
+    "@contentful/experience-design-system-extraction": "2.34.5-dev-build-4bbbf2f0.0",
+    "@contentful/experience-design-system-generation": "2.34.5-dev-build-4bbbf2f0.0"
   },
   "repository": {
     "type": "git",