@compilr-dev/sdk 0.2.6 → 0.2.8

package/dist/index.d.ts

@@ -56,7 +56,8 @@ export type { SystemPromptContext, BuildResult, SystemPromptModule, ModuleCondit
 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, IAnchorService, IArtifactService, IEpisodeService, AnchorData, ArtifactType, ArtifactData, ArtifactSummaryData, WorkEpisode, ProjectWorkSummary, PlatformContext, PlatformToolsConfig, PlatformHooks, StepCriteria, } from './platform/index.js';
 export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './platform/index.js';
 export type { SQLiteRepositories, CreateSQLiteRepositoriesOptions, ProjectDeleteHooks, ProjectRecord, WorkItemRecord, ProjectDocumentRecord, } from './platform/index.js';
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, } from './platform/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, ProjectAnchorStore, } from './platform/index.js';
+export type { ProjectAnchorStoreConfig } from './platform/index.js';
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
 export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, } from './skills/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';

package/dist/index.js

@@ -119,7 +119,7 @@ export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemReposi
 // =============================================================================
 // Platform Tools (runtime — createPlatformTools factory + individual factories)
 // =============================================================================
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, } from './platform/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, ProjectAnchorStore, } from './platform/index.js';
 // =============================================================================
 // Platform Workflow (pure step-criteria logic)
 // =============================================================================

package/dist/platform/file-anchor-service.d.ts

@@ -0,0 +1,62 @@
+/**
+ * ProjectAnchorStore — File-based anchor management with dual-scope routing.
+ *
+ * Manages per-project and global anchors using @compilr-dev/agents AnchorManager
+ * with JSON file persistence. Used by both CLI and Desktop app.
+ *
+ * Storage structure:
+ *   {anchorsDir}/
+ *     ├── global.json           # Non-project anchors (includes safety defaults)
+ *     └── project-{id}.json     # Per-project anchors
+ */
+import { AnchorManager } from '@compilr-dev/agents';
+import type { Anchor, AnchorInput, AnchorQueryOptions } from '@compilr-dev/agents';
+import type { IAnchorService } from './services.js';
+export interface ProjectAnchorStoreConfig {
+    /** Directory for anchor JSON files (e.g. ~/.compilr-dev/anchors/) */
+    anchorsDir: string;
+    /** Returns the currently active project ID, or undefined if none */
+    getCurrentProjectId: () => number | undefined;
+    /** Returns display name for a project ID (used in list results) */
+    getProjectName?: (id: number) => string | null | Promise<string | null>;
+    /** Max anchors per manager (default: 50) */
+    maxAnchors?: number;
+    /** Max tokens per manager (default: 4000) */
+    maxTokens?: number;
+}
+export declare class ProjectAnchorStore {
+    private readonly managers;
+    private readonly config;
+    constructor(config: ProjectAnchorStoreConfig);
+    /** Get anchor manager for a project (or global if projectId is null). */
+    getManager(projectId: string | null): AnchorManager;
+    /** Get the global anchor manager (shorthand for getManager(null)). */
+    getGlobalManager(): AnchorManager;
+    /** Add an anchor, routing to the appropriate manager. */
+    addAnchor(input: AnchorInput & {
+        projectId?: string;
+    }): Anchor;
+    /** Get all anchors across all cached managers. */
+    getAllAnchors(options?: AnchorQueryOptions): Anchor[];
+    /** Clear all anchors for a project and delete the persistence file. */
+    clearProjectAnchors(projectId: string): number;
+    /**
+     * Get formatted anchor content for system prompt injection.
+     * Combines global anchors with project-specific anchors.
+     */
+    getFormattedAnchors(projectId?: string): string;
+    /** Get list of project IDs that have anchor files. */
+    getProjectsWithAnchors(): string[];
+    /** Get anchor statistics. */
+    getAnchorStats(): {
+        globalCount: number;
+        projectCounts: Map<string, number>;
+        totalTokens: number;
+    };
+    /** Clear all cached managers (useful for testing or refresh). */
+    clearCache(): void;
+    /** Create an IAnchorService implementation for use with createPlatformTools(). */
+    toService(): IAnchorService;
+    private getPersistPath;
+    private ensureDir;
+}

package/dist/platform/file-anchor-service.js

@@ -0,0 +1,241 @@
+/**
+ * ProjectAnchorStore — File-based anchor management with dual-scope routing.
+ *
+ * Manages per-project and global anchors using @compilr-dev/agents AnchorManager
+ * with JSON file persistence. Used by both CLI and Desktop app.
+ *
+ * Storage structure:
+ *   {anchorsDir}/
+ *     ├── global.json           # Non-project anchors (includes safety defaults)
+ *     └── project-{id}.json     # Per-project anchors
+ */
+import { existsSync, mkdirSync, readdirSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { AnchorManager } from '@compilr-dev/agents';
+// =============================================================================
+// ProjectAnchorStore
+// =============================================================================
+export class ProjectAnchorStore {
+    managers = new Map();
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    // ---------------------------------------------------------------------------
+    // Manager Access
+    // ---------------------------------------------------------------------------
+    /** Get anchor manager for a project (or global if projectId is null). */
+    getManager(projectId) {
+        const existing = this.managers.get(projectId);
+        if (existing) {
+            return existing;
+        }
+        this.ensureDir();
+        const manager = new AnchorManager({
+            persistPath: this.getPersistPath(projectId),
+            includeDefaults: projectId === null,
+            maxAnchors: this.config.maxAnchors ?? 50,
+            maxTokens: this.config.maxTokens ?? 4000,
+        });
+        this.managers.set(projectId, manager);
+        return manager;
+    }
+    /** Get the global anchor manager (shorthand for getManager(null)). */
+    getGlobalManager() {
+        return this.getManager(null);
+    }
+    // ---------------------------------------------------------------------------
+    // Convenience Methods
+    // ---------------------------------------------------------------------------
+    /** Add an anchor, routing to the appropriate manager. */
+    addAnchor(input) {
+        const manager = this.getManager(input.projectId ?? null);
+        return manager.add(input);
+    }
+    /** Get all anchors across all cached managers. */
+    getAllAnchors(options) {
+        const all = [];
+        for (const manager of this.managers.values()) {
+            all.push(...manager.getAll(options));
+        }
+        return all;
+    }
+    /** Clear all anchors for a project and delete the persistence file. */
+    clearProjectAnchors(projectId) {
+        const manager = this.managers.get(projectId);
+        let removed = 0;
+        if (manager) {
+            removed = manager.clear();
+            this.managers.delete(projectId);
+        }
+        const filePath = this.getPersistPath(projectId);
+        if (existsSync(filePath)) {
+            unlinkSync(filePath);
+        }
+        return removed;
+    }
+    /**
+     * Get formatted anchor content for system prompt injection.
+     * Combines global anchors with project-specific anchors.
+     */
+    getFormattedAnchors(projectId) {
+        const parts = [];
+        const globalFormatted = this.getGlobalManager().format();
+        if (globalFormatted) {
+            parts.push(globalFormatted);
+        }
+        if (projectId) {
+            const projectFormatted = this.getManager(projectId).format();
+            if (projectFormatted) {
+                if (parts.length > 0) {
+                    parts.push('');
+                    parts.push(`### Project Anchors (${projectId})`);
+                }
+                parts.push(projectFormatted);
+            }
+        }
+        return parts.join('\n');
+    }
+    /** Get list of project IDs that have anchor files. */
+    getProjectsWithAnchors() {
+        if (!existsSync(this.config.anchorsDir)) {
+            return [];
+        }
+        const files = readdirSync(this.config.anchorsDir);
+        const projectIds = [];
+        for (const file of files) {
+            const match = /^project-(.+)\.json$/.exec(file);
+            if (match?.[1]) {
+                projectIds.push(match[1]);
+            }
+        }
+        return projectIds;
+    }
+    /** Get anchor statistics. */
+    getAnchorStats() {
+        const globalManager = this.getGlobalManager();
+        const projectCounts = new Map();
+        let totalTokens = globalManager.getTotalTokens();
+        for (const projectId of this.getProjectsWithAnchors()) {
+            const manager = this.getManager(projectId);
+            projectCounts.set(projectId, manager.size);
+            totalTokens += manager.getTotalTokens();
+        }
+        return {
+            globalCount: globalManager.size,
+            projectCounts,
+            totalTokens,
+        };
+    }
+    /** Clear all cached managers (useful for testing or refresh). */
+    clearCache() {
+        this.managers.clear();
+    }
+    // ---------------------------------------------------------------------------
+    // IAnchorService — for platform tools
+    // ---------------------------------------------------------------------------
+    /** Create an IAnchorService implementation for use with createPlatformTools(). */
+    toService() {
+        return {
+            add: (input) => {
+                const priority = input.priority ?? 'info';
+                const projId = this.config.getCurrentProjectId();
+                let scope = input.scope;
+                if (!scope) {
+                    scope = projId ? 'project' : 'global';
+                }
+                if (scope === 'project' && !projId) {
+                    throw new Error('Cannot add project-scoped anchor: no active project. Use scope: "global" instead.');
+                }
+                const projectKey = scope === 'project' && projId ? String(projId) : null;
+                const manager = this.getManager(projectKey);
+                const anchor = manager.add({
+                    content: input.content,
+                    priority,
+                    scope: 'persistent',
+                    tags: input.tags,
+                    projectId: projectKey ?? undefined,
+                });
+                return Promise.resolve({
+                    id: anchor.id,
+                    content: anchor.content,
+                    priority: anchor.priority,
+                    scope,
+                    tags: anchor.tags,
+                });
+            },
+            remove: (id) => {
+                let removed = false;
+                let scope;
+                const projId = this.config.getCurrentProjectId();
+                if (projId) {
+                    const projectManager = this.getManager(String(projId));
+                    if (projectManager.has(id)) {
+                        removed = projectManager.remove(id);
+                        scope = 'project';
+                    }
+                }
+                if (!removed) {
+                    const globalManager = this.getGlobalManager();
+                    if (globalManager.has(id)) {
+                        removed = globalManager.remove(id);
+                        scope = 'global';
+                    }
+                }
+                return Promise.resolve({ removed, scope });
+            },
+            list: async (options) => {
+                const projId = this.config.getCurrentProjectId();
+                const scope = options?.scope ?? 'all';
+                const anchors = [];
+                if (scope === 'global' || scope === 'all') {
+                    for (const anchor of this.getGlobalManager().getAll({ priority: options?.priority })) {
+                        anchors.push({
+                            id: anchor.id,
+                            content: anchor.content,
+                            priority: anchor.priority,
+                            scope: 'global',
+                            tags: anchor.tags,
+                        });
+                    }
+                }
+                if ((scope === 'project' || scope === 'all') && projId) {
+                    const projectManager = this.getManager(String(projId));
+                    for (const anchor of projectManager.getAll({ priority: options?.priority })) {
+                        anchors.push({
+                            id: anchor.id,
+                            content: anchor.content,
+                            priority: anchor.priority,
+                            scope: 'project',
+                            tags: anchor.tags,
+                        });
+                    }
+                }
+                // Sort by priority (critical first)
+                const priorityOrder = { critical: 0, safety: 1, info: 2 };
+                anchors.sort((a, b) => {
+                    const pa = priorityOrder[a.priority] ?? 2;
+                    const pb = priorityOrder[b.priority] ?? 2;
+                    return pa - pb;
+                });
+                let activeProjectName = null;
+                if (projId && this.config.getProjectName) {
+                    activeProjectName = await Promise.resolve(this.config.getProjectName(projId));
+                }
+                return { count: anchors.length, activeProjectName, anchors };
+            },
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Private Helpers
+    // ---------------------------------------------------------------------------
+    getPersistPath(projectId) {
+        const filename = projectId ? `project-${projectId}.json` : 'global.json';
+        return join(this.config.anchorsDir, filename);
+    }
+    ensureDir() {
+        if (!existsSync(this.config.anchorsDir)) {
+            mkdirSync(this.config.anchorsDir, { recursive: true });
+        }
+    }
+}

package/dist/platform/index.d.ts

@@ -8,5 +8,7 @@ export type { PlatformContext, PlatformToolsConfig, PlatformHooks } from './cont
 export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, } from './tools/index.js';
 export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './sqlite/index.js';
 export type { SQLiteRepositories, CreateSQLiteRepositoriesOptions, ProjectDeleteHooks, ProjectRecord, WorkItemRecord, ProjectDocumentRecord, } from './sqlite/index.js';
+export { ProjectAnchorStore } from './file-anchor-service.js';
+export type { ProjectAnchorStoreConfig } from './file-anchor-service.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

@@ -5,5 +5,7 @@
 export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, } from './tools/index.js';
 // SQLite implementations (concrete repositories)
 export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './sqlite/index.js';
+// File-based anchor service (shared by CLI and Desktop)
+export { ProjectAnchorStore } from './file-anchor-service.js';
 // Workflow (pure step-criteria logic)
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './workflow.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",