@compilr-dev/sdk 0.10.41 → 0.12.0

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/dist/skills/software-skills.js

@@ -60,10 +60,14 @@ When you have enough information:
    - Nice-to-haves (type: feature, priority: medium/low)
    - Technical setup tasks (type: chore, priority: high)
    - Known risks/unknowns (type: tech-debt, priority: medium)
-4. Update the PRD.md file with gathered requirements:
-   - Use the edit tool to update PRD.md (located in .compilr/requirements/PRD.md or {project}-docs/00-requirements/PRD.md)
+4. Save the PRD to the project DATABASE (never a file):
+   - Check for an existing PRD first: project_document_get({ doc_type: "prd" })
+   - If none exists, create it:
+     project_document_add({ doc_type: "prd", title: "Product Requirements Document", content: "<full markdown>" })
+   - If one exists, update it section by section:
+     project_document_patch({ doc_type: "prd", operation: "replace_section", section_heading: "## <heading>", content: "..." })
    - Fill in: Problem Statement, Goals, User Stories, Functional Requirements
-   - Keep the existing structure, just replace placeholder text
+   - CRITICAL: project documents live in the database. NEVER use write_file / edit / bash mkdir to create a PRD.md file on disk.
 5. Present the backlog and PRD summary to user for confirmation
    - If CHORE-001 was added, mention: "Run /scaffold to create the project foundation"
 6. If the project involves managing entities (CRUD operations on things like users, orders, products):
@@ -83,7 +87,7 @@ When you have enough information:
 ✓ MVP features are defined
 ✓ Backlog has 5-15 items
 ✓ For fresh projects: CHORE-001 scaffolding item is first (critical priority)
-✓ PRD.md is populated with requirements
+✓ PRD saved to the database (doc_type: prd) — not written to a file
 ✓ If entity-based: user informed about /scaffold auto-generation
 ✓ User has approved the backlog`,
     tags: ['planning', 'requirements'],
@@ -440,11 +444,12 @@ export const prdSkill = defineSkill({
    - "Read current PRD"
    - "Identify section to update"
    - "Gather updates"
-   - "Write updated PRD"
+   - "Save updated PRD"
 
-2. Read the existing PRD.md:
-   - Location: .compilr/requirements/PRD.md or {project}-docs/00-requirements/PRD.md
-   - If no PRD exists, inform the user to run /design first
+2. Read the existing PRD from the project DATABASE:
+   - Use project_document_get({ doc_type: "prd" })
+   - If it returns no document, inform the user to run /design first
+   - The PRD is a database document, NOT a file — never read PRD.md from disk
 
 3. Present current PRD sections to user using ask_user_simple:
    - Question: "Which section would you like to update?"
@@ -482,21 +487,23 @@ Based on section selected:
    - What to add/change
    - What to remove
    - Any clarifications
-3. Use the edit tool to update PRD.md
+3. Save the change to the database with project_document_patch:
+   - project_document_patch({ doc_type: "prd", operation: "replace_section", section_heading: "## <heading>", content: "..." })
+   - Use operation "append" / "prepend" to add new content without replacing
 4. Show the updated section for confirmation
 
 ## RULES
 
-1. ALWAYS read the existing PRD first
+1. ALWAYS read the existing PRD first (project_document_get)
 2. Use ask_user_simple for section selection
 3. Use ask_user for gathering detailed updates
-4. Preserve sections you're not updating
-5. Use edit tool (not write_file) to update specific sections
+4. Preserve sections you're not updating (patch one section at a time)
+5. CRITICAL: the PRD lives in the database. Save with project_document_patch / project_document_add — NEVER write_file / edit / a PRD.md file on disk
 6. Keep formatting consistent with existing document
 7. If scope changes affect backlog, suggest running /refine
 
 ## COMPLETION CRITERIA
-✓ PRD.md is updated with changes
+✓ PRD is updated in the database (doc_type: prd)
 ✓ User has reviewed the updates
 ✓ Related backlog updates are suggested if needed`,
     tags: ['planning', 'requirements'],
@@ -532,7 +539,7 @@ export const sessionNotesSkill = defineSkill({
 
 ## SESSION NOTE STRUCTURE
 
-Create a markdown file with this structure:
+Compose a markdown note with this structure (it will be saved to the database, not a file):
 
 \`\`\`markdown
 # Session Note - {{title}}
@@ -573,13 +580,12 @@ Create a markdown file with this structure:
 *Generated by /note*
 \`\`\`
 
-## FILE LOCATION
+## WHERE TO SAVE
 
-Save the note to:
-- Single repo: \`.compilr/sessions/{{YYYY-MM-DD}}-{{slug}}.md\`
-- Two repo: \`{{project}}-docs/04-session-notes/{{YYYY-MM-DD}}-{{slug}}.md\`
+Save the note to the project DATABASE with:
+  project_document_add({ doc_type: "notes", title: "Session Note — {{title}}", content: "<full markdown>" })
 
-Create the directory if it doesn't exist.
+CRITICAL: session notes are database documents. NEVER write a .md file (no write_file / edit / bash mkdir, no .compilr/sessions/ or {{project}}-docs/ paths).
 
 ## RULES
 
@@ -591,7 +597,7 @@ Create the directory if it doesn't exist.
 6. If user provides a title, use it; otherwise generate one from the summary
 
 ## COMPLETION CRITERIA
-✓ Session note file is created
+✓ Session note saved to the database (doc_type: notes)
 ✓ All sections are filled in
 ✓ User has reviewed the note`,
     tags: ['documentation', 'session'],

package/package.json

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