@stoneforge/quarry 0.1.0

package/dist/cli/commands/gc.js

@@ -0,0 +1,257 @@
+/**
+ * Garbage Collection Commands - Clean up ephemeral data
+ *
+ * Provides commands for:
+ * - gc tasks: Garbage collect old ephemeral tasks
+ * - gc workflows: Garbage collect old ephemeral workflows
+ */
+import { success, failure, ExitCode } from '../types.js';
+import { getFormatter, getOutputMode } from '../formatter.js';
+import { suggestCommands } from '../suggest.js';
+import { createAPI } from '../db.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_GC_AGE_DAYS = 1; // 24 hours
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const gcTasksOptions = [
+    {
+        name: 'age',
+        short: 'a',
+        description: `Maximum age in days (default: ${DEFAULT_GC_AGE_DAYS})`,
+        hasValue: true,
+    },
+    {
+        name: 'dry-run',
+        description: 'Show what would be deleted without deleting',
+        hasValue: false,
+    },
+    {
+        name: 'limit',
+        short: 'l',
+        description: 'Maximum number of tasks to delete',
+        hasValue: true,
+    },
+];
+async function gcTasksHandler(_args, options) {
+    const { api, error } = createAPI(options);
+    if (error) {
+        return failure(error, ExitCode.GENERAL_ERROR);
+    }
+    try {
+        // Parse age option (in days)
+        const ageDays = options.age ? parseFloat(options.age) : DEFAULT_GC_AGE_DAYS;
+        if (isNaN(ageDays) || ageDays < 0) {
+            return failure('Invalid age value. Must be a positive number.', ExitCode.INVALID_ARGUMENTS);
+        }
+        const maxAgeMs = ageDays * MS_PER_DAY;
+        // Parse limit option
+        const limit = options.limit ? parseInt(options.limit, 10) : undefined;
+        if (options.limit && (isNaN(limit) || limit < 1)) {
+            return failure('Invalid limit value. Must be a positive integer.', ExitCode.INVALID_ARGUMENTS);
+        }
+        const dryRun = !!options['dry-run'];
+        // Task GC is now a no-op - tasks no longer have an ephemeral property.
+        // Only workflows can be ephemeral, and their tasks are GC'd via garbageCollectWorkflows().
+        const gcResult = await api.garbageCollectTasks({
+            maxAgeMs,
+            dryRun,
+            limit,
+        });
+        if (gcResult.tasksDeleted === 0) {
+            return success({ deleted: 0 }, 'No tasks eligible for garbage collection (tasks are now GC\'d via their parent workflows)');
+        }
+        return success(gcResult, `Garbage collected ${gcResult.tasksDeleted} task(s), ${gcResult.dependenciesDeleted} dependency(ies)`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return failure(`Failed to garbage collect tasks: ${message}`, ExitCode.GENERAL_ERROR);
+    }
+}
+const gcTasksCommand = {
+    name: 'tasks',
+    description: 'Garbage collect old tasks (deprecated - use "sf gc workflows" instead)',
+    usage: 'sf gc tasks [options]',
+    help: `Garbage collect old tasks.
+
+NOTE: This command is now a no-op. Tasks no longer have an ephemeral property.
+Only workflows can be ephemeral, and their child tasks are garbage collected
+automatically when you run 'sf gc workflows'.
+
+Use 'sf gc workflows' to garbage collect ephemeral workflows and their tasks.
+
+Options:
+  -a, --age <days>   Maximum age in days (default: ${DEFAULT_GC_AGE_DAYS})
+  -l, --limit <n>    Maximum number of tasks to delete
+      --dry-run      Show what would be deleted without deleting
+
+Examples:
+  sf gc workflows          # Recommended: GC workflows and their tasks
+  sf gc tasks              # No-op, kept for backwards compatibility`,
+    options: gcTasksOptions,
+    handler: gcTasksHandler,
+};
+const gcWorkflowsOptions = [
+    {
+        name: 'age',
+        short: 'a',
+        description: `Maximum age in days (default: ${DEFAULT_GC_AGE_DAYS})`,
+        hasValue: true,
+    },
+    {
+        name: 'dry-run',
+        description: 'Show what would be deleted without deleting',
+        hasValue: false,
+    },
+    {
+        name: 'limit',
+        short: 'l',
+        description: 'Maximum number of workflows to delete',
+        hasValue: true,
+    },
+];
+async function gcWorkflowsHandler(_args, options) {
+    const { api, error } = createAPI(options);
+    if (error) {
+        return failure(error, ExitCode.GENERAL_ERROR);
+    }
+    try {
+        const mode = getOutputMode(options);
+        const formatter = getFormatter(mode);
+        // Parse age option (in days)
+        const ageDays = options.age ? parseFloat(options.age) : DEFAULT_GC_AGE_DAYS;
+        if (isNaN(ageDays) || ageDays < 0) {
+            return failure('Invalid age value. Must be a positive number.', ExitCode.INVALID_ARGUMENTS);
+        }
+        const maxAgeMs = ageDays * MS_PER_DAY;
+        // Parse limit option
+        const limit = options.limit ? parseInt(options.limit, 10) : undefined;
+        if (options.limit && (isNaN(limit) || limit < 1)) {
+            return failure('Invalid limit value. Must be a positive integer.', ExitCode.INVALID_ARGUMENTS);
+        }
+        const dryRun = !!options['dry-run'];
+        // If dry run, show what would be deleted first
+        if (dryRun) {
+            // Get eligible workflows without deleting
+            const allWorkflows = await api.list({ type: 'workflow' });
+            const terminalStatuses = ['completed', 'failed', 'cancelled'];
+            const now = Date.now();
+            const eligibleWorkflows = allWorkflows.filter(workflow => {
+                if (!workflow.ephemeral)
+                    return false;
+                if (!terminalStatuses.includes(workflow.status))
+                    return false;
+                if (!workflow.finishedAt)
+                    return false;
+                const finishedTime = new Date(workflow.finishedAt).getTime();
+                return now - finishedTime >= maxAgeMs;
+            });
+            // Apply limit for display
+            const toShow = limit ? eligibleWorkflows.slice(0, limit) : eligibleWorkflows;
+            if (toShow.length === 0) {
+                return success({ wouldDelete: [], count: 0 }, 'No workflows eligible for garbage collection');
+            }
+            if (mode === 'json') {
+                return success({
+                    wouldDelete: toShow.map(w => w.id),
+                    count: toShow.length,
+                });
+            }
+            if (mode === 'quiet') {
+                return success(toShow.map(w => w.id).join('\n'));
+            }
+            const headers = ['ID', 'TITLE', 'STATUS', 'FINISHED'];
+            const rows = toShow.map(w => [
+                w.id,
+                w.title.length > 40 ? w.title.substring(0, 37) + '...' : w.title,
+                w.status,
+                w.finishedAt ? w.finishedAt.split('T')[0] : '-',
+            ]);
+            const table = formatter.table(headers, rows);
+            return success({ wouldDelete: toShow.map(w => w.id), count: toShow.length }, `Would delete ${toShow.length} workflow(s):\n${table}`);
+        }
+        // Actually run garbage collection
+        const gcResult = await api.garbageCollectWorkflows({
+            maxAgeMs,
+            dryRun: false,
+            limit,
+        });
+        if (gcResult.workflowsDeleted === 0) {
+            return success({ deleted: 0 }, 'No workflows eligible for garbage collection');
+        }
+        return success(gcResult, `Garbage collected ${gcResult.workflowsDeleted} workflow(s), ${gcResult.tasksDeleted} task(s), ${gcResult.dependenciesDeleted} dependency(ies)`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return failure(`Failed to garbage collect workflows: ${message}`, ExitCode.GENERAL_ERROR);
+    }
+}
+const gcWorkflowsCommand = {
+    name: 'workflows',
+    description: 'Garbage collect old ephemeral workflows',
+    usage: 'sf gc workflows [options]',
+    help: `Delete old ephemeral workflows that have reached a terminal state.
+
+Workflows are eligible for garbage collection if they are:
+- Ephemeral (not durable)
+- In a terminal state (completed, failed, or cancelled)
+- Older than the specified age
+
+Note: Deleting a workflow also deletes all tasks that belong to it.
+
+Options:
+  -a, --age <days>   Maximum age in days (default: ${DEFAULT_GC_AGE_DAYS})
+  -l, --limit <n>    Maximum number of workflows to delete
+      --dry-run      Show what would be deleted without deleting
+
+Examples:
+  sf gc workflows
+  sf gc workflows --age 7
+  sf gc workflows --dry-run`,
+    options: gcWorkflowsOptions,
+    handler: gcWorkflowsHandler,
+};
+// ============================================================================
+// GC Root Command
+// ============================================================================
+export const gcCommand = {
+    name: 'gc',
+    description: 'Garbage collect old ephemeral data',
+    usage: 'sf gc <subcommand> [options]',
+    help: `Garbage collect old ephemeral data.
+
+Stoneforge supports ephemeral tasks and workflows that are not synced to permanent
+storage. These can accumulate over time and should be periodically cleaned up.
+
+Subcommands:
+  tasks       Garbage collect old ephemeral tasks
+  workflows   Garbage collect old ephemeral workflows
+
+By default, items must be at least ${DEFAULT_GC_AGE_DAYS} day(s) old to be eligible for garbage collection.
+Use --age to change this threshold.
+
+Examples:
+  sf gc tasks                    Delete old ephemeral tasks
+  sf gc tasks --dry-run          Preview what would be deleted
+  sf gc workflows                Delete old ephemeral workflows
+  sf gc workflows --age 7        Delete workflows older than 7 days`,
+    subcommands: {
+        tasks: gcTasksCommand,
+        workflows: gcWorkflowsCommand,
+    },
+    handler: async (args, options) => {
+        if (args.length === 0) {
+            return failure(`Missing subcommand. Use 'sf gc tasks' or 'sf gc workflows'. Run 'sf gc --help' for more information.`, ExitCode.INVALID_ARGUMENTS);
+        }
+        // Show "did you mean?" for unknown subcommands
+        const subNames = Object.keys(gcCommand.subcommands);
+        const suggestions = suggestCommands(args[0], subNames);
+        let msg = `Unknown subcommand: ${args[0]}`;
+        if (suggestions.length > 0) {
+            msg += `\n\nDid you mean?\n${suggestions.map(s => `  ${s}`).join('\n')}`;
+        }
+        msg += '\n\nRun "sf gc --help" to see available subcommands.';
+        return failure(msg, ExitCode.INVALID_ARGUMENTS);
+    },
+};
+//# sourceMappingURL=gc.js.map

package/dist/cli/commands/gc.js.map

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

package/dist/cli/commands/help.d.ts

@@ -0,0 +1,11 @@
+/**
+ * help command - Display help information
+ */
+import type { Command } from '../types.js';
+export declare const helpCommand: Command;
+export declare const versionCommand: Command;
+/**
+ * Gets help text for a specific command
+ */
+export declare function getCommandHelp(command: Command): string;
+//# sourceMappingURL=help.d.ts.map

package/dist/cli/commands/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/help.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAiB,MAAM,aAAa,CAAC;AA+I1D,eAAO,MAAM,WAAW,EAAE,OAKzB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,OAK5B,CAAC;AAEF;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAmCvD"}

package/dist/cli/commands/help.js

@@ -0,0 +1,169 @@
+/**
+ * help command - Display help information
+ */
+import { success } from '../types.js';
+import { getGlobalOptionsHelp } from '../parser.js';
+import { getAllCommands } from '../runner.js';
+// ============================================================================
+// Version Info
+// ============================================================================
+const VERSION = '0.1.0';
+// ============================================================================
+// Help Text
+// ============================================================================
+// Subcommand hints for resource commands
+const SUBCOMMAND_HINTS = {
+    task: 'create, list, ready, close, ...',
+    plan: 'create, activate, tasks, ...',
+    dependency: 'add, remove, list, tree',
+    message: 'send, reply, list, thread',
+    document: 'create, list, search, ...',
+    channel: 'create, list, join, ...',
+    workflow: 'create, list, promote, ...',
+    entity: 'register, list, reports, ...',
+    team: 'create, list, ...',
+    library: 'create, list, ...',
+    inbox: 'read, read-all, archive, ...',
+};
+// Built-in command categories for display
+const COMMAND_CATEGORIES = {
+    'Elements': ['show', 'update', 'delete', 'history'],
+    'Tasks': ['task'],
+    'Planning': ['plan', 'workflow', 'playbook'],
+    'Dependencies': ['dependency'],
+    'Communication': ['message', 'inbox', 'channel'],
+    'Knowledge': ['document', 'library', 'embeddings'],
+    'Organization': ['entity', 'team'],
+    'Sync': ['sync', 'export', 'import', 'status'],
+    'System': ['init', 'reset', 'config', 'identity', 'whoami', 'stats'],
+    'Admin': ['doctor', 'migrate', 'gc'],
+    'Shell': ['completion', 'alias', 'install', 'help', 'version'],
+};
+// All categorized commands for distinguishing plugins
+const BUILTIN_COMMANDS = new Set(Object.values(COMMAND_CATEGORIES).flat());
+// Top-level task convenience commands (not shown in categories but listed separately)
+const TASK_CONVENIENCE_COMMANDS = [
+    'ready', 'blocked', 'backlog', 'close', 'reopen', 'assign', 'defer', 'undefer',
+];
+// Add task convenience commands to built-in set so they don't appear as plugins
+for (const cmd of TASK_CONVENIENCE_COMMANDS) {
+    BUILTIN_COMMANDS.add(cmd);
+}
+/**
+ * Generates the main help text dynamically
+ */
+function generateMainHelp() {
+    const lines = [
+        'Stoneforge - Agent coordination system',
+        '',
+        'Usage: stoneforge <command> [options]',
+        '       sf <command> [options]',
+        '',
+        'Commands:',
+    ];
+    const allCommands = getAllCommands();
+    const commandMap = new Map(allCommands.map(cmd => [cmd.name, cmd]));
+    // Add categorized built-in commands
+    for (const [category, commands] of Object.entries(COMMAND_CATEGORIES)) {
+        const availableCommands = commands.filter(cmd => commandMap.has(cmd));
+        if (availableCommands.length === 0)
+            continue;
+        lines.push(`  ${category}:`);
+        for (const cmdName of availableCommands) {
+            const cmd = commandMap.get(cmdName);
+            if (cmd) {
+                const hint = SUBCOMMAND_HINTS[cmdName];
+                const desc = hint ? `${cmd.description} (${hint})` : cmd.description;
+                lines.push(`    ${cmdName.padEnd(16)} ${desc}`);
+            }
+        }
+        lines.push('');
+    }
+    // Add plugin commands (commands not in built-in set)
+    const pluginCommands = allCommands
+        .filter(cmd => !BUILTIN_COMMANDS.has(cmd.name))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    if (pluginCommands.length > 0) {
+        lines.push('  Plugin Commands:');
+        for (const cmd of pluginCommands) {
+            lines.push(`    ${cmd.name.padEnd(16)} ${cmd.description}`);
+        }
+        lines.push('');
+    }
+    // Add aliases section
+    lines.push('  Aliases:');
+    lines.push('    dep              dependency');
+    lines.push('    msg              message');
+    lines.push('    doc              document');
+    lines.push('    rm, remove       delete');
+    lines.push('    s, get           show');
+    lines.push('    st               status');
+    lines.push('    todo, tasks      ready (also: sf task ready)');
+    lines.push('    done             close (also: sf task close)');
+    lines.push('    ready, blocked, close, ...  also available as sf task <verb>');
+    lines.push('');
+    lines.push(getGlobalOptionsHelp());
+    lines.push('');
+    lines.push('Use "sf <command> --help" for more information about a command.');
+    return lines.join('\n');
+}
+// ============================================================================
+// Handler
+// ============================================================================
+function helpHandler() {
+    return success(undefined, generateMainHelp());
+}
+function versionHandler() {
+    return success({ version: VERSION }, `stoneforge v${VERSION}`);
+}
+// ============================================================================
+// Command Definitions
+// ============================================================================
+export const helpCommand = {
+    name: 'help',
+    description: 'Show help information',
+    usage: 'sf help [command]',
+    handler: helpHandler,
+};
+export const versionCommand = {
+    name: 'version',
+    description: 'Show version',
+    usage: 'sf version',
+    handler: versionHandler,
+};
+/**
+ * Gets help text for a specific command
+ */
+export function getCommandHelp(command) {
+    const lines = [
+        command.description,
+        '',
+        `Usage: ${command.usage}`,
+    ];
+    if (command.help) {
+        lines.push('', command.help);
+    }
+    if (command.options && command.options.length > 0) {
+        lines.push('', 'Options:');
+        for (const opt of command.options) {
+            const shortPart = opt.short ? `-${opt.short}, ` : '    ';
+            const valuePart = opt.hasValue ? ` <${opt.name}>` : '';
+            const requiredPart = opt.required ? ' (required)' : '';
+            lines.push(`  ${shortPart}--${opt.name}${valuePart}${requiredPart}`);
+            lines.push(`        ${opt.description}`);
+        }
+    }
+    if (command.subcommands) {
+        lines.push('', 'Subcommands:');
+        const seen = new Set();
+        for (const [name, sub] of Object.entries(command.subcommands)) {
+            if (seen.has(sub))
+                continue; // skip aliases
+            seen.add(sub);
+            lines.push(`  ${name.padEnd(20)} ${sub.description}`);
+        }
+    }
+    lines.push('', getGlobalOptionsHelp());
+    return lines.join('\n');
+}
+//# sourceMappingURL=help.js.map

package/dist/cli/commands/help.js.map

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

package/dist/cli/commands/history.d.ts

@@ -0,0 +1,9 @@
+/**
+ * History Command - Show event history/timeline for elements
+ *
+ * Provides CLI commands for viewing element history:
+ * - history: Show event timeline for an element
+ */
+import type { Command } from '../types.js';
+export declare const historyCommand: Command;
+//# sourceMappingURL=history.d.ts.map

package/dist/cli/commands/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/history.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAA+C,MAAM,aAAa,CAAC;AA6JxF,eAAO,MAAM,cAAc,EAAE,OAkC5B,CAAC"}

package/dist/cli/commands/history.js

@@ -0,0 +1,160 @@
+/**
+ * History Command - Show event history/timeline for elements
+ *
+ * Provides CLI commands for viewing element history:
+ * - history: Show event timeline for an element
+ */
+import { success, failure, ExitCode } from '../types.js';
+import { getOutputMode, formatEventsTable, formatTimeline } from '../formatter.js';
+import { createAPI } from '../db.js';
+const historyOptions = [
+    {
+        name: 'limit',
+        short: 'l',
+        description: 'Maximum number of events to show (default: 50)',
+        hasValue: true,
+    },
+    {
+        name: 'type',
+        short: 't',
+        description: 'Filter by event type (created, updated, closed, reopened, deleted, dependency_added, dependency_removed)',
+        hasValue: true,
+    },
+    {
+        name: 'actor',
+        short: 'a',
+        description: 'Filter by actor',
+        hasValue: true,
+    },
+    {
+        name: 'after',
+        description: 'Show events after this timestamp (ISO 8601)',
+        hasValue: true,
+    },
+    {
+        name: 'before',
+        description: 'Show events before this timestamp (ISO 8601)',
+        hasValue: true,
+    },
+    {
+        name: 'format',
+        short: 'f',
+        description: 'Output format: timeline or table (default: timeline)',
+        hasValue: true,
+    },
+];
+async function historyHandler(args, options) {
+    const [id] = args;
+    if (!id) {
+        return failure('Usage: sf history <id>', ExitCode.INVALID_ARGUMENTS);
+    }
+    const { api, error } = createAPI(options);
+    if (error) {
+        return failure(error, ExitCode.GENERAL_ERROR);
+    }
+    try {
+        // Build event filter
+        const filter = {};
+        if (options.limit) {
+            const limit = parseInt(options.limit, 10);
+            if (isNaN(limit) || limit < 1) {
+                return failure('Limit must be a positive number', ExitCode.VALIDATION);
+            }
+            filter.limit = limit;
+        }
+        else {
+            filter.limit = 50; // Default limit
+        }
+        if (options.type) {
+            // Validate event type
+            const validTypes = [
+                'created', 'updated', 'closed', 'reopened', 'deleted',
+                'dependency_added', 'dependency_removed',
+                'tag_added', 'tag_removed',
+                'member_added', 'member_removed',
+            ];
+            if (!validTypes.includes(options.type)) {
+                return failure(`Invalid event type: ${options.type}. Must be one of: ${validTypes.join(', ')}`, ExitCode.VALIDATION);
+            }
+            filter.eventType = options.type;
+        }
+        if (options.actor) {
+            filter.actor = options.actor;
+        }
+        if (options.after) {
+            filter.after = options.after;
+        }
+        if (options.before) {
+            filter.before = options.before;
+        }
+        // Get events - api is guaranteed to be defined since we checked for error above
+        const events = await api.getEvents(id, filter);
+        // Format output based on mode
+        const mode = getOutputMode(options);
+        if (mode === 'json') {
+            return success(events);
+        }
+        if (mode === 'quiet') {
+            // Just return count in quiet mode
+            return success(events.length.toString());
+        }
+        // Determine format (timeline or table)
+        const format = options.format || 'timeline';
+        if (format !== 'timeline' && format !== 'table') {
+            return failure('Format must be "timeline" or "table"', ExitCode.VALIDATION);
+        }
+        // Human-readable output
+        if (events.length === 0) {
+            return success([], 'No events found');
+        }
+        let output;
+        if (format === 'table') {
+            output = formatEventsTable(events);
+        }
+        else {
+            output = formatTimeline(events);
+        }
+        const header = `History for ${id} (${events.length} events):\n\n`;
+        return success(events, header + output);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return failure(`Failed to get history: ${message}`, ExitCode.GENERAL_ERROR);
+    }
+}
+export const historyCommand = {
+    name: 'history',
+    description: 'Show event history for an element',
+    usage: 'sf history <id> [options]',
+    help: `Display the event history/timeline for an element.
+
+Shows all recorded events including creates, updates, status changes,
+dependency changes, and more.
+
+Arguments:
+  id    Element identifier (e.g., el-abc123)
+
+Options:
+  -n, --limit <n>       Maximum events to show (default: 50)
+  -t, --type <type>     Filter by event type
+  -a, --actor <actor>   Filter by actor
+      --after <time>    Show events after this time (ISO 8601)
+      --before <time>   Show events before this time (ISO 8601)
+  -f, --format <fmt>    Output format: timeline or table (default: timeline)
+
+Event types:
+  created, updated, closed, reopened, deleted,
+  dependency_added, dependency_removed
+
+Examples:
+  sf history el-abc123
+  sf history el-abc123 --limit 10
+  sf history el-abc123 --type updated
+  sf history el-abc123 --actor user:alice
+  sf history el-abc123 --format table
+  sf history el-abc123 --after 2024-01-01
+  sf history el-abc123 --json`,
+    options: historyOptions,
+    handler: historyHandler,
+};
+//# sourceMappingURL=history.js.map

package/dist/cli/commands/history.js.map

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