knoxis-helper 1.0.0

package/lib/knoxis-pair-program.js

@@ -0,0 +1,513 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+
+function parseArgs(argv) {
+  const args = {};
+  const multi = {};
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (!next || next.startsWith('--')) {
+        args[key] = true;
+      } else {
+        if (multi[key]) {
+          multi[key].push(next);
+        } else if (args[key]) {
+          multi[key] = [args[key], next];
+          delete args[key];
+        } else {
+          args[key] = next;
+        }
+        i++;
+      }
+    }
+  }
+  Object.entries(multi).forEach(([key, list]) => {
+    args[key] = list;
+  });
+  return args;
+}
+
+function decodeBase64(value) {
+  try {
+    return Buffer.from(value, 'base64').toString('utf8');
+  } catch (err) {
+    console.error('Failed to decode base64 value:', err.message);
+    process.exit(1);
+  }
+}
+
+function decodeJsonBase64(value, label) {
+  const decoded = decodeBase64(value);
+  try {
+    return JSON.parse(decoded);
+  } catch (err) {
+    console.error(`Failed to parse ${label} JSON: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+function commandExists(cmd) {
+  const detector = process.platform === 'win32' ? 'where' : 'which';
+  const result = spawnSync(detector, [cmd], { stdio: 'ignore' });
+  return result.status === 0;
+}
+
+// Resolve workspace name to path using knoxis registry
+function resolveWorkspacePath(nameOrPath) {
+  const os = require('os');
+
+  // Direct path - check if exists
+  if (fs.existsSync(nameOrPath)) {
+    return path.resolve(nameOrPath);
+  }
+
+  // Try knoxis workspace registry
+  const workspacesFile = path.join(os.homedir(), '.knoxis', 'workspaces.json');
+  if (fs.existsSync(workspacesFile)) {
+    try {
+      const workspaces = JSON.parse(fs.readFileSync(workspacesFile, 'utf8'));
+
+      // Exact match
+      if (workspaces[nameOrPath]) {
+        return workspaces[nameOrPath];
+      }
+
+      // Fuzzy match
+      const lower = nameOrPath.toLowerCase();
+      for (const [name, wsPath] of Object.entries(workspaces)) {
+        if (name.toLowerCase().includes(lower)) {
+          console.log(`Matched workspace: ${name} -> ${wsPath}`);
+          return wsPath;
+        }
+      }
+    } catch (e) {
+      // Fall through
+    }
+  }
+
+  return null;
+}
+
+function resolveAiProvider(preference) {
+  const normalized = (preference || 'auto').toLowerCase();
+  if (normalized === 'claude' && commandExists('claude')) {
+    return { cmd: 'claude', args: ['--dangerously-skip-permissions'], label: 'Claude Code' };
+  }
+  if (normalized === 'codex' && commandExists('codex')) {
+    return { cmd: 'codex', args: [], label: 'Codex' };
+  }
+  if (normalized === 'auto') {
+    if (commandExists('claude')) {
+      return { cmd: 'claude', args: ['--dangerously-skip-permissions'], label: 'Claude Code' };
+    }
+    if (commandExists('codex')) {
+      return { cmd: 'codex', args: [], label: 'Codex' };
+    }
+  }
+  console.error('No supported AI provider found. Install the Claude or Codex CLI and try again.');
+  process.exit(1);
+}
+
+function formatSection(title, body) {
+  const border = '-'.repeat(title.length + 4);
+  return `${border}\n| ${title} |\n${border}\n${body.trim()}\n`;
+}
+
+function toArray(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) {
+    const result = [];
+    value.forEach(item => {
+      result.push(...toArray(item));
+    });
+    return result;
+  }
+  return [value];
+}
+
+function gatherContext(workspace, inputs) {
+  const sections = [];
+  const labels = [];
+  const seen = new Set();
+
+  toArray(inputs).forEach(entry => {
+    if (typeof entry !== 'string') {
+      return;
+    }
+    const trimmed = entry.trim();
+    if (!trimmed) {
+      return;
+    }
+    const absolute = path.isAbsolute(trimmed) ? trimmed : path.join(workspace, trimmed);
+    if (!fs.existsSync(absolute)) {
+      return;
+    }
+    if (seen.has(absolute)) {
+      return;
+    }
+    seen.add(absolute);
+    const content = fs.readFileSync(absolute, 'utf8');
+    const title = path.relative(workspace, absolute) || path.basename(absolute);
+    labels.push(title);
+    sections.push(formatSection(title, content));
+  });
+
+  return { sections, labels };
+}
+
+function buildDefaultTemplates(stepInput) {
+  const defaults = [
+    {
+      key: 'understand',
+      title: 'Understanding',
+      template: ({ taskDescription }) => `Let's understand what we're working with before diving in.
+
+The task: ${taskDescription}
+
+First:
+1. Read the relevant code to understand the current state
+2. Identify what needs to change
+3. Note any potential issues or dependencies
+
+Share your understanding briefly. For any ambiguities, state your assumption and move on - do not ask questions.`
+    },
+    {
+      key: 'plan',
+      title: 'Planning',
+      template: ({ taskDescription }) => `Good. Now create a concrete implementation plan for: ${taskDescription}
+
+Plan requirements:
+1. What files need to be created or modified?
+2. What's the order of changes?
+3. What could go wrong?
+4. How will we verify it works?
+
+For any open questions from the previous step, make your best judgment call and note the decision. Do not ask - decide and move forward.`
+    },
+    {
+      key: 'implement',
+      title: 'Implementation',
+      template: ({ taskDescription }) => `Now implement the plan. Work through it step by step.
+
+Rules:
+- Make one logical change at a time
+- For any decisions or unknowns, pick the most standard approach and note your choice
+- If you flagged questions earlier, answer them yourself with reasonable defaults and proceed
+- Flag if you hit something truly blocking (missing credentials, broken dependencies)
+- Otherwise, keep building
+
+Start implementing now.`
+    },
+    {
+      key: 'verify',
+      title: 'Review',
+      template: () => `Let's review what we built.
+
+Quick checklist:
+- Does it solve the original problem?
+- Any edge cases we missed?
+- Is the code clean and following project patterns?
+- Anything we should test?
+
+Give me the summary and any follow-up recommendations.`
+    }
+  ];
+
+  if (!stepInput) {
+    return defaults;
+  }
+
+  const requested = (Array.isArray(stepInput) ? stepInput.join(',') : stepInput)
+    .split(',')
+    .map(s => s.trim().toLowerCase())
+    .filter(Boolean);
+
+  if (!requested.length) {
+    return defaults;
+  }
+
+  const resolved = [];
+  requested.forEach(key => {
+    const match = defaults.find(step => step.key === key);
+    if (match) {
+      resolved.push(match);
+    } else {
+      resolved.push({
+        key,
+        title: key.charAt(0).toUpperCase() + key.slice(1),
+        template: ({ taskDescription }) => `Directive (${key}): ${taskDescription}`
+      });
+    }
+  });
+
+  return resolved.length ? resolved : defaults;
+}
+
+function scheduleDefaultSteps(templates, taskDescription, agentLabel) {
+  const trimmedTask = taskDescription.trim();
+  return templates.map(template => ({
+    key: template.key,
+    title: template.title,
+    displayName: agentLabel,
+    persona: null,
+    instruction: template.template({ taskDescription: trimmedTask }),
+    contextPaths: [],
+    includeContext: false
+  }));
+}
+
+function buildPrompt(options) {
+  const {
+    systemIntro,
+    personaIntro,
+    conversation,
+    instructionLabel,
+    instructionTitle,
+    instruction,
+    includeContextBlock,
+    globalContext,
+    stepContext,
+    agentLabel
+  } = options;
+
+  const sections = [];
+
+  if (systemIntro) {
+    sections.push(systemIntro);
+  }
+
+  if (personaIntro) {
+    sections.push(personaIntro);
+  }
+
+  if (includeContextBlock && globalContext) {
+    sections.push(`Project context:\n${globalContext}`);
+  }
+
+  if (includeContextBlock && stepContext) {
+    sections.push(`Step-specific context:\n${stepContext}`);
+  }
+
+  if (conversation) {
+    sections.push(`Conversation so far:\n${conversation}`);
+  }
+
+  const heading = instructionTitle
+    ? `${instructionLabel} -> ${agentLabel} (${instructionTitle})`
+    : `${instructionLabel} -> ${agentLabel}`;
+
+  sections.push(`${heading}:\n${instruction}`);
+  sections.push(`${agentLabel}:`);
+
+  return sections.join('\n\n');
+}
+
+async function callAi(aiConfig, prompt, livePrinter) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(aiConfig.cmd, aiConfig.args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    let pendingLine = '';
+
+    proc.stdout.on('data', chunk => {
+      const text = chunk.toString();
+      stdout += text;
+      pendingLine += text;
+      let index;
+      while ((index = pendingLine.indexOf('\n')) !== -1) {
+        const line = pendingLine.slice(0, index);
+        pendingLine = pendingLine.slice(index + 1);
+        livePrinter(line);
+      }
+    });
+
+    proc.stderr.on('data', chunk => {
+      const text = chunk.toString();
+      stderr += text;
+    });
+
+    proc.on('close', code => {
+      if (pendingLine.length) {
+        livePrinter(pendingLine);
+        pendingLine = '';
+      }
+      if (code === 0) {
+        resolve(stdout.trim());
+      } else {
+        reject(new Error(stderr.trim() || `AI command exited with status ${code}`));
+      }
+    });
+
+    proc.stdin.write(prompt);
+    proc.stdin.end();
+  });
+}
+
+async function run() {
+  const args = parseArgs(process.argv);
+  const workspaceArg = args.workspace || args['workspace-dir'] || args['working-directory'] || args.w;
+
+  if (!workspaceArg) {
+    console.error('Missing required --workspace argument.');
+    console.error('Usage: knoxis-pair-program --workspace <name-or-path> --prompt "task"');
+    console.error('       knoxis-pair-program -w voice-backend --prompt "add authentication"');
+    process.exit(1);
+  }
+
+  // Resolve workspace (supports names from knoxis registry)
+  let workspace = resolveWorkspacePath(workspaceArg);
+  if (!workspace) {
+    // Maybe it's a new path to create
+    workspace = path.resolve(workspaceArg);
+    console.log(`Creating new workspace: ${workspace}`);
+  }
+
+  if (!fs.existsSync(workspace)) {
+    fs.mkdirSync(workspace, { recursive: true });
+  }
+
+  const timeline = args['timeline-base64'] ? decodeJsonBase64(args['timeline-base64'], 'timeline') : null;
+
+  let task = args['prompt-base64'] ? decodeBase64(args['prompt-base64']) : args.prompt;
+  if ((!task || !task.trim()) && timeline && typeof timeline.task === 'string') {
+    task = timeline.task;
+  }
+
+  if (!task || !task.trim()) {
+    console.error('A task prompt is required via --prompt, --prompt-base64, or timeline.task.');
+    process.exit(1);
+  }
+
+  task = task.trim();
+
+  const aiConfig = resolveAiProvider(args['ai-provider'] || args.provider);
+
+  const globalContextInputs = [];
+  if (args['context']) {
+    globalContextInputs.push(args['context']);
+  }
+  if (args['context-file']) {
+    globalContextInputs.push(args['context-file']);
+  }
+  if (timeline && Array.isArray(timeline.sharedContext)) {
+    globalContextInputs.push(timeline.sharedContext);
+  }
+
+  const globalContext = gatherContext(workspace, globalContextInputs);
+  const globalContextBlock = globalContext.sections.join('\n\n');
+
+  let scheduledSteps;
+  if (timeline && Array.isArray(timeline.steps) && timeline.steps.length) {
+    scheduledSteps = timeline.steps.map((step, index) => ({
+      key: step.key || `step-${index + 1}`,
+      title: step.title || '',
+      displayName: step.displayName || step.agentId || `Agent ${index + 1}`,
+      persona: step.persona || null,
+      instruction: typeof step.instruction === 'string' && step.instruction.trim().length
+        ? step.instruction
+        : `Proceed with the shared task: ${task}`,
+      contextPaths: step.contextFiles || [],
+      includeContext: Boolean(step.includeContext)
+    }));
+  } else {
+    const templates = buildDefaultTemplates(args['steps']);
+    scheduledSteps = scheduleDefaultSteps(templates, task, aiConfig.label);
+  }
+
+  if (!scheduledSteps.length) {
+    console.error('No steps configured for the pair programming session.');
+    process.exit(1);
+  }
+
+  console.log('==============================================');
+  console.log('Knoxis Pair Programming Session');
+  console.log(`Workspace: ${workspace}`);
+  console.log(`AI Partner: ${aiConfig.label}`);
+  console.log(`Task: ${task}`);
+  console.log('==============================================');
+  console.log('');
+
+  if (globalContext.labels.length) {
+    console.log(`Shared context files: ${globalContext.labels.join(', ')}`);
+    console.log('');
+  }
+
+  const history = [];
+  const conversationLines = () => history.map(entry => `${entry.role}: ${entry.content}`).join('\n\n');
+
+  const systemIntro = `You are a senior software developer pair programming with your colleague Knoxis.
+
+Your communication style:
+- Be direct and concise - no fluff or excessive politeness
+- Think out loud briefly before acting
+- Do NOT ask clarifying questions. Make your best engineering judgment and proceed.
+- If you need to choose between approaches, pick the most standard one and briefly note why.
+- Warn about potential issues or gotchas you notice
+- Suggest better approaches when you see them
+
+Your technical approach:
+- Read and understand existing code before making changes
+- Follow existing patterns in the codebase
+- Write clean, maintainable code
+- Consider edge cases and error handling
+- Don't over-engineer - solve the problem at hand
+- Leave the codebase better than you found it
+
+IMPORTANT: Work autonomously. Do not ask questions or wait for confirmation. Make decisions and implement.
+Only work inside the provided workspace and preserve user data.`;
+
+  for (const step of scheduledSteps) {
+    const stepContext = gatherContext(workspace, step.contextPaths);
+    if (stepContext.labels.length) {
+      console.log(`Step context for ${step.displayName}: ${stepContext.labels.join(', ')}`);
+      console.log('');
+    }
+
+    const titleSuffix = step.title ? ` (${step.title})` : '';
+    console.log(`Coordinator -> ${step.displayName}${titleSuffix}:`);
+    console.log(step.instruction);
+    console.log('');
+
+    history.push({ role: 'Coordinator', content: step.instruction });
+
+    console.log(`${step.displayName}:`);
+
+    const includeContext = history.length <= 1 || step.includeContext || stepContext.sections.length > 0;
+    const prompt = buildPrompt({
+      systemIntro,
+      personaIntro: step.persona,
+      conversation: conversationLines(),
+      instructionLabel: 'Coordinator',
+      instructionTitle: step.title,
+      instruction: step.instruction,
+      includeContextBlock: includeContext,
+      globalContext: globalContextBlock,
+      stepContext: stepContext.sections.join('\n\n'),
+      agentLabel: step.displayName
+    });
+
+    try {
+      const response = await callAi(aiConfig, prompt, line => {
+        console.log(`  ${line}`);
+      });
+      history.push({ role: step.displayName, content: response });
+      console.log('');
+    } catch (err) {
+      console.error(`Failed to complete step "${step.title || step.key}": ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  console.log('Session complete. Knoxis and the AI partner are standing by for further instructions.');
+}
+
+run().catch(err => {
+  console.error(err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "knoxis-helper",
+  "version": "1.0.0",
+  "description": "Local helper for Knoxis pair programming - connects your machine to Knoxis on qig.ai",
+  "bin": {
+    "knoxis-helper": "./bin/knoxis-helper.js"
+  },
+  "keywords": ["knoxis", "pair-programming", "claude", "qig"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "lib/"
+  ]
+}