knoxis-helper 1.4.7 → 1.5.0

package/bin/knoxis-helper.js

@@ -81,10 +81,25 @@ function ask(rl, question) {
  * Copy agent files to ~/.knoxis/agent/ so they persist across npx cache clears,
  * VPN changes, and reboots. Returns the stable path.
  */
+function copyDirRecursive(src, dest) {
+  if (!fs.existsSync(src)) return;
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDirRecursive(s, d);
+    else if (entry.isFile()) fs.copyFileSync(s, d);
+  }
+}
+
 function installAgentLocally(force) {
-  const sourceAgent = path.join(__dirname, '..', 'lib', 'knoxis-local-agent.js');
-  const sourcePairProgram = path.join(__dirname, '..', 'lib', 'knoxis-pair-program.js');
-  const sourceInteractivePair = path.join(__dirname, '..', 'lib', 'knoxis-interactive-pair.js');
+  const libDir = path.join(__dirname, '..', 'lib');
+  const sourceAgent = path.join(libDir, 'knoxis-local-agent.js');
+  const sourcePairProgram = path.join(libDir, 'knoxis-pair-program.js');
+  const sourceInteractivePair = path.join(libDir, 'knoxis-interactive-pair.js');
+  const sourceStateScaffold = path.join(libDir, 'state-scaffold.js');
+  const sourcePortalSync = path.join(libDir, 'portal-sync.js');
+  const sourceTemplatesDir = path.join(libDir, 'templates');
   const sourcePackage = path.join(__dirname, '..', 'package.json');
 
   if (!fs.existsSync(sourceAgent)) {
@@ -125,6 +140,21 @@ function installAgentLocally(force) {
     console.log('  Installed: knoxis-interactive-pair.js');
   }
 
+  if (fs.existsSync(sourceStateScaffold)) {
+    fs.copyFileSync(sourceStateScaffold, path.join(AGENT_DIR, 'state-scaffold.js'));
+    console.log('  Installed: state-scaffold.js');
+  }
+
+  if (fs.existsSync(sourcePortalSync)) {
+    fs.copyFileSync(sourcePortalSync, path.join(AGENT_DIR, 'portal-sync.js'));
+    console.log('  Installed: portal-sync.js');
+  }
+
+  if (fs.existsSync(sourceTemplatesDir)) {
+    copyDirRecursive(sourceTemplatesDir, path.join(AGENT_DIR, 'templates'));
+    console.log('  Installed: templates/');
+  }
+
   if (fs.existsSync(sourcePackage)) {
     fs.copyFileSync(sourcePackage, path.join(AGENT_DIR, 'package.json'));
   }

package/lib/knoxis-interactive-pair.js

@@ -193,15 +193,30 @@ function runClaudeTurn(message, isResume) {
       args.push('--session-id', SESSION_ID);
     }
 
-    // shell: true on Windows so the claude.cmd shim resolves via PATHEXT.
-    // Required since Node 18.20.2/20.12.2 (CVE-2024-27980) refuses to spawn
-    // .cmd/.bat files without it.
-    const proc = spawn('claude', args, {
-      cwd: process.cwd(),
-      env: process.env,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      shell: isWindows
-    });
+    // Windows: claude is usually claude.cmd (npm shim) or claude.exe.
+    // .cmd/.bat shims require going through cmd.exe (Node CVE-2024-27980).
+    // We can't just pass `shell: true` with an args array — that triggers
+    // DEP0190 in Node 22+ (args get concatenated into the shell command
+    // line without escaping). Instead, build the command line ourselves
+    // and pass it as a single string. Our args are static flags + a UUID
+    // (no whitespace, no quotes) so trivial space-quoting is sufficient.
+    let proc;
+    if (isWindows) {
+      const quote = a => /\s/.test(a) ? `"${a}"` : a;
+      const cmdLine = ['claude', ...args].map(quote).join(' ');
+      proc = spawn(cmdLine, [], {
+        cwd: process.cwd(),
+        env: process.env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        shell: true
+      });
+    } else {
+      proc = spawn('claude', args, {
+        cwd: process.cwd(),
+        env: process.env,
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+    }
 
     let stdout = '';
     let stderr = '';

package/lib/knoxis-local-agent.js

@@ -580,6 +580,47 @@ function resolveInteractiveScript() {
   return null;
 }
 
+// Resolve the kit-aware pair-program runner (used when caller specifies --mode)
+function resolvePairProgramScript() {
+  const candidates = [
+    path.join(__dirname, 'knoxis-pair-program.js'),
+    path.join(__dirname, '..', 'knoxis-pair-program.js'),
+    path.join(os.homedir(), '.knoxis', 'agent', 'knoxis-pair-program.js'),
+    path.join(__dirname, '..', '..', 'knoxis-pair-program.js'),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+const KIT_MODES = new Set(['kickoff', 'resume', 'session-end', 'recovery']);
+
+function buildPairProgramCommand({ scriptPath, workspace, mode, archetype, pattern, productSlug, projectSlug, taskPrompt, userId, workspaceId, taskIds }) {
+  const q = v => `"${escapeForDoubleQuotedShellArg(v)}"`;
+  // Mode/archetype/pattern are constrained to known short tokens — no need to quote.
+  // Slugs and paths can contain spaces or special chars — always quote.
+  const parts = [`node ${q(scriptPath)}`, `--workspace ${q(workspace)}`];
+  if (mode) parts.push(`--mode ${mode}`);
+  if (archetype) parts.push(`--archetype ${archetype}`);
+  if (pattern) parts.push(`--pattern ${pattern}`);
+  if (productSlug) parts.push(`--product-slug ${q(productSlug)}`);
+  if (projectSlug) parts.push(`--project-slug ${q(projectSlug)}`);
+  if (userId) parts.push(`--user-id ${q(userId)}`);
+  if (workspaceId) parts.push(`--workspace-id ${q(workspaceId)}`);
+  if (Array.isArray(taskIds)) {
+    for (const t of taskIds) {
+      if (t) parts.push(`--task-id ${q(t)}`);
+    }
+  }
+  if (taskPrompt && taskPrompt.length) {
+    // Use base64 to avoid shell-quoting hazards (newlines, quotes, backticks).
+    const b64 = Buffer.from(taskPrompt, 'utf8').toString('base64');
+    parts.push(`--prompt-base64 ${b64}`);
+  }
+  return parts.join(' ');
+}
+
 // Request handler
 async function handleRequest(req, res) {
   const parsedUrl = url.parse(req.url, true);
@@ -867,8 +908,22 @@ async function handleRequest(req, res) {
       const body = await parseBody(req);
       const { workspace, task, file, provider, headless, sessionId, claudeMdContent } = body;
       const interactive = body.interactive === true || body.interactive === 'true';
-
-      if (!task) {
+      const kitMode = typeof body.mode === 'string' && KIT_MODES.has(body.mode) ? body.mode : null;
+      const archetype = typeof body.archetype === 'string' ? body.archetype : null;
+      const pattern = typeof body.pattern === 'string' ? body.pattern : null;
+      const productSlug = typeof body.productSlug === 'string' ? body.productSlug : null;
+      const projectSlug = typeof body.projectSlug === 'string' ? body.projectSlug : null;
+      // QIG portal linkage — let session records get tied back to the user / workspace / tasks.
+      const portalUserId = typeof body.userId === 'string' ? body.userId : null;
+      const portalWorkspaceId = typeof body.workspaceId === 'string' ? body.workspaceId : null;
+      const portalTaskIds = Array.isArray(body.taskIds)
+        ? body.taskIds.filter(t => typeof t === 'string' && t)
+        : (typeof body.taskId === 'string' ? [body.taskId] : []);
+
+      // Kickoff and session-end modes don't strictly need a task — the kit prompt
+      // drives the interaction. For all other paths a task is still required.
+      const taskOptionalForMode = kitMode === 'kickoff' || kitMode === 'session-end';
+      if (!task && !taskOptionalForMode) {
         return sendJSON(res, 400, { success: false, error: 'Task description required' }, requestOrigin);
       }
 
@@ -895,16 +950,44 @@ async function handleRequest(req, res) {
         }
       }
 
-      // Write the actual task to a temp file
+      // Write the actual task to a temp file (used by single-shot and interactive paths)
       const promptFile = path.join(os.tmpdir(), `knoxis-task-${sessionId || Date.now()}.txt`);
-      const promptText = file ? `Working on file: ${file}\n\nTask: ${task}` : task;
-      fs.writeFileSync(promptFile, promptText, 'utf8');
+      const promptText = task ? (file ? `Working on file: ${file}\n\nTask: ${task}` : task) : '';
+      if (promptText) fs.writeFileSync(promptFile, promptText, 'utf8');
 
-      // Determine the command to run
+      // Determine the command to run.
       let command;
       let mode = 'single-shot';
 
-      if (interactive) {
+      // Route through knoxis-pair-program.js whenever it's installed — gives
+      // every task auto-scaffold, the standards systemIntro, auto-context, and
+      // portal-sync. Kit mode adds --mode; default mode runs the standard
+      // 4-step pipeline. Interactive (Groq) mode and the legacy claude-pipe
+      // fallback remain available when the runner isn't present.
+      const ppScript = resolvePairProgramScript();
+      if (kitMode && !ppScript) {
+        return sendJSON(res, 500, { success: false, error: 'knoxis-pair-program.js not found — reinstall knoxis-helper.' }, requestOrigin);
+      }
+
+      if (kitMode || (ppScript && !interactive && promptText)) {
+        command = buildPairProgramCommand({
+          scriptPath: ppScript,
+          workspace: workspaceDir,
+          mode: kitMode || null,
+          archetype,
+          pattern,
+          productSlug,
+          projectSlug,
+          taskPrompt: promptText,
+          userId: portalUserId,
+          workspaceId: portalWorkspaceId,
+          taskIds: portalTaskIds
+        });
+        mode = kitMode
+          ? `kit:${kitMode}${archetype ? `/${archetype}` : ''}${pattern ? `/${pattern}` : ''}`
+          : 'pair-program:default';
+        console.log(`🧰 ${kitMode ? 'Kit' : 'Pair-program (default pipeline)'}: ${mode}`);
+      } else if (interactive) {
         const scriptPath = resolveInteractiveScript();
         if (scriptPath) {
           // Interactive mode: multi-turn with Groq pair programmer
@@ -917,17 +1000,19 @@ async function handleRequest(req, res) {
           command = buildCatCommand(promptFile) + ' | claude --dangerously-skip-permissions';
         }
       } else {
-        // Standard single-shot mode: pipe task to Claude
+        // Legacy fallback when neither pair-program nor interactive scripts are installed.
         command = buildCatCommand(promptFile) + ' | claude --dangerously-skip-permissions';
       }
 
       if (headless) {
-        if (interactive && mode === 'interactive') {
-          // Headless interactive: run the script directly as a process
+        // Anything routed through pair-program.js or knoxis-interactive-pair.js
+        // is a script invocation — run the assembled command verbatim.
+        const isScriptInvocation = mode === 'interactive' || mode === 'pair-program:default' || (kitMode != null);
+        if (isScriptInvocation) {
           const result = await runHeadlessProcess({
             workspace: workspaceDir,
             command,
-            sessionLabel: sessionId || 'interactive-pair'
+            sessionLabel: sessionId || (kitMode ? `kit-${kitMode}` : (mode === 'interactive' ? 'interactive-pair' : 'pair-program'))
           });
           return sendJSON(res, result.success ? 200 : 500, { ...result, mode }, requestOrigin);
         }
@@ -956,10 +1041,15 @@ async function handleRequest(req, res) {
 
       return sendJSON(res, 200, {
         success: true,
-        message: interactive ? 'Interactive pair programming session started' : 'Pair programming session started',
+        message: kitMode ? `Pair programming session started (kit mode: ${kitMode})`
+          : interactive ? 'Interactive pair programming session started'
+          : 'Pair programming session started',
         mode,
+        kitMode: kitMode || null,
+        archetype: archetype || null,
+        pattern: pattern || null,
         workspace: workspaceDir,
-        task,
+        task: task || null,
         file: file || null
       }, requestOrigin);
     } catch (error) {
@@ -1338,8 +1428,37 @@ function connectRelayWebSocket() {
         }
 
         const interactive = msg.interactive === true;
-
-        if (taskPrompt) {
+        const kitMode = typeof msg.mode === 'string' && KIT_MODES.has(msg.mode) ? msg.mode : null;
+        const archetype = typeof msg.archetype === 'string' ? msg.archetype : null;
+        const pattern = typeof msg.pattern === 'string' ? msg.pattern : null;
+        const productSlug = typeof msg.productSlug === 'string' ? msg.productSlug : null;
+        const projectSlug = typeof msg.projectSlug === 'string' ? msg.projectSlug : null;
+        const portalUserId = typeof msg.userId === 'string' ? msg.userId : null;
+        const portalWorkspaceId = typeof msg.workspaceId === 'string' ? msg.workspaceId : null;
+        const portalTaskIds = Array.isArray(msg.taskIds)
+          ? msg.taskIds.filter(t => typeof t === 'string' && t)
+          : (typeof msg.taskId === 'string' ? [msg.taskId] : []);
+        const ppScript = resolvePairProgramScript();
+        const routeViaPairProgram = (kitMode || (ppScript && !interactive && taskPrompt));
+
+        if (routeViaPairProgram && ppScript) {
+          command = buildPairProgramCommand({
+            scriptPath: ppScript,
+            workspace: wsDir,
+            mode: kitMode || null,
+            archetype,
+            pattern,
+            productSlug,
+            projectSlug,
+            taskPrompt: taskPrompt || '',
+            userId: portalUserId,
+            workspaceId: portalWorkspaceId,
+            taskIds: portalTaskIds
+          });
+          console.log(`   🧰 ${kitMode ? `Kit mode: ${kitMode}` : 'Pair-program (default pipeline)'}${archetype ? `/${archetype}` : ''}${pattern ? `/${pattern}` : ''}`);
+        } else if (kitMode) {
+          console.warn(`   ⚠️ knoxis-pair-program.js not found — cannot run kit mode`);
+        } else if (taskPrompt) {
           promptFile = path.join(os.tmpdir(), `knoxis-task-${msg.requestId || Date.now()}.txt`);
           fs.writeFileSync(promptFile, taskPrompt, 'utf8');
 
@@ -1406,6 +1525,28 @@ function connectRelayWebSocket() {
         }
       } else if (msg.type === 'connected') {
         console.log(`🤝 Backend acknowledged: ${msg.message}`);
+      } else if (msg.type === 'portal_config') {
+        // Backend is auto-distributing the portal-sync token + URL so devs
+        // don't paste them by hand. Merge into ~/.knoxis/config.json so
+        // portal-sync.js picks them up on the next session save.
+        try {
+          ensureKnoxisDir();
+          const cfgPath = path.join(KNOXIS_DIR, 'config.json');
+          let existing = {};
+          try {
+            if (fs.existsSync(cfgPath)) existing = JSON.parse(fs.readFileSync(cfgPath, 'utf8')) || {};
+          } catch (_) {}
+          if (typeof msg.portalToken === 'string' && msg.portalToken) existing.portalToken = msg.portalToken;
+          if (typeof msg.portalUrl === 'string' && msg.portalUrl) existing.portalUrl = msg.portalUrl;
+          if (typeof msg.portalSessionsPath === 'string' && msg.portalSessionsPath) {
+            existing.portalSessionsPath = msg.portalSessionsPath;
+          }
+          fs.writeFileSync(cfgPath, JSON.stringify(existing, null, 2));
+          // Don't log the token itself.
+          console.log(`🔐 Portal-sync config received (token len ${(msg.portalToken || '').length})`);
+        } catch (cfgErr) {
+          console.warn(`⚠️ Failed to persist portal_config: ${cfgErr.message}`);
+        }
       }
     } catch (e) {
       console.error('❌ Relay message handling error:', e.message);