@compilr-dev/sdk 0.11.0 → 0.13.0

package/dist/host/index.d.ts

@@ -11,3 +11,5 @@ export { ensureFreshToken } from './token.js';
 export type { EnsureFreshTokenOptions, FreshToken } from './token.js';
 export { runDeviceFlow, nextPollInterval } from './device-flow.js';
 export type { DeviceFlowStatus, DeviceFlowCallbacks, LoginResult, RunDeviceFlowOptions, } from './device-flow.js';
+export { loadProjectContextFiles, hasProjectContextFile, PROJECT_CONTEXT_FILES, } from './project-context.js';
+export type { ProjectContextResult, LoadProjectContextOptions } from './project-context.js';

package/dist/host/index.js

@@ -8,3 +8,5 @@ export { refreshToken, sendHeartbeat, getProfile, updateProfile, requestDeviceCo
 export { loadAuthData, saveAuthData, clearAuthData, updateSession, hasAuthData, checkAuthFilePermissions, readAuthFile, writeAuthFile, } from './auth-store.js';
 export { ensureFreshToken } from './token.js';
 export { runDeviceFlow, nextPollInterval } from './device-flow.js';
+// ── Project context files (COMPILR.md / CLAUDE.md → system prompt) ────────────
+export { loadProjectContextFiles, hasProjectContextFile, PROJECT_CONTEXT_FILES, } from './project-context.js';

package/dist/host/project-context.d.ts

@@ -0,0 +1,43 @@
+/**
+ * loadProjectContextFiles — read a project's instruction file (COMPILR.md etc.)
+ * for injection into the system prompt.
+ *
+ * Shared by CLI and Desktop: the CLI had this logic in utils/project-memory.ts
+ * and Desktop hand-rolled a thinner inline 2-file version. This is the single
+ * implementation — searches a priority-ordered list, size-guards/truncates large
+ * files, and reports metadata.
+ *
+ * Pure file read; no fs writes, no electron. `estimatedTokens` is a cheap
+ * chars/4 heuristic (callers that need a real count tokenize themselves).
+ */
+/** Instruction files searched, in priority order. */
+export declare const PROJECT_CONTEXT_FILES: readonly ["COMPILR.md", ".compilr/instructions.md", "CLAUDE.md", ".claude/instructions.md"];
+export interface ProjectContextResult {
+    /** Whether an instruction file was found. */
+    found: boolean;
+    /** Loaded content (possibly truncated); '' when not found. */
+    content: string;
+    /** Path of the file that was loaded, or null. */
+    filePath: string | null;
+    /** Original file size in bytes. */
+    originalSize: number;
+    /** Whether the content was truncated due to size. */
+    truncated: boolean;
+    /** Rough token estimate (chars / 4). */
+    estimatedTokens: number;
+}
+export interface LoadProjectContextOptions {
+    /** Directory to search (default: process.cwd()). */
+    cwd?: string;
+    /** Max content bytes before truncation (default: 100KB). */
+    maxSize?: number;
+    /** Override the filenames searched, in priority order. */
+    files?: readonly string[];
+}
+/**
+ * Load the first matching project instruction file from `cwd`. Returns a
+ * not-found result (never throws) if none exists or all are unreadable.
+ */
+export declare function loadProjectContextFiles(options?: LoadProjectContextOptions): ProjectContextResult;
+/** Quick existence check (no read) for any project instruction file. */
+export declare function hasProjectContextFile(cwd?: string): boolean;

package/dist/host/project-context.js

@@ -0,0 +1,76 @@
+/**
+ * loadProjectContextFiles — read a project's instruction file (COMPILR.md etc.)
+ * for injection into the system prompt.
+ *
+ * Shared by CLI and Desktop: the CLI had this logic in utils/project-memory.ts
+ * and Desktop hand-rolled a thinner inline 2-file version. This is the single
+ * implementation — searches a priority-ordered list, size-guards/truncates large
+ * files, and reports metadata.
+ *
+ * Pure file read; no fs writes, no electron. `estimatedTokens` is a cheap
+ * chars/4 heuristic (callers that need a real count tokenize themselves).
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** Instruction files searched, in priority order. */
+export const PROJECT_CONTEXT_FILES = [
+    'COMPILR.md',
+    '.compilr/instructions.md',
+    'CLAUDE.md',
+    '.claude/instructions.md',
+];
+/** Default max content size before truncation: 100KB. */
+const DEFAULT_MAX_SIZE = 100 * 1024;
+/**
+ * Load the first matching project instruction file from `cwd`. Returns a
+ * not-found result (never throws) if none exists or all are unreadable.
+ */
+export function loadProjectContextFiles(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const maxSize = options.maxSize ?? DEFAULT_MAX_SIZE;
+    const files = options.files ?? PROJECT_CONTEXT_FILES;
+    for (const filename of files) {
+        const filePath = join(cwd, filename);
+        if (!existsSync(filePath))
+            continue;
+        try {
+            const originalSize = statSync(filePath).size;
+            let content = readFileSync(filePath, 'utf-8');
+            let truncated = false;
+            if (content.length > maxSize) {
+                content = content.slice(0, maxSize);
+                // Prefer a line boundary if one is reasonably close to the cut.
+                const lastNewline = content.lastIndexOf('\n');
+                if (lastNewline > maxSize * 0.8) {
+                    content = content.slice(0, lastNewline);
+                }
+                content += '\n\n[... truncated due to size ...]';
+                truncated = true;
+            }
+            return {
+                found: true,
+                content,
+                filePath,
+                originalSize,
+                truncated,
+                estimatedTokens: Math.ceil(content.length / 4),
+            };
+        }
+        catch {
+            // Exists but unreadable — try the next candidate.
+            continue;
+        }
+    }
+    return {
+        found: false,
+        content: '',
+        filePath: null,
+        originalSize: 0,
+        truncated: false,
+        estimatedTokens: 0,
+    };
+}
+/** Quick existence check (no read) for any project instruction file. */
+export function hasProjectContextFile(cwd = process.cwd()) {
+    return PROJECT_CONTEXT_FILES.some((f) => existsSync(join(cwd, f)));
+}

package/dist/index.d.ts

@@ -64,8 +64,8 @@ export { detectProject, suggestProjectType, detectCommon } from './detection/ind
 export type { DetectProjectOptions, DetectionResult, ContentSummary } from './detection/index.js';
 export { createGuideTool, SHARED_GUIDE_ENTRIES, searchGuideEntries, topicToGuideEntry, } from './guide/index.js';
 export type { GuideEntry, ContentTopic, ContentSection, GuideToolConfig } from './guide/index.js';
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, ProjectAnchorStore, } from './platform/index.js';
-export type { ProjectAnchorStoreConfig, ImageToolsConfig, ImageResizer } from './platform/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, ProjectAnchorStore, FileArtifactService, } from './platform/index.js';
+export type { ProjectAnchorStoreConfig, FileArtifactServiceConfig, ImageToolsConfig, ImageResizer, } from './platform/index.js';
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
 export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker, SkillEligibilityContext, SkillCollision, SkillDiffLine, SkillValidationIssue, ScopeConfig, SkillResolution, } from './skills/index.js';
 export { RESERVED_SKILL_NAMES, isReservedSkillName, parseSkillMarkdown, loadSkillsFromDir, resolveLayeredSkills, resolveSkillsForAgent, detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill as validateSkillQuality, getSkillsDir, getSkillFolder, getSkillFile, ensureSkillsDir, isValidSkillName, getScopeConfigPath, readSkillScopeConfig, readSkillScopeConfigSync, writeSkillScopeConfig, getSkillBindings, resolveSkillBinding, } from './skills/index.js';
@@ -83,8 +83,8 @@ export { DEFAULT_PERMISSION_RULES, WRITE_TOOLS, findMatchingRule, permissionMode
 export type { PermissionRule, PermissionMode, PermissionLevel } from './permissions.js';
 export { SHARED_DEFAULTS, migrateRawSettings } from './host/index.js';
 export type { HostSettings, SettingsProviderType, TextSize, NotificationMode, Verbosity, CompactMode, ProjectSessionMode, MascotSetting, StartupMode, ProjectStartupMode, StartupBehavior, DefaultLeftPanel, TipsProficiency, } from './host/index.js';
-export { refreshToken, sendHeartbeat, getProfile, updateProfile, requestDeviceCode, pollDeviceToken, getAuthorizationUrl, loadAuthData, saveAuthData, clearAuthData, updateSession, hasAuthData, checkAuthFilePermissions, readAuthFile, writeAuthFile, ensureFreshToken, runDeviceFlow, nextPollInterval, } from './host/index.js';
-export type { AccountType, AuthUser, AuthSession, AuthData, RefreshTokenResponse, ProfileData, HeartbeatData, DeviceCodeResponse, DeviceTokenResponse, DeviceTokenError, AuthEndpoints, EnsureFreshTokenOptions, FreshToken, DeviceFlowStatus, DeviceFlowCallbacks, LoginResult, RunDeviceFlowOptions, } from './host/index.js';
+export { refreshToken, sendHeartbeat, getProfile, updateProfile, requestDeviceCode, pollDeviceToken, getAuthorizationUrl, loadAuthData, saveAuthData, clearAuthData, updateSession, hasAuthData, checkAuthFilePermissions, readAuthFile, writeAuthFile, ensureFreshToken, runDeviceFlow, nextPollInterval, loadProjectContextFiles, hasProjectContextFile, PROJECT_CONTEXT_FILES, } from './host/index.js';
+export type { AccountType, AuthUser, AuthSession, AuthData, RefreshTokenResponse, ProfileData, HeartbeatData, DeviceCodeResponse, DeviceTokenResponse, DeviceTokenError, AuthEndpoints, EnsureFreshTokenOptions, FreshToken, DeviceFlowStatus, DeviceFlowCallbacks, LoginResult, RunDeviceFlowOptions, ProjectContextResult, LoadProjectContextOptions, } from './host/index.js';
 export { DEFAULT_DELEGATION_CONFIG } from './delegation.js';
 export { FileEpisodeStore, EpisodeRecorder, isSignificantWork, extractAffectedFiles, extractLinesChanged, queryWorkAtRisk, buildWorkSummaryContent, updateWorkSummaryAnchor, } from './episodes/index.js';
 export type { FileEpisodeStoreOptions, EpisodeRecorderConfig, WorkSummaryAnchorConfig, PendingToolSignal, EpisodeFile, } from './episodes/index.js';

package/dist/index.js

@@ -147,7 +147,7 @@ export { createGuideTool, SHARED_GUIDE_ENTRIES, searchGuideEntries, topicToGuide
 // =============================================================================
 // Platform Tools (runtime — createPlatformTools factory + individual factories)
 // =============================================================================
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, ProjectAnchorStore, } from './platform/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, ProjectAnchorStore, FileArtifactService, } from './platform/index.js';
 // =============================================================================
 // Platform Workflow (pure step-criteria logic)
 // =============================================================================
@@ -202,7 +202,7 @@ export { DEFAULT_PERMISSION_RULES, WRITE_TOOLS, findMatchingRule, permissionMode
 // =============================================================================
 export { SHARED_DEFAULTS, migrateRawSettings } from './host/index.js';
 // Auth: shared backend client, credential store, token refresh, device flow.
-export { refreshToken, sendHeartbeat, getProfile, updateProfile, requestDeviceCode, pollDeviceToken, getAuthorizationUrl, loadAuthData, saveAuthData, clearAuthData, updateSession, hasAuthData, checkAuthFilePermissions, readAuthFile, writeAuthFile, ensureFreshToken, runDeviceFlow, nextPollInterval, } from './host/index.js';
+export { refreshToken, sendHeartbeat, getProfile, updateProfile, requestDeviceCode, pollDeviceToken, getAuthorizationUrl, loadAuthData, saveAuthData, clearAuthData, updateSession, hasAuthData, checkAuthFilePermissions, readAuthFile, writeAuthFile, ensureFreshToken, runDeviceFlow, nextPollInterval, loadProjectContextFiles, hasProjectContextFile, PROJECT_CONTEXT_FILES, } from './host/index.js';
 // =============================================================================
 // Shared Delegation Config Defaults
 // =============================================================================

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

@@ -0,0 +1,55 @@
+/**
+ * FileArtifactService — file-backed IArtifactService shared by CLI and Desktop.
+ *
+ * Both hosts previously hand-rolled identical artifact CRUD on top of the SDK's
+ * ArtifactStore, reading/writing the SAME file:
+ *   {sessionsDir}/{global | project-<id>}/artifacts/artifacts.json
+ * This consolidates that logic next to FileEpisodeStore / ProjectAnchorStore.
+ *
+ * Each operation does a fresh load → mutate → save (the file is the source of
+ * truth, shared per-project across terminals), matching the prior behavior.
+ *
+ * Hosts wire in:
+ *  - getProjectId: resolved per call, so the service follows project switches
+ *  - onSaved (optional): fired after a create/update persists — the CLI uses it
+ *    to record team activity; Desktop omits it
+ *  - onError (optional): load/save failures, so each host logs as it sees fit
+ */
+import type { IArtifactService, ArtifactData, ArtifactSummaryData, ArtifactType } from './services.js';
+export interface FileArtifactServiceConfig {
+    /** Sessions root, e.g. ~/.compilr-dev/sessions */
+    sessionsDir: string;
+    /** Active project id (null = global), resolved on every call. */
+    getProjectId: () => number | null;
+    /** Fired after a successful create/update persists. */
+    onSaved?: (artifact: ArtifactData, isUpdate: boolean) => void;
+    /** Fired on a load/save failure (host decides how to log). */
+    onError?: (err: unknown, op: 'load' | 'save') => void;
+}
+export declare class FileArtifactService implements IArtifactService {
+    private readonly config;
+    constructor(config: FileArtifactServiceConfig);
+    private artifactsDir;
+    private dataFile;
+    /** Load the artifact store for a project from disk (empty store if absent). */
+    private loadStore;
+    /** Persist the artifact store for a project to disk. */
+    private saveStore;
+    save(input: {
+        name: string;
+        type: ArtifactType;
+        content: string;
+        summary?: string;
+        agent?: string;
+    }): Promise<{
+        artifact: ArtifactData;
+        isUpdate: boolean;
+    }>;
+    getByName(name: string): Promise<ArtifactData | null>;
+    list(options?: {
+        type?: ArtifactType;
+        agent?: string;
+        search?: string;
+    }): Promise<ArtifactSummaryData[]>;
+    delete(name: string): Promise<ArtifactData | null>;
+}

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

@@ -0,0 +1,140 @@
+/**
+ * FileArtifactService — file-backed IArtifactService shared by CLI and Desktop.
+ *
+ * Both hosts previously hand-rolled identical artifact CRUD on top of the SDK's
+ * ArtifactStore, reading/writing the SAME file:
+ *   {sessionsDir}/{global | project-<id>}/artifacts/artifacts.json
+ * This consolidates that logic next to FileEpisodeStore / ProjectAnchorStore.
+ *
+ * Each operation does a fresh load → mutate → save (the file is the source of
+ * truth, shared per-project across terminals), matching the prior behavior.
+ *
+ * Hosts wire in:
+ *  - getProjectId: resolved per call, so the service follows project switches
+ *  - onSaved (optional): fired after a create/update persists — the CLI uses it
+ *    to record team activity; Desktop omits it
+ *  - onError (optional): load/save failures, so each host logs as it sees fit
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { ArtifactStore } from '../team/artifacts.js';
+function toArtifactData(a) {
+    return {
+        id: a.id,
+        name: a.name,
+        agent: a.agent,
+        type: a.type,
+        content: a.content,
+        summary: a.summary,
+        version: a.version,
+        createdAt: a.createdAt,
+        updatedAt: a.updatedAt,
+    };
+}
+export class FileArtifactService {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    artifactsDir(projectId) {
+        const projectDir = projectId === null
+            ? join(this.config.sessionsDir, 'global')
+            : join(this.config.sessionsDir, `project-${String(projectId)}`);
+        return join(projectDir, 'artifacts');
+    }
+    dataFile(projectId) {
+        return join(this.artifactsDir(projectId), 'artifacts.json');
+    }
+    /** Load the artifact store for a project from disk (empty store if absent). */
+    loadStore(projectId) {
+        const store = new ArtifactStore();
+        const file = this.dataFile(projectId);
+        if (!existsSync(file))
+            return store;
+        try {
+            const data = JSON.parse(readFileSync(file, 'utf-8'));
+            store.restore(data);
+        }
+        catch (err) {
+            // Corrupt/unreadable — start fresh rather than crash the tool call.
+            this.config.onError?.(err, 'load');
+        }
+        return store;
+    }
+    /** Persist the artifact store for a project to disk. */
+    saveStore(projectId, store) {
+        const dir = this.artifactsDir(projectId);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        try {
+            writeFileSync(this.dataFile(projectId), JSON.stringify(store.serialize(), null, 2), 'utf-8');
+        }
+        catch (err) {
+            this.config.onError?.(err, 'save');
+        }
+    }
+    save(input) {
+        const projectId = this.config.getProjectId();
+        const store = this.loadStore(projectId);
+        const agentId = input.agent ?? 'default';
+        const existing = store.getByName(input.name);
+        if (existing) {
+            const updated = store.update(existing.id, {
+                content: input.content,
+                summary: input.summary,
+                type: input.type,
+            });
+            if (!updated)
+                throw new Error(`Failed to update artifact "${input.name}"`);
+            this.saveStore(projectId, store);
+            const artifact = toArtifactData(updated);
+            this.config.onSaved?.(artifact, true);
+            return Promise.resolve({ artifact, isUpdate: true });
+        }
+        const created = store.create({
+            name: input.name,
+            agent: agentId,
+            type: input.type,
+            content: input.content,
+            summary: input.summary,
+        });
+        this.saveStore(projectId, store);
+        const artifact = toArtifactData(created);
+        this.config.onSaved?.(artifact, false);
+        return Promise.resolve({ artifact, isUpdate: false });
+    }
+    getByName(name) {
+        const store = this.loadStore(this.config.getProjectId());
+        const a = store.getByName(name);
+        return Promise.resolve(a ? toArtifactData(a) : null);
+    }
+    list(options) {
+        const store = this.loadStore(this.config.getProjectId());
+        let items = options?.search ? store.search(options.search) : store.list();
+        if (options?.type)
+            items = items.filter((a) => a.type === options.type);
+        if (options?.agent)
+            items = items.filter((a) => a.agent === options.agent);
+        const summaries = items.map((a) => ({
+            id: a.id,
+            name: a.name,
+            agent: a.agent,
+            type: a.type,
+            summary: a.summary,
+            version: a.version,
+            updatedAt: a.updatedAt,
+        }));
+        return Promise.resolve(summaries);
+    }
+    delete(name) {
+        const projectId = this.config.getProjectId();
+        const store = this.loadStore(projectId);
+        const a = store.getByName(name);
+        if (!a)
+            return Promise.resolve(null);
+        if (!store.delete(a.id))
+            return Promise.resolve(null);
+        this.saveStore(projectId, store);
+        return Promise.resolve(toArtifactData(a));
+    }
+}

package/dist/platform/index.d.ts

@@ -11,5 +11,7 @@ export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemReposi
 export type { SQLiteRepositories, CreateSQLiteRepositoriesOptions, ProjectDeleteHooks, ProjectRecord, WorkItemRecord, ProjectDocumentRecord, WorkItemCommentRecord, } from './sqlite/index.js';
 export { ProjectAnchorStore } from './file-anchor-service.js';
 export type { ProjectAnchorStoreConfig } from './file-anchor-service.js';
+export { FileArtifactService } from './file-artifact-service.js';
+export type { FileArtifactServiceConfig } from './file-artifact-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

@@ -7,5 +7,7 @@ export { createPlatformTools, createProjectTools, createWorkItemTools, createDoc
 export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, SQLiteCommentRepository, 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';
+// File-based artifact service (shared by CLI and Desktop)
+export { FileArtifactService } from './file-artifact-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.11.0",
+  "version": "0.13.0",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",