@contentful/experience-design-system-generation 2.34.1-dev-build-cafcfc3.0 → 2.34.1-dev-build-928f202.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-generation",
-  "version": "2.34.1-dev-build-cafcfc3.0",
+  "version": "2.34.1-dev-build-928f202.0",
   "description": "Agent-invocation and skill-prompt engine for the Contentful Experience Design System SDK",
   "license": "MIT",
   "type": "module",

package/dist/src/agent-runner.d.ts

@@ -113,6 +113,20 @@ export declare function agentSupportsBedrock(agent: AgentName): boolean;
  */
 export declare function resolveAgentModel(agent: AgentName, explicit?: string, bedrock?: boolean): string | undefined;
 export type AgentDebugEvent = (name: string, payload?: Record<string, unknown>) => void;
+export declare function agentSupportsStdinPrompt(agent: AgentName): boolean;
+/**
+ * Decide how to deliver the prompt.
+ *
+ * Prefer stdin whenever the agent supports it and the prompt is large enough for
+ * argv limits to matter. This is what makes `generate components` work on Windows,
+ * and it removes a latent ARG_MAX failure on macOS as the skills grow.
+ *
+ * Exported so callers can detect the case that has no answer: a large prompt for an
+ * agent that can only accept argv.
+ */
+export declare function shouldUseStdinPrompt(agent: AgentName, prompt: string): boolean;
+/** True when the prompt cannot be delivered to this agent on this platform. */
+export declare function promptExceedsArgvLimit(agent: AgentName, prompt: string, platform?: NodeJS.Platform): boolean;
 export declare function buildArgs(agent: AgentName, prompt: string, model?: string, promptViaStdin?: boolean, bedrock?: boolean): string[];
 export declare function runAgent(options: {
     agent: AgentName;
@@ -123,9 +137,12 @@ export declare function runAgent(options: {
     bedrock?: boolean;
     onOutput?: (chunk: string) => void;
     /**
-     * Deliver the prompt on stdin instead of as an argv positional. Required for
-     * large prompts (e.g. the composition resolver inlining candidate files),
-     * which overflow ARG_MAX when passed as an argument.
+     * Force the prompt onto stdin instead of an argv positional.
+     *
+     * Usually unnecessary: a prompt large enough for argv limits to matter is sent
+     * on stdin automatically (see shouldUseStdinPrompt). Set this to opt in for a
+     * small prompt too. It cannot force stdin for an agent that has no stdin path —
+     * copilot requires the prompt as its `-p` value.
      */
     promptViaStdin?: boolean;
     /** Optional debug-event sink; callers own how/where events get logged. */

package/dist/src/agent-runner.js

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { findBinary, resolveSpawn, spawnSpec } from './lib/binary-launch.js';
 export { AGENT_NAMES, DEFAULT_AGENT_NAME, isAgentName } from './agent-names.js';
 const VALID_SELECT_TOOL_NAMES = new Set(['select_component', 'reject_component']);
 function findJsonObjectEnd(line) {
@@ -355,15 +356,62 @@ function codexBedrockConfigArgs() {
     const region = process.env.AWS_REGION?.trim() || process.env.AWS_DEFAULT_REGION?.trim() || DEFAULT_CODEX_BEDROCK_REGION;
     return ['-c', 'model_provider=amazon-bedrock', '-c', `model_providers.amazon-bedrock.region=${region}`];
 }
+/**
+ * Agents that can read the prompt from stdin instead of argv.
+ *
+ * copilot cannot: its `-p` flag requires the prompt as the flag's value (see
+ * buildArgs), so there is nowhere for stdin to go.
+ */
+const STDIN_CAPABLE_AGENTS = new Set(['claude', 'codex', 'opencode', 'cursor']);
+export function agentSupportsStdinPrompt(agent) {
+    return STDIN_CAPABLE_AGENTS.has(agent);
+}
+/**
+ * Windows caps a command line at 8191 characters through cmd.exe, and 32767 in
+ * CreateProcess. Our skill prompts are far larger than both — generate-components
+ * alone is ~50KB — so passing one as an argv positional cannot work there. POSIX
+ * is far more generous (ARG_MAX ~1MB on macOS) but not unlimited.
+ *
+ * Kept deliberately low: stdin is the better path for any prompt of real size, and
+ * there is no benefit to argv beyond the few agents that require it.
+ */
+const ARGV_PROMPT_LIMIT = 4096;
+/**
+ * Decide how to deliver the prompt.
+ *
+ * Prefer stdin whenever the agent supports it and the prompt is large enough for
+ * argv limits to matter. This is what makes `generate components` work on Windows,
+ * and it removes a latent ARG_MAX failure on macOS as the skills grow.
+ *
+ * Exported so callers can detect the case that has no answer: a large prompt for an
+ * agent that can only accept argv.
+ */
+export function shouldUseStdinPrompt(agent, prompt) {
+    return agentSupportsStdinPrompt(agent) && prompt.length > ARGV_PROMPT_LIMIT;
+}
+/** True when the prompt cannot be delivered to this agent on this platform. */
+export function promptExceedsArgvLimit(agent, prompt, platform = process.platform) {
+    if (agentSupportsStdinPrompt(agent))
+        return false;
+    // 8191 is the cmd.exe ceiling; every Windows launch of a .cmd shim goes through it.
+    return platform === 'win32' && prompt.length > 8191;
+}
 export function buildArgs(agent, prompt, model, promptViaStdin = false, bedrock = false) {
     // codex with no configured model resolves to undefined — omit --model
     // entirely so the CLI picks its own account-compatible default.
     const resolvedModel = resolveAgentModel(agent, model, bedrock);
     const modelArg = resolvedModel ? ['--model', resolvedModel] : [];
-    // When the prompt is delivered on stdin, omit it from argv — a large prompt
-    // as a command-line argument overflows ARG_MAX (spawn E2BIG). All four CLIs
-    // read the prompt from stdin when it isn't passed positionally.
-    const promptArg = promptViaStdin ? [] : [prompt];
+    // Ignore a stdin request for an agent that has no stdin path. copilot's `-p`
+    // takes the prompt as its value, so honouring the request would emit a bare
+    // `-p` and silently drop the prompt. runAgent already avoids asking, but keep
+    // the guard here so the function can't be misused.
+    const useStdin = promptViaStdin && agentSupportsStdinPrompt(agent);
+    // When the prompt is delivered on stdin, omit it from argv — a large prompt as
+    // a command-line argument overflows ARG_MAX on POSIX (E2BIG) and cannot be
+    // passed at all on Windows, whose command line caps at 8191 characters through
+    // cmd.exe. These CLIs read the prompt from stdin when it isn't passed
+    // positionally.
+    const promptArg = useStdin ? [] : [prompt];
     switch (agent) {
         case 'claude':
             return ['--print', ...modelArg, ...promptArg];
@@ -406,7 +454,11 @@ export async function runAgent(options) {
     // call sites that forget to thread the flag through by hand.
     const bedrock = options.bedrock ?? process.env.EDS_BEDROCK === '1';
     const binary = resolveBinary(agent);
-    const useStdin = !!promptViaStdin;
+    // Send a large prompt on stdin even when the caller didn't ask: a ~50KB skill
+    // prompt exceeds every Windows command-line limit, so argv simply cannot carry
+    // it. Honour an explicit promptViaStdin for smaller prompts, but never route to
+    // stdin for an agent that can't read it (copilot).
+    const useStdin = agentSupportsStdinPrompt(agent) && (!!promptViaStdin || shouldUseStdinPrompt(agent, prompt));
     const args = buildArgs(agent, prompt, model, useStdin, bedrock);
     const startedAt = Date.now();
     onDebugEvent?.('run.start', {
@@ -420,8 +472,14 @@ export async function runAgent(options) {
     });
     return new Promise((resolve) => {
         const bedrockEnv = bedrock ? BEDROCK_ENV_BY_AGENT[agent] : undefined;
-        const child = spawn(binary, args, {
+        // On Windows the agent CLIs are `.cmd` shims, which spawn can neither find
+        // (libuv ignores PATHEXT) nor start directly (EINVAL). Resolve and wrap.
+        // Falling back to the bare name keeps the existing 'error' handling path,
+        // which reports a missing binary far better than throwing from here.
+        const launch = resolveSpawn(binary, args) ?? { command: binary, args };
+        const child = spawn(launch.command, launch.args, {
             stdio: ['pipe', 'pipe', 'pipe'],
+            ...(launch.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
             ...(bedrockEnv ? { env: { ...process.env, ...bedrockEnv } } : {}),
         });
         if (useStdin && child.stdin) {
@@ -477,19 +535,12 @@ export async function runAgent(options) {
 export async function checkAgentAuth(agent) {
     const binary = resolveBinary(agent);
     // Verify the selected agent's binary exists first — for EVERY agent, not
-    // just claude. When `binary` is an absolute path (e.g. set via
-    // EDS_AGENT_BINARY_<AGENT>=/opt/custom/bin), `which` on some shells doesn't
-    // resolve it — check the filesystem directly for absolute paths, and fall
-    // back to `which` for bare names on $PATH.
-    const binaryExists = await new Promise((resolve) => {
-        if (binary.startsWith('/')) {
-            import('node:fs/promises').then((fs) => fs.access(binary).then(() => resolve(true), () => resolve(false)));
-            return;
-        }
-        const child = spawn('which', [binary], { stdio: 'ignore' });
-        child.on('close', (code) => resolve(code === 0));
-    });
-    if (!binaryExists)
+    // just claude. findBinary handles both shapes this has to cover: an absolute
+    // path (e.g. EDS_AGENT_BINARY_<AGENT>=/opt/custom/bin, or C:\tools\claude.cmd)
+    // and a bare name on PATH. It replaces shelling out to `which`, which doesn't
+    // exist on Windows, and recognises Windows `.cmd` shims.
+    const resolvedBinary = findBinary(binary);
+    if (!resolvedBinary)
         return 'not-found';
     // Only Claude exposes `auth status --json`. Non-Claude agents are considered
     // authenticated once their binary is present — never gate them on claude
@@ -499,8 +550,11 @@ export async function checkAgentAuth(agent) {
     // Use `claude auth status` — fast, no API call, works regardless of which
     // auth provider (direct, Bedrock, Vertex) or whether AWS_PROFILE is set.
     return new Promise((resolve) => {
-        const child = spawn(binary, ['auth', 'status', '--json'], {
+        // Already resolved above, so wrap the real path rather than looking it up again.
+        const launch = spawnSpec(resolvedBinary, ['auth', 'status', '--json']);
+        const child = spawn(launch.command, launch.args, {
             stdio: ['ignore', 'pipe', 'pipe'],
+            ...(launch.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
         });
         let stdout = '';
         let done = false;

package/dist/src/index.d.ts

@@ -1,9 +1,11 @@
 export { AGENT_NAMES, DEFAULT_AGENT_NAME, isAgentName } from './agent-names.js';
 export type { AgentName } from './agent-names.js';
-export { agentSupportsBedrock, buildArgs, checkAgentAuth, describeAgentFailure, extractSentinelOutput, parseMapTokenPropToolCallLines, parseSelectToolCallLines, parseTokenToolCallLines, parseToolCallLines, resolveAgentModel, resolveBinary, runAgent, } from './agent-runner.js';
+export { agentSupportsBedrock, agentSupportsStdinPrompt, buildArgs, checkAgentAuth, describeAgentFailure, extractSentinelOutput, parseMapTokenPropToolCallLines, parseSelectToolCallLines, parseTokenToolCallLines, parseToolCallLines, promptExceedsArgvLimit, resolveAgentModel, resolveBinary, runAgent, shouldUseStdinPrompt, } from './agent-runner.js';
 export type { AgentAuthStatus, AgentDebugEvent, AgentRunResult, ClassifyComponentCall, ClassifyPropCall, ClassifySlotCall, ExcludePropCall, MapTokenPropCall, ParsedMapTokenPropToolCalls, ParsedSelectToolCalls, ParsedTokenToolCalls, ParsedToolCalls, RejectComponentCall, SelectComponentCall, SelectToolCall, SetGroupCall, SetTokenCall, ToolCall, TokenToolCall, } from './agent-runner.js';
 export { createLocalCliAgentInvoker } from './agent-invoker.js';
 export type { AgentInvoker, CreateLocalCliAgentInvokerOptions, InvokeAgentOptions } from './agent-invoker.js';
 export { buildPrompt, formatCustomPromptBanner, resolveSkillPath } from './prompt-builder.js';
 export type { ComponentSourceRef, GeneratedCdf, Mode, PromptOptions, Skill } from './prompt-builder.js';
 export { formatGenerateProgressLine } from './progress.js';
+export { binaryExists, findBinary, resolveSpawn, spawnSpec } from './lib/binary-launch.js';
+export type { SpawnSpec } from './lib/binary-launch.js';

package/dist/src/index.js

@@ -1,10 +1,12 @@
 // Agent identity
 export { AGENT_NAMES, DEFAULT_AGENT_NAME, isAgentName } from './agent-names.js';
 // Agent invocation (low-level)
-export { agentSupportsBedrock, buildArgs, checkAgentAuth, describeAgentFailure, extractSentinelOutput, parseMapTokenPropToolCallLines, parseSelectToolCallLines, parseTokenToolCallLines, parseToolCallLines, resolveAgentModel, resolveBinary, runAgent, } from './agent-runner.js';
+export { agentSupportsBedrock, agentSupportsStdinPrompt, buildArgs, checkAgentAuth, describeAgentFailure, extractSentinelOutput, parseMapTokenPropToolCallLines, parseSelectToolCallLines, parseTokenToolCallLines, parseToolCallLines, promptExceedsArgvLimit, resolveAgentModel, resolveBinary, runAgent, shouldUseStdinPrompt, } from './agent-runner.js';
 // Agent invocation (interface)
 export { createLocalCliAgentInvoker } from './agent-invoker.js';
 // Prompt building
 export { buildPrompt, formatCustomPromptBanner, resolveSkillPath } from './prompt-builder.js';
 // Progress reporting
 export { formatGenerateProgressLine } from './progress.js';
+// Cross-platform binary lookup and launch (Windows .cmd shims, PATHEXT)
+export { binaryExists, findBinary, resolveSpawn, spawnSpec } from './lib/binary-launch.js';

package/dist/src/lib/binary-launch.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Resolve a command to an absolute path, or null when it isn't on PATH.
+ *
+ * Replaces shelling out to `which`, which doesn't exist on Windows. An absolute
+ * path is checked directly — on Windows `which` wouldn't resolve one anyway, and
+ * `isAbsolute` recognises `C:\...` where a `startsWith('/')` test does not.
+ */
+export declare function findBinary(binary: string, platform?: NodeJS.Platform): string | null;
+/** True when `binary` resolves to something executable. */
+export declare function binaryExists(binary: string, platform?: NodeJS.Platform): boolean;
+export type SpawnSpec = {
+    command: string;
+    args: string[];
+    /** Set when `args` are pre-quoted and Node must pass them through untouched. */
+    windowsVerbatimArguments?: boolean;
+};
+/**
+ * Build the argv for launching an already-resolved executable.
+ *
+ * Off Windows, and for a real `.exe`/`.com`, this passes straight through. A
+ * Windows `.cmd`/`.bat` is wrapped in `cmd.exe /d /s /c "..."`, which is the only
+ * way to start one.
+ *
+ * Quoting note: the wrapped form re-parses the command line, so arguments are
+ * quoted here. That quoting is deliberately simple — double quotes are doubled
+ * and each argument wrapped — which is sufficient because the arguments reaching
+ * this path are our own flags and model names. Large or user-controlled text
+ * (agent prompts) travels over stdin instead, and must keep doing so. If
+ * user-controlled values ever need to go through argv here, replace this with
+ * `cross-spawn` rather than extending the escaping: it implements the full
+ * cmd.exe rules, including the double-escaping that `node_modules/.bin` shims
+ * require.
+ */
+export declare function spawnSpec(resolved: string, args: string[], platform?: NodeJS.Platform): SpawnSpec;
+/**
+ * Resolve a command and build its launch spec in one step. Returns null when the
+ * command isn't installed, so callers can report that distinctly from a failure
+ * to run.
+ */
+export declare function resolveSpawn(binary: string, args: string[], platform?: NodeJS.Platform): SpawnSpec | null;

package/dist/src/lib/binary-launch.js

@@ -0,0 +1,115 @@
+/**
+ * Cross-platform binary lookup and launch.
+ *
+ * Two separate Windows problems live here, and they need different fixes:
+ *
+ *  1. LOOKUP. libuv's spawn only tries `.com` and `.exe` when resolving a bare
+ *     command name against PATH — it ignores PATHEXT. Every tool installed via
+ *     npm (`claude`, `codex`, `pnpm`) is a `.cmd` shim on Windows, so a bare
+ *     name resolves to nothing and spawn fails with ENOENT. `findBinary` walks
+ *     PATH itself and tries the Windows executable extensions.
+ *
+ *  2. LAUNCH. Even with the full path, Node refuses to start a `.bat`/`.cmd`
+ *     directly — it throws EINVAL (a deliberate guard added for CVE-2024-27980).
+ *     Such a file has to run through `cmd.exe /d /s /c`. `spawnSpec` builds that
+ *     argv.
+ *
+ * Both take `platform` as an argument so tests can assert Windows behaviour
+ * while running on macOS or Linux.
+ */
+import { accessSync, constants } from 'node:fs';
+import { delimiter, isAbsolute, join } from 'node:path';
+/**
+ * Executable suffixes to try for a bare command name. The POSIX case is a
+ * single empty string: the name is already the whole filename.
+ */
+function executableExtensions(platform) {
+    return platform === 'win32' ? ['.exe', '.cmd', '.bat', '.com'] : [''];
+}
+/**
+ * Resolve a command to an absolute path, or null when it isn't on PATH.
+ *
+ * Replaces shelling out to `which`, which doesn't exist on Windows. An absolute
+ * path is checked directly — on Windows `which` wouldn't resolve one anyway, and
+ * `isAbsolute` recognises `C:\...` where a `startsWith('/')` test does not.
+ */
+export function findBinary(binary, platform = process.platform) {
+    const extensions = executableExtensions(platform);
+    if (isAbsolute(binary)) {
+        // An explicit path may already carry its extension, or (on Windows) omit it.
+        for (const extension of ['', ...extensions]) {
+            try {
+                accessSync(binary + extension, constants.F_OK);
+                return binary + extension;
+            }
+            catch {
+                continue;
+            }
+        }
+        return null;
+    }
+    for (const directory of (process.env['PATH'] ?? '').split(delimiter)) {
+        // Skip empty and relative PATH entries: resolving a command against the cwd
+        // would make the result depend on where the CLI happens to be run from.
+        if (!directory || !isAbsolute(directory))
+            continue;
+        for (const extension of extensions) {
+            const candidate = join(directory, binary + extension);
+            try {
+                accessSync(candidate, constants.X_OK);
+                return candidate;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return null;
+}
+/** True when `binary` resolves to something executable. */
+export function binaryExists(binary, platform = process.platform) {
+    return findBinary(binary, platform) !== null;
+}
+/**
+ * Build the argv for launching an already-resolved executable.
+ *
+ * Off Windows, and for a real `.exe`/`.com`, this passes straight through. A
+ * Windows `.cmd`/`.bat` is wrapped in `cmd.exe /d /s /c "..."`, which is the only
+ * way to start one.
+ *
+ * Quoting note: the wrapped form re-parses the command line, so arguments are
+ * quoted here. That quoting is deliberately simple — double quotes are doubled
+ * and each argument wrapped — which is sufficient because the arguments reaching
+ * this path are our own flags and model names. Large or user-controlled text
+ * (agent prompts) travels over stdin instead, and must keep doing so. If
+ * user-controlled values ever need to go through argv here, replace this with
+ * `cross-spawn` rather than extending the escaping: it implements the full
+ * cmd.exe rules, including the double-escaping that `node_modules/.bin` shims
+ * require.
+ */
+export function spawnSpec(resolved, args, platform = process.platform) {
+    if (platform !== 'win32' || /\.(exe|com)$/i.test(resolved)) {
+        return { command: resolved, args };
+    }
+    // `||` not `??`: an empty ComSpec is as unusable as an absent one.
+    const shell = process.env['ComSpec'] || 'cmd.exe';
+    const quote = (value) => `"${value.replace(/"/g, '""')}"`;
+    const commandLine = [resolved, ...args].map(quote).join(' ');
+    return {
+        command: shell,
+        // /d skips AutoRun scripts, /s keeps the outer quotes intact, /c runs and exits.
+        args: ['/d', '/s', '/c', `"${commandLine}"`],
+        windowsVerbatimArguments: true,
+    };
+}
+/**
+ * Resolve a command and build its launch spec in one step. Returns null when the
+ * command isn't installed, so callers can report that distinctly from a failure
+ * to run.
+ */
+export function resolveSpawn(binary, args, platform = process.platform) {
+    const resolved = findBinary(binary, platform);
+    if (!resolved)
+        return null;
+    return spawnSpec(resolved, args, platform);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-generation",
-  "version": "2.34.1-dev-build-cafcfc3.0",
+  "version": "2.34.1-dev-build-928f202.0",
   "description": "Agent-invocation and skill-prompt engine for the Contentful Experience Design System SDK",
   "license": "MIT",
   "type": "module",
@@ -22,7 +22,7 @@
     "skills/"
   ],
   "dependencies": {
-    "@contentful/experience-design-system-types": "2.34.1-dev-build-cafcfc3.0"
+    "@contentful/experience-design-system-types": "2.34.1-dev-build-928f202.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.4",