@hienlh/ppm 0.5.13 → 0.5.14

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.5.14] - 2026-03-18
+
+### Fixed
+- **Windows: `claude` .cmd resolution** — `Bun.spawn` can't resolve `.cmd` wrapper scripts (npm globals) directly. Now spawns via `cmd /c claude` so Windows shell resolves PATH correctly
+
 ## [0.5.13] - 2026-03-18
 
 ### Fixed

package/docs/lessons-learned.md

@@ -42,6 +42,25 @@ settingSources: [],
 
 ---
 
+### Windows: SDK query() hangs — direct CLI fallback
+
+**Problem**: On Windows, Bun subprocess stdin pipe buffering prevents SDK `query()` from working. Data written to stdin stays in buffer, never reaches the CLI child process → async iterator yields zero events → hangs forever.
+
+**Root cause**: Python SDK had identical issue (#208), fixed with `asyncio.StreamWriter.drain()`. TypeScript SDK lacks this fix.
+
+**Workaround**: Bypass SDK on Windows — spawn `claude -p --verbose --output-format stream-json` directly. CLI stream-json output uses same event types as SDK (`system/init`, `assistant`, `result`, `rate_limit_event`), so existing event handling works unchanged.
+
+**Caveat**: CLI stream-json doesn't emit per-token `stream_event` deltas. Provider synthesizes them by chunking `assistant` message text into ~30-char pieces as synthetic `content_block_delta` events.
+
+**Tracking**:
+- Python SDK #208 (FIXED): stdin drain fix
+- TS SDK #44 (OPEN): query() yields zero events
+- TS SDK #64 (OPEN): bash tool hangs on empty output
+
+**File**: `src/providers/claude-agent-sdk.ts` — `queryDirectCli()` method
+
+---
+
 ## WebSocket Chat Architecture
 
 ### Event flow: SDK → Provider → WS → Frontend

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.5.13",
+  "version": "0.5.14",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "module": "src/index.ts",
   "type": "module",

package/src/providers/claude-agent-sdk.ts

@@ -92,6 +92,17 @@ export class ClaudeAgentSdkProvider implements AIProvider {
    * Direct CLI fallback for Windows — spawns `claude -p` with stream-json output.
    * Workaround for Bun + Windows SDK subprocess pipe buffering issue.
    * Returns an async generator yielding the same event types as SDK query().
+   *
+   * TODO: Remove this fallback when TypeScript SDK fixes Windows stdin pipe buffering.
+   * Tracking issues:
+   *   - Python SDK #208 (FIXED): https://github.com/anthropics/claude-agent-sdk-python/issues/208
+   *     Fix: stdin drain() after writes — TypeScript SDK lacks equivalent fix.
+   *   - TS SDK #44 (OPEN): https://github.com/anthropics/claude-agent-sdk-typescript/issues/44
+   *     query() yields zero events for 3+ minutes on Windows.
+   *   - TS SDK #64 (OPEN): https://github.com/anthropics/claude-agent-sdk-typescript/issues/64
+   *     Bash tool hangs on empty output — related pipe/EOF handling issue.
+   * When these are resolved, switch back to SDK query() by removing the
+   * `useDirectCli` branch in sendMessage() and deleting this method.
    */
   private async *queryDirectCli(opts: {
     prompt: string;
@@ -119,10 +130,15 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     // Permission mode
     args.push("--permission-mode", "bypassPermissions", "--dangerously-skip-permissions");
 
-    console.log(`[sdk-cli] spawning: claude ${args.slice(0, 6).join(" ")}... cwd=${opts.cwd}`);
+    // On Windows, `claude` is a .cmd wrapper (npm global) — Bun.spawn can't resolve .cmd
+    // files directly. Use `cmd /c` to let the Windows shell find it via PATH.
+    const cmd = process.platform === "win32"
+      ? ["cmd", "/c", "claude", ...args]
+      : ["claude", ...args];
+    console.log(`[sdk-cli] spawning: ${cmd.slice(0, 7).join(" ")}... cwd=${opts.cwd}`);
 
     const proc = Bun.spawn({
-      cmd: ["claude", ...args],
+      cmd,
       cwd: opts.cwd,
       stdout: "pipe",
       stderr: "pipe",
@@ -424,7 +440,8 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       const queryEnv = { ...process.env, ...this.getProjectEnvOverrides(meta.projectPath) };
       console.log(`[sdk] query: session=${sessionId} sdkId=${sdkId} isFirst=${isFirstMessage} fork=${shouldFork} cwd=${effectiveCwd} platform=${process.platform}`);
 
-      // On Windows, use direct CLI fallback (SDK query() hangs due to Bun subprocess pipe buffering)
+      // TODO: Remove when TS SDK fixes Windows stdin pipe buffering (see queryDirectCli() JSDoc for tracking issues)
+      // On Windows, SDK query() hangs because Bun subprocess stdin pipe never flushes to child process.
       const useDirectCli = process.platform === "win32";
       let eventSource: AsyncIterable<any>;