ai-cli-log 1.0.5 → 1.0.9

package/README.md

@@ -10,27 +10,33 @@ npm install -g ai-cli-log
 
 ## Usage
 
-Wrap any command with `ai-cli-log` to start a logging session.
+Wrap any command with `ai-cli-log` to start a logging session. The core structure is:
 
 ```bash
-ai-cli-log <command> [args...]
+ai-cli-log [global-options] run <command-to-log> [args...]
 ```
 
 **Examples:**
 
 - **Basic Logging:** Record a session with Google's Gemini CLI.
   ```bash
-  ai-cli-log gemini
+  ai-cli-log run gemini
   ```
   *Logs are saved to the `.ai-cli-log/` directory.*
 
-- **AI-Powered Filenames:** Use an AI summary for the log's filename.
+- **AI-Powered Filenames:** Use an AI summary for the log's filename. The options must come **before** the `run` command.
   ```bash
-  ai-cli-log -s <command> [args...]
+  # Enable summary with the default summarizer
+  ai-cli-log -s run gemini
   # or
-  ai-cli-log --with-summary <command> [args...]
+  ai-cli-log --with-summary run gemini
+
+  # Enable summary and specify a summarizer
+  ai-cli-log --by gemini-pro run gemini
+  # or
+  ai-cli-log --summarizer gemini-pro run gemini
   ```
-  This will use your default summarizer to generate a descriptive filename like `gemini-20250713-153000-fix-database-connection-error.md`. You can also specify a summarizer: `ai-cli-log -s=my-ollama-summarizer ...`.
+  This will use your default (or specified) summarizer to generate a descriptive filename like `gemini-20250713-153000-fix-database-connection-error.txt`.
 
 ## Configuration
 
@@ -42,19 +48,19 @@ ai-cli-log <command> [args...]
 
 You can create these files manually or by using the interactive setup command.
 
-### Interactive Setup (`--init`)
+### Interactive Setup (`init`)
 
-The `--init` command helps you create a configuration file.
+The `init` command helps you create a configuration file. It will scan for available AI tools, guide you through creating summarizer profiles, and set a default.
 
 *   **To create a global configuration:**
     ```bash
-    ai-cli-log --init
+    ai-cli-log init
     ```
     This saves the configuration to `~/.config/ai-cli-log/config.json`.
 
 *   **To create a local (project-specific) configuration:**
     ```bash
-    ai-cli-log --init --local
+    ai-cli-log init --local
     ```
     This saves the configuration to `.ai-cli-log/config.json` in the current directory.
 
@@ -83,23 +89,14 @@ Here is an example of a manual `config.json`:
       {
         "name": "sgpt",
         "tool": "custom",
-        "command": ["sgpt", "--chat", "session-summary", "\"{{prompt}}\""]
-      },
-
-*   **To create a global configuration file (at `~/.config/ai-cli-log/config.json`):**
-    ```bash
-    ai-cli-log --init
-    ```
-
-*   **To create a local, project-specific configuration file (at `.ai-cli-log/config.json`):**
-    ```bash
-    ai-cli-log --init --local
-    ```
-
-This command will:
-1.  Scan for available AI tools on your system (like `gemini`, `sgpt`, or `ollama`).
-2.  Guide you through creating summarizer profiles for them.
-3.  Set a default summarizer.
+        "prompt": "You are a log summarizer. Your response MUST be a valid JSON object with one key: \"summary\" (a 3-5 word, lowercase, filename-friendly phrase). Example: {\"summary\": \"refactor-database-schema\"}. The session content is:",
+        "command": ["sgpt", "--chat", "session-summary", "\"{{prompt}}\""],
+        "maxLines": 50
+      }
+    ]
+  }
+}
+```
 
 ## Features
 
@@ -108,7 +105,7 @@ This command will:
 *   **Accurate Rendering:** Uses `@xterm/headless` to interpret ANSI escape codes, ensuring the log accurately reflects the final terminal state (spinners, progress bars, etc.).
 *   **Configurable:** Supports different AI backends (`gemini`, `sgpt`, `ollama`, etc.) for generating summaries.
 *   **Performance-Aware:** When summarizing long sessions, it intelligently samples the beginning and end of the output to ensure fast and cost-effective summary generation.
-*   **Markdown Output:** Saves sessions as clean Markdown files.
+*   **Plain Text Output:** Saves sessions as clean plain text files.
 
 ## Development Notes
 
@@ -118,7 +115,6 @@ Special thanks to Gemini for its invaluable help in the development of this tool
 
 ## TODO
 
-*   **Argument Parsing:** Refactor the manual argument parsing to use a robust library like `yargs` or `commander` to improve maintainability and provide standard features like `--help`.
 *   **Markdown Support:** Investigate and potentially implement saving logs in Markdown format, which could include session metadata (e.g., command, timestamp, summary) in a frontmatter block.
 
 ---
@@ -135,27 +131,33 @@ npm install -g ai-cli-log
 
 ## 使用方法
 
-使用 `ai-cli-log` 命令来包装任何您想记录的命令。
+使用 `ai-cli-log` 命令来包装任何您想记录的命令。核心结构是：
 
 ```bash
-ai-cli-log <command> [args...]
+ai-cli-log [全局选项] run <要记录的命令> [参数...]
 ```
 
 **示例:**
 
 - **基本日志记录:** 记录与 Google Gemini CLI 的会话。
   ```bash
-  ai-cli-log gemini
+  ai-cli-log run gemini
   ```
   *日志将保存到 `.ai-cli-log/` 目录中。*
 
-- **AI 驱动的文件名:** 使用 AI 摘要作为日志文件名。
+- **AI 驱动的文件名:** 使用 AI 摘要作为日志文件名。选项必须在 `run` 命令**之前**。
   ```bash
-  ai-cli-log -s <命令> [参数...]
+  # 使用默认摘要器启用摘要
+  ai-cli-log -s run gemini
   # 或
-  ai-cli-log --with-summary <命令> [参数...]
+  ai-cli-log --with-summary run gemini
+
+  # 启用摘要并指定一个摘要器
+  ai-cli-log --by gemini-pro run gemini
+  # 或
+  ai-cli-log --summarizer gemini-pro run gemini
   ```
-  这将使用您的默认摘要器生成一个描述性的文件名，例如 `gemini-20250713-153000-fix-database-connection-error.md`。您也可以指定一个摘要器：`ai-cli-log -s=my-ollama-summarizer ...`。
+  这将使用您默认（或指定）的摘要器生成一个描述性的文件名，例如 `gemini-20250713-153000-fix-database-connection-error.txt`。
 
 ## 配置
 
@@ -167,19 +169,19 @@ ai-cli-log <command> [args...]
 
 您可以通过手动或使用交互式设置命令来创建这些文件。
 
-### 交互式设置 (`--init`)
+### 交互式设置 (`init`)
 
-`--init` 命令可以帮助您创建配置文件。
+`init` 命令可以帮助您创建配置文件。它会扫描可用的 AI 工具，引导您完成摘要器配置的创建，并设置一个默认值。
 
 *   **创建全局配置文件:**
     ```bash
-    ai-cli-log --init
+    ai-cli-log init
     ```
     这会将配置保存到 `~/.config/ai-cli-log/config.json`。
 
 *   **创建本地（项目特定）配置文件:**
     ```bash
-    ai-cli-log --init --local
+    ai-cli-log init --local
     ```
     这会将配置保存到当前目录的 `.ai-cli-log/config.json` 中。
 
@@ -195,22 +197,22 @@ ai-cli-log <command> [args...]
       {
         "name": "gemini-pro",
         "tool": "gemini",
-        "prompt": "你是一个日志摘要器。你的响应必须是一个有效的 JSON 对象，其中包含一个键："summary"（一个 3-5 个单词的、小写的、文件名友好的短语）。示例：{"summary": "refactor-database-schema"}。会话内容是：",
+        "prompt": "你是一个日志摘要器。你的响应必须是一个有效的 JSON 对象，其中包含一个键：\"summary\"（一个 3-5 个单词的、小写的、文件名友好的短语）。示例：{\"summary\": \"refactor-database-schema\"}。会话内容是：",
         "maxLines": 100
       },
       {
         "name": "ollama",
         "tool": "ollama",
         "model": "llama3",
-        "prompt": "你是一个日志摘要器。你的响应必须是一个有效的 JSON 对象，其中包含一个键："summary"（一个 3-5 个单词的、小写的、文件名友好的短语）。示例：{"summary": "refactor-database-schema"}。会话内容是：",
+        "prompt": "你是一个日志摘要器。你的响应必须是一个有效的 JSON 对象，其中包含一个键：\"summary\"（一个 3-5 个单词的、小写的、文件名友好的短语）。示例：{\"summary\": \"refactor-database-schema\"}。会话内容是：",
         "maxLines": 50
       },
       {
         "name": "sgpt",
         "tool": "custom",
-        "command": ["sgpt", "--chat", "session-summary", ""{{prompt}}""],
-        "prompt": "你是一个日志摘要器。你的响应必须是一个有效的 JSON 对象，其中包含一个键："summary"（一个 3-5 个单词的、小写的、文件名友好的短语）。示例：{"summary": "refactor-database-schema"}。会话内容是：",
-        "maxLines": 100
+        "command": ["sgpt", "--chat", "session-summary", "\"{{prompt}}\""],
+        "prompt": "你是一个日志摘要器。你的响应必须是一个有效的 JSON 对象，其中包含一个键\"summary\"（一个 3-5 个单词的、小写的、文件名友好的短语）。示例：{\"summary\": \"refactor-database-schema\"}。会话内容是：",
+        "maxLines": 50
       },
       {
         "name": "my-custom-summarizer",
@@ -238,40 +240,7 @@ ai-cli-log <command> [args...]
     *   **`prompt`**: 传递给摘要器命令的提示。会话内容将作为标准输入传递。
     *   **`maxLines`** (可选): 限制传递给摘要器的会话内容行数。如果会话内容超过此限制，将只采样开头和结尾的行。
     *   **`command`** (可选): 对于 `custom` 工具，指定要执行的命令数组。会话内容会通过管道传递给该命令的 `stdin`。`{{prompt}}` 占位符将被实际的提示字符串替换。例如: `["my-summarizer-script", "--prompt", "{{prompt}}"]`。
-    *   **重要**: 摘要器的输出**必须**是一个有效的 JSON 对象，其中包含一个名为 `summary` 的键（例如，`{"summary": "你的摘要短语"}`）。
-```
-
-**Field Descriptions:**
-
-*   `summarizer.default` (optional): The name of the default summarizer configuration to use.
-*   `summarizer.summarizers`: An array of different summarizer configurations.
-    *   **`name`**: A unique name you give to the summarizer configuration (e.g., `gemini-pro`, `ollama`, `claude-opus`, `my-custom-summarizer`).
-    *   **`tool`**: The type of tool the summarizer uses.
-        *   `gemini`: Uses the `gemini` CLI tool.
-        *   `ollama`: Uses the `ollama` CLI tool.
-        *   `claude`: Uses the `claude` CLI tool.
-        *   `custom`: Uses a custom command.
-    *   **`model`** (optional): For the `ollama` tool, specifies the model name to use (e.g., `llama3`).
-    *   **`prompt`**: The prompt passed to the summarizer command. The session content will be passed as standard input.
-    *   **`maxLines`** (optional): Limits the number of session content lines passed to the summarizer. If the session exceeds this limit, only the beginning and end lines will be sampled.
-    *   **`command`** (optional): For the `custom` tool, specifies the command array to execute. The session content is piped to this command's `stdin`. The `{{prompt}}` placeholder will be replaced with the actual prompt string. Example: `["my-summarizer-script", "--prompt", "{{prompt}}"]`.
-    *   **Important**: The output from the summarizer **MUST** be a valid JSON object containing a key named `summary` (e.g., `{"summary": "your-summary-phrase"}`).
-
-### 交互式设置 (`--init`)
-
-运行交互式设置来创建配置文件。
-
-*   **创建全局配置文件 (位于 `~/.config/ai-cli-log/config.json`):**
-    ```bash
-    ai-cli-log --init
-    ```
-
-*   **创建本地、项目特定的配置文件 (位于 `.ai-cli-log/config.json`):**
-    ```bash
-    ai-cli-log --init --local
-    ```
-
-该命令将引导您完成配置过程，包括扫描可用的 AI 工具、创建摘要器配置和设置默认摘要器。
+    *   **重要**: 摘要器的输出**必须**是一个有效的 JSON 对象，其中包含一个名为 `summary` 的键（例如，`{"summary": "fix-login-bug"}`）。
 
 ## 功能特性
 
@@ -290,8 +259,4 @@ ai-cli-log <command> [args...]
 
 ## 待办事项 (TODO)
 
-*   **内容处理:**
-    *   当会话输出为空时，避免保存空的日志文件。
-    *   尾随空格和空行现在已从输出中删除，以解决内容不足导致大片空白区域的问题。
-*   **文件名约定:** 当前基于时间戳的文件名虽然功能上可行，但可能过于单调。评估其他更具描述性的文件名方案，同时仔细考虑如果使用 AI 摘要进行命名可能导致的信息泄露问题。
-
+*   **Markdown 支持:** 探寻并实现将日志保存为 Markdown 格式的可能性，可在文件的 frontmatter 中包含会话元数据（如：命令、时间戳、摘要等）。

package/dist/index.js

@@ -44,6 +44,7 @@ const os = __importStar(require("os"));
 const child_process_1 = require("child_process");
 const headless_1 = require("@xterm/headless");
 const readline_1 = __importDefault(require("readline"));
+const commander_1 = require("commander");
 // --- 1. CONFIGURATION & TYPE DEFINITIONS ---
 const GLOBAL_CONFIG_DIR = path.join(os.homedir(), '.config', 'ai-cli-log');
 const GLOBAL_CONFIG_PATH = path.join(GLOBAL_CONFIG_DIR, 'config.json');
@@ -125,7 +126,7 @@ async function handleInitCommand(isLocal) {
         }
         const config = readConfig();
         const summarizersToUpdate = [];
-        const newPrompt = 'You are a log summarizer. Your response MUST be a valid JSON object with one key: "summary" (a 3-5 word, lowercase, filename-friendly phrase). Example: {"summary": "refactor-database-schema"}. The session content is:';
+        const newPrompt = 'You are a log summarizer. Your response MUST be a raw, valid JSON object and nothing else. Do not wrap it in markdown blocks like ```json. The JSON object must have a single key "summary" which is a 3-5 word, lowercase, filename-friendly phrase. Example: {"summary": "refactor-database-schema"}. The session content is:';
         if (availableTools.includes('gemini')) {
             const add = await ask('\n> Found Gemini. Add/update the \'gemini-pro\' summarizer? (Y/n): ');
             if (add.toLowerCase() !== 'n') {
@@ -345,7 +346,10 @@ function runLoggingSession(command, commandArgs, summaryArg) {
                     const config = readConfig();
                     const summarizerName = (typeof summaryArg === 'string' ? summaryArg : config.summarizer.default) || 'default';
                     try {
-                        const summaryData = JSON.parse(rawSummaryJson);
+                        // Pre-process the raw summary to extract JSON from markdown blocks if present
+                        const jsonMatch = rawSummaryJson.match(/\{.*\}/s);
+                        const cleanJson = jsonMatch ? jsonMatch[0] : rawSummaryJson;
+                        const summaryData = JSON.parse(cleanJson);
                         const slug = summaryData.summary;
                         if (typeof slug !== 'string') {
                             throw new Error('Invalid JSON structure from summarizer: "summary" key is missing or not a string.');
@@ -382,34 +386,46 @@ function runLoggingSession(command, commandArgs, summaryArg) {
 }
 // --- 3. MAIN ENTRY POINT & ARGUMENT PARSER ---
 function main() {
-    const args = process.argv.slice(2);
-    if (args.includes('--version') || args.includes('-v')) {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const pkg = require('../package.json');
-        console.log(pkg.version);
-        return;
-    }
-    if (args.includes('--init')) {
-        const isLocal = args.includes('--local');
-        handleInitCommand(isLocal);
-        return;
-    }
-    const summaryArgRaw = args.find(arg => arg.startsWith('--with-summary') || arg.startsWith('-s'));
-    const otherArgs = args.filter(arg => !arg.startsWith('--with-summary') &&
-        !arg.startsWith('-s') &&
-        arg !== '--init' &&
-        arg !== '--local');
-    const command = otherArgs[0];
-    const commandArgs = otherArgs.slice(1);
-    if (!command) {
-        console.error('Usage: ai-cli-log [-s[=<summarizer>]] <command> [args...]');
-        console.error('       ai-cli-log --init [--local]');
-        process.exit(1);
-    }
-    let summaryArg = false;
-    if (summaryArgRaw) {
-        summaryArg = summaryArgRaw.includes('=') ? summaryArgRaw.split('=')[1] : true;
+    const program = new commander_1.Command();
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const pkg = require('../package.json');
+    program
+        .name('ai-cli-log')
+        .description('A CLI tool to seamlessly log terminal sessions with AI models.')
+        .version(pkg.version, '-v, --version', 'Output the current version')
+        .option('-s, --with-summary', 'Enable AI summary for the session using the default summarizer.')
+        .option('--by <name>, --summarizer <name>', 'Specify a summarizer to use. Implies --with-summary.');
+    program
+        .command('init')
+        .description('Initialize or update the configuration file.')
+        .option('--local', 'Create the configuration file in the current directory\'s .ai-cli-log folder.', false)
+        .action((options) => {
+        handleInitCommand(options.local);
+    });
+    program
+        .command('run')
+        .usage('<command> [args...]')
+        .description("Run a command and log the session. Any options for ai-cli-log itself (like -s) must come before the 'run' command.")
+        .argument('<command>', 'The command to execute and log.')
+        .argument('[args...]', 'Arguments for the command.')
+        .allowUnknownOption()
+        .action((command, args) => {
+        const options = program.opts();
+        let summaryArg = false;
+        if (options.by) {
+            summaryArg = options.by;
+        }
+        else if (options.summarizer) {
+            summaryArg = options.summarizer;
+        }
+        else if (options.withSummary) {
+            summaryArg = true;
+        }
+        runLoggingSession(command, args, summaryArg);
+    });
+    program.parse(process.argv);
+    if (!process.argv.slice(2).length) {
+        program.help();
     }
-    runLoggingSession(command, commandArgs, summaryArg);
 }
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-cli-log",
-  "version": "1.0.5",
+  "version": "1.0.9",
   "description": "Seamlessly log your AI-powered coding conversations. This command-line interface (CLI) tool captures your terminal   interactions with AI models like Gemini and Claude, saving entire sessions as clean plain text documents for easy   review and documentation.",
   "main": "dist/index.js",
   "bin": {
@@ -23,12 +23,14 @@
   },
   "homepage": "https://github.com/alingse/ai-cli-log#readme",
   "devDependencies": {
+    "@types/commander": "^2.12.0",
     "@types/node": "^24.0.10",
     "ts-node": "^10.9.2",
     "typescript": "^5.8.3"
   },
   "dependencies": {
     "@xterm/headless": "^5.5.0",
+    "commander": "^14.0.0",
     "node-pty": "^1.0.0"
   }
 }

package/src/index.ts

@@ -7,6 +7,7 @@ import * as os from 'os';
 import { spawn } from 'child_process';
 import { Terminal } from '@xterm/headless';
 import readline from 'readline';
+import { Command } from 'commander';
 
 // --- 1. CONFIGURATION & TYPE DEFINITIONS ---
 
@@ -110,7 +111,7 @@ async function handleInitCommand(isLocal: boolean) {
 
         const config = readConfig();
         const summarizersToUpdate: Summarizer[] = [];
-        const newPrompt = 'You are a log summarizer. Your response MUST be a valid JSON object with one key: "summary" (a 3-5 word, lowercase, filename-friendly phrase). Example: {"summary": "refactor-database-schema"}. The session content is:';
+        const newPrompt = 'You are a log summarizer. Your response MUST be a raw, valid JSON object and nothing else. Do not wrap it in markdown blocks like ```json. The JSON object must have a single key "summary" which is a 3-5 word, lowercase, filename-friendly phrase. Example: {"summary": "refactor-database-schema"}. The session content is:';
 
         if (availableTools.includes('gemini')) {
             const add = await ask('\n> Found Gemini. Add/update the \'gemini-pro\' summarizer? (Y/n): ');
@@ -357,7 +358,11 @@ function runLoggingSession(command: string, commandArgs: string[], summaryArg?:
                     const summarizerName = (typeof summaryArg === 'string' ? summaryArg : config.summarizer.default) || 'default';
                     
                     try {
-                        const summaryData = JSON.parse(rawSummaryJson);
+                        // Pre-process the raw summary to extract JSON from markdown blocks if present
+                        const jsonMatch = rawSummaryJson.match(/\{.*\}/s);
+                        const cleanJson = jsonMatch ? jsonMatch[0] : rawSummaryJson;
+
+                        const summaryData = JSON.parse(cleanJson);
                         const slug = summaryData.summary;
 
                         if (typeof slug !== 'string') {
@@ -399,45 +404,50 @@ function runLoggingSession(command: string, commandArgs: string[], summaryArg?:
 // --- 3. MAIN ENTRY POINT & ARGUMENT PARSER ---
 
 function main() {
-    const args = process.argv.slice(2);
-
-    if (args.includes('--version') || args.includes('-v')) {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const pkg = require('../package.json');
-        console.log(pkg.version);
-        return;
-    }
+    const program = new Command();
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const pkg = require('../package.json');
+
+    program
+        .name('ai-cli-log')
+        .description('A CLI tool to seamlessly log terminal sessions with AI models.')
+        .version(pkg.version, '-v, --version', 'Output the current version')
+        .option('-s, --with-summary', 'Enable AI summary for the session using the default summarizer.')
+        .option('--by <name>, --summarizer <name>', 'Specify a summarizer to use. Implies --with-summary.');
+
+    program
+        .command('init')
+        .description('Initialize or update the configuration file.')
+        .option('--local', 'Create the configuration file in the current directory\'s .ai-cli-log folder.', false)
+        .action((options) => {
+            handleInitCommand(options.local);
+        });
 
-    if (args.includes('--init')) {
-        const isLocal = args.includes('--local');
-        handleInitCommand(isLocal);
-        return;
-    }
+    program
+        .command('run')
+        .usage('<command> [args...]')
+        .description("Run a command and log the session. Any options for ai-cli-log itself (like -s) must come before the 'run' command.")
+        .argument('<command>', 'The command to execute and log.')
+        .argument('[args...]', 'Arguments for the command.')
+        .allowUnknownOption()
+        .action((command, args) => {
+            const options = program.opts();
+            let summaryArg: string | boolean = false;
+            if (options.by) {
+                summaryArg = options.by;
+            } else if (options.summarizer) {
+                summaryArg = options.summarizer;
+            } else if (options.withSummary) {
+                summaryArg = true;
+            }
+            runLoggingSession(command, args, summaryArg);
+        });
 
-    const summaryArgRaw = args.find(arg => arg.startsWith('--with-summary') || arg.startsWith('-s'));
-    
-    const otherArgs = args.filter(arg => 
-        !arg.startsWith('--with-summary') && 
-        !arg.startsWith('-s') &&
-        arg !== '--init' &&
-        arg !== '--local'
-    );
-    
-    const command = otherArgs[0];
-    const commandArgs = otherArgs.slice(1);
-
-    if (!command) {
-        console.error('Usage: ai-cli-log [-s[=<summarizer>]] <command> [args...]');
-        console.error('       ai-cli-log --init [--local]');
-        process.exit(1);
-    }
+    program.parse(process.argv);
 
-    let summaryArg: string | boolean = false;
-    if (summaryArgRaw) {
-        summaryArg = summaryArgRaw.includes('=') ? summaryArgRaw.split('=')[1] : true;
+    if (!process.argv.slice(2).length) {
+        program.help();
     }
-
-    runLoggingSession(command, commandArgs, summaryArg);
 }
 
-main();
+main();