@hienlh/ppm 0.8.6 → 0.8.8

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.8.7] - 2026-03-23
+
+### Fixed
+- **Auth env priority chain**: Properly resolve auth env vars with priority: PPM accounts > project `.env` > shell env. Previously project `.env` vars were neutralized (set empty) instead of parsed and used as overrides.
+- **Env var diagnostics in timeout/error messages**: When SDK hangs or returns `unknown` error, error message guides user to check `ANTHROPIC_API_KEY`/`ANTHROPIC_BASE_URL` env vars with exact debug commands
+- **Auth source logging**: Log which source each auth var comes from (project .env vs shell env) — helps diagnose SDK hangs
+
 ## [0.8.6] - 2026-03-23
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",

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

@@ -50,40 +50,67 @@ export class ClaudeAgentSdkProvider implements AIProvider {
   /** Fork source: ppmSessionId → sourceSessionId (used on first message to fork) */
   private forkSources = new Map<string, string>();
 
-  /** Env vars to neutralize — only if project .env contains them (prevents .env poisoning) */
-  private readonly SENSITIVE_ENV_KEYS = ["ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN"];
+  /** Auth-related env keys — priority: account > project .env > shell env */
+  private readonly AUTH_ENV_KEYS = ["ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN"];
 
-  private getProjectEnvOverrides(projectPath?: string): Record<string, string> {
+  /**
+   * Parse project .env file and extract auth-related values.
+   * Returns actual values (not neutralized) so they can override shell env.
+   */
+  private parseProjectEnv(projectPath?: string): Record<string, string> {
     if (!projectPath) return {};
     try {
       const envPath = resolve(projectPath, ".env");
       if (!existsSync(envPath)) return {};
       const content = readFileSync(envPath, "utf-8");
-      const overrides: Record<string, string> = {};
-      for (const key of this.SENSITIVE_ENV_KEYS) {
-        if (content.includes(key)) {
-          overrides[key] = "";
-          console.log(`[sdk] Neutralizing ${key} from project .env (prevents poisoning)`);
+      const parsed: Record<string, string> = {};
+      for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) continue;
+        const eqIdx = trimmed.indexOf("=");
+        if (eqIdx < 0) continue;
+        const key = trimmed.slice(0, eqIdx).trim();
+        if (!this.AUTH_ENV_KEYS.includes(key)) continue;
+        // Strip surrounding quotes
+        let val = trimmed.slice(eqIdx + 1).trim();
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+          val = val.slice(1, -1);
         }
+        parsed[key] = val;
       }
-      return overrides;
+      return parsed;
     } catch { return {}; }
   }
 
   /**
    * Build env for SDK query.
-   * If account mode: detect token type and inject the correct env var.
-   *   - OAuth tokens (sk-ant-oat*) → CLAUDE_CODE_OAUTH_TOKEN (SDK reads this for subscription auth)
-   *   - API keys (sk-ant-api* or other) → ANTHROPIC_API_KEY
-   * Otherwise: pass through existing env (backward compatible).
+   * Priority: PPM accounts > project .env > shell env.
+   *   - Account mode: inject account token, neutralize conflicting vars.
+   *     TODO: support base_url from PPM AI settings.
+   *   - No account: project .env overrides shell env for auth vars.
    */
   private buildQueryEnv(
     projectPath: string | undefined,
     account: { id: string; accessToken: string } | null,
   ): Record<string, string | undefined> {
-    const base = { ...process.env, ...this.getProjectEnvOverrides(projectPath) };
+    const projectEnv = this.parseProjectEnv(projectPath);
+    // Merge: shell env ← project .env (project wins)
+    const base = { ...process.env, ...projectEnv };
+
+    // Log auth source for diagnostics
+    for (const key of this.AUTH_ENV_KEYS) {
+      if (projectEnv[key]) {
+        console.log(`[sdk] ${key} from project .env (length=${projectEnv[key].length})`);
+      } else if (process.env[key]) {
+        console.log(`[sdk] ${key} from shell env (length=${process.env[key]!.length})`);
+      }
+    }
+
     if (!account) return base;
+
+    // Account mode: account token takes highest priority
     const isOAuthToken = account.accessToken.startsWith("sk-ant-oat");
+    // TODO: support base_url from PPM AI provider settings
     if (isOAuthToken) {
       return {
         ...base,
@@ -813,7 +840,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
               rate_limit: "Rate limited by the API. Please wait and try again.",
               invalid_request: "Invalid request sent to the API.",
               server_error: "Anthropic API server error. Try again shortly.",
-              unknown: `API error in project "${effectiveCwd}". Debug: run \`cd ${effectiveCwd} && claude -p "hi"\` in your terminal. If that also fails, the issue is Claude CLI auth or project config (.claude/ folder). Try: 1) \`claude login\`, 2) Remove .claude/settings.local.json, 3) Create a new chat session.`,
+              unknown: `API error in project "${effectiveCwd}". Debug:\n1. Run: \`cd ${effectiveCwd} && claude -p "hi"\`\n2. Check env: \`echo $ANTHROPIC_API_KEY $ANTHROPIC_BASE_URL\` — stale/invalid keys cause this\n3. Try: \`ANTHROPIC_API_KEY="" ANTHROPIC_BASE_URL="" claude -p "hi"\`\n4. Refresh auth: \`claude login\``,
             };
             const hint = errorHints[assistantError] ?? `API error: ${assistantError}`;
             yield { type: "error", message: hint };

package/src/server/ws/chat.ts

@@ -138,7 +138,7 @@ async function runStreamLoop(sessionId: string, providerId: string, content: str
         const debugCmd = projectPath ? `cd ${projectPath} && claude -p "hi"` : `claude -p "hi"`;
         safeSend(sessionId, {
           type: "error",
-          message: `Claude SDK timed out after ${elapsed}s for project "${projectPath || "(no project)"}".${wslHint}\n\nDebug steps:\n1. Run in your terminal: \`${debugCmd}\`\n2. Check for hanging hooks/MCP servers: \`cat ${projectPath}/.claude/settings.local.json\`\n3. Try removing project Claude config: \`mv ${projectPath}/.claude ${projectPath}/.claude.bak\`\n4. If none of the above helps, try: \`claude login\` to refresh auth`,
+          message: `Claude SDK timed out after ${elapsed}s for project "${projectPath || "(no project)"}".${wslHint}\n\nDebug steps:\n1. Run: \`${debugCmd}\` — if it also hangs, the issue is your Claude CLI environment\n2. Check env vars: \`echo $ANTHROPIC_API_KEY $ANTHROPIC_BASE_URL\` — stale/invalid keys cause silent hang\n3. Try with env cleared: \`ANTHROPIC_API_KEY="" ANTHROPIC_BASE_URL="" ${debugCmd}\`\n4. Check hooks/MCP: \`cat ${projectPath}/.claude/settings.local.json\`\n5. Refresh auth: \`claude login\``,
         });
         abortController.abort();
         return;