clawck 0.1.0 → 0.1.3

package/README.md

@@ -160,15 +160,37 @@ Entries merge cleanly by UUID — no conflicts, no duplicates.
 ## CLI Commands
 
 ```bash
-clawck init                  # Create .clawck/ directory with config
-clawck serve                 # Start API + dashboard (default: port 3456)
-clawck serve --port 8080     # Custom port
-clawck mcp                   # Start MCP server on stdio
-clawck status                # Show running tasks and stats
-clawck report                # Timesheet summary (last 7 days)
-clawck report --days 30      # Last 30 days
-clawck report --client acme  # Filter by client
-clawck seed --count 50       # Generate test data
+clawck init                          # Create .clawck/ directory with config
+clawck serve                         # Start API + dashboard (default: port 3456)
+clawck serve --port 8080             # Custom port
+clawck mcp                           # Start MCP server on stdio
+
+# Time tracking
+clawck start <task>                  # Start a timer
+clawck stop <id>                     # Stop a timer
+clawck log <task> --duration 30      # Log a completed task retroactively
+
+# Viewing entries
+clawck status                        # Show running tasks and stats
+clawck list                          # List entries in a table (last 7 days)
+clawck list --days 30 --project web  # Filter by days/project/client/agent
+clawck get <id>                      # Show a single entry
+clawck entries --status running      # Query with filters
+
+# Reports & export
+clawck report                        # Timesheet summary (last 7 days)
+clawck report --days 30 --detailed   # With individual entries
+clawck export --format csv --days 30 # Export as CSV (also: json)
+
+# Editing & deleting
+clawck edit <id> --task "New name"   # Edit fields (task, project, client, agent, etc.)
+clawck delete <id>                   # Delete an entry (supports 8-char prefix)
+
+# Testing
+clawck seed --count 50               # Generate test data
+
+# Global options
+clawck --json <command>              # Output as JSON (for scripting)
 ```
 
 ## Configuration
@@ -197,6 +219,8 @@ Edit `.clawck/config.json`:
 }
 ```
 
+Clawck validates config on load. Invalid values (e.g., non-numeric port, malformed human_equivalents) will show a clear error message.
+
 ## REST API
 
 | Method | Endpoint | Description |
@@ -234,7 +258,7 @@ clawck/
 **Design principles:**
 - **Zero external dependencies** — SQLite is embedded, no Redis/Postgres/Docker needed
 - **One process** — API, dashboard, and MCP all run from the same `clawck serve`
-- **Append-only writes** — Entries are created and updated, never deleted
+- **Append-first writes** — Entries are created and updated; deletion available via CLI
 - **UUID-based merging** — Multi-agent data combines without conflicts
 - **Configurable multipliers** — Human-equivalent estimates are transparent and adjustable
 

package/dist/cli/index.js

@@ -26,7 +26,8 @@ const program = new commander_1.Command();
 program
     .name('clawck')
     .description('⏱️🦀 Clawck — Time tracking for AI agents')
-    .version('0.1.0');
+    .version('0.1.3')
+    .option('--json', 'Output as JSON (for scripting/pipelines)');
 // ─── Init ─────────────────────────────────────────────────
 program
     .command('init')
@@ -34,6 +35,16 @@ program
     .option('-d, --dir <path>', 'Data directory', '.clawck')
     .action(async (opts) => {
     const dir = path_1.default.resolve(opts.dir);
+    // Prevent nesting: don't create .clawck inside an existing .clawck
+    const cwd = process.cwd();
+    if (path_1.default.basename(cwd) === '.clawck' && opts.dir === '.clawck') {
+        console.error('  Already inside a .clawck directory. Aborting to prevent nesting.');
+        process.exit(1);
+    }
+    if (path_1.default.basename(dir) === '.clawck' && fs_1.default.existsSync(path_1.default.join(dir, 'clawck.db'))) {
+        console.error('  Already inside a .clawck directory. Aborting to prevent nesting.');
+        process.exit(1);
+    }
     if (!fs_1.default.existsSync(dir)) {
         fs_1.default.mkdirSync(dir, { recursive: true });
     }
@@ -92,6 +103,11 @@ program
     const clawck = await new clawck_1.Clawck(config).ready();
     const stats = clawck.stats();
     const running = clawck.running();
+    if (program.opts().json) {
+        console.log(JSON.stringify({ stats, running }));
+        clawck.close();
+        return;
+    }
     console.log(`\n  ⏱️🦀 Clawck Status`);
     console.log(`  ├─ Total entries:  ${stats.total_entries}`);
     console.log(`  ├─ Running now:    ${stats.running}`);
@@ -118,6 +134,7 @@ program
     .option('--client <name>', 'Filter by client')
     .option('--project <name>', 'Filter by project')
     .option('--agent <name>', 'Filter by agent')
+    .option('--detailed', 'Show individual entries')
     .action(async (opts) => {
     const config = loadConfig(opts.dir);
     const clawck = await new clawck_1.Clawck(config).ready();
@@ -129,10 +146,15 @@ program
         project: opts.project,
         agent: opts.agent,
     });
+    if (program.opts().json) {
+        console.log(JSON.stringify(ts));
+        clawck.close();
+        return;
+    }
     console.log(`\n  📋 Clawck Timesheet — Last ${days} days`);
     console.log(`  ${'─'.repeat(50)}`);
-    console.log(`  ⏱️  Agent hours:       ${ts.total_agent_hours.toFixed(1)} hrs`);
-    console.log(`  👤 Human equiv:       ${ts.total_human_equiv_hours.toFixed(1)} hrs`);
+    console.log(`  ⏱️  Agent hours:       ${ts.total_agent_hours.toFixed(2)} hrs`);
+    console.log(`  👤 Human equiv:       ${ts.total_human_equiv_hours.toFixed(2)} hrs`);
     console.log(`  💰 Agent cost:        $${ts.total_cost_usd.toFixed(2)}`);
     console.log(`  💚 Est. savings:      $${ts.total_savings_usd.toFixed(0)}`);
     console.log(`  🔢 Total entries:     ${ts.total_entries}`);
@@ -141,13 +163,206 @@ program
         console.log(`\n  📁 By Project:`);
         for (const p of ts.by_project) {
             const bar = '█'.repeat(Math.max(1, Math.round(p.agent_hours / (ts.total_agent_hours || 1) * 20)));
-            console.log(`  ${bar} ${p.project} (${p.client}): ${p.agent_hours.toFixed(1)}h → ${p.human_equiv_hours.toFixed(1)}h human equiv`);
+            console.log(`  ${bar} ${p.project} (${p.client}): ${p.agent_hours.toFixed(2)}h → ${p.human_equiv_hours.toFixed(2)}h human equiv`);
         }
     }
     if (ts.by_agent.length > 0) {
         console.log(`\n  🤖 By Agent:`);
         for (const a of ts.by_agent) {
-            console.log(`  • ${a.agent} (${a.model}): ${a.agent_hours.toFixed(1)}h, ${a.success_rate}% success`);
+            console.log(`  • ${a.agent} (${a.model}): ${a.agent_hours.toFixed(2)}h, ${a.success_rate}% success`);
+        }
+    }
+    if (opts.detailed) {
+        const entries = clawck.query({ client: opts.client, project: opts.project, agent: opts.agent, from, to, limit: 500 });
+        console.log(`\n  📝 Entries:`);
+        printEntryTable(entries);
+    }
+    console.log('');
+    clawck.close();
+});
+// ─── Start ───────────────────────────────────────────────
+program
+    .command('start <task>')
+    .description('Start tracking time for a task')
+    .option('-d, --dir <path>', 'Data directory', '.clawck')
+    .option('--project <name>', 'Project name')
+    .option('--client <name>', 'Client name')
+    .option('--category <type>', 'Task category')
+    .option('--agent <name>', 'Agent name')
+    .option('--model <name>', 'Model name')
+    .option('--tags <tags...>', 'Tags')
+    .action(async (task, opts) => {
+    const config = loadConfig(opts.dir);
+    const clawck = await new clawck_1.Clawck(config).ready();
+    const entry = clawck.start({
+        task,
+        project: opts.project,
+        client: opts.client,
+        category: opts.category,
+        agent: opts.agent,
+        model: opts.model,
+        tags: opts.tags,
+    });
+    if (program.opts().json) {
+        console.log(JSON.stringify(entry));
+    }
+    else {
+        console.log(`  Started: ${entry.task}`);
+        console.log(`  ID:      ${entry.id}`);
+        console.log(`  Project: ${entry.project}  Client: ${entry.client}`);
+    }
+    clawck.close();
+});
+// ─── Stop ────────────────────────────────────────────────
+program
+    .command('stop <id>')
+    .description('Stop tracking time for a task')
+    .option('-d, --dir <path>', 'Data directory', '.clawck')
+    .option('--status <status>', 'Outcome (completed/failed)', 'completed')
+    .option('--summary <text>', 'Summary of work done')
+    .option('--tokens-in <n>', 'Input tokens consumed', parseFloat)
+    .option('--tokens-out <n>', 'Output tokens generated', parseFloat)
+    .option('--cost <n>', 'Cost in USD', parseFloat)
+    .option('--tool-calls <n>', 'Number of tool calls', parseInt)
+    .action(async (id, opts) => {
+    const config = loadConfig(opts.dir);
+    const clawck = await new clawck_1.Clawck(config).ready();
+    const entry = clawck.stop({
+        id,
+        status: opts.status,
+        summary: opts.summary,
+        tokens_in: opts.tokensIn,
+        tokens_out: opts.tokensOut,
+        cost_usd: opts.cost,
+        tool_calls: opts.toolCalls,
+    });
+    if (!entry) {
+        if (program.opts().json) {
+            console.log(JSON.stringify({ ok: false, error: `Entry not found: ${id}` }));
+        }
+        else {
+            console.error(`  Entry not found: ${id}`);
+        }
+        clawck.close();
+        process.exit(1);
+    }
+    const duration_minutes = entry.end
+        ? +((new Date(entry.end).getTime() - new Date(entry.start).getTime()) / 60000).toFixed(1)
+        : null;
+    if (program.opts().json) {
+        console.log(JSON.stringify({ ...entry, duration_minutes }));
+    }
+    else {
+        console.log(`  Stopped: ${entry.task}`);
+        console.log(`  Duration: ${duration_minutes}m  Status: ${entry.status}`);
+    }
+    clawck.close();
+});
+// ─── Log ─────────────────────────────────────────────────
+program
+    .command('log <task>')
+    .description('Log a completed task retroactively')
+    .option('-d, --dir <path>', 'Data directory', '.clawck')
+    .option('--duration <minutes>', 'Duration in minutes', parseFloat)
+    .option('--project <name>', 'Project name')
+    .option('--client <name>', 'Client name')
+    .option('--category <type>', 'Task category')
+    .option('--agent <name>', 'Agent name')
+    .option('--model <name>', 'Model name')
+    .option('--summary <text>', 'Summary of work done')
+    .option('--tags <tags...>', 'Tags')
+    .action(async (task, opts) => {
+    if (!opts.duration) {
+        console.error('  --duration <minutes> is required');
+        process.exit(1);
+    }
+    const config = loadConfig(opts.dir);
+    const clawck = await new clawck_1.Clawck(config).ready();
+    const entry = clawck.log({
+        task,
+        duration_minutes: opts.duration,
+        project: opts.project,
+        client: opts.client,
+        category: opts.category,
+        agent: opts.agent,
+        model: opts.model,
+        summary: opts.summary,
+        tags: opts.tags,
+    });
+    if (program.opts().json) {
+        console.log(JSON.stringify(entry));
+    }
+    else {
+        console.log(`  Logged: ${entry.task}`);
+        console.log(`  ID: ${entry.id}  Duration: ${opts.duration}m`);
+    }
+    clawck.close();
+});
+// ─── Get ─────────────────────────────────────────────────
+program
+    .command('get <id>')
+    .description('Get a single time entry by ID')
+    .option('-d, --dir <path>', 'Data directory', '.clawck')
+    .action(async (id, opts) => {
+    const config = loadConfig(opts.dir);
+    const clawck = await new clawck_1.Clawck(config).ready();
+    const entry = clawck.get(id);
+    if (!entry) {
+        if (program.opts().json) {
+            console.log(JSON.stringify({ ok: false, error: `Entry not found: ${id}` }));
+        }
+        else {
+            console.error(`  Entry not found: ${id}`);
+        }
+        clawck.close();
+        process.exit(1);
+    }
+    if (program.opts().json) {
+        console.log(JSON.stringify(entry));
+    }
+    else {
+        console.log(`  ${entry.task}`);
+        console.log(`  ID: ${entry.id}  Status: ${entry.status}`);
+        console.log(`  Project: ${entry.project}  Client: ${entry.client}`);
+        console.log(`  Agent: ${entry.agent}  Model: ${entry.model}`);
+        console.log(`  Start: ${entry.start}  End: ${entry.end || '(running)'}`);
+    }
+    clawck.close();
+});
+// ─── Entries ─────────────────────────────────────────────
+program
+    .command('entries')
+    .description('Query time entries')
+    .option('-d, --dir <path>', 'Data directory', '.clawck')
+    .option('--client <name>', 'Filter by client')
+    .option('--project <name>', 'Filter by project')
+    .option('--agent <name>', 'Filter by agent')
+    .option('--status <status>', 'Filter by status')
+    .option('--from <date>', 'Start date (ISO 8601)')
+    .option('--to <date>', 'End date (ISO 8601)')
+    .option('--limit <n>', 'Max entries', '50')
+    .action(async (opts) => {
+    const config = loadConfig(opts.dir);
+    const clawck = await new clawck_1.Clawck(config).ready();
+    const entries = clawck.query({
+        client: opts.client,
+        project: opts.project,
+        agent: opts.agent,
+        status: opts.status,
+        from: opts.from,
+        to: opts.to,
+        limit: parseInt(opts.limit) || 50,
+    });
+    if (program.opts().json) {
+        console.log(JSON.stringify(entries));
+    }
+    else {
+        console.log(`\n  ${entries.length} entries:`);
+        for (const e of entries) {
+            const dur = e.end
+                ? `${((new Date(e.end).getTime() - new Date(e.start).getTime()) / 60000).toFixed(0)}m`
+                : 'running';
+            console.log(`  ${e.id.slice(0, 8)}  ${e.status.padEnd(9)}  ${dur.padStart(6)}  ${e.project}/${e.client}  ${e.task.slice(0, 50)}`);
         }
     }
     console.log('');
@@ -210,7 +425,227 @@ program
     console.log(`  └─ Run: clawck serve\n`);
     clawck.close();
 });
+// ─── List ───────────────────────────────────────────────
+program
+    .command('list')
+    .description('List time entries in a human-readable table')
+    .option('-d, --dir <path>', 'Data directory', '.clawck')
+    .option('--days <number>', 'Number of days to include', '7')
+    .option('--client <name>', 'Filter by client')
+    .option('--project <name>', 'Filter by project')
+    .option('--agent <name>', 'Filter by agent')
+    .option('--limit <n>', 'Max entries', '50')
+    .action(async (opts) => {
+    const config = loadConfig(opts.dir);
+    const clawck = await new clawck_1.Clawck(config).ready();
+    const days = parseInt(opts.days) || 7;
+    const from = new Date(Date.now() - days * 86400000).toISOString();
+    const to = new Date().toISOString();
+    const entries = clawck.query({
+        client: opts.client,
+        project: opts.project,
+        agent: opts.agent,
+        from,
+        to,
+        limit: parseInt(opts.limit) || 50,
+    });
+    if (program.opts().json) {
+        console.log(JSON.stringify(entries));
+        clawck.close();
+        return;
+    }
+    printEntryTable(entries);
+    clawck.close();
+});
+// ─── Delete ─────────────────────────────────────────────
+program
+    .command('delete <id>')
+    .description('Delete a time entry by ID (supports 8-char prefix)')
+    .option('-d, --dir <path>', 'Data directory', '.clawck')
+    .action(async (id, opts) => {
+    const config = loadConfig(opts.dir);
+    const clawck = await new clawck_1.Clawck(config).ready();
+    const entry = resolveEntryId(clawck, id);
+    if (!entry) {
+        clawck.close();
+        process.exit(1);
+    }
+    clawck.delete(entry.id);
+    if (program.opts().json) {
+        console.log(JSON.stringify({ ok: true, deleted: entry }));
+    }
+    else {
+        console.log(`  Deleted: ${entry.task}`);
+        console.log(`  ID: ${entry.id.slice(0, 8)}  Project: ${entry.project}  Agent: ${entry.agent}`);
+    }
+    clawck.close();
+});
+// ─── Edit ───────────────────────────────────────────────
+program
+    .command('edit <id>')
+    .description('Edit a time entry by ID (supports 8-char prefix)')
+    .option('-d, --dir <path>', 'Data directory', '.clawck')
+    .option('--task <text>', 'Update task description')
+    .option('--duration <minutes>', 'Update duration (recalculates end)', parseFloat)
+    .option('--project <name>', 'Update project')
+    .option('--client <name>', 'Update client')
+    .option('--agent <name>', 'Update agent')
+    .option('--category <type>', 'Update category')
+    .option('--summary <text>', 'Update summary')
+    .action(async (id, opts) => {
+    const config = loadConfig(opts.dir);
+    const clawck = await new clawck_1.Clawck(config).ready();
+    const entry = resolveEntryId(clawck, id);
+    if (!entry) {
+        clawck.close();
+        process.exit(1);
+    }
+    const updates = {};
+    if (opts.task)
+        updates.task = opts.task;
+    if (opts.project)
+        updates.project = opts.project;
+    if (opts.client)
+        updates.client = opts.client;
+    if (opts.agent)
+        updates.agent = opts.agent;
+    if (opts.category)
+        updates.category = opts.category;
+    if (opts.summary)
+        updates.summary = opts.summary;
+    if (opts.duration !== undefined) {
+        updates.end = new Date(new Date(entry.start).getTime() + opts.duration * 60000).toISOString();
+    }
+    const updated = clawck.update(entry.id, updates);
+    if (program.opts().json) {
+        console.log(JSON.stringify(updated));
+    }
+    else {
+        console.log(`  Updated: ${updated.task}`);
+        console.log(`  ID: ${updated.id.slice(0, 8)}  Project: ${updated.project}  Agent: ${updated.agent}`);
+        if (opts.duration !== undefined) {
+            console.log(`  Duration: ${formatDuration(opts.duration)}`);
+        }
+    }
+    clawck.close();
+});
+// ─── Export ──────────────────────────────────────────────
+program
+    .command('export')
+    .description('Export time entries as JSON or CSV')
+    .option('-d, --dir <path>', 'Data directory', '.clawck')
+    .option('--format <type>', 'Output format (json or csv)', 'json')
+    .option('--days <number>', 'Number of days to include', '7')
+    .option('--client <name>', 'Filter by client')
+    .option('--project <name>', 'Filter by project')
+    .option('--agent <name>', 'Filter by agent')
+    .action(async (opts) => {
+    const config = loadConfig(opts.dir);
+    const clawck = await new clawck_1.Clawck(config).ready();
+    const days = parseInt(opts.days) || 7;
+    const from = new Date(Date.now() - days * 86400000).toISOString();
+    const to = new Date().toISOString();
+    const entries = clawck.query({
+        client: opts.client,
+        project: opts.project,
+        agent: opts.agent,
+        from,
+        to,
+        limit: 10000,
+    });
+    if (opts.format === 'csv') {
+        const csvEscape = (val) => {
+            if (val.includes(',') || val.includes('"') || val.includes('\n')) {
+                return '"' + val.replace(/"/g, '""') + '"';
+            }
+            return val;
+        };
+        console.log('id,date,task,category,duration_minutes,project,client,agent,model,status,tokens_in,tokens_out,cost_usd,summary');
+        for (const e of entries) {
+            const durationMin = e.end
+                ? ((new Date(e.end).getTime() - new Date(e.start).getTime()) / 60000).toFixed(2)
+                : '0';
+            const date = e.start.split('T')[0];
+            console.log([
+                csvEscape(e.id),
+                date,
+                csvEscape(e.task),
+                csvEscape(e.category),
+                durationMin,
+                csvEscape(e.project),
+                csvEscape(e.client),
+                csvEscape(e.agent),
+                csvEscape(e.model),
+                csvEscape(e.status),
+                String(e.tokens_in),
+                String(e.tokens_out),
+                e.cost_usd.toFixed(4),
+                csvEscape(e.summary),
+            ].join(','));
+        }
+    }
+    else {
+        console.log(JSON.stringify(entries, null, 2));
+    }
+    clawck.close();
+});
 // ─── Helpers ──────────────────────────────────────────────
+function formatDuration(mins) {
+    if (mins < 1)
+        return '<1 min';
+    if (mins < 60)
+        return `${Math.round(mins)} min`;
+    const h = Math.floor(mins / 60);
+    const m = Math.round(mins % 60);
+    return m > 0 ? `${h}h ${m}m` : `${h}h`;
+}
+function resolveEntryId(clawck, idPrefix) {
+    const exact = clawck.get(idPrefix);
+    if (exact)
+        return exact;
+    const matches = clawck.findByPrefix(idPrefix);
+    if (matches.length === 0) {
+        if (program.opts().json) {
+            console.log(JSON.stringify({ ok: false, error: `No entry found matching: ${idPrefix}` }));
+        }
+        else {
+            console.error(`  No entry found matching: ${idPrefix}`);
+        }
+        return null;
+    }
+    if (matches.length > 1) {
+        if (program.opts().json) {
+            console.log(JSON.stringify({ ok: false, error: 'Ambiguous ID prefix', matches: matches.map(e => ({ id: e.id, task: e.task })) }));
+        }
+        else {
+            console.error(`  Ambiguous ID prefix "${idPrefix}". Matches:`);
+            for (const m of matches) {
+                console.error(`    ${m.id.slice(0, 8)}  ${m.task.slice(0, 50)}`);
+            }
+        }
+        return null;
+    }
+    return matches[0];
+}
+function printEntryTable(entries) {
+    if (entries.length === 0) {
+        console.log('\n  No entries found.\n');
+        return;
+    }
+    const header = `  ${'ID'.padEnd(10)} ${'Task'.padEnd(42)} ${'Duration'.padEnd(10)} ${'Project'.padEnd(12)} ${'Agent'.padEnd(12)} ${'Time'}`;
+    console.log(`\n${header}`);
+    console.log(`  ${'─'.repeat(header.length - 2)}`);
+    for (const e of entries) {
+        const durationMin = e.end
+            ? (new Date(e.end).getTime() - new Date(e.start).getTime()) / 60000
+            : (Date.now() - new Date(e.start).getTime()) / 60000;
+        const dur = e.end ? formatDuration(durationMin) : 'running';
+        const task = e.task.length > 40 ? e.task.slice(0, 37) + '...' : e.task;
+        const time = new Date(e.start).toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit', hour12: false });
+        console.log(`  ${e.id.slice(0, 8).padEnd(10)} ${task.padEnd(42)} ${dur.padEnd(10)} ${e.project.slice(0, 12).padEnd(12)} ${e.agent.padEnd(12)} ${time}`);
+    }
+    console.log(`\n  ${entries.length} entries\n`);
+}
 function loadConfig(dir) {
     const dataDir = path_1.default.resolve(dir);
     const configPath = path_1.default.join(dataDir, 'config.json');
@@ -223,6 +658,30 @@ function loadConfig(dir) {
             // Ignore bad config
         }
     }
+    // Validate key config fields
+    if (fileConfig.port !== undefined) {
+        if (typeof fileConfig.port !== 'number' || fileConfig.port < 1 || fileConfig.port > 65535) {
+            console.error(`  Config error: "port" must be a number between 1 and 65535 (got ${JSON.stringify(fileConfig.port)})`);
+            process.exit(1);
+        }
+    }
+    if (fileConfig.human_equivalents !== undefined) {
+        if (typeof fileConfig.human_equivalents !== 'object' || fileConfig.human_equivalents === null) {
+            console.error('  Config error: "human_equivalents" must be an object');
+            process.exit(1);
+        }
+        for (const [key, val] of Object.entries(fileConfig.human_equivalents)) {
+            const v = val;
+            if (typeof v.multiplier !== 'number' || typeof v.human_rate_usd !== 'number') {
+                console.error(`  Config error: "human_equivalents.${key}" must have numeric "multiplier" and "human_rate_usd"`);
+                process.exit(1);
+            }
+        }
+    }
+    if (fileConfig.remote_sources !== undefined && !Array.isArray(fileConfig.remote_sources)) {
+        console.error('  Config error: "remote_sources" must be an array');
+        process.exit(1);
+    }
     return {
         ...types_1.DEFAULT_CONFIG,
         ...fileConfig,