@compilr-dev/sdk 0.1.6 → 0.1.8

package/README.md

@@ -0,0 +1,136 @@
+# @compilr-dev/sdk
+
+```
+      \|/
+    ╭══════════╮     ___  ___  _ __ ___  _ __ (_) |_ __
+    ║'  ▐▌  ▐▌ │    / __|/ _ \| '_ ` _ \| '_ \| | | '__|
+    ║          │   | (__| (_) | | | | | | |_) | | | |
+    ╰─═──────═─╯    \___|\___/|_| |_| |_| .__/|_|_|_|
+      \________\                        | | .dev
+                                        |_| sdk
+```
+
+> Universal agent runtime for building AI-powered applications
+
+[![npm version](https://img.shields.io/npm/v/@compilr-dev/sdk.svg)](https://www.npmjs.com/package/@compilr-dev/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> [!WARNING]
+> This package is in beta. APIs may change between minor versions.
+
+## Overview
+
+The SDK sits on top of [@compilr-dev/agents](https://www.npmjs.com/package/@compilr-dev/agents) and [@compilr-dev/agents-coding](https://www.npmjs.com/package/@compilr-dev/agents-coding), providing a high-level API for agent creation, tool assembly, and multi-agent teams. It's the runtime that powers [@compilr-dev/cli](https://www.npmjs.com/package/@compilr-dev/cli).
+
+## Features
+
+- **`createCompilrAgent()`** — three lines to a fully configured AI agent
+- **`createTeam()`** — multi-agent teams with role identity and task handoff
+- **Presets** — `coding` (40+ tools) and `read-only` out of the box
+- **9 LLM Providers** — Claude, OpenAI, Gemini, Ollama, Together, Groq, Fireworks, Perplexity, OpenRouter
+- **System Prompt Builder** — modular, token-aware prompt assembly
+- **Full Re-exports** — use the SDK as your single dependency for the entire compilr-dev stack
+
+## Installation
+
+```bash
+npm install @compilr-dev/sdk
+```
+
+Peer dependencies:
+
+```bash
+npm install @compilr-dev/agents @compilr-dev/agents-coding
+```
+
+## Quick Start
+
+```typescript
+import { createCompilrAgent } from '@compilr-dev/sdk';
+
+const agent = createCompilrAgent({
+  provider: { type: 'anthropic' },
+});
+
+const result = await agent.run('Fix the failing tests in src/auth/');
+console.log(result.response);
+```
+
+### Custom Domain (Non-Coding)
+
+```typescript
+import { createCompilrAgent, defineTool, createSuccessResult } from '@compilr-dev/sdk';
+
+const agent = createCompilrAgent({
+  preset: 'none',
+  systemPrompt: 'You are an HR assistant.',
+  tools: {
+    custom: [
+      defineTool({
+        name: 'search_kb',
+        description: 'Search the knowledge base',
+        parameters: { query: { type: 'string' } },
+        execute: async ({ query }) => createSuccessResult(`Results for: ${query}`),
+      }),
+    ],
+  },
+});
+```
+
+### Multi-Agent Team
+
+```typescript
+import { createTeam } from '@compilr-dev/sdk';
+
+const team = createTeam({
+  agents: {
+    arch: { role: 'architect' },
+    dev: { role: 'developer' },
+  },
+});
+
+await team.run('Add rate limiting to the API');
+```
+
+## Supported Providers
+
+| Provider | Type | Models |
+|----------|------|--------|
+| Anthropic | `anthropic` | Claude 4.5, Claude 4, Claude 3.5 |
+| OpenAI | `openai` | GPT-4o, GPT-4, o1, o3 |
+| Google | `gemini` | Gemini 2.5, Gemini 2.0 |
+| Ollama | `ollama` | Any local model |
+| Together AI | `together` | Llama, Qwen, DeepSeek |
+| Groq | `groq` | Llama, Mixtral |
+| Fireworks | `fireworks` | Llama, Qwen |
+| Perplexity | `perplexity` | Sonar models |
+| OpenRouter | `openrouter` | Multi-provider routing |
+
+## Requirements
+
+- Node.js >= 18
+- Peer dependencies: `@compilr-dev/agents` ^0.3.14, `@compilr-dev/agents-coding` ^1.0.2
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [@compilr-dev/cli](https://www.npmjs.com/package/@compilr-dev/cli) | AI-powered coding assistant for your terminal |
+| [@compilr-dev/agents](https://www.npmjs.com/package/@compilr-dev/agents) | Multi-LLM agent library |
+| [@compilr-dev/agents-coding](https://www.npmjs.com/package/@compilr-dev/agents-coding) | Coding-specific tools and language analysis |
+
+## Links
+
+- [Website](https://compilr.dev)
+- [npm Package](https://www.npmjs.com/package/@compilr-dev/sdk)
+- [Report Issues](https://github.com/compilr-dev/sdk/issues)
+
+## License
+
+MIT - See [LICENSE](LICENSE) for details.
+
+---
+
+<p align="center">
+  <strong>Built with care by <a href="https://compilr.dev">compilr.dev</a></strong>
+</p>

package/dist/index.d.ts

@@ -47,6 +47,9 @@ export { MetaToolsRegistry, createMetaTools, META_TOOLS_SYSTEM_PROMPT_PREFIX, }
 export type { MetaToolStats, MetaTools } from './meta-tools/index.js';
 export { SystemPromptBuilder, buildSystemPrompt, detectGitRepository, getModuleStats, 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 './system-prompt/index.js';
 export type { SystemPromptContext, BuildResult, SystemPromptModule, ModuleConditions, } from './system-prompt/index.js';
+export type { ProjectType, ProjectStatus, RepoPattern, WorkflowMode, LifecycleState, WorkItemType, WorkItemStatus, WorkItemPriority, GuidedStep, DocumentType, PlanStatus, Project, WorkItem, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, PlatformContext, PlatformToolsConfig, PlatformHooks, StepCriteria, } from './platform/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, } from './platform/index.js';
+export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
 export { defineTool, createSuccessResult, createErrorResult, mergeHooks, createLoggingHooks, createClaudeProvider, createOpenAIProvider, createGeminiNativeProvider, createOllamaProvider, createTogetherProvider, createGroqProvider, createFireworksProvider, createPerplexityProvider, createOpenRouterProvider, createMockProvider, MockProvider, Agent, ContextManager, DEFAULT_CONTEXT_CONFIG, createTaskTool, createSuggestTool, defaultAgentTypes, TOOL_SETS, BUILTIN_GUARDRAILS, TOOL_NAMES, getDefaultShellManager, builtinSkills, AnchorManager, MCPManager, AgentError, ProviderError, ToolError, ToolTimeoutError, MaxIterationsError, AbortError, } from '@compilr-dev/agents';
 export type { Tool, HooksConfig, AgentEvent, Message, LLMProvider, AnchorInput, ToolExecutionResult, AgentRunResult, PermissionHandler, ToolPermission, AgentTypeConfig, GuardrailTriggeredHandler, BeforeLLMHookResult, BeforeToolHook, BeforeToolHookResult, AfterToolHook, AgentState, AgentConfig, SessionInfo, Anchor, AnchorScope, AnchorClearOptions, AnchorPriority, AnchorQueryOptions, FileAccessType, FileAccess, GuardrailResult, GuardrailContext, MCPClient, MCPToolDefinition, } from '@compilr-dev/agents';
 export { readFileTool, writeFileTool, createBashTool, bashTool, bashOutputTool, killShellTool, grepTool, globTool, editTool, todoWriteTool, todoReadTool, createTodoTools, TodoStore, webFetchTool, suggestTool, } from '@compilr-dev/agents';

package/dist/index.js

@@ -75,6 +75,14 @@ ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEME
 // Module utilities
 shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, } from './system-prompt/index.js';
 // =============================================================================
+// Platform Tools (runtime — createPlatformTools factory + individual factories)
+// =============================================================================
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, } from './platform/index.js';
+// =============================================================================
+// Platform Workflow (pure step-criteria logic)
+// =============================================================================
+export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
+// =============================================================================
 // Re-exports from @compilr-dev/agents (convenience — no need to install separately)
 // =============================================================================
 export { 

package/dist/platform/context.d.ts

@@ -0,0 +1,44 @@
+/**
+ * PlatformContext — Unified access to all platform repositories.
+ *
+ * Provides a single entry point for data access, abstracting over the
+ * underlying storage backend (SQLite in CLI, PostgreSQL in web/API).
+ */
+import type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository } from './repositories.js';
+export interface PlatformContext {
+    readonly projects: IProjectRepository;
+    readonly workItems: IWorkItemRepository;
+    readonly documents: IDocumentRepository;
+    readonly plans: IPlanRepository;
+    currentProjectId?: number;
+}
+export interface PlatformHooks {
+    /** Called when a project is resolved/selected as the current project */
+    onProjectResolved?: (project: {
+        id: number;
+        name: string;
+        displayName: string;
+        path: string;
+    }) => void;
+    /** Called when a work item is completed */
+    onWorkItemCompleted?: (item: {
+        id: number;
+        itemId: string;
+        title: string;
+    }) => void;
+    /** Called when the first project is created (for gamification) */
+    onFirstProject?: (project: {
+        id: number;
+        name: string;
+    }) => void;
+    /** Resolve owner aliases (e.g., 'self' → active agent ID) */
+    resolveOwner?: (alias: 'self') => string | undefined;
+}
+export interface PlatformToolsConfig {
+    /** Data access layer */
+    context: PlatformContext;
+    /** Working directory override (defaults to process.cwd()) */
+    cwd?: string;
+    /** Optional hooks for CLI-specific side effects */
+    hooks?: PlatformHooks;
+}

package/dist/platform/context.js

@@ -0,0 +1,7 @@
+/**
+ * PlatformContext — Unified access to all platform repositories.
+ *
+ * Provides a single entry point for data access, abstracting over the
+ * underlying storage backend (SQLite in CLI, PostgreSQL in web/API).
+ */
+export {};

package/dist/platform/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Platform — Repository interfaces, data models, tools, and workflow.
+ */
+export type { ProjectType, ProjectStatus, RepoPattern, WorkflowMode, LifecycleState, WorkItemType, WorkItemStatus, WorkItemPriority, GuidedStep, DocumentType, PlanStatus, Project, WorkItem, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, } from './types.js';
+export type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, } from './repositories.js';
+export type { PlatformContext, PlatformToolsConfig, PlatformHooks } from './context.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, } from './tools/index.js';
+export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './workflow.js';
+export type { StepCriteria } from './workflow.js';

package/dist/platform/index.js

@@ -0,0 +1,7 @@
+/**
+ * Platform — Repository interfaces, data models, tools, and workflow.
+ */
+// Platform tools (runtime)
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, } from './tools/index.js';
+// Workflow (pure step-criteria logic)
+export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './workflow.js';

package/dist/platform/repositories.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Repository Interfaces — Storage-agnostic data access contracts.
+ *
+ * All methods return Promise<T> even though the current CLI implementation
+ * uses synchronous SQLite. This ensures compatibility with future async
+ * backends (PostgreSQL, HTTP APIs).
+ */
+import type { Project, WorkItem, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, ProjectStatus, WorkItemType, WorkItemStatus, DocumentType, PlanStatus } from './types.js';
+export interface IProjectRepository {
+    create(input: CreateProjectInput): Promise<Project>;
+    getById(id: number): Promise<Project | null>;
+    getByName(name: string): Promise<Project | null>;
+    getByPath(path: string): Promise<Project | null>;
+    getByDocsPath(docsPath: string): Promise<Project | null>;
+    findByPath(searchPath: string): Promise<Project | null>;
+    list(options?: ProjectListOptions): Promise<ProjectListResult>;
+    update(id: number, input: UpdateProjectInput): Promise<Project | null>;
+    touch(id: number): Promise<void>;
+    delete(id: number): Promise<boolean>;
+    archive(id: number): Promise<Project | null>;
+    isNameAvailable(name: string, excludeId?: number): Promise<boolean>;
+    getStatusCounts(): Promise<Record<ProjectStatus, number>>;
+}
+export interface IWorkItemRepository {
+    create(input: CreateWorkItemInput): Promise<WorkItem>;
+    getById(id: number): Promise<WorkItem | null>;
+    getByItemId(projectId: number, itemId: string): Promise<WorkItem | null>;
+    query(input: QueryWorkItemsInput): Promise<WorkItemQueryResult>;
+    getNext(projectId: number, type?: WorkItemType): Promise<WorkItem | null>;
+    update(id: number, input: UpdateWorkItemInput): Promise<WorkItem | null>;
+    delete(id: number): Promise<boolean>;
+    getByOwner(projectId: number, owner: string, status?: WorkItemStatus): Promise<WorkItem[]>;
+    getOwnerCounts(projectId: number): Promise<Record<string, number>>;
+    getStatusCounts(projectId: number): Promise<Record<WorkItemStatus, number>>;
+    getHistory(workItemId: number): Promise<HistoryEntry[]>;
+    bulkCreate(projectId: number, items: BulkCreateItem[]): Promise<WorkItem[]>;
+}
+export interface IDocumentRepository {
+    upsert(input: CreateDocumentInput): Promise<ProjectDocument>;
+    create(input: CreateDocumentInput): Promise<ProjectDocument>;
+    getById(id: number): Promise<ProjectDocument | null>;
+    getByType(projectId: number, docType: DocumentType): Promise<ProjectDocument | null>;
+    listByProject(projectId: number): Promise<ProjectDocument[]>;
+    update(id: number, input: UpdateDocumentInput): Promise<ProjectDocument | null>;
+    delete(id: number): Promise<boolean>;
+    deleteByType(projectId: number, docType: DocumentType): Promise<boolean>;
+    getTypeCounts(projectId: number): Promise<Record<DocumentType, number>>;
+}
+export interface IPlanRepository {
+    create(input: CreatePlanInput): Promise<Plan>;
+    getById(id: number): Promise<Plan | null>;
+    getByName(projectId: number, name: string): Promise<Plan | null>;
+    getWithWorkItem(id: number): Promise<PlanWithWorkItem | null>;
+    update(id: number, input: UpdatePlanInput): Promise<Plan | null>;
+    delete(id: number): Promise<boolean>;
+    list(projectId: number, options?: ListPlansOptions): Promise<PlanSummary[]>;
+    countByStatus(projectId: number): Promise<Record<PlanStatus, number>>;
+    getInProgress(projectId: number): Promise<PlanSummary[]>;
+    hasInProgress(projectId: number): Promise<boolean>;
+    linkWorkItem(planId: number, workItemId: number): Promise<Plan | null>;
+    unlinkWorkItem(planId: number): Promise<Plan | null>;
+}

package/dist/platform/repositories.js

@@ -0,0 +1,8 @@
+/**
+ * Repository Interfaces — Storage-agnostic data access contracts.
+ *
+ * All methods return Promise<T> even though the current CLI implementation
+ * uses synchronous SQLite. This ensures compatibility with future async
+ * backends (PostgreSQL, HTTP APIs).
+ */
+export {};

package/dist/platform/tools/backlog-tools.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Backlog Wrapper Tools — Library-compatible backlog interface over work items.
+ *
+ * 2 tools: backlog_read, backlog_write
+ *
+ * These wrappers provide `backlog_read` and `backlog_write` tools that skills expect,
+ * but internally delegate to the work item repository. This allows library skills
+ * (which reference backlog_*) to work seamlessly with the database-backed work items.
+ *
+ * Ported from CLI's src/tools/backlog-wrappers.ts.
+ */
+import type { PlatformToolsConfig } from '../context.js';
+export declare function createBacklogTools(config: PlatformToolsConfig): (import("@compilr-dev/agents").Tool<{
+    id?: string;
+    status?: string;
+    type?: string;
+    search?: string;
+    priority?: string;
+    limit?: number;
+}> | import("@compilr-dev/agents").Tool<{
+    action: string;
+    item?: {
+        id?: string;
+        type?: string;
+        title?: string;
+        description?: string;
+        status?: string;
+        priority?: string;
+        owner?: string;
+        commit_hash?: string;
+    };
+    deleteId?: string;
+    items?: Array<{
+        id?: string;
+        type: string;
+        title: string;
+        description?: string;
+        status?: string;
+        priority?: string;
+    }>;
+}>)[];