dsh-agent-plugins-market 0.6.2 → 0.7.0

package/lib/application/catalog-context.js

@@ -0,0 +1,181 @@
+/**
+ * The shared mutable core of one catalog: the persisted state, the serialized
+ * mutation queue, the revision and scan generations, and the change pipeline
+ * every mutation funnels through.
+ *
+ * The collaborators receive this object instead of reaching into each other,
+ * so the invariants they share — one queue, one generation counter, one
+ * notification path — have a single owner.
+ */
+import { join } from 'node:path';
+import { STATE_FILE_NAME } from '../catalog/paths.js';
+import { settlesWithin } from '../runtime/deadline.js';
+import { EMPTY_STATE, loadState, saveState } from '../runtime/state-store.js';
+import { effectiveSurfaces } from '../model/types.js';
+import { SCAN_CACHE_TTL_MS, SnapshotCache } from './snapshot-cache.js';
+/** Key of one install entry in the persisted `installed` record. */
+export function installKey(sourceId, suiteId) {
+    return `${sourceId}/${suiteId}`;
+}
+/**
+ * How long an explicit caller waits for the derived refresh before answering
+ * anyway. The refresh keeps running; only the wait ends.
+ */
+export const DERIVED_REFRESH_WAIT_MS = 10_000;
+export class CatalogContext {
+    currentState = EMPTY_STATE;
+    mutationQueue = Promise.resolve();
+    currentRevision = 0;
+    currentScanGeneration = 0;
+    scanProjectLayoutsEnabled = false;
+    /** The derived refresh in flight, shared by every change that lands while it runs. */
+    refreshPass;
+    /** Whether a change landed after the running pass started; it earns one more pass. */
+    refreshQueued = false;
+    statePath;
+    userRoot;
+    dataRoot;
+    agentsRoot;
+    git;
+    /** Discovery scans and dimension snapshots derived from {@link state}. */
+    snapshots;
+    onChanged;
+    constructor(options) {
+        this.statePath = join(options.userRoot, STATE_FILE_NAME);
+        this.userRoot = options.userRoot;
+        this.dataRoot = options.dataRoot;
+        this.agentsRoot = options.agentsRoot;
+        this.git = options.git ?? {};
+        this.onChanged = options.onChanged;
+        this.snapshots = new SnapshotCache(this, {
+            user: options.userSnapshotTtlMs ?? SCAN_CACHE_TTL_MS,
+            project: options.projectSnapshotTtlMs ?? 5_000
+        });
+    }
+    get state() {
+        return this.currentState;
+    }
+    /** Bumped by every mutation: a snapshot built at an older revision is never published. */
+    get revision() {
+        return this.currentRevision;
+    }
+    /** Bumped by every content-changing mutation: a scan started earlier never repopulates its cache. */
+    get scanGeneration() {
+        return this.currentScanGeneration;
+    }
+    /** Whether native project layouts (`.claude/`, `.agents/`) take part in discovery. */
+    get scanProjectLayouts() {
+        return this.scanProjectLayoutsEnabled;
+    }
+    /** One install entry, or undefined when the suite is not installed. */
+    installed(sourceId, suiteId) {
+        return this.currentState.installed[installKey(sourceId, suiteId)];
+    }
+    /** Load persisted user state once at plugin activation. */
+    async load() {
+        this.currentState = await loadState(this.statePath);
+        this.invalidateScans();
+        this.invalidateSnapshot(false);
+    }
+    /** Replace the persisted state and write it out. */
+    async commit(next) {
+        this.currentState = next;
+        await saveState(this.statePath, next);
+    }
+    /** Apply the host's project-layout switch and invalidate every project snapshot. */
+    async setScanProjectLayouts(enabled) {
+        if (this.scanProjectLayoutsEnabled === enabled)
+            return;
+        this.scanProjectLayoutsEnabled = enabled;
+        await this.notifyChanged();
+    }
+    /**
+     * Apply the install state to freshly discovered suites: enablement, the
+     * effective surface toggles, and the lock/install timestamps the market
+     * cards report.
+     */
+    project(discovered, state, dimension) {
+        return discovered.map(suite => {
+            const installed = state.installed[installKey(suite.sourceId, suite.id)];
+            // Native project layouts (`.claude/`, `.agents/`) are the repository's
+            // own files read in place: they carry no install state and stay enabled.
+            const enabled = suite.manifest.layout === 'project-native' || installed?.enabled === true;
+            return {
+                ...suite,
+                enabled,
+                activeSurfaces: {
+                    ...effectiveSurfaces(installed?.surfaces),
+                    ...(suite.manifest.layout === 'project-native' ? suite.activeSurfaces : {}),
+                    ...(dimension === 'project' ? { lsp: false } : {})
+                },
+                ...(installed?.lockCommit === undefined ? {} : { lockCommit: installed.lockCommit }),
+                ...(installed?.installedAt === undefined ? {} : { installedAt: installed.installedAt })
+            };
+        });
+    }
+    /**
+     * Invalidate snapshots and schedule the change pipeline. `keepScanCache`
+     * marks state-only mutations (install, enable, surface toggles, MCP
+     * overrides) whose inputs leave every checkout untouched, so the next
+     * snapshot re-derives from cached discovery instead of rescanning the
+     * filesystem.
+     *
+     * The invalidation is synchronous and the refresh is coalesced in the
+     * background: resolving here means the state is durable, never that every
+     * mount has finished. Callers that must observe the refreshed surfaces await
+     * {@link refreshSettled}, whose wait is bounded so one stuck mount cannot
+     * hold a request — or the next mutation behind it — open.
+     */
+    async notifyChanged(keepScanCache = false) {
+        if (!keepScanCache)
+            this.invalidateScans();
+        this.invalidateSnapshot(true);
+        this.scheduleRefresh();
+    }
+    /**
+     * Resolve once the queued derived refresh finishes, `false` when the deadline
+     * elapses first. The refresh itself is never cancelled.
+     */
+    async refreshSettled(deadlineMs = DERIVED_REFRESH_WAIT_MS) {
+        const pass = this.refreshPass;
+        return pass === undefined ? true : settlesWithin(pass, deadlineMs);
+    }
+    /** Queue one derived refresh; a pass already in flight absorbs it. */
+    scheduleRefresh() {
+        this.refreshQueued = true;
+        this.refreshPass ??= (async () => {
+            try {
+                while (this.refreshQueued) {
+                    this.refreshQueued = false;
+                    try {
+                        await this.onChanged();
+                    }
+                    catch {
+                        // The pipeline owner reports its own stage failures. A rejected
+                        // pass must not wedge the queue for every later change.
+                    }
+                }
+            }
+            finally {
+                this.refreshPass = undefined;
+            }
+        })();
+    }
+    /** Drop every cached dimension snapshot; `increment` advances the revision. */
+    invalidateSnapshot(increment) {
+        if (increment)
+            this.currentRevision++;
+        this.snapshots.invalidateSnapshots();
+    }
+    /** Drop cached discovery and advance the generation a scan is validated against. */
+    invalidateScans() {
+        this.currentScanGeneration++;
+        this.snapshots.invalidateScans();
+    }
+    /** Serialize one mutation behind every mutation queued before it. */
+    enqueue(operation) {
+        const result = this.mutationQueue.then(operation, operation);
+        this.mutationQueue = result.catch(() => { });
+        return result;
+    }
+}