@aexol/spectral 0.7.0 → 0.7.3

package/dist/designer/systems.js

@@ -0,0 +1,216 @@
+/**
+ * Design System Registry — 150+ Curated Systems from Open Design
+ *
+ * Design systems are stored as DESIGN.md + tokens.css files under
+ * data/systems/<name>/. At import time, we scan the directory and
+ * parse each system's metadata (name, category, description) from
+ * the DESIGN.md frontmatter. Full content is lazily loaded on first
+ * access and cached.
+ *
+ * The tool interface remains the same as the original systems.ts:
+ *   findSystem(name)  → DesignSystem | undefined
+ *   formatSystemForLLM(system) → string
+ *   listSystemsForLLM() → string
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// ---------------------------------------------------------------------------
+// Discovery — build the registry from data/systems/
+// ---------------------------------------------------------------------------
+/** The directory containing design system data. We try multiple paths to
+ *  handle both dev (src/) and production (dist/) layouts. */
+function discoverDataDir() {
+    // Production: __dirname is dist/designer/, data is dist/designer/data/systems/
+    const prodPath = resolve(__dirname, "data", "systems");
+    if (existsSync(prodPath))
+        return prodPath;
+    // Both dev (src/designer/) and production (dist/designer/) layouts resolve the same way
+    return prodPath;
+}
+function parseCategory(line) {
+    const m = /Category:\s*(.+)/i.exec(line);
+    return m ? m[1].trim() : "Uncategorised";
+}
+function parseName(h1) {
+    return h1
+        .replace(/^#\s*Design System Inspired by\s*/i, "")
+        .replace(/^#\s*/i, "")
+        .trim();
+}
+function parseDescription(lines) {
+    // Take the first non-empty, non-heading, non-bracket line after the header
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith(">"))
+            continue;
+        // Take up to 120 chars for the description
+        return trimmed.length > 120 ? trimmed.slice(0, 117) + "..." : trimmed;
+    }
+    return "Design system from the Open Design registry.";
+}
+function buildRegistry() {
+    const map = new Map();
+    const baseDir = discoverDataDir();
+    if (!existsSync(baseDir)) {
+        process.stderr.write(`[designer] Design system data directory not found at ${baseDir}\n`);
+        return map;
+    }
+    let entries;
+    try {
+        entries = readdirSync(baseDir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name);
+    }
+    catch {
+        process.stderr.write(`[designer] Cannot read design system directory ${baseDir}\n`);
+        return map;
+    }
+    for (const name of entries) {
+        const dir = resolve(baseDir, name);
+        const mdPath = resolve(dir, "DESIGN.md");
+        const cssPath = resolve(dir, "tokens.css");
+        if (!existsSync(mdPath))
+            continue;
+        let designMd;
+        try {
+            designMd = readFileSync(mdPath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const mdLines = designMd.split("\n");
+        // Extract metadata from the first heading lines
+        let h1Line = "";
+        let categoryLine = "";
+        const bodyLines = [];
+        for (const line of mdLines) {
+            const t = line.trim();
+            if (!h1Line && t.startsWith("# "))
+                h1Line = t;
+            else if (!categoryLine && t.startsWith("> Category:"))
+                categoryLine = t;
+            else
+                bodyLines.push(line);
+        }
+        const parsedName = parseName(h1Line || `# ${name}`);
+        const category = parseCategory(categoryLine);
+        const description = parseDescription(bodyLines);
+        let tokensCss = "";
+        if (existsSync(cssPath)) {
+            try {
+                tokensCss = readFileSync(cssPath, "utf-8");
+            }
+            catch {
+                // tokens optional
+            }
+        }
+        let componentsHtml = "";
+        const compPath = resolve(dir, "components.html");
+        if (existsSync(compPath)) {
+            try {
+                componentsHtml = readFileSync(compPath, "utf-8");
+            }
+            catch {
+                // components optional
+            }
+        }
+        map.set(parsedName.toLowerCase(), {
+            name: parsedName,
+            category,
+            description,
+            designMd,
+            tokensCss,
+            componentsHtml,
+        });
+    }
+    return map;
+}
+// ---------------------------------------------------------------------------
+// Registry singleton
+// ---------------------------------------------------------------------------
+let _registry = null;
+function registry() {
+    if (!_registry)
+        _registry = buildRegistry();
+    return _registry;
+}
+// ---------------------------------------------------------------------------
+// Lookup
+// ---------------------------------------------------------------------------
+export function findSystem(name) {
+    const lower = name.toLowerCase().trim();
+    const reg = registry();
+    // Exact match
+    if (reg.has(lower))
+        return reg.get(lower);
+    // Prefix / fuzzy match
+    for (const [key, sys] of reg) {
+        if (key.startsWith(lower) || key.includes(lower))
+            return sys;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// LLM formatters
+// ---------------------------------------------------------------------------
+/**
+ * Format a single design system for the LLM.
+ * Concatenates the DESIGN.md and tokens.css for a complete picture.
+ */
+export function formatSystemForLLM(system) {
+    const parts = [system.designMd];
+    if (system.tokensCss) {
+        parts.push("\n---\n## CSS Custom Properties (tokens.css)\n");
+        parts.push("```css");
+        parts.push(system.tokensCss);
+        parts.push("```");
+    }
+    if (system.componentsHtml) {
+        parts.push("\n---\n## Component Examples (components.html)\n");
+        parts.push(system.componentsHtml);
+    }
+    parts.push("\n---\n", "## How to Use This System\n", "1. Copy the `:root { ... }` block from tokens.css into your `<style>` block.", "2. Reference tokens as `var(--bg)`, `var(--fg)`, `var(--accent)`, `var(--font-body)`, etc.", "3. Follow the component styling guidelines from the DESIGN.md sections.", "4. Use the component examples as concrete starting points — adapt colors and fonts to the active design system.", "5. Apply typography rules: font families, sizes, and line-heights from the tokens.");
+    return parts.join("\n");
+}
+/**
+ * List all available design systems as a compact markdown table for the LLM.
+ */
+export function listSystemsForLLM() {
+    const reg = registry();
+    const all = [...reg.values()];
+    // Group by category
+    const byCategory = new Map();
+    for (const sys of all) {
+        const cat = sys.category;
+        if (!byCategory.has(cat))
+            byCategory.set(cat, []);
+        byCategory.get(cat).push(sys);
+    }
+    const lines = [
+        `# Available Design Systems (${all.length} total)`,
+        "",
+        "Grouped by category. Use `designer_get_system` with the system **name** to load full tokens and guidelines.",
+        "",
+    ];
+    for (const [category, systems] of [...byCategory].sort((a, b) => a[0].localeCompare(b[0]))) {
+        systems.sort((a, b) => a.name.localeCompare(b.name));
+        lines.push(`## ${category}`);
+        lines.push("");
+        for (const s of systems) {
+            lines.push(`- **${s.name}** — ${s.description}`);
+        }
+        lines.push("");
+    }
+    // Quick-select list at the end
+    lines.push("---");
+    lines.push("");
+    lines.push("Quick reference (all system names, one per line):");
+    lines.push("");
+    const sorted = [...all].sort((a, b) => a.name.localeCompare(b.name));
+    for (const s of sorted) {
+        lines.push(`- ${s.name}`);
+    }
+    return lines.join("\n");
+}

package/dist/mcp/sampling-handler.js

@@ -1,4 +1,4 @@
-import { complete } from "@mariozechner/pi-ai";
+import { complete } from "../pi/ai/index.js";
 import { truncateAtWord } from "./utils.js";
 import { CreateMessageRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 export function registerSamplingHandler(client, options) {

package/dist/memory/commands/status.js

@@ -1,4 +1,4 @@
-import { SettingsManager } from "@mariozechner/pi-coding-agent";
+import { SettingsManager } from "../../pi/coding-agent/index.js";
 import { getMemoryState, rawTokensSinceLastBound, rawTokensSinceLastCompaction, } from "../branch.js";
 import { observationPoolTokens as estimateObservationPoolTokens } from "../compaction.js";
 import { countByRelevance, formatRelevanceHistogram } from "../relevance.js";

package/dist/memory/compaction.js

@@ -1,5 +1,5 @@
-import { agentLoop } from "@mariozechner/pi-agent-core";
-import { Type } from "@mariozechner/pi-ai";
+import { agentLoop } from "../pi/agent-core/index.js";
+import { Type } from "../pi/ai/index.js";
 import { debugLog, isDebugLogEnabled } from "./debug-log.js";
 import { hashId } from "./ids.js";
 import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "./model-budget.js";

package/dist/memory/config.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { getAgentDir } from "../pi/coding-agent/index.js";
 export const DEFAULTS = {
     observationThresholdTokens: 1_000,
     compactionThresholdTokens: 50_000,

package/dist/memory/debug-log.js

@@ -1,7 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { existsSync, mkdirSync, renameSync, statSync, unlinkSync, appendFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { getAgentDir } from "../pi/coding-agent/index.js";
 export const DEBUG_LOG_MAX_BYTES = 10 * 1024 * 1024;
 export const DEBUG_LOG_RELATIVE_PATH = join("observational-memory", "debug.ndjson");
 const storage = new AsyncLocalStorage();

package/dist/memory/hooks/compaction-hook.js

@@ -1,5 +1,6 @@
 import { debugLog, withDebugLogContext } from "../debug-log.js";
 import { resolveTurnLimits } from "../config.js";
+import { getProjectObsStore } from "../project-observations-store.js";
 import { collectObservationsByCoverage, findLastCompactionIndex, gapRawEntries, getMemoryState, } from "../branch.js";
 import { coverageTagCounts, migrateLegacyReflections, observationPoolTokens, renderSummary, runPruner, runReflector, } from "../compaction.js";
 import { observationsToPromptLines, runObserver } from "../observer.js";
@@ -188,6 +189,8 @@ export function registerCompactionHook(pi, runtime) {
                     };
                     if (hasUI)
                         ui?.notify(`Observational memory: no new observations — carrying forward ${memoryState.committedObs.length} observation${memoryState.committedObs.length === 1 ? "" : "s"}, ${workingReflections.length} reflection${workingReflections.length === 1 ? "" : "s"}`, "info");
+                    // Promote reflections as project observations (cross-session durable memory).
+                    persistProjectObservations(ctx, workingReflections);
                     return {
                         compaction: {
                             summary,
@@ -274,6 +277,8 @@ export function registerCompactionHook(pi, runtime) {
                 });
                 if (hasUI)
                     ui?.notify(`Observational memory: compaction assembled — ${finalObservations.length} observation${finalObservations.length === 1 ? "" : "s"}, ${finalReflections.length} reflection${finalReflections.length === 1 ? "" : "s"}`, "info");
+                // Promote reflections as project observations (cross-session durable memory).
+                persistProjectObservations(ctx, finalReflections);
                 return {
                     compaction: {
                         summary,
@@ -288,4 +293,28 @@ export function registerCompactionHook(pi, runtime) {
             runtime.compactHookInFlight = false;
         }
     });
+    function persistProjectObservations(ctx, reflections) {
+        const store = getProjectObsStore();
+        if (!store)
+            return; // Not available in standalone pi mode.
+        const projectId = store.getProjectByCwd(ctx.cwd);
+        if (!projectId)
+            return; // No project registered for this cwd.
+        const sessionId = ctx.sessionManager.getSessionId?.();
+        if (!sessionId)
+            return;
+        if (reflections.length === 0)
+            return;
+        const projectObs = reflections.map((r) => ({
+            id: typeof r === "string" ? r : r.id ?? r.content.slice(0, 64),
+            content: typeof r === "string" ? r : r.content,
+            relevance: "high",
+        }));
+        store.insertProjectObservations(projectId, sessionId, projectObs, Date.now());
+        debugLog("compaction.project_obs", {
+            count: projectObs.length,
+            projectId,
+            sessionId,
+        });
+    }
 }

package/dist/memory/index.js

@@ -5,6 +5,7 @@ import { registerCompactionTrigger } from "./hooks/compaction-trigger.js";
 import { registerObserverTrigger } from "./hooks/observer-trigger.js";
 import { Runtime } from "./runtime.js";
 import { registerRecallTool } from "./tools/recall-observation.js";
+import { registerReadProjectObservationsTool } from "./tools/read-project-observations.js";
 export default function observationalMemory(pi) {
     const runtime = new Runtime();
     // Log extension load so we can confirm it's running in serve mode.
@@ -15,4 +16,5 @@ export default function observationalMemory(pi) {
     registerStatusCommand(pi, runtime);
     registerViewCommand(pi, runtime);
     registerRecallTool(pi);
+    registerReadProjectObservationsTool(pi);
 }

package/dist/memory/observer.js

@@ -1,5 +1,5 @@
-import { agentLoop } from "@mariozechner/pi-agent-core";
-import { Type } from "@mariozechner/pi-ai";
+import { agentLoop } from "../pi/agent-core/index.js";
+import { Type } from "../pi/ai/index.js";
 import { hashId } from "./ids.js";
 import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "./model-budget.js";
 import { OBSERVER_SYSTEM } from "./prompts.js";

package/dist/memory/project-observations-store.js

@@ -0,0 +1,14 @@
+/**
+ * Module-level singleton that bridges the server's SessionStore into the
+ * memory extension so the `read_project_observations` tool can query
+ * cross-session observations.
+ *
+ * Set once by the SessionStreamManager at startup. Read by tools at runtime.
+ */
+let _store = null;
+export function setProjectObsStore(store) {
+    _store = store;
+}
+export function getProjectObsStore() {
+    return _store;
+}

package/dist/memory/tokens.js

@@ -1,4 +1,4 @@
-import { estimateTokens as estimateMessageTokens } from "@mariozechner/pi-coding-agent";
+import { estimateTokens as estimateMessageTokens } from "../pi/coding-agent/index.js";
 export function estimateStringTokens(text) {
     return Math.ceil(text.length / 4);
 }

package/dist/memory/tools/read-project-observations.js

@@ -0,0 +1,82 @@
+import { Type } from "../../pi/ai/index.js";
+import { defineTool } from "../../pi/coding-agent/index.js";
+import { getProjectObsStore } from "../project-observations-store.js";
+export const READ_PROJECT_OBSERVATIONS_TOOL_NAME = "read_project_observations";
+export const readProjectObservationsTool = defineTool({
+    name: READ_PROJECT_OBSERVATIONS_TOOL_NAME,
+    label: "Search project observations",
+    description: "Search all past observations across ALL sessions in this project. " +
+        "Use this when you need to recall project conventions, past decisions, " +
+        "file locations, or user preferences before editing or creating files. " +
+        "Uses simple substring matching — be specific with your query terms. " +
+        "Returns up to 20 most recent matching observations with relevance tags.",
+    promptSnippet: "Use read_project_observations(<query>) to search past observations across ALL sessions in this project.",
+    promptGuidelines: [
+        "Use read_project_observations before creating new files to find conventions for that file kind.",
+        "Use read_project_observations before editing a file to find past context about that file or its directory.",
+        "Be specific: search for file paths, technology names, or pattern keywords.",
+        "Do not use for broad topic searches — keep queries narrow for relevant results.",
+        "Results include relevance tags (critical/high/medium/low) to help you prioritize.",
+    ],
+    parameters: Type.Object({
+        query: Type.String({
+            minLength: 1,
+            description: "Substring to search for in past observation content. " +
+                "Use file paths (e.g. 'src/auth/middleware'), technology names, " +
+                "or pattern keywords (e.g. 'convention', 'api route').",
+        }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        const query = params.query.trim();
+        if (!query) {
+            const message = "Query must be a non-empty string.";
+            return {
+                content: [{ type: "text", text: message }],
+                details: { status: "empty_query", results: [], count: 0 },
+            };
+        }
+        const store = getProjectObsStore();
+        if (!store) {
+            const message = "Project observations store is not available — " +
+                "this tool requires the spectral server (spectral serve).";
+            return {
+                content: [{ type: "text", text: message }],
+                details: { status: "store_unavailable", results: [], count: 0 },
+            };
+        }
+        const projectId = store.getProjectByCwd(ctx.cwd);
+        if (!projectId) {
+            const message = `No project found for current working directory: ${ctx.cwd}`;
+            return {
+                content: [{ type: "text", text: message }],
+                details: { status: "no_project", results: [], count: 0 },
+            };
+        }
+        const results = store.searchProjectObservations(projectId, query);
+        if (results.length === 0) {
+            const message = `No past observations found matching "${query}" in this project.`;
+            return {
+                content: [{ type: "text", text: message }],
+                details: { status: "no_results", query, results: [], count: 0 },
+            };
+        }
+        const lines = results.map((r) => `[${r.relevance}] ${r.content}`);
+        const text = `Found ${results.length} past observation(s) matching "${query}" in this project:\n\n${lines.join("\n")}`;
+        return {
+            content: [{ type: "text", text }],
+            details: {
+                status: "ok",
+                query,
+                results: results.map((r) => ({
+                    content: r.content,
+                    relevance: r.relevance,
+                    sessionId: r.sessionId,
+                })),
+                count: results.length,
+            },
+        };
+    },
+});
+export function registerReadProjectObservationsTool(pi) {
+    pi.registerTool(readProjectObservationsTool);
+}

package/dist/memory/tools/recall-observation.js

@@ -1,5 +1,5 @@
-import { Type } from "@mariozechner/pi-ai";
-import { defineTool } from "@mariozechner/pi-coding-agent";
+import { Type } from "../../pi/ai/index.js";
+import { defineTool } from "../../pi/coding-agent/index.js";
 import { recallMemorySources, } from "../branch.js";
 import { renderRecallSourceEntries, renderRecallSourceEntry } from "../serialize.js";
 import { estimateEntryTokens } from "../tokens.js";