@compilr-dev/sdk 0.29.6 → 0.29.7

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

@@ -10,7 +10,7 @@
  *     └── project-{id}.json     # Per-project anchors
  */
 import { AnchorManager } from '@compilr-dev/agents';
-import type { Anchor, AnchorInput, AnchorQueryOptions } from '@compilr-dev/agents';
+import type { Anchor, AnchorInput, AnchorPriority, AnchorQueryOptions } from '@compilr-dev/agents';
 import type { IAnchorService } from './services.js';
 export interface ProjectAnchorStoreConfig {
     /** Directory for anchor JSON files (e.g. ~/.compilr-dev/anchors/) */
@@ -36,6 +36,55 @@ export declare class ProjectAnchorStore {
     addAnchor(input: AnchorInput & {
         projectId?: string;
     }): Anchor;
+    /**
+     * Find an anchor by id, and say which file holds it.
+     *
+     * Searches the active project's manager then the global one — the same two the UI lists, and
+     * the same order `toService().remove` already uses. It deliberately does not sweep
+     * `this.managers`: those are lazily cached, so which ones exist depends on what happened
+     * earlier in the session, and the answer would drift with it.
+     *
+     * The null check on `currentProjectId` is defensive rather than behavioural — `String(null)`
+     * would key an empty manager and the lookup would fall through to global with the same
+     * result, and `loadPersistent` writes nothing for a file that does not exist. It is here so
+     * the intent is legible, not because a test can tell the difference. Mutating it away leaves
+     * every test green, and that is correct.
+     */
+    findAnchor(id: string, currentProjectId?: string | null): {
+        anchor: Anchor;
+        projectKey: string | null;
+    } | undefined;
+    /** Remove an anchor by id from whichever file holds it. */
+    removeAnchorById(id: string, currentProjectId?: string | null): {
+        removed: boolean;
+        scope?: 'global' | 'project';
+    };
+    /**
+     * Edit an anchor in place, keeping its id.
+     *
+     * ⚠️ WHY THE ID MATTERS. Without this the caller has to remove and re-add, which mints a new
+     * id — an open tab would then point at an anchor that no longer exists, and the row would
+     * jump in the list. `AnchorInput` accepts an id, so the re-add reuses the old one and both
+     * stay put.
+     *
+     * ⚠️ CHANGING SCOPE IS A MOVE BETWEEN FILES, not a field edit. Global anchors live in
+     * `global.json` and project ones in `project-<id>.json`, so switching "applies to" removes
+     * from one manager and adds to the other. The id survives that too.
+     *
+     * ⚠️ `createdAt` IS RESET, deliberately. `AnchorManager.add` always stamps `new Date()` and
+     * its `savePersistent` is private, so the only ways to keep the original are to mutate a
+     * stored object behind the manager's back or to widen `AnchorInput` in @compilr-dev/agents.
+     * Nothing displays `createdAt`; it is read only by the two eviction tie-breakers
+     * (`makeRoom`, `removeOldestLowPriority`), so on an edited anchor it now means "last edited"
+     * and that anchor is evicted last under budget pressure. Built-ins keep `new Date(0)` because
+     * they cannot be edited at all. See F-4.
+     */
+    updateAnchor(id: string, patch: {
+        content?: string;
+        priority?: AnchorPriority;
+        tags?: string[];
+        scope?: 'global' | 'project';
+    }, currentProjectId?: string | null): Anchor | undefined;
     /** Get all anchors across all cached managers. */
     getAllAnchors(options?: AnchorQueryOptions): Anchor[];
     /** Clear all anchors for a project and delete the persistence file. */
@@ -53,6 +102,29 @@ export declare class ProjectAnchorStore {
         projectCounts: Map<string, number>;
         totalTokens: number;
     };
+    /**
+     * Usage against the caps, per file.
+     *
+     * ⚠️ THE CAPS ARE PER FILE, NOT COMBINED. Each `AnchorManager` enforces `maxAnchors` and
+     * `maxTokens` on its own store, so global.json and project-<id>.json each get the full
+     * budget. A single meter summing the two and measuring it against one cap would read half
+     * full at the moment an `anchor_add` starts evicting — which is the opposite of the point,
+     * since the meter exists to show the limit before it bites.
+     *
+     * Both are returned and the caller shows the fuller one.
+     */
+    getUsage(projectId?: string | null): {
+        global: {
+            anchors: number;
+            tokens: number;
+        };
+        project: {
+            anchors: number;
+            tokens: number;
+        } | null;
+        maxAnchors: number;
+        maxTokens: number;
+    };
     /** Clear all cached managers (useful for testing or refresh). */
     clearCache(): void;
     /** Create an IAnchorService implementation for use with createPlatformTools(). */

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

@@ -52,6 +52,89 @@ export class ProjectAnchorStore {
         const manager = this.getManager(input.projectId ?? null);
         return manager.add(input);
     }
+    /**
+     * Find an anchor by id, and say which file holds it.
+     *
+     * Searches the active project's manager then the global one — the same two the UI lists, and
+     * the same order `toService().remove` already uses. It deliberately does not sweep
+     * `this.managers`: those are lazily cached, so which ones exist depends on what happened
+     * earlier in the session, and the answer would drift with it.
+     *
+     * The null check on `currentProjectId` is defensive rather than behavioural — `String(null)`
+     * would key an empty manager and the lookup would fall through to global with the same
+     * result, and `loadPersistent` writes nothing for a file that does not exist. It is here so
+     * the intent is legible, not because a test can tell the difference. Mutating it away leaves
+     * every test green, and that is correct.
+     */
+    findAnchor(id, currentProjectId) {
+        if (currentProjectId != null && currentProjectId !== '') {
+            const projectManager = this.getManager(currentProjectId);
+            const anchor = projectManager.get(id);
+            if (anchor)
+                return { anchor, projectKey: currentProjectId };
+        }
+        const anchor = this.getGlobalManager().get(id);
+        return anchor ? { anchor, projectKey: null } : undefined;
+    }
+    /** Remove an anchor by id from whichever file holds it. */
+    removeAnchorById(id, currentProjectId) {
+        const found = this.findAnchor(id, currentProjectId);
+        if (!found)
+            return { removed: false };
+        const removed = this.getManager(found.projectKey).remove(id);
+        return { removed, scope: found.projectKey === null ? 'global' : 'project' };
+    }
+    /**
+     * Edit an anchor in place, keeping its id.
+     *
+     * ⚠️ WHY THE ID MATTERS. Without this the caller has to remove and re-add, which mints a new
+     * id — an open tab would then point at an anchor that no longer exists, and the row would
+     * jump in the list. `AnchorInput` accepts an id, so the re-add reuses the old one and both
+     * stay put.
+     *
+     * ⚠️ CHANGING SCOPE IS A MOVE BETWEEN FILES, not a field edit. Global anchors live in
+     * `global.json` and project ones in `project-<id>.json`, so switching "applies to" removes
+     * from one manager and adds to the other. The id survives that too.
+     *
+     * ⚠️ `createdAt` IS RESET, deliberately. `AnchorManager.add` always stamps `new Date()` and
+     * its `savePersistent` is private, so the only ways to keep the original are to mutate a
+     * stored object behind the manager's back or to widen `AnchorInput` in @compilr-dev/agents.
+     * Nothing displays `createdAt`; it is read only by the two eviction tie-breakers
+     * (`makeRoom`, `removeOldestLowPriority`), so on an edited anchor it now means "last edited"
+     * and that anchor is evicted last under budget pressure. Built-ins keep `new Date(0)` because
+     * they cannot be edited at all. See F-4.
+     */
+    updateAnchor(id, patch, currentProjectId) {
+        const found = this.findAnchor(id, currentProjectId);
+        if (!found)
+            return undefined;
+        const { anchor, projectKey } = found;
+        let targetKey = projectKey;
+        if (patch.scope !== undefined) {
+            if (patch.scope === 'project') {
+                if (currentProjectId == null || currentProjectId === '') {
+                    throw new Error('Cannot scope an anchor to a project: no active project. Use scope: "global" instead.');
+                }
+                targetKey = currentProjectId;
+            }
+            else {
+                targetKey = null;
+            }
+        }
+        // Remove first: re-adding the same id into the same manager would otherwise be an
+        // overwrite whose budget accounting counts the content twice.
+        this.getManager(projectKey).remove(id);
+        return this.getManager(targetKey).add({
+            id,
+            content: patch.content ?? anchor.content,
+            priority: patch.priority ?? anchor.priority,
+            scope: anchor.scope,
+            tags: patch.tags ?? anchor.tags,
+            metadata: anchor.metadata,
+            expiresAt: anchor.expiresAt,
+            projectId: targetKey ?? undefined,
+        });
+    }
     /** Get all anchors across all cached managers. */
     getAllAnchors(options) {
         const all = [];
@@ -127,6 +210,30 @@ export class ProjectAnchorStore {
             totalTokens,
         };
     }
+    /**
+     * Usage against the caps, per file.
+     *
+     * ⚠️ THE CAPS ARE PER FILE, NOT COMBINED. Each `AnchorManager` enforces `maxAnchors` and
+     * `maxTokens` on its own store, so global.json and project-<id>.json each get the full
+     * budget. A single meter summing the two and measuring it against one cap would read half
+     * full at the moment an `anchor_add` starts evicting — which is the opposite of the point,
+     * since the meter exists to show the limit before it bites.
+     *
+     * Both are returned and the caller shows the fuller one.
+     */
+    getUsage(projectId) {
+        const globalManager = this.getGlobalManager();
+        const hasProject = projectId != null && projectId !== '';
+        const projectManager = hasProject ? this.getManager(projectId) : null;
+        return {
+            global: { anchors: globalManager.size, tokens: globalManager.getTotalTokens() },
+            project: projectManager === null
+                ? null
+                : { anchors: projectManager.size, tokens: projectManager.getTotalTokens() },
+            maxAnchors: this.config.maxAnchors ?? 50,
+            maxTokens: this.config.maxTokens ?? 4000,
+        };
+    }
     /** Clear all cached managers (useful for testing or refresh). */
     clearCache() {
         this.managers.clear();
@@ -164,6 +271,32 @@ export class ProjectAnchorStore {
                     tags: anchor.tags,
                 });
             },
+            update: (id, patch) => {
+                const projId = this.config.getCurrentProjectId();
+                const updated = this.updateAnchor(id, patch, projId == null ? null : String(projId));
+                if (!updated)
+                    return Promise.resolve(null);
+                return Promise.resolve({
+                    id: updated.id,
+                    content: updated.content,
+                    priority: updated.priority,
+                    scope: updated.projectId === undefined ? 'global' : 'project',
+                    tags: updated.tags,
+                });
+            },
+            get: (id) => {
+                const projId = this.config.getCurrentProjectId();
+                const found = this.findAnchor(id, projId == null ? null : String(projId));
+                if (!found)
+                    return Promise.resolve(null);
+                return Promise.resolve({
+                    id: found.anchor.id,
+                    content: found.anchor.content,
+                    priority: found.anchor.priority,
+                    scope: found.projectKey === null ? 'global' : 'project',
+                    tags: found.anchor.tags,
+                });
+            },
             remove: (id) => {
                 let removed = false;
                 let scope;

package/dist/platform/services.d.ts

@@ -23,6 +23,21 @@ export interface IAnchorService {
         removed: boolean;
         scope?: string;
     }>;
+    /**
+     * Edit an anchor in place, keeping its id.
+     *
+     * Optional so existing hosts are unaffected. Without it a caller has to remove and re-add,
+     * which mints a new id — anything holding the old one (an open tab, a row in a list) is then
+     * pointing at an anchor that no longer exists.
+     */
+    update?(id: string, patch: {
+        content?: string;
+        priority?: AnchorPriority;
+        tags?: string[];
+        scope?: 'global' | 'project';
+    }): Promise<AnchorData | null>;
+    /** One anchor by id, or null. */
+    get?(id: string): Promise<AnchorData | null>;
     list(options?: {
         scope?: 'global' | 'project' | 'all';
         priority?: AnchorPriority;

package/package.json

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