@compilr-dev/sdk 0.1.4 → 0.1.6

package/dist/system-prompt/builder.js

@@ -0,0 +1,255 @@
+/**
+ * System Prompt Builder
+ *
+ * Assembles system prompt from modules based on current context.
+ * Provides ~50% token reduction by only including relevant modules.
+ *
+ * Git/CWD detection is injectable via SystemPromptContext for non-Node environments.
+ * Falls back to execSync detection in Node.js when not provided.
+ */
+import { ALL_MODULES, shouldIncludeModule, getEstimatedTokensForConditions, } from './modules.js';
+/**
+ * Get git configuration (user.name and user.email).
+ * Returns provided overrides, or auto-detects via execSync in Node.js.
+ */
+function getGitConfig(context) {
+    // Use injected values if provided
+    if (context.gitUserName !== undefined && context.gitUserEmail !== undefined) {
+        return { userName: context.gitUserName, userEmail: context.gitUserEmail };
+    }
+    let userName = context.gitUserName ?? '(not set - commits will fail)';
+    let userEmail = context.gitUserEmail ?? '(not set - commits will fail)';
+    try {
+        // Dynamic import to avoid bundler issues in non-Node environments
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { execSync } = require('child_process');
+        if (context.gitUserName === undefined) {
+            try {
+                const name = execSync('git config --global user.name', {
+                    encoding: 'utf8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                }).trim();
+                if (name)
+                    userName = name;
+            }
+            catch {
+                // Not configured
+            }
+        }
+        if (context.gitUserEmail === undefined) {
+            try {
+                const email = execSync('git config --global user.email', {
+                    encoding: 'utf8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                }).trim();
+                if (email)
+                    userEmail = email;
+            }
+            catch {
+                // Not configured
+            }
+        }
+    }
+    catch {
+        // child_process not available (browser/edge runtime)
+    }
+    return { userName, userEmail };
+}
+/**
+ * Detect if a directory is a git repository.
+ * Uses execSync when available; returns false in non-Node environments.
+ */
+export function detectGitRepository(cwd) {
+    try {
+        // Dynamic import to avoid bundler issues in non-Node environments
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { execSync } = require('child_process');
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { existsSync } = require('fs');
+        const dir = cwd ?? process.cwd();
+        // Check for .git directory
+        if (existsSync(`${dir}/.git`)) {
+            return true;
+        }
+        // Also check via git command (handles worktrees, etc.)
+        execSync('git rev-parse --is-inside-work-tree', {
+            cwd: dir,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Replace placeholders in module content
+ */
+function replacePlaceholders(content, context) {
+    const gitConfig = getGitConfig(context);
+    let cwd;
+    try {
+        cwd = context.cwd ?? process.cwd();
+    }
+    catch {
+        cwd = context.cwd ?? '(unknown)';
+    }
+    return content
+        .replace('{{CWD}}', cwd)
+        .replace('{{GIT_USER_NAME}}', gitConfig.userName)
+        .replace('{{GIT_USER_EMAIL}}', gitConfig.userEmail);
+}
+/**
+ * SystemPromptBuilder - assembles modular system prompts
+ */
+export class SystemPromptBuilder {
+    context;
+    modules;
+    constructor(context = {}, modules) {
+        // Auto-detect git if not specified
+        this.context = {
+            ...context,
+            hasGit: context.hasGit ?? detectGitRepository(context.cwd),
+        };
+        this.modules = modules ?? ALL_MODULES;
+    }
+    /**
+     * Update context (e.g., when mode changes)
+     */
+    setContext(context) {
+        this.context = { ...this.context, ...context };
+    }
+    /**
+     * Get current context
+     */
+    getContext() {
+        return { ...this.context };
+    }
+    /**
+     * Build the system prompt based on current context
+     */
+    build() {
+        const includedModules = [];
+        const excludedModules = [];
+        const parts = [];
+        // Process each module
+        for (const module of this.modules) {
+            if (shouldIncludeModule(module, this.context)) {
+                includedModules.push(module.id);
+                parts.push(replacePlaceholders(module.content, this.context));
+            }
+            else {
+                // Determine reason for exclusion
+                let reason = 'Unknown';
+                if (module.conditions?.hasGit && !this.context.hasGit) {
+                    reason = 'Not a git repository';
+                }
+                else if (module.conditions?.enableMetaTools && !this.context.enableMetaTools) {
+                    reason = 'Meta-tools not enabled';
+                }
+                else if (module.conditions?.modes && this.context.mode) {
+                    reason = `Mode is ${this.context.mode}, requires ${module.conditions.modes.join('/')}`;
+                }
+                else if (module.conditions?.hasProject && !this.context.hasProject) {
+                    reason = 'No active project';
+                }
+                excludedModules.push({ id: module.id, reason });
+            }
+        }
+        // Join modules with separators
+        let prompt = parts.join('\n\n---\n\n');
+        // Append meta-tools index if provided
+        if (this.context.metaToolsIndex) {
+            prompt += `\n\n---\n\n${this.context.metaToolsIndex}`;
+        }
+        // Append project context if provided
+        if (this.context.projectContext) {
+            const projectHeader = this.context.projectName
+                ? `## Project Context (${this.context.projectName})`
+                : '## Project Context';
+            prompt += `\n\n---\n\n${projectHeader}\n\nThe following is project-specific context loaded from COMPILR.md:\n\n${this.context.projectContext}`;
+        }
+        else if (this.context.projectName) {
+            prompt += `\n\n---\n\n## Active Project\n\nThe current project is: **${this.context.projectName}**`;
+        }
+        // Append guided mode context if provided
+        if (this.context.guidedModeContext) {
+            prompt += `\n\n---\n\n${this.context.guidedModeContext}`;
+        }
+        // Append plan mode context if provided
+        if (this.context.planModeContext) {
+            prompt += `\n\n---\n\n${this.context.planModeContext}`;
+        }
+        // Calculate estimated tokens
+        const baseTokens = getEstimatedTokensForConditions(this.context);
+        // Rough estimate for appended contexts (4 chars ≈ 1 token)
+        const appendedTokens = Math.ceil(((this.context.projectContext?.length ?? 0) +
+            (this.context.guidedModeContext?.length ?? 0) +
+            (this.context.planModeContext?.length ?? 0) +
+            (this.context.metaToolsIndex?.length ?? 0)) /
+            4);
+        return {
+            prompt,
+            includedModules,
+            excludedModules,
+            estimatedTokens: baseTokens + appendedTokens,
+        };
+    }
+    /**
+     * Build and return just the prompt string
+     */
+    buildPrompt() {
+        return this.build().prompt;
+    }
+    /**
+     * Get estimated token count for current context
+     */
+    getEstimatedTokens() {
+        return this.build().estimatedTokens;
+    }
+    /**
+     * Get a summary of what modules will be included/excluded
+     */
+    getSummary() {
+        const result = this.build();
+        return {
+            included: result.includedModules,
+            excluded: result.excludedModules,
+            estimatedTokens: result.estimatedTokens,
+        };
+    }
+}
+/**
+ * Convenience function to build a system prompt
+ */
+export function buildSystemPrompt(context = {}) {
+    const builder = new SystemPromptBuilder(context);
+    return builder.buildPrompt();
+}
+/**
+ * Get module stats for debugging
+ */
+export function getModuleStats() {
+    const conditional = ALL_MODULES.filter((m) => m.conditions);
+    const always = ALL_MODULES.filter((m) => !m.conditions);
+    // Max: all modules
+    const maxTokens = getEstimatedTokensForConditions({
+        hasGit: true,
+        enableMetaTools: true,
+        hasProject: true,
+    });
+    // Min: no conditional modules
+    const minTokens = getEstimatedTokensForConditions({
+        hasGit: false,
+        enableMetaTools: false,
+        hasProject: false,
+    });
+    return {
+        totalModules: ALL_MODULES.length,
+        conditionalModules: conditional.length,
+        alwaysIncludedModules: always.length,
+        maxTokens,
+        minTokens,
+    };
+}

package/dist/system-prompt/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Modular System Prompt
+ *
+ * Token-optimized system prompt that only includes relevant modules
+ * based on current context (git repo, mode, project, etc.).
+ *
+ * Usage:
+ * ```typescript
+ * import { SystemPromptBuilder, buildSystemPrompt } from '@compilr-dev/sdk';
+ *
+ * // Simple usage
+ * const prompt = buildSystemPrompt({ hasGit: true, enableMetaTools: true });
+ *
+ * // Builder pattern for more control
+ * const builder = new SystemPromptBuilder({ hasGit: true });
+ * builder.setContext({ enableMetaTools: true, projectContext: '...' });
+ * const result = builder.build();
+ * console.log(`Included: ${result.includedModules.join(', ')}`);
+ * console.log(`Est. tokens: ${result.estimatedTokens}`);
+ *
+ * // Injectable context (for non-Node environments)
+ * const prompt2 = buildSystemPrompt({
+ *   hasGit: true,
+ *   cwd: '/app',
+ *   gitUserName: 'Alice',
+ *   gitUserEmail: 'alice@example.com',
+ * });
+ *
+ * // Custom modules
+ * const builder2 = new SystemPromptBuilder({}, [STYLE_MODULE, TASK_EXECUTION_MODULE]);
+ * ```
+ */
+export { SystemPromptBuilder, buildSystemPrompt, detectGitRepository, getModuleStats, type SystemPromptContext, type BuildResult, } from './builder.js';
+export { ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, ENVIRONMENT_MODULE, shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, type SystemPromptModule, type ModuleConditions, } from './modules.js';

package/dist/system-prompt/index.js

@@ -0,0 +1,34 @@
+/**
+ * Modular System Prompt
+ *
+ * Token-optimized system prompt that only includes relevant modules
+ * based on current context (git repo, mode, project, etc.).
+ *
+ * Usage:
+ * ```typescript
+ * import { SystemPromptBuilder, buildSystemPrompt } from '@compilr-dev/sdk';
+ *
+ * // Simple usage
+ * const prompt = buildSystemPrompt({ hasGit: true, enableMetaTools: true });
+ *
+ * // Builder pattern for more control
+ * const builder = new SystemPromptBuilder({ hasGit: true });
+ * builder.setContext({ enableMetaTools: true, projectContext: '...' });
+ * const result = builder.build();
+ * console.log(`Included: ${result.includedModules.join(', ')}`);
+ * console.log(`Est. tokens: ${result.estimatedTokens}`);
+ *
+ * // Injectable context (for non-Node environments)
+ * const prompt2 = buildSystemPrompt({
+ *   hasGit: true,
+ *   cwd: '/app',
+ *   gitUserName: 'Alice',
+ *   gitUserEmail: 'alice@example.com',
+ * });
+ *
+ * // Custom modules
+ * const builder2 = new SystemPromptBuilder({}, [STYLE_MODULE, TASK_EXECUTION_MODULE]);
+ * ```
+ */
+export { SystemPromptBuilder, buildSystemPrompt, detectGitRepository, getModuleStats, } from './builder.js';
+export { ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, ENVIRONMENT_MODULE, shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, } from './modules.js';

package/dist/system-prompt/modules.d.ts

@@ -0,0 +1,124 @@
+/**
+ * System Prompt Modules
+ *
+ * Modular system prompt for token optimization.
+ * Each module has content and optional conditions for inclusion.
+ *
+ * Token savings: ~50% reduction on average by only including relevant modules.
+ */
+/**
+ * Conditions that determine if a module should be included
+ */
+export interface ModuleConditions {
+    /** Include only if in a git repository */
+    hasGit?: boolean;
+    /** Include only in these workflow modes */
+    modes?: ('flexible' | 'guided' | 'plan')[];
+    /** Include only if there's an active project */
+    hasProject?: boolean;
+    /** Include only if meta-tools are enabled */
+    enableMetaTools?: boolean;
+    /** Include only if NO role identity is specified (for default identity module) */
+    noRoleIdentity?: boolean;
+}
+/**
+ * A system prompt module
+ */
+export interface SystemPromptModule {
+    /** Unique identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** The actual prompt content */
+    content: string;
+    /** Conditions for inclusion (empty = always include) */
+    conditions?: ModuleConditions;
+    /** Estimated token count (for debugging/optimization) */
+    estimatedTokens: number;
+}
+/**
+ * Default identity module - only included when NO role is specified
+ * When a specialized role (pm, arch, qa, etc.) is used, this is skipped
+ * and the role's identity is prepended instead.
+ */
+export declare const IDENTITY_MODULE: SystemPromptModule;
+/**
+ * Style module - always included
+ * Defines tone, style, and behavioral guidelines that apply to ALL agents
+ */
+export declare const STYLE_MODULE: SystemPromptModule;
+/**
+ * Task execution module - always included
+ * Defines how to approach coding tasks
+ */
+export declare const TASK_EXECUTION_MODULE: SystemPromptModule;
+/**
+ * Todo management module - always included
+ * Defines how to use the todo_write tool
+ */
+export declare const TODO_MANAGEMENT_MODULE: SystemPromptModule;
+/**
+ * Tool usage module (direct tools) - always included
+ * Lists tools that are always available
+ */
+export declare const TOOL_USAGE_DIRECT_MODULE: SystemPromptModule;
+/**
+ * Tool usage module (meta-tools) - only if enableMetaTools=true
+ * Explains how to use specialized tools via meta-tools
+ */
+export declare const TOOL_USAGE_META_MODULE: SystemPromptModule;
+/**
+ * Token delegation module - always included
+ * CRITICAL for token efficiency - teaches agent to use sub-agents
+ */
+export declare const DELEGATION_MODULE: SystemPromptModule;
+/**
+ * Git safety module - only if hasGit=true
+ * Defines safety rules for git operations
+ */
+export declare const GIT_SAFETY_MODULE: SystemPromptModule;
+/**
+ * Suggest module - always included
+ * Defines how to use the suggest tool
+ */
+export declare const SUGGEST_MODULE: SystemPromptModule;
+/**
+ * Important rules module - always included
+ * Summary of critical rules
+ */
+export declare const IMPORTANT_RULES_MODULE: SystemPromptModule;
+/**
+ * Environment module - always included
+ * Current working directory and git config
+ * Note: {{PLACEHOLDERS}} are replaced at runtime
+ */
+export declare const ENVIRONMENT_MODULE: SystemPromptModule;
+/**
+ * All modules in the order they should appear in the prompt.
+ * Modules without conditions are always included.
+ */
+export declare const ALL_MODULES: SystemPromptModule[];
+/**
+ * Get total estimated tokens for all modules
+ */
+export declare function getTotalEstimatedTokens(): number;
+/**
+ * Get estimated tokens for modules that match given conditions
+ */
+export declare function getEstimatedTokensForConditions(conditions: {
+    hasGit?: boolean;
+    enableMetaTools?: boolean;
+    mode?: 'flexible' | 'guided' | 'plan';
+    hasProject?: boolean;
+    hasRoleIdentity?: boolean;
+}): number;
+/**
+ * Check if a module should be included based on conditions
+ */
+export declare function shouldIncludeModule(module: SystemPromptModule, context: {
+    hasGit?: boolean;
+    enableMetaTools?: boolean;
+    mode?: 'flexible' | 'guided' | 'plan';
+    hasProject?: boolean;
+    hasRoleIdentity?: boolean;
+}): boolean;