k0ntext 3.0.0

package/templates/base/tools/lib/placeholder.js

@@ -0,0 +1,201 @@
+/**
+ * Claude Context Engineering - Placeholder Replacement Engine
+ *
+ * Finds and replaces {{PLACEHOLDER}} patterns in template files.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logger } = require('./logger');
+
+/**
+ * Known placeholders with their descriptions
+ */
+const KNOWN_PLACEHOLDERS = {
+  // Project identity
+  PROJECT_NAME: { description: 'Project name', example: 'my-awesome-app' },
+  PROJECT_DESCRIPTION: { description: 'Brief project description', example: 'A web application for...' },
+  TECH_STACK: { description: 'Technologies used', example: 'Python 3.11, FastAPI, PostgreSQL' },
+  PRODUCTION_URL: { description: 'Production URL', example: 'https://api.example.com' },
+  PROJECT_STATUS: { description: 'Project status', example: 'Production' },
+
+  // URLs
+  API_URL: { description: 'API base URL', example: 'https://api.example.com/v1' },
+  REPO_URL: { description: 'Repository URL', example: 'https://github.com/user/repo' },
+  DEPLOYMENT_PLATFORM: { description: 'Where deployed', example: 'AWS ECS' },
+
+  // Commands
+  INSTALL_COMMAND: { description: 'Install dependencies command', example: 'npm install' },
+  DEV_START_COMMAND: { description: 'Start dev server command', example: 'npm run dev' },
+  TEST_COMMAND: { description: 'Run tests command', example: 'npm test' },
+  TEST_E2E_COMMAND: { description: 'Run E2E tests command', example: 'npm run test:e2e' },
+  TEST_COVERAGE_COMMAND: { description: 'Run coverage command', example: 'npm run coverage' },
+  MIGRATION_CREATE_COMMAND: { description: 'Create migration command', example: 'npm run db:migrate:create' },
+  MIGRATION_RUN_COMMAND: { description: 'Run migrations command', example: 'npm run db:migrate' },
+  DEPLOY_COMMAND: { description: 'Deploy command', example: 'npm run deploy' },
+
+  // Paths
+  MODELS_PATH: { description: 'Models directory path', example: 'src/models/' },
+  MIGRATIONS_PATH: { description: 'Migrations directory path', example: 'src/migrations/' },
+  CORE_FILES_LIST: { description: 'List of core files', example: '- src/services/\n- src/models/' },
+
+  // Patterns
+  CONFIG_SEARCH_PATTERN: { description: 'Config search grep pattern', example: 'grep -r "process.env" src/' },
+  URL_SEARCH_PATTERN: { description: 'URL search grep pattern', example: 'grep -rE "https?://" src/' },
+
+  // Architecture
+  ARCHITECTURE_DIAGRAM: { description: 'ASCII architecture diagram', example: '```\nClient → API → DB\n```' },
+  EXTERNAL_INTEGRATIONS_LIST: { description: 'List of external integrations', example: '- Stripe: payments\n- SendGrid: email' },
+
+  // Counts
+  WORKFLOWS_COUNT: { description: 'Number of workflows', example: '12' },
+  WORKFLOW_DOMAINS_COUNT: { description: 'Number of workflow domains', example: '5' },
+  CODE_DOMAINS_COUNT: { description: 'Number of code domains', example: '4' },
+  AGENTS_COUNT: { description: 'Number of agents', example: '6' },
+  COMMANDS_COUNT: { description: 'Number of commands', example: '5' },
+  INDEX_FILES_COUNT: { description: 'Number of index files', example: '25' },
+
+  // Meta
+  DATE: { description: 'Current date', example: '2025-12-06' },
+
+  // Quick references
+  DEBUGGING_QUICK_REFS: { description: 'Quick debug references', example: '[logs.md], [errors.md]' },
+  CRITICAL_URLS: { description: 'Critical URLs list', example: '- API: https://...\n- Admin: https://...' },
+  BUSINESS_CONSTANTS: { description: 'Business constants', example: '- MAX_USERS: 1000' },
+
+  // Gotchas
+  GOTCHA_CATEGORY_1: { description: 'First gotcha category', example: 'Authentication' },
+  GOTCHA_1_ITEMS: { description: 'First gotcha items', example: '- Token expiry: 24h' },
+  GOTCHA_CATEGORY_2: { description: 'Second gotcha category', example: 'Database' },
+  GOTCHA_2_ITEMS: { description: 'Second gotcha items', example: '- Connection pooling required' },
+
+  // Agent/command routing
+  AGENT_ROUTING_TABLE: { description: 'Agent routing reference', example: '| Task | Agent |\n|---|---|' },
+  COMMAND_LIST: { description: 'Command list', example: '/rpi-research, /rpi-plan' },
+
+  // Tasks
+  EXAMPLE_REFACTOR_TASK: { description: 'Example refactor task', example: 'Refactor authentication flow' },
+  EXAMPLE_LOWLEVEL_TASK: { description: 'Example low-level task', example: 'Fix hardcoded API URL' },
+  EXAMPLE_FEATURE_TASK: { description: 'Example feature task', example: 'Add user profile page' },
+
+  // Production
+  PRODUCTION_PLATFORM: { description: 'Production platform', example: 'AWS' },
+  PRODUCTION_SERVICES: { description: 'Production services', example: 'ECS, RDS, ElastiCache' },
+  MONITORING_COMMANDS: { description: 'Monitoring commands', example: 'kubectl logs, aws logs' },
+
+  // Constraints
+  MIGRATION_CONSTRAINTS: { description: 'Migration constraints', example: 'Always backup first' },
+  TESTING_CONSTRAINTS: { description: 'Testing constraints', example: 'Must pass CI before merge' },
+  SECURITY_CONSTRAINTS: { description: 'Security constraints', example: 'No secrets in code' },
+
+  // Contact
+  CONTACT_INFO: { description: 'Contact information', example: 'team@example.com' },
+};
+
+/**
+ * Replace placeholders in a file
+ */
+async function replacePlaceholders(filePath, values, options = {}) {
+  const { dryRun = false, backup = true } = options;
+
+  const result = {
+    file: filePath,
+    replaced: 0,
+    remaining: 0,
+    replacements: [],
+  };
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8');
+  const placeholderPattern = /\{\{([A-Z_]+)\}\}/g;
+
+  // Find all placeholders
+  const found = new Set();
+  let match;
+  while ((match = placeholderPattern.exec(content)) !== null) {
+    found.add(match[1]);
+  }
+
+  // Replace placeholders with provided values
+  for (const placeholder of found) {
+    const value = values[placeholder];
+
+    if (value !== undefined && value !== `{{${placeholder}}}`) {
+      const pattern = new RegExp(`\\{\\{${placeholder}\\}\\}`, 'g');
+      const before = content;
+      content = content.replace(pattern, value);
+
+      if (content !== before) {
+        result.replaced++;
+        result.replacements.push({
+          placeholder,
+          value: value.substring(0, 50) + (value.length > 50 ? '...' : ''),
+        });
+      }
+    } else {
+      result.remaining++;
+    }
+  }
+
+  // Write changes
+  if (!dryRun && result.replaced > 0) {
+    if (backup) {
+      const backupPath = filePath + '.bak';
+      fs.copyFileSync(filePath, backupPath);
+    }
+    fs.writeFileSync(filePath, content, 'utf8');
+  }
+
+  return result;
+}
+
+/**
+ * Find all placeholders in a file
+ */
+function findPlaceholders(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const placeholderPattern = /\{\{([A-Z_]+)\}\}/g;
+
+  const found = [];
+  let match;
+
+  while ((match = placeholderPattern.exec(content)) !== null) {
+    found.push({
+      placeholder: match[0],
+      name: match[1],
+      index: match.index,
+      known: KNOWN_PLACEHOLDERS.hasOwnProperty(match[1]),
+    });
+  }
+
+  return found;
+}
+
+/**
+ * Get placeholder information
+ */
+function getPlaceholderInfo(name) {
+  return KNOWN_PLACEHOLDERS[name] || null;
+}
+
+/**
+ * List all known placeholders
+ */
+function listKnownPlaceholders() {
+  return Object.entries(KNOWN_PLACEHOLDERS).map(([name, info]) => ({
+    name,
+    placeholder: `{{${name}}}`,
+    ...info,
+  }));
+}
+
+module.exports = {
+  replacePlaceholders,
+  findPlaceholders,
+  getPlaceholderInfo,
+  listKnownPlaceholders,
+  KNOWN_PLACEHOLDERS,
+};

package/templates/base/tools/lib/session-manager.js

@@ -0,0 +1,354 @@
+/**
+ * Session Manager - Handles session state persistence and resumption
+ *
+ * Enables self-sustaining session tracking across Claude Code sessions.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { logger } = require('./logger');
+
+const SESSION_DIR = path.join(__dirname, '..', '..', 'session');
+const CURRENT_STATE_PATH = path.join(SESSION_DIR, 'current', 'state.json');
+const HISTORY_DIR = path.join(SESSION_DIR, 'history');
+const CHECKPOINTS_DIR = path.join(SESSION_DIR, 'checkpoints');
+
+/**
+ * Generate a unique session ID
+ */
+function generateSessionId() {
+  return crypto.randomUUID();
+}
+
+/**
+ * Get current timestamp in ISO format
+ */
+function now() {
+  return new Date().toISOString();
+}
+
+/**
+ * Load current session state
+ */
+function loadSession() {
+  try {
+    if (fs.existsSync(CURRENT_STATE_PATH)) {
+      const content = fs.readFileSync(CURRENT_STATE_PATH, 'utf-8');
+      return JSON.parse(content);
+    }
+  } catch (error) {
+    logger.warn('Failed to load session state:', error.message);
+  }
+  return null;
+}
+
+/**
+ * Save current session state
+ */
+function saveSession(state) {
+  try {
+    // Ensure directory exists
+    const dir = path.dirname(CURRENT_STATE_PATH);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    // Update last activity
+    state.lastActivity = now();
+
+    fs.writeFileSync(CURRENT_STATE_PATH, JSON.stringify(state, null, 2));
+    logger.info('Session state saved');
+    return true;
+  } catch (error) {
+    logger.error('Failed to save session state:', error.message);
+    return false;
+  }
+}
+
+/**
+ * Start a new session
+ */
+function startSession(taskName = null, taskDescription = null) {
+  const session = {
+    sessionId: generateSessionId(),
+    started: now(),
+    lastActivity: now(),
+    phase: 'idle',
+    task: {
+      name: taskName,
+      description: taskDescription,
+      artifacts: []
+    },
+    context: {
+      tokensUsed: 0,
+      filesLoaded: [],
+      workflowsActive: []
+    },
+    pendingUpdates: [],
+    checkpoints: []
+  };
+
+  saveSession(session);
+  logger.info(`New session started: ${session.sessionId}`);
+  return session;
+}
+
+/**
+ * Update session phase
+ */
+function updatePhase(phase) {
+  const session = loadSession();
+  if (!session) {
+    logger.warn('No active session to update');
+    return null;
+  }
+
+  const validPhases = ['idle', 'research', 'plan', 'implement'];
+  if (!validPhases.includes(phase)) {
+    logger.error(`Invalid phase: ${phase}`);
+    return null;
+  }
+
+  session.phase = phase;
+  saveSession(session);
+  return session;
+}
+
+/**
+ * Add file to loaded files list
+ */
+function trackFileLoad(filePath) {
+  const session = loadSession();
+  if (!session) return;
+
+  if (!session.context.filesLoaded.includes(filePath)) {
+    session.context.filesLoaded.push(filePath);
+    saveSession(session);
+  }
+}
+
+/**
+ * Add artifact to current task
+ */
+function addArtifact(artifactPath) {
+  const session = loadSession();
+  if (!session) return;
+
+  if (!session.task.artifacts.includes(artifactPath)) {
+    session.task.artifacts.push(artifactPath);
+    saveSession(session);
+  }
+}
+
+/**
+ * Add pending documentation update
+ */
+function addPendingUpdate(workflowPath, reason) {
+  const session = loadSession();
+  if (!session) return;
+
+  session.pendingUpdates.push({
+    workflow: workflowPath,
+    reason: reason,
+    addedAt: now()
+  });
+  saveSession(session);
+}
+
+/**
+ * Create a checkpoint for resumption
+ */
+function createCheckpoint(description) {
+  const session = loadSession();
+  if (!session) return null;
+
+  const checkpoint = {
+    id: crypto.randomUUID(),
+    timestamp: now(),
+    description: description,
+    phase: session.phase,
+    filesLoaded: [...session.context.filesLoaded],
+    pendingUpdates: [...session.pendingUpdates]
+  };
+
+  session.checkpoints.push(checkpoint);
+  saveSession(session);
+
+  // Also save to checkpoints directory
+  const checkpointPath = path.join(CHECKPOINTS_DIR, `${checkpoint.id}.json`);
+  if (!fs.existsSync(CHECKPOINTS_DIR)) {
+    fs.mkdirSync(CHECKPOINTS_DIR, { recursive: true });
+  }
+  fs.writeFileSync(checkpointPath, JSON.stringify(checkpoint, null, 2));
+
+  logger.info(`Checkpoint created: ${checkpoint.id}`);
+  return checkpoint;
+}
+
+/**
+ * Archive current session to history
+ */
+function archiveSession() {
+  const session = loadSession();
+  if (!session || !session.sessionId) {
+    logger.warn('No active session to archive');
+    return false;
+  }
+
+  try {
+    // Create history directory for today
+    const today = new Date().toISOString().split('T')[0];
+    const todayDir = path.join(HISTORY_DIR, today);
+    if (!fs.existsSync(todayDir)) {
+      fs.mkdirSync(todayDir, { recursive: true });
+    }
+
+    // Save to history
+    const historyPath = path.join(todayDir, `${session.sessionId}.json`);
+    fs.writeFileSync(historyPath, JSON.stringify(session, null, 2));
+
+    // Clear current state
+    const emptyState = {
+      sessionId: null,
+      started: null,
+      lastActivity: null,
+      phase: 'idle',
+      task: { name: null, description: null, artifacts: [] },
+      context: { tokensUsed: 0, filesLoaded: [], workflowsActive: [] },
+      pendingUpdates: [],
+      checkpoints: []
+    };
+    fs.writeFileSync(CURRENT_STATE_PATH, JSON.stringify(emptyState, null, 2));
+
+    logger.info(`Session archived: ${session.sessionId}`);
+    return true;
+  } catch (error) {
+    logger.error('Failed to archive session:', error.message);
+    return false;
+  }
+}
+
+/**
+ * List available sessions from history
+ */
+function listSessions(limit = 10) {
+  const sessions = [];
+
+  try {
+    if (!fs.existsSync(HISTORY_DIR)) {
+      return sessions;
+    }
+
+    // Get all date directories
+    const dateDirs = fs.readdirSync(HISTORY_DIR)
+      .filter(d => /^\d{4}-\d{2}-\d{2}$/.test(d))
+      .sort()
+      .reverse();
+
+    for (const dateDir of dateDirs) {
+      if (sessions.length >= limit) break;
+
+      const dirPath = path.join(HISTORY_DIR, dateDir);
+      const files = fs.readdirSync(dirPath).filter(f => f.endsWith('.json'));
+
+      for (const file of files) {
+        if (sessions.length >= limit) break;
+
+        try {
+          const content = fs.readFileSync(path.join(dirPath, file), 'utf-8');
+          const session = JSON.parse(content);
+          sessions.push({
+            sessionId: session.sessionId,
+            date: dateDir,
+            started: session.started,
+            phase: session.phase,
+            taskName: session.task?.name
+          });
+        } catch (e) {
+          // Skip invalid files
+        }
+      }
+    }
+  } catch (error) {
+    logger.error('Failed to list sessions:', error.message);
+  }
+
+  return sessions;
+}
+
+/**
+ * Resume a session from history
+ */
+function resumeSession(sessionId) {
+  try {
+    // Search in history
+    if (!fs.existsSync(HISTORY_DIR)) {
+      logger.error('No session history found');
+      return null;
+    }
+
+    const dateDirs = fs.readdirSync(HISTORY_DIR)
+      .filter(d => /^\d{4}-\d{2}-\d{2}$/.test(d));
+
+    for (const dateDir of dateDirs) {
+      const filePath = path.join(HISTORY_DIR, dateDir, `${sessionId}.json`);
+      if (fs.existsSync(filePath)) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const session = JSON.parse(content);
+
+        // Update timestamps
+        session.lastActivity = now();
+
+        // Save as current
+        saveSession(session);
+        logger.info(`Session resumed: ${sessionId}`);
+        return session;
+      }
+    }
+
+    logger.error(`Session not found: ${sessionId}`);
+    return null;
+  } catch (error) {
+    logger.error('Failed to resume session:', error.message);
+    return null;
+  }
+}
+
+/**
+ * Get session summary for display
+ */
+function getSessionSummary() {
+  const session = loadSession();
+  if (!session || !session.sessionId) {
+    return null;
+  }
+
+  return {
+    sessionId: session.sessionId,
+    started: session.started,
+    duration: session.started
+      ? Math.round((Date.now() - new Date(session.started).getTime()) / 60000)
+      : 0,
+    phase: session.phase,
+    task: session.task?.name || '(none)',
+    filesLoaded: session.context.filesLoaded.length,
+    pendingUpdates: session.pendingUpdates.length,
+    checkpoints: session.checkpoints.length
+  };
+}
+
+module.exports = {
+  loadSession,
+  saveSession,
+  startSession,
+  updatePhase,
+  trackFileLoad,
+  addArtifact,
+  addPendingUpdate,
+  createCheckpoint,
+  archiveSession,
+  listSessions,
+  resumeSession,
+  getSessionSummary
+};