@substrate-ai/factory 0.19.54

package/dist/context/__tests__/summary-types.test.js

@@ -0,0 +1,130 @@
+import { describe, it, expect } from 'vitest';
+import { SUMMARY_BUDGET, DEFAULT_SUMMARY_LEVEL, computeBudget, } from '../summary-types.js';
+// MockSummaryEngine implements SummaryEngine — compile-time verification
+class MockSummaryEngine {
+    name = 'mock';
+    async summarize(content, targetLevel, _opts) {
+        return {
+            level: targetLevel,
+            content: content.slice(0, Math.floor(content.length * SUMMARY_BUDGET[targetLevel])),
+            originalHash: 'abc123deadbeef0000000000000000000000000000000000000000000000000000',
+            createdAt: new Date().toISOString(),
+        };
+    }
+    async expand(summary, _targetLevel, opts) {
+        return opts?.originalContent ?? summary.content;
+    }
+}
+describe('SUMMARY_BUDGET', () => {
+    it('full level has budget 1.0', () => {
+        expect(SUMMARY_BUDGET['full']).toBe(1.0);
+    });
+    it('high level has budget 0.75', () => {
+        expect(SUMMARY_BUDGET['high']).toBe(0.75);
+    });
+    it('medium level has budget 0.50', () => {
+        expect(SUMMARY_BUDGET['medium']).toBe(0.50);
+    });
+    it('low level has budget 0.25', () => {
+        expect(SUMMARY_BUDGET['low']).toBe(0.25);
+    });
+});
+describe('DEFAULT_SUMMARY_LEVEL', () => {
+    it('default level is medium', () => {
+        expect(DEFAULT_SUMMARY_LEVEL).toBe('medium');
+    });
+});
+describe('Summary interface shape', () => {
+    it('minimal Summary with all required fields is valid', () => {
+        const summary = {
+            level: 'medium',
+            content: 'Summarized content here.',
+            originalHash: 'deadbeef00000000000000000000000000000000000000000000000000000000',
+            createdAt: '2026-03-26T00:00:00.000Z',
+        };
+        expect(summary).toMatchObject({
+            level: 'medium',
+            content: 'Summarized content here.',
+            originalHash: 'deadbeef00000000000000000000000000000000000000000000000000000000',
+            createdAt: '2026-03-26T00:00:00.000Z',
+        });
+    });
+    it('full Summary with all optional fields is valid', () => {
+        const summary = {
+            level: 'high',
+            content: 'High-fidelity summary.',
+            originalHash: 'cafebabe00000000000000000000000000000000000000000000000000000000',
+            createdAt: '2026-03-26T12:00:00.000Z',
+            originalTokenCount: 8000,
+            summaryTokenCount: 6000,
+            metadata: { engine: 'llm', model: 'claude-3-5-sonnet' },
+        };
+        expect(summary.originalTokenCount).toBe(8000);
+        expect(summary.summaryTokenCount).toBe(6000);
+        expect(summary.metadata).toEqual({ engine: 'llm', model: 'claude-3-5-sonnet' });
+    });
+});
+describe('SummaryEngine interface', () => {
+    it('engine.name is a string', () => {
+        const engine = new MockSummaryEngine();
+        expect(typeof engine.name).toBe('string');
+        expect(engine.name).toBe('mock');
+    });
+    it('summarize() returns a Summary with the requested level', async () => {
+        const engine = new MockSummaryEngine();
+        const content = 'This is a long piece of context that should be summarized.';
+        const summary = await engine.summarize(content, 'medium');
+        expect(summary.level).toBe('medium');
+        expect(typeof summary.content).toBe('string');
+        expect(typeof summary.originalHash).toBe('string');
+        expect(typeof summary.createdAt).toBe('string');
+    });
+    it('expand() returns a string', async () => {
+        const engine = new MockSummaryEngine();
+        const summary = {
+            level: 'medium',
+            content: 'Compressed context.',
+            originalHash: 'abc123',
+            createdAt: new Date().toISOString(),
+        };
+        const expanded = await engine.expand(summary, 'full');
+        expect(typeof expanded).toBe('string');
+    });
+    it('expand() uses originalContent when provided', async () => {
+        const engine = new MockSummaryEngine();
+        const summary = {
+            level: 'medium',
+            content: 'Compressed context.',
+            originalHash: 'abc123',
+            createdAt: new Date().toISOString(),
+        };
+        const original = 'Full original context that was compressed.';
+        const expanded = await engine.expand(summary, 'full', { originalContent: original });
+        expect(expanded).toBe(original);
+    });
+});
+describe('computeBudget', () => {
+    it('returns 100% of tokens for full level', () => {
+        const budget = computeBudget(100_000, 'full');
+        expect(budget.targetTokenCount).toBe(100_000);
+        expect(budget.compressionRatio).toBe(1.0);
+        expect(budget.modelTokenLimit).toBe(100_000);
+        expect(budget.level).toBe('full');
+    });
+    it('returns 50% of tokens for medium level', () => {
+        const budget = computeBudget(100_000, 'medium');
+        expect(budget.targetTokenCount).toBe(50_000);
+        expect(budget.compressionRatio).toBe(0.50);
+    });
+    it('returns 25% of tokens for low level', () => {
+        const budget = computeBudget(100_000, 'low');
+        expect(budget.targetTokenCount).toBe(25_000);
+        expect(budget.compressionRatio).toBe(0.25);
+    });
+    it('returns 75% of tokens for high level with larger limit', () => {
+        const budget = computeBudget(200_000, 'high');
+        expect(budget.targetTokenCount).toBe(150_000);
+        expect(budget.compressionRatio).toBe(0.75);
+    });
+});
+//# sourceMappingURL=summary-types.test.js.map

package/dist/context/__tests__/summary-types.test.js.map

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

package/dist/context/auto-summarizer.d.ts

@@ -0,0 +1,120 @@
+/**
+ * AutoSummarizer — automatic context compression for long-running convergence loops.
+ *
+ * Monitors accumulated iteration contexts and compresses older iterations
+ * when the total token estimate crosses a configurable fraction of the model's
+ * token limit. Designed for injection into ConvergenceController (story 49-3).
+ */
+import type { SummaryEngine } from './summary-engine.js';
+import type { Summary, SummaryLevel } from './summary-types.js';
+/**
+ * Configuration for AutoSummarizer.
+ *
+ * All fields are optional; defaults are applied in the constructor.
+ */
+export interface AutoSummarizerConfig {
+    /**
+     * Fraction of the model's token limit that triggers compression.
+     * Default: 0.8. Valid range: [0.5, 0.95].
+     */
+    threshold?: number;
+    /**
+     * Summary level to compress older iterations to.
+     * Default: 'medium'.
+     */
+    targetLevel?: SummaryLevel;
+}
+/**
+ * Context accumulated during a single convergence iteration.
+ */
+export interface IterationContext {
+    /** Zero-based iteration index within the convergence loop. */
+    index: number;
+    /** Accumulated text for this iteration (agent output, decisions, diffs). */
+    content: string;
+    /**
+     * Cached token estimate. Auto-computed from content via estimateTokens() if absent.
+     * Set this field to avoid repeated computation across shouldTrigger() calls.
+     */
+    tokenEstimate?: number;
+}
+/**
+ * A previous iteration that has been compressed to a summary.
+ *
+ * The `compressed: true` discriminant literal enables TypeScript type narrowing:
+ *   if ('compressed' in ctx) { // ctx is CompressedIterationContext }
+ */
+export interface CompressedIterationContext {
+    index: number;
+    summary: Summary;
+    /** Discriminant literal — enables TypeScript type narrowing. */
+    compressed: true;
+}
+/**
+ * Result returned by AutoSummarizer.compress().
+ */
+export interface CompressionResult {
+    /**
+     * The updated iteration array: previous iterations are replaced with
+     * CompressedIterationContext objects; the current iteration passes through unchanged.
+     */
+    iterations: (IterationContext | CompressedIterationContext)[];
+    /**
+     * Indices of the iterations that were compressed in this call.
+     */
+    compressedIndices: number[];
+}
+/**
+ * Approximate token count using the chars/4 heuristic.
+ *
+ * Pure synchronous function — no imports, no async.
+ * Returns 0 for falsy input (empty string, null, undefined).
+ *
+ * @param text - The text to estimate token count for
+ * @returns Estimated token count: Math.ceil(text.length / 4)
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Monitors convergence loop iteration contexts and compresses older iterations
+ * when accumulated token usage exceeds the configured threshold.
+ *
+ * Inject into ConvergenceController via ConvergenceControllerConfig.autoSummarizer.
+ * Depends on the SummaryEngine interface — does NOT import LLMSummaryEngine directly
+ * (inversion of control).
+ */
+export declare class AutoSummarizer {
+    private readonly engine;
+    private readonly modelTokenLimit;
+    private readonly threshold;
+    private readonly targetLevel;
+    /**
+     * @param engine - The summarization engine to use for compression
+     * @param modelTokenLimit - The model's maximum token limit (positive integer)
+     * @param config - Optional configuration; defaults applied for missing fields
+     * @throws {RangeError} When threshold is outside the valid range [0.5, 0.95]
+     */
+    constructor(engine: SummaryEngine, modelTokenLimit: number, config?: AutoSummarizerConfig);
+    /**
+     * Returns true when the total estimated token count across all iterations
+     * is strictly greater than `threshold * modelTokenLimit`.
+     *
+     * Uses `iter.tokenEstimate` when present to avoid recomputing from content.
+     *
+     * @param iterations - The accumulated iteration contexts to evaluate
+     * @returns `true` when compression should be triggered; `false` otherwise
+     */
+    shouldTrigger(iterations: IterationContext[]): boolean;
+    /**
+     * Compress all iterations with `index < currentIndex` to the configured
+     * summary level. The iteration at `currentIndex` (and any later) passes through
+     * unchanged.
+     *
+     * @param iterations - The full set of iteration contexts to process
+     * @param currentIndex - The index of the iteration currently being dispatched;
+     *                       this iteration and any with higher indices are never compressed
+     * @returns A CompressionResult containing the updated iterations array and
+     *          the list of indices that were compressed
+     */
+    compress(iterations: IterationContext[], currentIndex: number): Promise<CompressionResult>;
+}
+//# sourceMappingURL=auto-summarizer.d.ts.map

package/dist/context/auto-summarizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-summarizer.d.ts","sourceRoot":"","sources":["../../src/context/auto-summarizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAE/D;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,YAAY,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IAChB,gEAAgE;IAChE,UAAU,EAAE,IAAI,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,UAAU,EAAE,CAAC,gBAAgB,GAAG,0BAA0B,CAAC,EAAE,CAAA;IAC7D;;OAEG;IACH,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAC5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED;;;;;;;GAOG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAE1C;;;;;OAKG;gBACS,MAAM,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,oBAAoB;IAWzF;;;;;;;;OAQG;IACH,aAAa,CAAC,UAAU,EAAE,gBAAgB,EAAE,GAAG,OAAO;IAQtD;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,UAAU,EAAE,gBAAgB,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAgBjG"}

package/dist/context/auto-summarizer.js

@@ -0,0 +1,91 @@
+/**
+ * AutoSummarizer — automatic context compression for long-running convergence loops.
+ *
+ * Monitors accumulated iteration contexts and compresses older iterations
+ * when the total token estimate crosses a configurable fraction of the model's
+ * token limit. Designed for injection into ConvergenceController (story 49-3).
+ */
+/**
+ * Approximate token count using the chars/4 heuristic.
+ *
+ * Pure synchronous function — no imports, no async.
+ * Returns 0 for falsy input (empty string, null, undefined).
+ *
+ * @param text - The text to estimate token count for
+ * @returns Estimated token count: Math.ceil(text.length / 4)
+ */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Monitors convergence loop iteration contexts and compresses older iterations
+ * when accumulated token usage exceeds the configured threshold.
+ *
+ * Inject into ConvergenceController via ConvergenceControllerConfig.autoSummarizer.
+ * Depends on the SummaryEngine interface — does NOT import LLMSummaryEngine directly
+ * (inversion of control).
+ */
+export class AutoSummarizer {
+    engine;
+    modelTokenLimit;
+    threshold;
+    targetLevel;
+    /**
+     * @param engine - The summarization engine to use for compression
+     * @param modelTokenLimit - The model's maximum token limit (positive integer)
+     * @param config - Optional configuration; defaults applied for missing fields
+     * @throws {RangeError} When threshold is outside the valid range [0.5, 0.95]
+     */
+    constructor(engine, modelTokenLimit, config) {
+        const threshold = config?.threshold ?? 0.8;
+        if (threshold < 0.5 || threshold > 0.95) {
+            throw new RangeError('context_summarize_threshold must be between 0.5 and 0.95');
+        }
+        this.engine = engine;
+        this.modelTokenLimit = modelTokenLimit;
+        this.threshold = threshold;
+        this.targetLevel = config?.targetLevel ?? 'medium';
+    }
+    /**
+     * Returns true when the total estimated token count across all iterations
+     * is strictly greater than `threshold * modelTokenLimit`.
+     *
+     * Uses `iter.tokenEstimate` when present to avoid recomputing from content.
+     *
+     * @param iterations - The accumulated iteration contexts to evaluate
+     * @returns `true` when compression should be triggered; `false` otherwise
+     */
+    shouldTrigger(iterations) {
+        const total = iterations.reduce((sum, iter) => sum + (iter.tokenEstimate ?? estimateTokens(iter.content)), 0);
+        return total > this.threshold * this.modelTokenLimit;
+    }
+    /**
+     * Compress all iterations with `index < currentIndex` to the configured
+     * summary level. The iteration at `currentIndex` (and any later) passes through
+     * unchanged.
+     *
+     * @param iterations - The full set of iteration contexts to process
+     * @param currentIndex - The index of the iteration currently being dispatched;
+     *                       this iteration and any with higher indices are never compressed
+     * @returns A CompressionResult containing the updated iterations array and
+     *          the list of indices that were compressed
+     */
+    async compress(iterations, currentIndex) {
+        const compressedIndices = [];
+        const result = [];
+        for (const iter of iterations) {
+            if (iter.index < currentIndex && iter.content !== '') {
+                const summary = await this.engine.summarize(iter.content, this.targetLevel);
+                result.push({ index: iter.index, summary, compressed: true });
+                compressedIndices.push(iter.index);
+            }
+            else {
+                result.push(iter);
+            }
+        }
+        return { iterations: result, compressedIndices };
+    }
+}
+//# sourceMappingURL=auto-summarizer.js.map

package/dist/context/auto-summarizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-summarizer.js","sourceRoot":"","sources":["../../src/context/auto-summarizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkEH;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAA;IACnB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,cAAc;IACR,MAAM,CAAe;IACrB,eAAe,CAAQ;IACvB,SAAS,CAAQ;IACjB,WAAW,CAAc;IAE1C;;;;;OAKG;IACH,YAAY,MAAqB,EAAE,eAAuB,EAAE,MAA6B;QACvF,MAAM,SAAS,GAAG,MAAM,EAAE,SAAS,IAAI,GAAG,CAAA;QAC1C,IAAI,SAAS,GAAG,GAAG,IAAI,SAAS,GAAG,IAAI,EAAE,CAAC;YACxC,MAAM,IAAI,UAAU,CAAC,0DAA0D,CAAC,CAAA;QAClF,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,eAAe,GAAG,eAAe,CAAA;QACtC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;QAC1B,IAAI,CAAC,WAAW,GAAG,MAAM,EAAE,WAAW,IAAI,QAAQ,CAAA;IACpD,CAAC;IAED;;;;;;;;OAQG;IACH,aAAa,CAAC,UAA8B;QAC1C,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAC7B,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,aAAa,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EACzE,CAAC,CACF,CAAA;QACD,OAAO,KAAK,GAAG,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,eAAe,CAAA;IACtD,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,QAAQ,CAAC,UAA8B,EAAE,YAAoB;QACjE,MAAM,iBAAiB,GAAa,EAAE,CAAA;QACtC,MAAM,MAAM,GAAsD,EAAE,CAAA;QAEpE,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;YAC9B,IAAI,IAAI,CAAC,KAAK,GAAG,YAAY,IAAI,IAAI,CAAC,OAAO,KAAK,EAAE,EAAE,CAAC;gBACrD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,CAAC,CAAA;gBAC3E,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAA;gBAC7D,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YACpC,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YACnB,CAAC;QACH,CAAC;QAED,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAA;IAClD,CAAC;CACF"}

package/dist/context/cli-command.d.ts

@@ -0,0 +1,109 @@
+/**
+ * CLI subcommand registration for pyramid summary management.
+ *
+ * Registers:
+ *   factory context summarize  --run <id> --iteration <n> --level <level>
+ *   factory context expand     --run <id> --iteration <n>
+ *   factory context stats      --run <id>
+ *
+ * Story 49-7.
+ */
+import type { Command } from 'commander';
+import type { SummaryLevel } from './summary-types.js';
+import type { SummaryEngine } from './summary-engine.js';
+/** Machine-readable JSON output envelope for `--output-format json` mode. */
+export interface CLIJsonOutput<T> {
+    timestamp: string;
+    version: string;
+    command: string;
+    data: T;
+}
+/** Build a CLIJsonOutput envelope. */
+export declare function buildJsonOutput<T>(command: string, data: T, version: string): CLIJsonOutput<T>;
+export interface SummarizeActionOpts {
+    run: string;
+    iteration: string;
+    level: string;
+    outputFormat: string;
+}
+export interface SummarizeActionDeps {
+    storageDir: string;
+    version: string;
+    engineFactory?: () => SummaryEngine;
+}
+/**
+ * Core logic for `factory context summarize`.
+ *
+ * Loads the original content, runs it through CachingSummaryEngine, stores the
+ * result, and prints compression statistics.
+ *
+ * @returns Exit code: 0 on success, 1 on error.
+ */
+export declare function summarizeAction(opts: SummarizeActionOpts, deps: SummarizeActionDeps, output?: {
+    stdout: NodeJS.WritableStream;
+    stderr: NodeJS.WritableStream;
+}): Promise<number>;
+export interface ExpandActionOpts {
+    run: string;
+    iteration: string;
+    outputFormat: string;
+}
+export interface ExpandActionDeps {
+    storageDir: string;
+    version: string;
+    engineFactory?: () => SummaryEngine;
+}
+/**
+ * Core logic for `factory context expand`.
+ *
+ * Finds the stored summary for the given iteration, then expands it back
+ * toward full content (lossless if .orig exists, LLM fallback otherwise).
+ *
+ * @returns Exit code: 0 on success, 1 on error.
+ */
+export declare function expandAction(opts: ExpandActionOpts, deps: ExpandActionDeps, output?: {
+    stdout: NodeJS.WritableStream;
+    stderr: NodeJS.WritableStream;
+}): Promise<number>;
+export interface StatsRow {
+    hash: string;
+    level: SummaryLevel;
+    compressionRatio: number;
+    keyFactRetentionRate: number;
+    cachedAt: string;
+}
+export interface StatsActionOpts {
+    run: string;
+    outputFormat: string;
+}
+export interface StatsActionDeps {
+    storageDir: string;
+    version: string;
+}
+/**
+ * Core logic for `factory context stats`.
+ *
+ * Reads all stored summary records for a run, computes compression metrics,
+ * and prints a formatted table (or JSON array).
+ *
+ * @returns Exit code: 0 on success, 1 on error.
+ */
+export declare function statsAction(opts: StatsActionOpts, deps: StatsActionDeps, output?: {
+    stdout: NodeJS.WritableStream;
+    stderr: NodeJS.WritableStream;
+}): Promise<number>;
+/**
+ * Register the `context` subcommand group on the provided factory command.
+ *
+ * Subcommands registered:
+ *   factory context summarize --run <id> --iteration <n> --level <level>
+ *   factory context expand    --run <id> --iteration <n>
+ *   factory context stats     --run <id>
+ *
+ * @param factoryCmd    - The factory Commander command to attach to
+ * @param version       - CLI version string for JSON output (e.g. "1.2.3")
+ * @param storageDir    - Base storage directory (defaults to `{cwd}/.substrate`)
+ * @param engineFactory - Optional SummaryEngine factory for testing injection
+ */
+export declare function registerContextCommand(factoryCmd: Command, version: string, storageDir?: string, engineFactory?: () => SummaryEngine): void;
+//# sourceMappingURL=cli-command.d.ts.map

package/dist/context/cli-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-command.d.ts","sourceRoot":"","sources":["../../src/context/cli-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAIxC,OAAO,KAAK,EAAE,YAAY,EAAW,MAAM,oBAAoB,CAAA;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAMxD,6EAA6E;AAC7E,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,CAAC,CAAA;CACR;AAED,sCAAsC;AACtC,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,CAO9F;AAmFD,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,aAAa,CAAC,EAAE,MAAM,aAAa,CAAA;CACpC;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,mBAAmB,EACzB,MAAM,GAAE;IAAE,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAA;CAGrE,GACA,OAAO,CAAC,MAAM,CAAC,CA+EjB;AAMD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,aAAa,CAAC,EAAE,MAAM,aAAa,CAAA;CACpC;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,gBAAgB,EACtB,MAAM,GAAE;IAAE,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAA;CAGrE,GACA,OAAO,CAAC,MAAM,CAAC,CAkDjB;AAMD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,YAAY,CAAA;IACnB,gBAAgB,EAAE,MAAM,CAAA;IACxB,oBAAoB,EAAE,MAAM,CAAA;IAC5B,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,eAAe,EACrB,MAAM,GAAE;IAAE,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAA;CAGrE,GACA,OAAO,CAAC,MAAM,CAAC,CAsGjB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,EACnB,aAAa,CAAC,EAAE,MAAM,aAAa,GAClC,IAAI,CAuDN"}