@lumenflow/cli 2.2.2 → 2.3.2

package/dist/mem-context.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+/* eslint-disable no-console -- CLI tool requires console output */
+/**
+ * Memory Context CLI (WU-1234, WU-1292)
+ *
+ * Generate deterministic, formatted context injection blocks for wu:spawn prompts.
+ * Outputs structured markdown with sections for project profile, summaries,
+ * WU context, and discoveries.
+ *
+ * Usage:
+ *   pnpm mem:context --wu WU-XXXX [options]
+ *
+ * Options:
+ *   --max-size <bytes>            Maximum context size in bytes (default: 4096)
+ *   --spawn-context-max-size <bytes>  Alias for --max-size (for config parity)
+ *   --lane <lane>                 Filter project memories by lane (WU-1292)
+ *   --max-recent-summaries <n>    Limit recent summaries included (WU-1292)
+ *   --max-project-nodes <n>       Limit project nodes included (WU-1292)
+ *   --format <json|human>         Output format (default: human)
+ *   --quiet                       Suppress header/footer output
+ *
+ * Includes audit logging to .lumenflow/telemetry/tools.ndjson.
+ *
+ * @see {@link packages/@lumenflow/memory/src/mem-context-core.ts} - Core logic
+ * @see {@link packages/@lumenflow/cli/__tests__/mem-context.test.ts} - Tests
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { generateContext } from '@lumenflow/memory/dist/mem-context-core.js';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { EXIT_CODES, LUMENFLOW_PATHS } from '@lumenflow/core/dist/wu-constants.js';
+/**
+ * Log prefix for mem:context output
+ */
+const LOG_PREFIX = '[mem:context]';
+/**
+ * Tool name for audit logging
+ */
+const TOOL_NAME = 'mem:context';
+/**
+ * Valid output formats
+ */
+const VALID_FORMATS = ['json', 'human'];
+/**
+ * CLI argument options specific to mem:context
+ */
+const CLI_OPTIONS = {
+    maxSize: {
+        name: 'maxSize',
+        flags: '-m, --max-size <bytes>',
+        description: 'Maximum context size in bytes (default: 4096)',
+    },
+    spawnContextMaxSize: {
+        name: 'spawnContextMaxSize',
+        flags: '--spawn-context-max-size <bytes>',
+        description: 'Alias for --max-size (for config parity with spawn_context_max_size)',
+    },
+    lane: {
+        name: 'lane',
+        flags: '-l, --lane <lane>',
+        description: 'Filter project memories by lane (e.g., "Framework: CLI")',
+    },
+    maxRecentSummaries: {
+        name: 'maxRecentSummaries',
+        flags: '--max-recent-summaries <count>',
+        description: 'Maximum number of recent summaries to include (default: 5)',
+    },
+    maxProjectNodes: {
+        name: 'maxProjectNodes',
+        flags: '--max-project-nodes <count>',
+        description: 'Maximum number of project nodes to include (default: 10)',
+    },
+    format: {
+        name: 'format',
+        flags: '-f, --format <format>',
+        description: 'Output format: json or human (default: human)',
+    },
+    baseDir: {
+        name: 'baseDir',
+        flags: '-d, --base-dir <path>',
+        description: 'Base directory (defaults to current directory)',
+    },
+    quiet: {
+        name: 'quiet',
+        flags: '-q, --quiet',
+        description: 'Suppress header/footer output, only show context block',
+    },
+};
+/**
+ * Write audit log entry for tool execution
+ *
+ * @param baseDir - Base directory
+ * @param entry - Audit log entry
+ */
+async function writeAuditLog(baseDir, entry) {
+    try {
+        const logPath = path.join(baseDir, LUMENFLOW_PATHS.AUDIT_LOG);
+        const logDir = path.dirname(logPath);
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool creates known directory
+        await fs.mkdir(logDir, { recursive: true });
+        const line = `${JSON.stringify(entry)}\n`;
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool writes audit log
+        await fs.appendFile(logPath, line, 'utf-8');
+    }
+    catch {
+        // Audit logging is non-fatal - silently ignore errors
+    }
+}
+/**
+ * Validate and parse a positive integer argument
+ *
+ * @param value - Raw argument value
+ * @param optionName - Name of the option for error messages
+ * @returns Parsed integer value
+ * @throws If value is invalid
+ */
+function parsePositiveInt(value, optionName) {
+    if (!value) {
+        return undefined;
+    }
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed) || parsed <= 0) {
+        throw new Error(`Invalid ${optionName} value: "${value}". Must be a positive integer.`);
+    }
+    return parsed;
+}
+/**
+ * WU-1292: Validate lane argument
+ *
+ * @param lane - Lane argument
+ * @returns Validated lane
+ * @throws If lane is empty string
+ */
+function validateLane(lane) {
+    if (lane === undefined) {
+        return undefined;
+    }
+    if (lane === '') {
+        throw new Error('Invalid --lane value: lane cannot be empty.');
+    }
+    return lane;
+}
+/**
+ * Validate format argument
+ *
+ * @param format - Format argument
+ * @returns Validated format
+ * @throws If format is invalid
+ */
+function validateFormat(format) {
+    if (!format) {
+        return 'human';
+    }
+    if (!VALID_FORMATS.includes(format)) {
+        throw new Error(`Invalid --format value: "${format}". Valid formats: ${VALID_FORMATS.join(', ')}`);
+    }
+    return format;
+}
+/**
+ * Print output in human-readable format
+ *
+ * @param result - Generate context result
+ * @param wuId - WU ID
+ * @param quiet - Whether to suppress headers
+ */
+function printHumanFormat(result, wuId, quiet) {
+    if (!quiet) {
+        console.log(`${LOG_PREFIX} Context for ${wuId}:`);
+        console.log('');
+    }
+    if (result.contextBlock === '') {
+        if (!quiet) {
+            console.log('  (no memories found - empty context block)');
+            console.log('');
+        }
+        return;
+    }
+    console.log(result.contextBlock);
+    if (!quiet) {
+        console.log('');
+        console.log(`${LOG_PREFIX} ${result.stats.totalNodes} node(s) included${result.stats.truncated ? ' (truncated)' : ''}`);
+    }
+}
+/**
+ * Print output in JSON format
+ *
+ * @param result - Generate context result
+ * @param wuId - WU ID
+ */
+function printJsonFormat(result, wuId) {
+    const output = {
+        wuId,
+        contextBlock: result.contextBlock,
+        stats: result.stats,
+    };
+    console.log(JSON.stringify(output, null, 2));
+}
+/**
+ * Main CLI entry point
+ */
+async function main() {
+    const args = createWUParser({
+        name: 'mem-context',
+        description: 'Generate context injection block for wu:spawn prompts',
+        options: [
+            WU_OPTIONS.wu,
+            CLI_OPTIONS.maxSize,
+            CLI_OPTIONS.spawnContextMaxSize,
+            CLI_OPTIONS.lane,
+            CLI_OPTIONS.maxRecentSummaries,
+            CLI_OPTIONS.maxProjectNodes,
+            CLI_OPTIONS.format,
+            CLI_OPTIONS.baseDir,
+            CLI_OPTIONS.quiet,
+        ],
+        required: ['wu'],
+    });
+    const baseDir = args.baseDir || process.cwd();
+    const startedAt = new Date().toISOString();
+    const startTime = Date.now();
+    let maxSize;
+    let lane;
+    let maxRecentSummaries;
+    let maxProjectNodes;
+    let format;
+    // Validate arguments
+    try {
+        // WU-1292: --spawn-context-max-size is an alias for --max-size (for config parity)
+        // If both are provided, --spawn-context-max-size takes precedence
+        const maxSizeArg = args.spawnContextMaxSize || args.maxSize;
+        maxSize = parsePositiveInt(maxSizeArg, '--max-size');
+        lane = validateLane(args.lane);
+        maxRecentSummaries = parsePositiveInt(args.maxRecentSummaries, '--max-recent-summaries');
+        maxProjectNodes = parsePositiveInt(args.maxProjectNodes, '--max-project-nodes');
+        format = validateFormat(args.format);
+    }
+    catch (err) {
+        const error = err;
+        console.error(`${LOG_PREFIX} Error: ${error.message}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Core returns any type due to loose tsconfig
+    let result;
+    let error = null;
+    try {
+        result = await generateContext(baseDir, {
+            wuId: args.wu,
+            maxSize,
+            lane,
+            maxRecentSummaries,
+            maxProjectNodes,
+        });
+    }
+    catch (err) {
+        const e = err;
+        error = e.message;
+        result = {
+            success: false,
+            contextBlock: '',
+            stats: { totalNodes: 0, byType: {}, truncated: false, size: 0 },
+        };
+    }
+    // Type assertion for type safety
+    const typedResult = result;
+    const durationMs = Date.now() - startTime;
+    // Write audit log entry
+    await writeAuditLog(baseDir, {
+        tool: TOOL_NAME,
+        status: error ? 'failed' : 'success',
+        startedAt,
+        completedAt: new Date().toISOString(),
+        durationMs,
+        input: {
+            baseDir,
+            wuId: args.wu,
+            maxSize,
+            lane,
+            maxRecentSummaries,
+            maxProjectNodes,
+            format,
+            quiet: args.quiet,
+        },
+        output: typedResult.success
+            ? {
+                contextSize: typedResult.contextBlock.length,
+                stats: typedResult.stats,
+            }
+            : null,
+        error: error ? { message: error } : null,
+    });
+    if (error) {
+        console.error(`${LOG_PREFIX} Error: ${error}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    // Print output based on format
+    if (format === 'json') {
+        printJsonFormat(typedResult, args.wu);
+    }
+    else {
+        printHumanFormat(typedResult, args.wu, !!args.quiet);
+    }
+}
+main().catch((e) => {
+    console.error(`${LOG_PREFIX} ${e.message}`);
+    process.exit(EXIT_CODES.ERROR);
+});

package/dist/mem-create.js

@@ -11,8 +11,8 @@
  * Usage:
  *   pnpm mem:create 'title' [--type <type>] [--discovered-from <id>] [--wu <id>] [--quiet]
  *
- * @see {@link tools/lib/mem-create-core.mjs} - Core logic
- * @see {@link tools/__tests__/mem-create.test.mjs} - Tests
+ * @see {@link packages/@lumenflow/cli/src/lib/mem-create-core.ts} - Core logic
+ * @see {@link packages/@lumenflow/cli/src/__tests__/mem-create.test.ts} - Tests
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';

package/dist/mem-delete.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+/* eslint-disable no-console -- CLI command uses console for status output */
+/**
+ * Memory Delete CLI (WU-1284)
+ *
+ * Delete or archive memory nodes using soft-delete pattern.
+ * Respects append-only pattern by marking nodes with metadata.status=deleted.
+ *
+ * Features:
+ * - Delete by node ID(s)
+ * - Bulk delete via --tag filter
+ * - Bulk delete via --older-than filter
+ * - Dry-run preview mode
+ *
+ * Usage:
+ *   pnpm mem:delete <node-id>                 # Delete single node
+ *   pnpm mem:delete <id1> <id2>               # Delete multiple nodes
+ *   pnpm mem:delete --tag obsolete            # Delete by tag
+ *   pnpm mem:delete --older-than 30d          # Delete old nodes
+ *   pnpm mem:delete --tag old --older-than 7d # Combined filters
+ *   pnpm mem:delete <id> --dry-run            # Preview only
+ *
+ * @see {@link packages/@lumenflow/memory/src/mem-delete-core.ts} - Core logic
+ * @see {@link packages/@lumenflow/memory/__tests__/mem-delete.test.ts} - Tests
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { deleteMemoryNodes } from '@lumenflow/memory/dist/mem-delete-core.js';
+import { createWUParser } from '@lumenflow/core/dist/arg-parser.js';
+import { EXIT_CODES, LUMENFLOW_PATHS } from '@lumenflow/core/dist/wu-constants.js';
+/**
+ * Log prefix for mem:delete output
+ */
+const LOG_PREFIX = '[mem:delete]';
+/**
+ * Tool name for audit logging
+ */
+const TOOL_NAME = 'mem:delete';
+/**
+ * CLI argument options specific to mem:delete
+ */
+const CLI_OPTIONS = {
+    dryRun: {
+        name: 'dryRun',
+        flags: '--dry-run',
+        description: 'Preview deletion without making changes',
+    },
+    tag: {
+        name: 'tag',
+        flags: '--tag <tag>',
+        description: 'Delete all nodes matching this tag',
+    },
+    olderThan: {
+        name: 'olderThan',
+        flags: '--older-than <duration>',
+        description: 'Delete nodes older than duration (e.g., 30d, 7d, 24h, 2w)',
+    },
+    json: {
+        name: 'json',
+        flags: '--json',
+        description: 'Output as JSON',
+    },
+    quiet: {
+        name: 'quiet',
+        flags: '-q, --quiet',
+        description: 'Suppress output except errors',
+    },
+    baseDir: {
+        name: 'baseDir',
+        flags: '-b, --base-dir <path>',
+        description: 'Base directory (defaults to current directory)',
+    },
+};
+/**
+ * Write audit log entry for tool execution
+ *
+ * @param baseDir - Base directory
+ * @param entry - Audit log entry
+ */
+async function writeAuditLog(baseDir, entry) {
+    try {
+        const logPath = path.join(baseDir, LUMENFLOW_PATHS.AUDIT_LOG);
+        const logDir = path.dirname(logPath);
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool creates known directory
+        await fs.mkdir(logDir, { recursive: true });
+        const line = `${JSON.stringify(entry)}\n`;
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool writes audit log
+        await fs.appendFile(logPath, line, 'utf-8');
+    }
+    catch {
+        // Audit logging is non-fatal - silently ignore errors
+    }
+}
+/**
+ * Parse CLI arguments and extract node IDs from positional args
+ *
+ * @returns Parsed args and node IDs
+ */
+function parseArguments() {
+    const args = createWUParser({
+        name: 'mem-delete',
+        description: 'Delete memory nodes (soft delete via metadata.status=deleted)',
+        options: [
+            CLI_OPTIONS.dryRun,
+            CLI_OPTIONS.tag,
+            CLI_OPTIONS.olderThan,
+            CLI_OPTIONS.json,
+            CLI_OPTIONS.quiet,
+            CLI_OPTIONS.baseDir,
+        ],
+        required: [],
+        allowPositionalId: true,
+    });
+    // Extract positional arguments as node IDs
+    const nodeIds = [];
+    const argv = process.argv.slice(2).filter((arg) => arg !== '--');
+    for (const arg of argv) {
+        // Skip flags and their values
+        if (arg.startsWith('-')) {
+            continue;
+        }
+        // Check if this arg is a value for a flag (by checking previous arg)
+        const prevArg = argv[argv.indexOf(arg) - 1];
+        if (prevArg &&
+            prevArg.startsWith('-') &&
+            !prevArg.startsWith('--dry-run') &&
+            !prevArg.startsWith('--json') &&
+            !prevArg.startsWith('-q')) {
+            continue;
+        }
+        // Node IDs start with 'mem-'
+        if (arg.startsWith('mem-')) {
+            nodeIds.push(arg);
+        }
+    }
+    return { args, nodeIds };
+}
+/**
+ * Display limit for ID lists
+ */
+const DISPLAY_LIMITS = {
+    DELETED_IDS: 10,
+    SKIPPED_IDS: 5,
+};
+/**
+ * Print a list of IDs with limit
+ */
+function printIdList(ids, limit, label) {
+    console.log('');
+    console.log(label);
+    const displayIds = ids.slice(0, limit);
+    for (const id of displayIds) {
+        console.log(`  - ${id}`);
+    }
+    if (ids.length > limit) {
+        console.log(`  ... and ${ids.length - limit} more`);
+    }
+}
+/**
+ * Print errors list
+ */
+function printErrors(errors) {
+    if (errors.length === 0)
+        return;
+    console.log('');
+    console.log('Errors:');
+    for (const error of errors) {
+        console.log(`  - ${error}`);
+    }
+}
+/**
+ * Print deletion result to console
+ *
+ * @param result - Deletion result
+ * @param quiet - Suppress verbose output
+ */
+function printResult(result, quiet) {
+    const statusMsg = result.dryRun
+        ? `${LOG_PREFIX} Dry-run: Would delete ${result.deletedCount} node(s)`
+        : `${LOG_PREFIX} Deletion complete`;
+    console.log(statusMsg);
+    if (quiet) {
+        console.log(`${result.deletedCount} deleted, ${result.skippedIds.length} skipped`);
+        return;
+    }
+    console.log('');
+    console.log('Summary:');
+    console.log(`  Deleted:  ${result.deletedCount} node(s)`);
+    console.log(`  Skipped:  ${result.skippedIds.length} node(s)`);
+    if (result.deletedIds.length > 0) {
+        const label = result.dryRun ? 'Would Delete:' : 'Deleted:';
+        printIdList(result.deletedIds, DISPLAY_LIMITS.DELETED_IDS, label);
+    }
+    if (result.skippedIds.length > 0) {
+        printIdList(result.skippedIds, DISPLAY_LIMITS.SKIPPED_IDS, 'Skipped (already deleted):');
+    }
+    printErrors(result.errors);
+    if (result.dryRun) {
+        console.log('');
+        console.log('To execute, run without --dry-run');
+    }
+}
+/**
+ * Build delete options from CLI arguments
+ */
+function buildDeleteOptions(args, nodeIds) {
+    const options = {
+        dryRun: args.dryRun,
+    };
+    if (nodeIds.length > 0) {
+        options.nodeIds = nodeIds;
+    }
+    if (args.tag) {
+        options.tag = args.tag;
+    }
+    if (args.olderThan) {
+        options.olderThan = args.olderThan;
+    }
+    return options;
+}
+/**
+ * Print usage help and exit with error
+ */
+function printUsageAndExit() {
+    console.error(`${LOG_PREFIX} Error: At least one filter is required`);
+    console.error('');
+    console.error('Usage:');
+    console.error('  pnpm mem:delete <node-id>        Delete single node by ID');
+    console.error('  pnpm mem:delete <id1> <id2>      Delete multiple nodes');
+    console.error('  pnpm mem:delete --tag <tag>      Delete all nodes with tag');
+    console.error('  pnpm mem:delete --older-than 30d Delete nodes older than 30 days');
+    console.error('  pnpm mem:delete --dry-run        Preview deletion');
+    process.exit(EXIT_CODES.ERROR);
+}
+/**
+ * Main CLI entry point
+ */
+async function main() {
+    const { args, nodeIds } = parseArguments();
+    const baseDir = args.baseDir || process.cwd();
+    const startedAt = new Date().toISOString();
+    const startTime = Date.now();
+    const deleteOptions = buildDeleteOptions(args, nodeIds);
+    // Check if any filter is provided
+    if (!deleteOptions.nodeIds && !deleteOptions.tag && !deleteOptions.olderThan) {
+        printUsageAndExit();
+    }
+    let result = null;
+    let error = null;
+    try {
+        result = await deleteMemoryNodes(baseDir, deleteOptions);
+    }
+    catch (err) {
+        error = err instanceof Error ? err.message : String(err);
+    }
+    const durationMs = Date.now() - startTime;
+    await writeAuditLog(baseDir, {
+        tool: TOOL_NAME,
+        status: error ? 'failed' : 'success',
+        startedAt,
+        completedAt: new Date().toISOString(),
+        durationMs,
+        input: { baseDir, nodeIds, tag: args.tag, olderThan: args.olderThan, dryRun: args.dryRun },
+        output: result
+            ? {
+                success: result.success,
+                deletedCount: result.deletedCount,
+                deletedIds: result.deletedIds,
+                skippedCount: result.skippedIds.length,
+                dryRun: result.dryRun,
+            }
+            : null,
+        error: error ? { message: error } : null,
+    });
+    if (error) {
+        console.error(`${LOG_PREFIX} Error: ${error}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    if (!result) {
+        console.error(`${LOG_PREFIX} Error: No result from delete operation`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    if (args.json) {
+        console.log(JSON.stringify(result, null, 2));
+        process.exit(result.success ? EXIT_CODES.SUCCESS : EXIT_CODES.ERROR);
+    }
+    printResult(result, args.quiet);
+    process.exit(result.success ? EXIT_CODES.SUCCESS : EXIT_CODES.ERROR);
+}
+main().catch((e) => {
+    console.error(`${LOG_PREFIX} ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(EXIT_CODES.ERROR);
+});

package/dist/mem-inbox.js

@@ -14,8 +14,8 @@
  * Usage:
  *   pnpm mem:inbox [--lane <name>] [--wu <id>] [--since <time>] [--watch]
  *
- * @see {@link tools/lib/mem-signal-core.mjs} - Core logic
- * @see {@link tools/__tests__/mem-inbox.test.mjs} - Tests
+ * @see {@link packages/@lumenflow/cli/src/lib/mem-signal-core.ts} - Core logic
+ * @see {@link packages/@lumenflow/cli/src/__tests__/mem-inbox.test.ts} - Tests
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';