@lumenflow/cli 2.2.1 → 2.3.1

package/dist/mem-index.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+/* eslint-disable no-console -- CLI tool requires console output */
+/**
+ * Memory Index CLI (WU-1235)
+ *
+ * Scans project conventions and creates project-lifecycle summary nodes.
+ * Indexes README.md, LUMENFLOW.md, package.json, .lumenflow.config.yaml,
+ * and .lumenflow/constraints.md to provide agent context awareness.
+ *
+ * Includes audit logging to .lumenflow/telemetry/tools.ndjson.
+ *
+ * Usage:
+ *   pnpm mem:index [--dry-run] [--quiet] [--json] [--base-dir <path>]
+ *
+ * @see {@link packages/@lumenflow/memory/src/mem-index-core.ts} - Core logic
+ * @see {@link packages/@lumenflow/cli/__tests__/mem-index.test.ts} - Tests
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { indexProject } from '@lumenflow/memory/dist/mem-index-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:index output
+ */
+const LOG_PREFIX = '[mem:index]';
+/**
+ * Tool name for audit logging
+ */
+const TOOL_NAME = 'mem:index';
+/**
+ * CLI argument options specific to mem:index
+ */
+const CLI_OPTIONS = {
+    dryRun: {
+        name: 'dryRun',
+        flags: '-n, --dry-run',
+        description: 'Show what would be indexed without writing',
+    },
+    quiet: {
+        name: 'quiet',
+        flags: '-q, --quiet',
+        description: 'Suppress output except summary',
+    },
+    json: {
+        name: 'json',
+        flags: '--json',
+        description: 'Output result as JSON',
+    },
+    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);
+        await fs.mkdir(logDir, { recursive: true });
+        const line = `${JSON.stringify(entry)}\n`;
+        await fs.appendFile(logPath, line, 'utf-8');
+    }
+    catch {
+        // Audit logging is non-fatal - silently ignore errors
+    }
+}
+/**
+ * Parse CLI arguments
+ */
+function parseArguments() {
+    return createWUParser({
+        name: 'mem-index',
+        description: 'Index project conventions for agent context awareness',
+        options: [CLI_OPTIONS.dryRun, CLI_OPTIONS.quiet, CLI_OPTIONS.json, CLI_OPTIONS.baseDir],
+        required: [],
+        allowPositionalId: false,
+    });
+}
+/**
+ * Print human-readable result
+ *
+ * @param result - Index result
+ * @param dryRun - Whether this was a dry-run
+ * @param quiet - Whether to use quiet mode
+ */
+function printResult(result, dryRun, quiet) {
+    if (dryRun) {
+        console.log(`${LOG_PREFIX} Dry-run mode - no changes written`);
+        console.log('');
+    }
+    if (quiet) {
+        // Minimal output
+        const action = dryRun ? 'Would index' : 'Indexed';
+        console.log(`${LOG_PREFIX} ${action}: ${result.nodesCreated} created, ${result.nodesUpdated} updated, ${result.nodesSkipped} skipped`);
+        return;
+    }
+    console.log(`${LOG_PREFIX} Project indexing complete`);
+    console.log('');
+    if (result.sourcesScanned.length > 0) {
+        console.log('Sources scanned:');
+        for (const source of result.sourcesScanned) {
+            console.log(`  - ${source}`);
+        }
+        console.log('');
+    }
+    if (result.sourcesMissing.length > 0) {
+        console.log('Sources not found:');
+        for (const source of result.sourcesMissing) {
+            console.log(`  - ${source}`);
+        }
+        console.log('');
+    }
+    console.log('Summary:');
+    const createLabel = dryRun ? 'Would create' : 'Created';
+    const updateLabel = dryRun ? 'Would update' : 'Updated';
+    console.log(`  ${createLabel}: ${result.nodesCreated} nodes`);
+    console.log(`  ${updateLabel}: ${result.nodesUpdated} nodes`);
+    console.log(`  Skipped: ${result.nodesSkipped} nodes (unchanged)`);
+    console.log('');
+}
+/**
+ * Print JSON result
+ *
+ * @param result - Index result
+ */
+function printJsonResult(result) {
+    console.log(JSON.stringify(result, null, 2));
+}
+/**
+ * Main CLI entry point
+ */
+async function main() {
+    const args = parseArguments();
+    const baseDir = args.baseDir || process.cwd();
+    const dryRun = Boolean(args.dryRun);
+    const quiet = Boolean(args.quiet);
+    const json = Boolean(args.json);
+    // Validate base directory exists
+    try {
+        const stat = await fs.stat(baseDir);
+        if (!stat.isDirectory()) {
+            console.error(`${LOG_PREFIX} Error: ${baseDir} is not a directory`);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    }
+    catch {
+        console.error(`${LOG_PREFIX} Error: Directory not found: ${baseDir}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    const startedAt = new Date().toISOString();
+    const startTime = Date.now();
+    let result;
+    let error = null;
+    try {
+        result = await indexProject(baseDir, { dryRun });
+    }
+    catch (err) {
+        error = err instanceof Error ? err.message : String(err);
+        result = {
+            success: false,
+            nodesCreated: 0,
+            nodesUpdated: 0,
+            nodesSkipped: 0,
+            sourcesScanned: [],
+            sourcesMissing: [],
+            error,
+        };
+    }
+    const durationMs = Date.now() - startTime;
+    // Write audit log
+    await writeAuditLog(baseDir, {
+        tool: TOOL_NAME,
+        status: error ? 'failed' : 'success',
+        startedAt,
+        completedAt: new Date().toISOString(),
+        durationMs,
+        input: {
+            baseDir,
+            dryRun,
+        },
+        output: {
+            success: result.success,
+            nodesCreated: result.nodesCreated,
+            nodesUpdated: result.nodesUpdated,
+            nodesSkipped: result.nodesSkipped,
+            sourcesScanned: result.sourcesScanned.length,
+        },
+        error: error ? { message: error } : null,
+    });
+    if (error) {
+        console.error(`${LOG_PREFIX} Error: ${error}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    if (json) {
+        printJsonResult(result);
+    }
+    else {
+        printResult(result, dryRun, quiet);
+    }
+}
+main().catch((e) => {
+    console.error(`${LOG_PREFIX} ${e.message}`);
+    process.exit(EXIT_CODES.ERROR);
+});

package/dist/mem-init.js

@@ -10,7 +10,7 @@
  * Usage:
  *   pnpm mem:init [--base-dir <path>] [--quiet]
  *
- * @see {@link tools/lib/mem-init-core.mjs} - Core logic
+ * @see {@link packages/@lumenflow/cli/src/lib/mem-init-core.ts} - Core logic
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';

package/dist/mem-profile.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/* eslint-disable no-console -- CLI tool requires console output */
+/**
+ * Memory Profile CLI (WU-1237)
+ *
+ * Renders top N project-level memories for context injection.
+ *
+ * Features:
+ * - Outputs project-level knowledge profile
+ * - Configurable limit (default N=20)
+ * - Tag-based filtering
+ * - Output format compatible with mem:context
+ *
+ * Usage:
+ *   pnpm mem:profile                           # Top 20 project memories
+ *   pnpm mem:profile --limit 10                # Top 10 project memories
+ *   pnpm mem:profile --tag decision            # Filter by tag
+ *   pnpm mem:profile --json                    # Output as JSON
+ *
+ * @see {@link packages/@lumenflow/memory/src/mem-profile-core.ts} - Core logic
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { generateProfile, DEFAULT_PROFILE_LIMIT } from '@lumenflow/memory/dist/mem-profile-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:profile output
+ */
+const LOG_PREFIX = '[mem:profile]';
+/**
+ * Tool name for audit logging
+ */
+const TOOL_NAME = 'mem:profile';
+/**
+ * CLI argument options specific to mem:profile
+ */
+const CLI_OPTIONS = {
+    limit: {
+        name: 'limit',
+        flags: '-l, --limit <n>',
+        description: `Maximum nodes to include (default: ${DEFAULT_PROFILE_LIMIT})`,
+    },
+    tag: {
+        name: 'tag',
+        flags: '-t, --tag <tag>',
+        description: 'Filter by tag category (e.g., decision, pattern)',
+    },
+    json: {
+        name: 'json',
+        flags: '--json',
+        description: 'Output as JSON',
+    },
+    raw: {
+        name: 'raw',
+        flags: '--raw',
+        description: 'Output raw profile block (for piping to mem:context)',
+    },
+    quiet: {
+        name: 'quiet',
+        flags: '-q, --quiet',
+        description: 'Suppress output except the profile block',
+    },
+};
+/**
+ * Write audit log entry for tool execution
+ */
+async function writeAuditLog(baseDir, entry) {
+    try {
+        const logPath = path.join(baseDir, LUMENFLOW_PATHS.AUDIT_LOG);
+        const logDir = path.dirname(logPath);
+        await fs.mkdir(logDir, { recursive: true });
+        const line = `${JSON.stringify(entry)}\n`;
+        await fs.appendFile(logPath, line, 'utf-8');
+    }
+    catch {
+        // Audit logging is non-fatal - silently ignore errors
+    }
+}
+/**
+ * Parse CLI arguments
+ */
+function parseArguments() {
+    return createWUParser({
+        name: 'mem-profile',
+        description: 'Generate project knowledge profile for context injection',
+        options: [
+            CLI_OPTIONS.limit,
+            CLI_OPTIONS.tag,
+            CLI_OPTIONS.json,
+            CLI_OPTIONS.raw,
+            CLI_OPTIONS.quiet,
+        ],
+        required: [],
+        allowPositionalId: false,
+    });
+}
+/**
+ * Output profile in JSON format
+ */
+function outputJson(result) {
+    console.log(JSON.stringify(result, null, 2));
+}
+/**
+ * Output profile in raw format (for piping)
+ */
+function outputRaw(result) {
+    if (result.profileBlock) {
+        process.stdout.write(result.profileBlock);
+    }
+}
+/**
+ * Output profile in human-readable format
+ */
+function outputHumanReadable(result, args) {
+    if (result.nodes.length === 0) {
+        if (!args.quiet) {
+            console.log(`${LOG_PREFIX} No project-level memories found.`);
+            if (args.tag) {
+                console.log(`  Filter: --tag ${args.tag}`);
+            }
+            console.log('');
+            console.log('To promote session learnings to project level, use:');
+            console.log('  pnpm mem:promote --node mem-xxxx --tag pattern');
+        }
+        return;
+    }
+    if (!args.quiet) {
+        console.log(`${LOG_PREFIX} Project Profile (${result.stats.includedNodes}/${result.stats.totalProjectNodes} nodes)`);
+        if (args.tag) {
+            console.log(`  Filter: --tag ${args.tag}`);
+        }
+        console.log('');
+    }
+    // Output the profile block
+    console.log(result.profileBlock);
+    if (!args.quiet) {
+        // Stats summary
+        console.log('Tag breakdown:');
+        for (const [tag, count] of Object.entries(result.stats.byTag)) {
+            console.log(`  ${tag}: ${count}`);
+        }
+    }
+}
+/**
+ * Main CLI entry point
+ */
+async function main() {
+    const args = parseArguments();
+    const baseDir = process.cwd();
+    const startedAt = new Date().toISOString();
+    const startTime = Date.now();
+    let result = null;
+    let error = null;
+    try {
+        const limit = args.limit ? parseInt(args.limit, 10) : DEFAULT_PROFILE_LIMIT;
+        if (isNaN(limit) || limit < 1) {
+            console.error(`${LOG_PREFIX} Error: --limit must be a positive integer`);
+            process.exit(EXIT_CODES.ERROR);
+        }
+        result = await generateProfile(baseDir, {
+            limit,
+            tag: args.tag,
+        });
+        // Output format based on flags
+        if (args.json) {
+            outputJson(result);
+        }
+        else if (args.raw) {
+            outputRaw(result);
+        }
+        else {
+            outputHumanReadable(result, args);
+        }
+    }
+    catch (err) {
+        error = err.message;
+        console.error(`${LOG_PREFIX} Error: ${error}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    const durationMs = Date.now() - startTime;
+    await writeAuditLog(baseDir, {
+        tool: TOOL_NAME,
+        action: 'generate',
+        status: error ? 'failed' : 'success',
+        startedAt,
+        completedAt: new Date().toISOString(),
+        durationMs,
+        input: {
+            baseDir,
+            limit: args.limit,
+            tag: args.tag,
+        },
+        output: result
+            ? {
+                includedNodes: result.stats.includedNodes,
+                totalProjectNodes: result.stats.totalProjectNodes,
+                byTag: result.stats.byTag,
+            }
+            : null,
+        error: error ? { message: error } : null,
+    });
+}
+main().catch((e) => {
+    console.error(`${LOG_PREFIX} ${e.message}`);
+    process.exit(EXIT_CODES.ERROR);
+});

package/dist/mem-promote.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+/* eslint-disable no-console -- CLI tool requires console output */
+/**
+ * Memory Promote CLI (WU-1237)
+ *
+ * Promotes session/WU learnings into project-level knowledge nodes.
+ *
+ * Features:
+ * - Promote individual nodes to project lifecycle
+ * - Promote all summaries from a WU
+ * - Enforced taxonomy tags
+ * - Creates discovered_from relationships for provenance
+ * - Dry-run mode for preview
+ *
+ * Usage:
+ *   pnpm mem:promote --node mem-xxxx --tag pattern           # Promote single node
+ *   pnpm mem:promote --wu WU-1234 --tag decision             # Promote all WU summaries
+ *   pnpm mem:promote --node mem-xxxx --tag pattern --dry-run # Preview
+ *
+ * @see {@link packages/@lumenflow/memory/src/mem-promote-core.ts} - Core logic
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { promoteNode, promoteFromWu, ALLOWED_PROMOTION_TAGS, } from '@lumenflow/memory/dist/mem-promote-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:promote output
+ */
+const LOG_PREFIX = '[mem:promote]';
+/**
+ * Tool name for audit logging
+ */
+const TOOL_NAME = 'mem:promote';
+/**
+ * CLI argument options specific to mem:promote
+ */
+const CLI_OPTIONS = {
+    node: {
+        name: 'node',
+        flags: '-n, --node <nodeId>',
+        description: 'Memory node ID to promote (mem-xxxx format)',
+    },
+    wu: {
+        name: 'wu',
+        flags: '-w, --wu <wuId>',
+        description: 'WU ID to promote all summaries from (WU-XXXX format)',
+    },
+    tag: {
+        name: 'tag',
+        flags: '-t, --tag <tag>',
+        description: `Tag from taxonomy: ${ALLOWED_PROMOTION_TAGS.join(', ')}`,
+    },
+    dryRun: {
+        name: 'dryRun',
+        flags: '--dry-run',
+        description: 'Preview what would be promoted without writing',
+    },
+    json: {
+        name: 'json',
+        flags: '--json',
+        description: 'Output as JSON',
+    },
+    quiet: {
+        name: 'quiet',
+        flags: '-q, --quiet',
+        description: 'Suppress output except errors',
+    },
+};
+/**
+ * Write audit log entry for tool execution
+ */
+async function writeAuditLog(baseDir, entry) {
+    try {
+        const logPath = path.join(baseDir, LUMENFLOW_PATHS.AUDIT_LOG);
+        const logDir = path.dirname(logPath);
+        await fs.mkdir(logDir, { recursive: true });
+        const line = `${JSON.stringify(entry)}\n`;
+        await fs.appendFile(logPath, line, 'utf-8');
+    }
+    catch {
+        // Audit logging is non-fatal - silently ignore errors
+    }
+}
+/**
+ * Handle promoting a single node
+ */
+async function handlePromoteNode(baseDir, args) {
+    if (!args.tag) {
+        console.error(`${LOG_PREFIX} Error: --tag is required`);
+        console.error('');
+        console.error(`Usage: pnpm mem:promote --node mem-xxxx --tag <tag>`);
+        console.error(`Tags: ${ALLOWED_PROMOTION_TAGS.join(', ')}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    // args.node is guaranteed to be defined when this function is called
+    const nodeId = args.node;
+    const result = await promoteNode(baseDir, {
+        nodeId,
+        tag: args.tag,
+        dryRun: args.dryRun,
+    });
+    if (args.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return result;
+    }
+    if (args.dryRun) {
+        console.log(`${LOG_PREFIX} Dry-run: Would promote to:`);
+        console.log('');
+        console.log(`  ID:        ${result.promotedNode.id}`);
+        console.log(`  Lifecycle: ${result.promotedNode.lifecycle}`);
+        console.log(`  Tags:      ${result.promotedNode.tags?.join(', ')}`);
+        console.log(`  Content:   ${result.promotedNode.content.substring(0, 80)}...`);
+        console.log('');
+        console.log('To execute, run without --dry-run');
+        return result;
+    }
+    if (!args.quiet) {
+        console.log(`${LOG_PREFIX} ✅ Promoted to project level`);
+        console.log('');
+        console.log(`  Source:    ${args.node}`);
+        console.log(`  New ID:    ${result.promotedNode.id}`);
+        console.log(`  Lifecycle: project`);
+        console.log(`  Tag:       ${args.tag}`);
+    }
+    return result;
+}
+/**
+ * Handle promoting all summaries from a WU
+ */
+async function handlePromoteFromWu(baseDir, args) {
+    if (!args.tag) {
+        console.error(`${LOG_PREFIX} Error: --tag is required`);
+        console.error('');
+        console.error(`Usage: pnpm mem:promote --wu WU-XXXX --tag <tag>`);
+        console.error(`Tags: ${ALLOWED_PROMOTION_TAGS.join(', ')}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    // args.wu is guaranteed to be defined when this function is called
+    const wuId = args.wu;
+    const result = await promoteFromWu(baseDir, {
+        wuId,
+        tag: args.tag,
+        dryRun: args.dryRun,
+    });
+    if (args.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return result;
+    }
+    if (result.promotedNodes.length === 0) {
+        if (!args.quiet) {
+            console.log(`${LOG_PREFIX} No summaries found for ${args.wu}`);
+        }
+        return result;
+    }
+    if (args.dryRun) {
+        console.log(`${LOG_PREFIX} Dry-run: Would promote ${result.promotedNodes.length} summary(ies):`);
+        console.log('');
+        for (const node of result.promotedNodes) {
+            console.log(`  - ${node.id}: ${node.content.substring(0, 60)}...`);
+        }
+        console.log('');
+        console.log('To execute, run without --dry-run');
+        return result;
+    }
+    if (!args.quiet) {
+        console.log(`${LOG_PREFIX} ✅ Promoted ${result.promotedNodes.length} summary(ies) from ${args.wu}`);
+        console.log('');
+        for (const node of result.promotedNodes) {
+            console.log(`  - ${node.id}: ${node.content.substring(0, 60)}...`);
+        }
+    }
+    return result;
+}
+/**
+ * Parse CLI arguments
+ */
+function parseArguments() {
+    return createWUParser({
+        name: 'mem-promote',
+        description: 'Promote session/WU learnings to project-level knowledge',
+        options: [
+            CLI_OPTIONS.node,
+            CLI_OPTIONS.wu,
+            CLI_OPTIONS.tag,
+            CLI_OPTIONS.dryRun,
+            CLI_OPTIONS.json,
+            CLI_OPTIONS.quiet,
+        ],
+        required: [],
+        allowPositionalId: false,
+    });
+}
+/**
+ * Main CLI entry point
+ */
+async function main() {
+    const args = parseArguments();
+    const baseDir = process.cwd();
+    const startedAt = new Date().toISOString();
+    const startTime = Date.now();
+    // Validate: one of --node or --wu must be provided
+    if (!args.node && !args.wu) {
+        console.error(`${LOG_PREFIX} Error: Either --node or --wu is required`);
+        console.error('');
+        console.error('Usage:');
+        console.error('  pnpm mem:promote --node mem-xxxx --tag pattern');
+        console.error('  pnpm mem:promote --wu WU-1234 --tag decision');
+        process.exit(EXIT_CODES.ERROR);
+    }
+    if (args.node && args.wu) {
+        console.error(`${LOG_PREFIX} Error: Cannot use both --node and --wu`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    let result = null;
+    let error = null;
+    const action = args.node ? 'promote-node' : 'promote-wu';
+    try {
+        if (args.node) {
+            result = await handlePromoteNode(baseDir, args);
+        }
+        else {
+            result = await handlePromoteFromWu(baseDir, args);
+        }
+    }
+    catch (err) {
+        error = err.message;
+        console.error(`${LOG_PREFIX} Error: ${error}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    const durationMs = Date.now() - startTime;
+    await writeAuditLog(baseDir, {
+        tool: TOOL_NAME,
+        action,
+        status: error ? 'failed' : 'success',
+        startedAt,
+        completedAt: new Date().toISOString(),
+        durationMs,
+        input: {
+            baseDir,
+            action,
+            node: args.node,
+            wu: args.wu,
+            tag: args.tag,
+            dryRun: args.dryRun,
+        },
+        output: result,
+        error: error ? { message: error } : null,
+    });
+}
+main().catch((e) => {
+    console.error(`${LOG_PREFIX} ${e.message}`);
+    process.exit(EXIT_CODES.ERROR);
+});

package/dist/mem-ready.js

@@ -10,8 +10,8 @@
  *
  * Includes audit logging to .lumenflow/telemetry/tools.ndjson.
  *
- * @see {@link tools/lib/mem-ready-core.mjs} - Core logic
- * @see {@link tools/__tests__/mem-ready.test.mjs} - Tests
+ * @see {@link packages/@lumenflow/cli/src/lib/mem-ready-core.ts} - Core logic
+ * @see {@link packages/@lumenflow/cli/src/__tests__/mem-ready.test.ts} - Tests
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';

package/dist/mem-signal.js

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