stoa-mcp 0.1.0

package/dist/guardrails/loader.js

@@ -0,0 +1,56 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { toSlug } from "../utils/slug.js";
+function guardrailsDir() {
+    return join(process.cwd(), ".stoa", "guardrails");
+}
+export function listGuardrails() {
+    if (!existsSync(guardrailsDir()))
+        return [];
+    const files = readdirSync(guardrailsDir())
+        .filter((f) => f.endsWith(".md"))
+        .sort();
+    return files.map((file) => {
+        const slug = file.replace(/\.md$/, "");
+        const content = readFileSync(join(guardrailsDir(), file), "utf-8");
+        const firstLine = content.split("\n")[0] ?? "";
+        const title = firstLine.replace(/^#\s*/, "");
+        return { slug, title };
+    });
+}
+export function addGuardrail(title) {
+    const slug = toSlug(title);
+    const filePath = join(guardrailsDir(), `${slug}.md`);
+    if (existsSync(filePath)) {
+        throw new Error(`Guardrail already exists: ${slug}`);
+    }
+    mkdirSync(guardrailsDir(), { recursive: true });
+    writeFileSync(filePath, `# ${title}\n`, "utf-8");
+}
+export function showGuardrail(slug) {
+    const filePath = join(guardrailsDir(), `${slug}.md`);
+    if (!existsSync(filePath)) {
+        throw new Error(`Guardrail not found: ${slug}`);
+    }
+    return readFileSync(filePath, "utf-8");
+}
+export function removeGuardrail(slug) {
+    const filePath = join(guardrailsDir(), `${slug}.md`);
+    if (!existsSync(filePath)) {
+        throw new Error(`Guardrail not found: ${slug}`);
+    }
+    unlinkSync(filePath);
+}
+export function loadAllGuardrails() {
+    if (!existsSync(guardrailsDir()))
+        return "";
+    const files = readdirSync(guardrailsDir())
+        .filter((f) => f.endsWith(".md"))
+        .sort();
+    if (files.length === 0)
+        return "";
+    return files
+        .map((file) => readFileSync(join(guardrailsDir(), file), "utf-8"))
+        .join("\n---\n");
+}
+//# sourceMappingURL=loader.js.map

package/dist/guardrails/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/guardrails/loader.ts"],"names":[],"mappings":"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"}

package/dist/guardrails/refine.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Guardrail Refine Pipeline.
+ * Runs a 3-stage refinement pipeline that transforms raw guardrail rules
+ * into precise, verifiable, example-backed specifications.
+ */
+/**
+ * Build the Stage 1 prompt: Clarify & Tighten.
+ * Rewrites the guardrail rule to be unambiguous, specific, and actionable.
+ * Removes vague language while preserving original intent.
+ * @param seed - The raw guardrail markdown content.
+ * @returns The full prompt string for Stage 1.
+ */
+export declare function buildStage1Prompt(seed: string): string;
+/**
+ * Build the Stage 2 prompt: Add Verification (How to Check).
+ * Appends a "How to Check" section with concrete, mechanical verification steps.
+ * @param stage1Output - The clarified guardrail text from Stage 1.
+ * @returns The full prompt string for Stage 2.
+ */
+export declare function buildStage2Prompt(stage1Output: string): string;
+/**
+ * Build the Stage 3 prompt: Add Examples (Good/Bad).
+ * Appends Good Example and Bad Example sections with inline code snippets.
+ * @param stage2Output - The guardrail text with verification from Stage 2.
+ * @returns The full prompt string for Stage 3.
+ */
+export declare function buildStage3Prompt(stage2Output: string): string;
+/** Options for the guardrail refine pipeline. */
+export interface GuardrailRefineOptions {
+    name: string;
+    mode: "clipboard" | "api" | "claude-code";
+    model?: string;
+    apiKey?: string;
+    onStageComplete?: (stageIndex: number, label: string, output: string) => void;
+}
+/** Result of the guardrail refine pipeline. */
+export interface GuardrailRefineResult {
+    prompts: string[];
+    finalOutput: string;
+}
+/**
+ * Run the 3-stage guardrail refinement pipeline.
+ *
+ * - clipboard: Executes all 3 stages via Anthropic API with chained outputs. Does not modify files.
+ * - api: Executes all 3 stages via Anthropic API. Writes final output to file.
+ * - claude-code: Executes via Claude Code CLI. Writes final output to file.
+ *
+ * @param options - Pipeline configuration including name, mode, and optional model/apiKey.
+ * @returns The prompts used and the final output.
+ * @throws If the guardrail file does not exist.
+ */
+export declare function refinePipeline(options: GuardrailRefineOptions): Promise<GuardrailRefineResult>;
+//# sourceMappingURL=refine.d.ts.map

package/dist/guardrails/refine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refine.d.ts","sourceRoot":"","sources":["../../src/guardrails/refine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAuBH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CActD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAc9D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAe9D;AAgFD,iDAAiD;AACjD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,WAAW,GAAG,KAAK,GAAG,aAAa,CAAC;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/E;AAED,+CAA+C;AAC/C,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAqChC"}

package/dist/guardrails/refine.js

@@ -0,0 +1,184 @@
+/**
+ * Guardrail Refine Pipeline.
+ * Runs a 3-stage refinement pipeline that transforms raw guardrail rules
+ * into precise, verifiable, example-backed specifications.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { spawn } from "child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const SPAWN_TIMEOUT_MS = 300_000;
+function guardrailsDir() {
+    return join(process.cwd(), ".stoa", "guardrails");
+}
+// ── Stage names ──────────────────────────────────────────────────────
+const STAGE_LABELS = [
+    "Stage 1: Clarify & Tighten",
+    "Stage 2: Add Verification (How to Check)",
+    "Stage 3: Add Examples (Good/Bad)",
+];
+// ── Pure prompt builders ─────────────────────────────────────────────
+/**
+ * Build the Stage 1 prompt: Clarify & Tighten.
+ * Rewrites the guardrail rule to be unambiguous, specific, and actionable.
+ * Removes vague language while preserving original intent.
+ * @param seed - The raw guardrail markdown content.
+ * @returns The full prompt string for Stage 1.
+ */
+export function buildStage1Prompt(seed) {
+    return [
+        "You are a technical writing editor specializing in software engineering guardrails and coding standards.",
+        "",
+        "Rewrite the following guardrail rule so it is unambiguous, specific, and actionable.",
+        "Remove vague language like \"should\", \"try to\", \"generally\", \"where possible\".",
+        "Replace subjective terms with objective, measurable criteria.",
+        "Preserve the original intent and all technical details.",
+        "Output only the rewritten guardrail in markdown format — no preamble, no commentary.",
+        "",
+        "---",
+        "",
+        seed,
+    ].join("\n");
+}
+/**
+ * Build the Stage 2 prompt: Add Verification (How to Check).
+ * Appends a "How to Check" section with concrete, mechanical verification steps.
+ * @param stage1Output - The clarified guardrail text from Stage 1.
+ * @returns The full prompt string for Stage 2.
+ */
+export function buildStage2Prompt(stage1Output) {
+    return [
+        "You are a technical writing editor specializing in software engineering guardrails and coding standards.",
+        "",
+        "The following is a refined guardrail rule. Append a \"## How to Check\" section at the end.",
+        "The section must describe concrete, mechanical ways to verify the rule is being followed.",
+        "Include specific grep patterns, lint rules, code review checkpoints, or CI checks as appropriate.",
+        "Each verification step must be a checklist item (- [ ]) that a reviewer can mark off.",
+        "Output the complete guardrail with the new section appended — no preamble, no commentary.",
+        "",
+        "---",
+        "",
+        stage1Output,
+    ].join("\n");
+}
+/**
+ * Build the Stage 3 prompt: Add Examples (Good/Bad).
+ * Appends Good Example and Bad Example sections with inline code snippets.
+ * @param stage2Output - The guardrail text with verification from Stage 2.
+ * @returns The full prompt string for Stage 3.
+ */
+export function buildStage3Prompt(stage2Output) {
+    return [
+        "You are a technical writing editor specializing in software engineering guardrails and coding standards.",
+        "",
+        "The following is a refined guardrail rule with verification steps.",
+        "Append a \"## Good Example\" section and a \"## Bad Example\" section at the end.",
+        "Each section must contain inline code snippets (using fenced code blocks) that illustrate",
+        "compliance and violation of the rule respectively.",
+        "Include brief comments in the code explaining why each example is good or bad.",
+        "Output the complete guardrail with both new sections appended — no preamble, no commentary.",
+        "",
+        "---",
+        "",
+        stage2Output,
+    ].join("\n");
+}
+// ── Execution helpers ────────────────────────────────────────────────
+async function executeStage(prompt, mode, model, apiKey) {
+    if (mode === "api") {
+        const client = new Anthropic({
+            apiKey: apiKey || process.env.ANTHROPIC_API_KEY,
+        });
+        const response = await client.messages.create({
+            model,
+            max_tokens: 4096,
+            messages: [{ role: "user", content: prompt }],
+        });
+        const textBlock = response.content.find((block) => block.type === "text");
+        return textBlock ? textBlock.text : "";
+    }
+    // claude-code mode — pipe prompt via stdin (the -p flag hangs as subprocess)
+    return new Promise((resolve, reject) => {
+        const child = spawn("claude", ["--print"], {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let resolved = false;
+        let dataTimer = null;
+        const finish = () => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(overallTimer);
+            if (dataTimer)
+                clearTimeout(dataTimer);
+            child.kill();
+            resolve(stdout.trim());
+        };
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+            if (dataTimer)
+                clearTimeout(dataTimer);
+            dataTimer = setTimeout(finish, 2000);
+        });
+        child.on("close", () => {
+            finish();
+        });
+        const overallTimer = setTimeout(() => {
+            if (!resolved) {
+                resolved = true;
+                if (dataTimer)
+                    clearTimeout(dataTimer);
+                child.kill("SIGKILL");
+                reject(new Error(`Claude Code timed out after ${SPAWN_TIMEOUT_MS / 1000}s`));
+            }
+        }, SPAWN_TIMEOUT_MS);
+        child.on("error", (err) => {
+            if (!resolved) {
+                resolved = true;
+                clearTimeout(overallTimer);
+                if (dataTimer)
+                    clearTimeout(dataTimer);
+                reject(err);
+            }
+        });
+        // Write prompt to stdin and close it
+        child.stdin.write(prompt);
+        child.stdin.end();
+    });
+}
+/**
+ * Run the 3-stage guardrail refinement pipeline.
+ *
+ * - clipboard: Executes all 3 stages via Anthropic API with chained outputs. Does not modify files.
+ * - api: Executes all 3 stages via Anthropic API. Writes final output to file.
+ * - claude-code: Executes via Claude Code CLI. Writes final output to file.
+ *
+ * @param options - Pipeline configuration including name, mode, and optional model/apiKey.
+ * @returns The prompts used and the final output.
+ * @throws If the guardrail file does not exist.
+ */
+export async function refinePipeline(options) {
+    const filePath = join(guardrailsDir(), `${options.name}.md`);
+    if (!existsSync(filePath)) {
+        throw new Error(`Guardrail not found: .stoa/guardrails/${options.name}.md`);
+    }
+    const seed = readFileSync(filePath, "utf-8");
+    const model = options.model ?? "claude-sonnet-4-6";
+    const builders = [buildStage1Prompt, buildStage2Prompt, buildStage3Prompt];
+    const executeMode = options.mode === "clipboard" ? "api" : options.mode;
+    const prompts = [];
+    let currentInput = seed;
+    for (let i = 0; i < builders.length; i++) {
+        const prompt = builders[i](currentInput);
+        prompts.push(prompt);
+        currentInput = await executeStage(prompt, executeMode, model, options.apiKey);
+        options.onStageComplete?.(i, STAGE_LABELS[i], currentInput);
+    }
+    // Only write back to file for api/claude-code modes
+    if (options.mode !== "clipboard") {
+        writeFileSync(filePath, currentInput, "utf-8");
+    }
+    return { prompts, finalOutput: currentInput };
+}
+//# sourceMappingURL=refine.js.map

package/dist/guardrails/refine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refine.js","sourceRoot":"","sources":["../../src/guardrails/refine.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Stoa MCP Server entry point.
+ * Registers refine_task, score_spec tools, guardrails resource, and refine prompt.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/index.js

@@ -0,0 +1,196 @@
+/**
+ * Stoa MCP Server entry point.
+ * Registers refine_task, score_spec tools, guardrails resource, and refine prompt.
+ */
+import { access, readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { refinePipeline } from "./core/refine.js";
+import { computeSpecScore } from "./core/spec-score.js";
+import { writeSpecFiles, writeRefineMeta } from "./storage/index.js";
+import { toSlug, resolveSlug } from "./utils/slug.js";
+import { scanProject } from "./storage/project-scan.js";
+import { syncMoodboard } from "./storage/moodboard-sync.js";
+const STAGE_NAMES = ["clarify", "structure", "score", "harden", "finalize"];
+const STAGE_NAME_TO_NUMBER = {
+    clarify: 1,
+    structure: 2,
+    score: 3,
+    harden: 4,
+    finalize: 5,
+};
+const server = new McpServer({
+    name: "stoa",
+    version: "0.1.0",
+});
+// ── Tool: refine_task ─────────────────────────────────────────────────
+server.tool("refine_task", "Refine a task description through a multi-stage pipeline that produces a structured specification.", {
+    title: z.string(),
+    description: z.string(),
+    stages: z.array(z.string()).optional(),
+    project_context: z.string().optional(),
+    role: z.string().optional(),
+}, async ({ title, description, stages, project_context, role }) => {
+    // Check that .stoa/ exists before running the pipeline
+    const stoaDir = join(process.cwd(), ".stoa");
+    try {
+        await access(stoaDir);
+    }
+    catch {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Error: .stoa/ directory not found. Run 'stoa init' to initialize your project.",
+                },
+            ],
+            isError: true,
+        };
+    }
+    const stageNumbers = (stages ?? [...STAGE_NAMES]).map((name) => {
+        const num = STAGE_NAME_TO_NUMBER[name];
+        if (!num) {
+            throw new Error(`Unknown stage: ${name}. Valid stages: ${STAGE_NAMES.join(", ")}`);
+        }
+        return num;
+    });
+    // Sync moodboard tokens before pipeline
+    try {
+        syncMoodboard(process.cwd());
+    }
+    catch {
+        // Non-critical — notes.md may not exist
+    }
+    // Scan project for context
+    let projectCtx;
+    try {
+        projectCtx = scanProject(process.cwd());
+    }
+    catch {
+        // Non-critical
+    }
+    const result = await refinePipeline({
+        title,
+        description,
+        projectContext: project_context,
+        projectCtx,
+        role,
+    }, { stages: stageNumbers });
+    // Write spec files to .stoa/specs/ — surface errors to caller
+    const specsDir = join(stoaDir, "specs");
+    const slug = await resolveSlug(specsDir, toSlug(title));
+    const stagesRun = {};
+    for (const sr of result.stages) {
+        stagesRun[sr.stage] = sr.rawResponse;
+    }
+    try {
+        await writeSpecFiles(specsDir, slug, stagesRun);
+        await writeRefineMeta(specsDir, slug, result.stages.map((s) => s.stage), result.executionMode, "0.1.0");
+    }
+    catch (writeErr) {
+        const msg = writeErr instanceof Error ? writeErr.message : String(writeErr);
+        process.stderr.write(`Warning: Failed to write spec files to .stoa/specs/${slug}/: ${msg}\n`);
+    }
+    // If all 5 stages ran successfully, the score is 5/5 regardless of input fields
+    const allFiveRan = result.stages.length === 5 &&
+        [1, 2, 3, 4, 5].every((s) => result.stages.some((sr) => sr.stage === s));
+    if (allFiveRan) {
+        result.finalSpecScore = 5;
+    }
+    const specPath = join(specsDir, slug);
+    const response = { ...result, spec_path: specPath };
+    return {
+        content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+    };
+});
+// ── Tool: score_spec ──────────────────────────────────────────────────
+server.tool("score_spec", "Compute a spec-readiness score for a specification string.", {
+    spec: z.string(),
+}, ({ spec }) => {
+    const hasDescription = spec.length > 0;
+    const result = computeSpecScore({
+        hasDescription,
+        descriptionLength: spec.length,
+        wasRefined: false,
+        hasAcceptanceCriteria: false,
+        hasGuardrails: false,
+        hasRole: false,
+        hasScenarios: false,
+        hasSubtasks: false,
+    });
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+// ── Resource: guardrails ──────────────────────────────────────────────
+server.resource("guardrails", "stoa://guardrails", { description: "Project guardrails from .stoa/guardrails/ directory" }, async () => {
+    const guardrailsDir = join(process.cwd(), ".stoa", "guardrails");
+    try {
+        const files = await readdir(guardrailsDir);
+        const mdFiles = files.filter((f) => f.endsWith(".md")).sort();
+        if (mdFiles.length === 0) {
+            return {
+                contents: [
+                    {
+                        uri: "stoa://guardrails",
+                        text: "No guardrail files found in .stoa/guardrails/",
+                        mimeType: "text/plain",
+                    },
+                ],
+            };
+        }
+        const parts = [];
+        for (const file of mdFiles) {
+            const content = await readFile(join(guardrailsDir, file), "utf-8");
+            parts.push(content);
+        }
+        return {
+            contents: [
+                {
+                    uri: "stoa://guardrails",
+                    text: parts.join("\n\n"),
+                    mimeType: "text/markdown",
+                },
+            ],
+        };
+    }
+    catch {
+        return {
+            contents: [
+                {
+                    uri: "stoa://guardrails",
+                    text: "Guardrails directory (.stoa/guardrails/) does not exist.",
+                    mimeType: "text/plain",
+                },
+            ],
+        };
+    }
+});
+// ── Prompt: refine ────────────────────────────────────────────────────
+server.prompt("refine", "Generate a prompt to refine a task using the refine_task tool.", {
+    title: z.string(),
+    description: z.string(),
+}, ({ title, description }) => ({
+    messages: [
+        {
+            role: "user",
+            content: {
+                type: "text",
+                text: `Please call the refine_task tool with the following:\n\ntitle: ${title}\ndescription: ${description}`,
+            },
+        },
+    ],
+}));
+// ── Start server ──────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("stoa-mcp server running on stdio\n");
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal: ${err}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/storage/change-detection.d.ts

@@ -0,0 +1,2 @@
+export declare function detectChanges(specDir: string, snapshot: Record<string, string>): Promise<number[]>;
+//# sourceMappingURL=change-detection.d.ts.map

package/dist/storage/change-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-detection.d.ts","sourceRoot":"","sources":["../../src/storage/change-detection.ts"],"names":[],"mappings":"AAWA,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,OAAO,CAAC,MAAM,EAAE,CAAC,CA6CnB"}

package/dist/storage/change-detection.js

@@ -0,0 +1,47 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+const STAGE_MAP = {
+    "01-problem-statement.md": [2, 3, 5],
+    "02-acceptance-criteria.md": [3, 5],
+    "03-constraints.md": [5],
+    "user-notes.md": [1, 3, 5],
+    "moodboard.md": [1, 3],
+};
+export async function detectChanges(specDir, snapshot) {
+    // Check all files in STAGE_MAP — not just snapshot keys.
+    // Files absent from the snapshot but now present on disk are new (dirty).
+    const filenames = Object.keys(STAGE_MAP);
+    const results = await Promise.all(filenames.map(async (filename) => {
+        let current;
+        try {
+            current = await readFile(join(specDir, filename), "utf-8");
+        }
+        catch {
+            current = null;
+        }
+        const prev = snapshot[filename];
+        // File didn't exist before and still doesn't — no change
+        if (prev === undefined && current === null) {
+            return [];
+        }
+        // File is new (didn't exist in snapshot but exists now)
+        if (prev === undefined && current !== null) {
+            process.stderr.write(`[change-detection] new: ${filename}\n`);
+            return STAGE_MAP[filename] ?? [];
+        }
+        // File was deleted (existed in snapshot but gone now)
+        if (prev !== undefined && current === null) {
+            process.stderr.write(`[change-detection] deleted: ${filename}\n`);
+            return STAGE_MAP[filename] ?? [];
+        }
+        // File content changed
+        if (current !== prev) {
+            process.stderr.write(`[change-detection] dirty: ${filename}\n`);
+            return STAGE_MAP[filename] ?? [];
+        }
+        return [];
+    }));
+    const stages = new Set(results.flat());
+    return [...stages].sort((a, b) => a - b);
+}
+//# sourceMappingURL=change-detection.js.map

package/dist/storage/change-detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-detection.js","sourceRoot":"","sources":["../../src/storage/change-detection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,SAAS,GAAsC;IACnD,yBAAyB,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACpC,2BAA2B,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IACnC,mBAAmB,EAAE,CAAC,CAAC,CAAC;IACxB,eAAe,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAC1B,cAAc,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;CACd,CAAC;AAEX,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAe,EACf,QAAgC;IAEhC,yDAAyD;IACzD,0EAA0E;IAC1E,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAEzC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE;QAC/B,IAAI,OAAsB,CAAC;QAC3B,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC;QAC7D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;QAED,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAEhC,yDAAyD;QACzD,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YAC3C,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,wDAAwD;QACxD,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YAC3C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2BAA2B,QAAQ,IAAI,CAAC,CAAC;YAC9D,OAAO,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,CAAC;QAED,sDAAsD;QACtD,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YAC3C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,+BAA+B,QAAQ,IAAI,CAAC,CAAC;YAClE,OAAO,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,CAAC;QAED,uBAAuB;QACvB,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,6BAA6B,QAAQ,IAAI,CAAC,CAAC;YAChE,OAAO,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,CAAC;QAED,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC,CACH,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAC3C,CAAC"}

package/dist/storage/change-detection.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=change-detection.test.d.ts.map

package/dist/storage/change-detection.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-detection.test.d.ts","sourceRoot":"","sources":["../../src/storage/change-detection.test.ts"],"names":[],"mappings":""}