lean-claudient-core 0.1.0

package/src/compression/caveman.ts

@@ -0,0 +1,257 @@
+type Intensity = 'lite' | 'full' | 'ultra' | 'wenyan';
+
+interface CompressionConfig {
+  preserveCodeBlocks: boolean;
+  preserveUrls: boolean;
+  preserveQuotes: boolean;
+}
+
+const defaultConfig: CompressionConfig = {
+  preserveCodeBlocks: true,
+  preserveUrls: true,
+  preserveQuotes: true,
+};
+
+const liteStopwords = new Set([
+  'that', 'this', 'very', 'quite', 'rather', 'extremely', 'so', 'just'
+]);
+
+const fullStopwords = new Set([
+  'that', 'this', 'very', 'quite', 'rather', 'extremely', 'so', 'just'
+]);
+
+const ultraStopwords = new Set([
+  'that', 'this', 'very', 'quite', 'rather', 'extremely', 'so', 'just',
+  'is', 'are', 'be', 'been'
+]);
+
+const abbreviations: Record<string, string> = {
+  'function': 'fn',
+  'config': 'cfg',
+  'database': 'db',
+  'variable': 'var',
+  'important': 'imp',
+  'documentation': 'doc',
+  'implementation': 'impl',
+  'interface': 'if',
+  'argument': 'arg',
+  'parameter': 'param',
+  'response': 'res',
+  'request': 'req',
+  'callback': 'cb',
+  'promise': 'prom',
+  'async': 'async',
+  'await': 'await',
+  'return': 'ret',
+  'throw': 'thr',
+  'constructor': 'ctor',
+  'destructor': 'dtor',
+  'method': 'mtd',
+  'property': 'prop',
+  'attribute': 'attr',
+  'constant': 'const',
+  'static': 'static',
+  'public': 'pub',
+  'private': 'priv',
+  'protected': 'prot',
+};
+
+const codeBlockRegex = /```[\s\S]*?```|`[^`]*`/g;
+const urlRegex = /https?:\/\/[^\s]+|www\.[^\s]+/g;
+const quotedRegex = /["'][^"']*["']/g;
+
+function extractPreservedContent(
+  text: string,
+  config: CompressionConfig
+): { processed: string; preserved: Map<string, string> } {
+  const preserved = new Map<string, string>();
+  let processed = text;
+  let index = 0;
+
+  if (config.preserveCodeBlocks) {
+    processed = processed.replace(codeBlockRegex, (match) => {
+      const placeholder = `__CODE_${index}__`;
+      preserved.set(placeholder, match);
+      index++;
+      return placeholder;
+    });
+  }
+
+  if (config.preserveUrls) {
+    processed = processed.replace(urlRegex, (match) => {
+      const placeholder = `__URL_${index}__`;
+      preserved.set(placeholder, match);
+      index++;
+      return placeholder;
+    });
+  }
+
+  if (config.preserveQuotes) {
+    processed = processed.replace(quotedRegex, (match) => {
+      const placeholder = `__QUOTE_${index}__`;
+      preserved.set(placeholder, match);
+      index++;
+      return placeholder;
+    });
+  }
+
+  return { processed, preserved };
+}
+
+function restorePreservedContent(
+  text: string,
+  preserved: Map<string, string>
+): string {
+  let result = text;
+  preserved.forEach((value, key) => {
+    result = result.replace(new RegExp(key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), value);
+  });
+  return result;
+}
+
+function compressLite(text: string): string {
+  let result = text;
+
+  result = result.replace(/\b(a|an)\s+/gi, '');
+
+  liteStopwords.forEach((word) => {
+    const regex = new RegExp(`\\b${word}\\b\\s*`, 'gi');
+    result = result.replace(regex, ' ');
+  });
+
+  result = result.replace(/\s+/g, ' ').trim();
+  return result;
+}
+
+function compressFull(text: string): string {
+  let result = compressLite(text);
+
+  result = result.replace(/\bthe\s+/gi, ' ');
+  result = result.replace(/\b(a|an)\s+/gi, ' ');
+
+  result = result.replace(/\s+and\s+/gi, ',');
+  result = result.replace(/\s+but\s+/gi, '-');
+  result = result.replace(/\s+or\s+/gi, '/');
+  result = result.replace(/\bbecause\b/gi, 'bc');
+
+  result = result.replace(/\s+(in|on|at|from|to|by)\s+/gi, ' ');
+
+  result = result.replace(/→|implies|causes/gi, '→');
+  result = result.replace(/←|reverse|reverse-caused/gi, '←');
+
+  Object.entries(abbreviations).forEach(([long, short]) => {
+    const regex = new RegExp(`\\b${long}\\b`, 'gi');
+    result = result.replace(regex, short);
+  });
+
+  result = result.replace(/\s+/g, ' ').trim();
+  return result;
+}
+
+function compressUltra(text: string): string {
+  let result = compressFull(text);
+
+  ultraStopwords.forEach((word) => {
+    if (!liteStopwords.has(word)) {
+      const regex = new RegExp(`\\b${word}\\b\\s*`, 'gi');
+      result = result.replace(regex, ' ');
+    }
+  });
+
+  result = result.replace(/\s+(have|has|had|do|does|did)\s+/gi, ' ');
+  result = result.replace(/\s+(which|that|where|when|why|what)\s+/gi, ' ');
+  result = result.replace(/\s+(all|some|any|each|every)\s+/gi, ' ');
+
+  result = result.replace(/([a-z])\s*\+\s*([a-z])/gi, '$1+$2');
+  result = result.replace(/([a-z])\s*-\s*([a-z])/gi, '$1-$2');
+  result = result.replace(/([a-z])\s*\/\s*([a-z])/gi, '$1/$2');
+  result = result.replace(/([a-z])\s*\*\s*([a-z])/gi, '$1*$2');
+
+  result = result.replace(/\s+/g, ' ').trim();
+  return result;
+}
+
+function compressWenyan(text: string): string {
+  let result = compressUltra(text);
+
+  result = result.replace(/\b(the|a|an)\s*/gi, '');
+  result = result.replace(/\s+(of|for|with)\s+/gi, '');
+
+  result = result.replace(/[,;:.!?]/g, '');
+
+  result = result.replace(/\b(which|that|where|when|why|what|who|whom)\b/gi, '');
+  result = result.replace(/\b(these|those|them|there|then)\b/gi, '');
+
+  result = result.replace(/\s+([a-z])\s+/gi, '$1');
+  result = result.replace(/\s+/g, '');
+
+  result = result.replace(/function\s*(\w+)/gi, '函$1');
+  result = result.replace(/calculate/gi, '算');
+  result = result.replace(/process/gi, '处');
+  result = result.replace(/database/gi, '库');
+  result = result.replace(/item/gi, '项');
+  result = result.replace(/array/gi, '组');
+
+  return result;
+}
+
+export function compress(
+  text: string,
+  intensity: Intensity = 'lite',
+  config: Partial<CompressionConfig> = {}
+): string {
+  const finalConfig = { ...defaultConfig, ...config };
+
+  const { processed, preserved } = extractPreservedContent(text, finalConfig);
+
+  let compressed: string;
+
+  switch (intensity) {
+    case 'lite':
+      compressed = compressLite(processed);
+      break;
+    case 'full':
+      compressed = compressFull(processed);
+      break;
+    case 'ultra':
+      compressed = compressUltra(processed);
+      break;
+    case 'wenyan':
+      compressed = compressWenyan(processed);
+      break;
+    default:
+      const _exhaustive: never = intensity;
+      return _exhaustive;
+  }
+
+  return restorePreservedContent(compressed, preserved);
+}
+
+export function getCompressionRatio(
+  original: string,
+  compressed: string
+): number {
+  if (original.length === 0) {
+    return 0;
+  }
+
+  const reduction = (original.length - compressed.length) / original.length;
+  return Math.max(0, Math.min(1, reduction));
+}
+
+export function analyzeCompression(
+  text: string,
+  intensities: Intensity[] = ['lite', 'full', 'ultra', 'wenyan']
+): Record<Intensity, { compressed: string; ratio: number }> {
+  const results: Record<Intensity, { compressed: string; ratio: number }> = {} as any;
+
+  intensities.forEach((intensity) => {
+    const compressed = compress(text, intensity);
+    const ratio = getCompressionRatio(text, compressed);
+    results[intensity] = { compressed, ratio };
+  });
+
+  return results;
+}
+
+export type { Intensity, CompressionConfig };

package/src/config/configManager.ts

@@ -0,0 +1,63 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { z } from 'zod';
+import { LeanClaudientConfigSchema, LeanClaudientConfig } from './schema.js';
+
+export function validateConfig(obj: unknown): LeanClaudientConfig {
+  const result = LeanClaudientConfigSchema.safeParse(obj);
+  if (!result.success) {
+    const errors = result.error.flatten().fieldErrors;
+    const message = Object.entries(errors)
+      .map(([key, msgs]) => `${key}: ${msgs?.join(', ')}`)
+      .join('\n');
+    throw new Error(`Config validation failed:\n${message}`);
+  }
+  return result.data;
+}
+
+export function loadConfig(path: string): LeanClaudientConfig {
+  const fullPath = resolve(path);
+  try {
+    const content = readFileSync(fullPath, 'utf-8');
+    const parsed = JSON.parse(content);
+    return validateConfig(parsed);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`Config file contains invalid JSON: ${fullPath}`);
+    }
+    if (error instanceof z.ZodError) {
+      throw error;
+    }
+    throw new Error(`Failed to load config from ${fullPath}: ${(error as Error).message}`);
+  }
+}
+
+export function saveConfig(path: string, config: LeanClaudientConfig): void {
+  const validated = validateConfig(config);
+  const fullPath = resolve(path);
+  try {
+    const dir = dirname(fullPath);
+    mkdirSync(dir, { recursive: true });
+    const content = JSON.stringify(validated, null, 2);
+    writeFileSync(fullPath, content, 'utf-8');
+  } catch (error) {
+    throw new Error(`Failed to save config to ${fullPath}: ${(error as Error).message}`);
+  }
+}
+
+export function getDefaultConfig(): LeanClaudientConfig {
+  return {
+    caveman: {
+      enabled: false,
+      intensity: 'lite',
+    },
+    conservativeCTO: {
+      enabled: false,
+      tokenBudgetPerSession: 50000,
+    },
+    persistentPlanning: {
+      enforceTwoActionRule: true,
+      readBeforeDecideHook: true,
+    },
+  };
+}

package/src/config/schema.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+
+const CavemanSchema = z.object({
+  enabled: z.boolean().default(false),
+  intensity: z.enum(['lite', 'full', 'ultra', 'wenyan']).default('lite'),
+});
+
+const ConservativeCTOSchema = z.object({
+  enabled: z.boolean().default(false),
+  tokenBudgetPerSession: z.number().positive().default(50000),
+});
+
+const PersistentPlanningSchema = z.object({
+  enforceTwoActionRule: z.boolean().default(true),
+  readBeforeDecideHook: z.boolean().default(true),
+});
+
+export const LeanClaudientConfigSchema = z.object({
+  caveman: CavemanSchema.optional(),
+  conservativeCTO: ConservativeCTOSchema.optional(),
+  persistentPlanning: PersistentPlanningSchema.optional(),
+});
+
+export type CavemanConfig = z.infer<typeof CavemanSchema>;
+export type ConservativeCTOConfig = z.infer<typeof ConservativeCTOSchema>;
+export type PersistentPlanningConfig = z.infer<typeof PersistentPlanningSchema>;
+export type LeanClaudientConfig = z.infer<typeof LeanClaudientConfigSchema>;

package/src/context/autoCompact.ts

@@ -0,0 +1,123 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { extname } from 'path';
+
+export class AutoCompactor {
+  constructor(private claudeMdPath: string) {}
+
+  shouldCompact(currentTokens: number, maxTokens: number): boolean {
+    return (currentTokens / maxTokens) >= 0.85;
+  }
+
+  extractArchitecturalState(conversationHistory: string): string {
+    const state: string[] = [];
+
+    const lines = conversationHistory.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      if (this.isDecision(line)) {
+        state.push(`- Decision: ${this.sanitizeLine(line)}`);
+      }
+      if (this.isApiShape(line)) {
+        state.push(`- API Shape: ${this.sanitizeLine(line)}`);
+      }
+      if (this.isFilePath(line)) {
+        state.push(`- File Path: ${this.extractFilePath(line)}`);
+      }
+      if (this.isEnvVar(line)) {
+        state.push(`- Env Var: ${this.extractEnvVar(line)}`);
+      }
+    }
+
+    return state.length > 0 ? state.join('\n') : '- No architectural state extracted';
+  }
+
+  summarizeState(state: string, maxTokens: number = 5000): string {
+    const lines = state.split('\n').filter((l) => l.trim());
+    const targetLineCount = Math.floor(maxTokens / 15);
+
+    if (lines.length <= targetLineCount) {
+      return state;
+    }
+
+    const grouped: { [key: string]: string[] } = {};
+    for (const line of lines) {
+      const prefix = line.split(':')[0];
+      if (!grouped[prefix]) grouped[prefix] = [];
+      grouped[prefix].push(line);
+    }
+
+    const summarized: string[] = [];
+    for (const [prefix, items] of Object.entries(grouped)) {
+      if (items.length <= 3) {
+        summarized.push(...items);
+      } else {
+        summarized.push(items[0]);
+        summarized.push(`- ... (${items.length - 1} more)`);
+      }
+    }
+
+    return summarized.slice(0, targetLineCount).join('\n');
+  }
+
+  compactSession(conversationHistory: string, claudeMdPath: string): { success: boolean; tokensFreed: number } {
+    try {
+      const state = this.extractArchitecturalState(conversationHistory);
+      const summarized = this.summarizeState(state);
+
+      const claudeMdContent = readFileSync(claudeMdPath, 'utf-8');
+
+      const stateSection = `## Architectural State\n\n${summarized}\n\n`;
+
+      let updatedContent: string;
+      if (claudeMdContent.includes('## Architectural State')) {
+        updatedContent = claudeMdContent.replace(
+          /## Architectural State\n\n[\s\S]*?(?=\n##|\Z)/,
+          stateSection.trimEnd(),
+        );
+      } else {
+        updatedContent = claudeMdContent.trimEnd() + '\n\n---\n\n' + stateSection;
+      }
+
+      writeFileSync(claudeMdPath, updatedContent, 'utf-8');
+
+      const originalTokens = Math.ceil(conversationHistory.length / 4);
+      const compactedTokens = Math.ceil(summarized.length / 4);
+      const tokensFreed = Math.max(0, originalTokens - compactedTokens);
+
+      return { success: true, tokensFreed };
+    } catch {
+      return { success: false, tokensFreed: 0 };
+    }
+  }
+
+  private isDecision(line: string): boolean {
+    return /\b(decided|decision|chose|architecture|design)\b/i.test(line);
+  }
+
+  private isApiShape(line: string): boolean {
+    return /\b(api|endpoint|route|interface|schema|type)\b.*\{/i.test(line);
+  }
+
+  private isFilePath(line: string): boolean {
+    return /\/[\w\-./]+\.\w+/i.test(line);
+  }
+
+  private isEnvVar(line: string): boolean {
+    return /\b[A-Z_]+=[^\s]+/i.test(line);
+  }
+
+  private sanitizeLine(line: string): string {
+    return line.replace(/^[\s\-*]+/, '').trim().slice(0, 120);
+  }
+
+  private extractFilePath(line: string): string {
+    const match = line.match(/\/[\w\-./]+\.\w+/);
+    return match ? match[0] : '';
+  }
+
+  private extractEnvVar(line: string): string {
+    const match = line.match(/\b([A-Z_]+)=([^\s]+)/);
+    return match ? `${match[1]}=***` : '';
+  }
+}

package/src/context/readDedup.ts

@@ -0,0 +1,84 @@
+import { createHash } from 'crypto';
+
+interface ReadRecord {
+  hash: string;
+  lineCount: number;
+  timestamp: number;
+}
+
+export class ReadDeduplicator {
+  private sessionId: string;
+  private readMap: Map<string, ReadRecord>;
+  private duplicateCount: number;
+  private totalReadCount: number;
+  private totalTokensSaved: number;
+
+  constructor(sessionId: string) {
+    this.sessionId = sessionId;
+    this.readMap = new Map();
+    this.duplicateCount = 0;
+    this.totalReadCount = 0;
+    this.totalTokensSaved = 0;
+  }
+
+  recordRead(filepath: string, content: string): string {
+    const hash = this.hashContent(content);
+    const lineCount = content.split('\n').length;
+    const timestamp = Date.now();
+
+    this.readMap.set(filepath, {
+      hash,
+      lineCount,
+      timestamp,
+    });
+
+    this.totalReadCount++;
+    return hash;
+  }
+
+  getDedupStub(
+    filepath: string,
+    content: string,
+  ): { isDuplicate: boolean; stub?: string } {
+    const hash = this.hashContent(content);
+    const existingRecord = this.readMap.get(filepath);
+
+    if (existingRecord && existingRecord.hash === hash) {
+      this.duplicateCount++;
+      const tokensSaved = Math.floor(content.length / 2);
+      this.totalTokensSaved += Math.floor(tokensSaved * 0.99);
+
+      return {
+        isDuplicate: true,
+        stub: `[Cached: ${filepath} (${existingRecord.lineCount} lines, hash: ${hash})]`,
+      };
+    }
+
+    return {
+      isDuplicate: false,
+    };
+  }
+
+  getStats(): {
+    totalReads: number;
+    duplicates: number;
+    tokensSaved: number;
+  } {
+    return {
+      totalReads: this.totalReadCount,
+      duplicates: this.duplicateCount,
+      tokensSaved: this.totalTokensSaved,
+    };
+  }
+
+  clear(): void {
+    this.readMap.clear();
+    this.duplicateCount = 0;
+    this.totalReadCount = 0;
+    this.totalTokensSaved = 0;
+  }
+
+  private hashContent(content: string): string {
+    return createHash('sha256').update(content).digest('hex').slice(0, 12);
+  }
+}

package/src/context/toolBudgets.ts

@@ -0,0 +1,43 @@
+export class ToolBudgetEnforcer {
+  constructor() {}
+
+  stripANSI(text: string): string {
+    return text.replace(/\x1b\[[0-9;]*m/g, '');
+  }
+
+  getLineCount(text: string): number {
+    return text.split('\n').length;
+  }
+
+  truncateOutput(toolName: string, output: string, lineLimit: number): string {
+    const stripped = this.stripANSI(output);
+    const lines = stripped.split('\n');
+
+    if (lines.length > lineLimit) {
+      const excess = lines.length - lineLimit + 1;
+      return lines.slice(0, lineLimit - 1).join('\n') + `\n... (${excess} lines truncated)`;
+    }
+
+    return stripped;
+  }
+
+  enforceGrepBudget(output: string): string {
+    return this.truncateOutput('grep', output, 120);
+  }
+
+  enforceBashBudget(output: string): string {
+    return this.truncateOutput('bash', output, 80);
+  }
+
+  enforceReadBudget(output: string): string {
+    return this.truncateOutput('read', output, 300);
+  }
+
+  getBudgets(): { grep: number; bash: number; read: number } {
+    return {
+      grep: 120,
+      bash: 80,
+      read: 300,
+    };
+  }
+}

package/src/core/auditLogger.ts

@@ -0,0 +1,69 @@
+/**
+ * Audit Logger
+ * Logs all automation events (workflow, approval, execution) for compliance & debugging
+ */
+
+import { writeFileSync, mkdirSync, existsSync, appendFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export interface AuditLogEntry {
+  timestamp: string;
+  event: string;
+  [key: string]: any;
+}
+
+/**
+ * AuditLogger: Persistent logging for automation events
+ */
+export class AuditLogger {
+  private logPath: string;
+
+  constructor(logPath?: string) {
+    this.logPath = logPath || join(homedir(), '.lean-claudient', 'automation-audit.log');
+    this.ensureLogDirectory();
+  }
+
+  /**
+   * Ensure log directory exists
+   */
+  private ensureLogDirectory(): void {
+    const dir = join(homedir(), '.lean-claudient');
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+  }
+
+  /**
+   * Log an event
+   */
+  log(entry: AuditLogEntry | Record<string, any>): void {
+    const baseEntry = {
+      timestamp: new Date().toISOString()
+    };
+
+    const record = {
+      ...baseEntry,
+      ...(entry && typeof entry === 'object' && 'timestamp' in entry ? { ...entry } : entry)
+    };
+
+    try {
+      appendFileSync(
+        this.logPath,
+        JSON.stringify(record) + '\n',
+        { mode: 0o600 }
+      );
+    } catch (error) {
+      console.error('Failed to write audit log:', (error as Error).message);
+    }
+  }
+
+  /**
+   * Get log path
+   */
+  getLogPath(): string {
+    return this.logPath;
+  }
+}
+
+export default AuditLogger;