skilltally 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ {
2
+ "name": "skilltally",
3
+ "interface": {
4
+ "displayName": "SkillTally"
5
+ },
6
+ "plugins": [
7
+ {
8
+ "name": "skilltally",
9
+ "source": {
10
+ "source": "url",
11
+ "url": "https://github.com/112516101106/skilltally.git",
12
+ "ref": "main"
13
+ },
14
+ "policy": {
15
+ "installation": "AVAILABLE",
16
+ "authentication": "ON_INSTALL"
17
+ },
18
+ "category": "Productivity"
19
+ }
20
+ ]
21
+ }
@@ -0,0 +1,18 @@
1
+ {
2
+ "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
3
+ "name": "skilltally",
4
+ "description": "Real-time skill usage tracking via hooks for Claude Code, Codex, Antigravity & Gemini CLI.",
5
+ "owner": {
6
+ "name": "112516101106",
7
+ "url": "https://github.com/112516101106"
8
+ },
9
+ "plugins": [
10
+ {
11
+ "name": "skilltally",
12
+ "description": "Track skill activations and identify unused skills eating context.",
13
+ "version": "1.0.0",
14
+ "source": "./",
15
+ "category": "productivity"
16
+ }
17
+ ]
18
+ }
@@ -0,0 +1,13 @@
1
+ {
2
+ "name": "skilltally",
3
+ "version": "1.0.0",
4
+ "description": "Real-time skill usage tracking via hooks for Antigravity, Claude Code, Codex & Gemini CLI.",
5
+ "author": {
6
+ "name": "112516101106",
7
+ "url": "https://github.com/112516101106"
8
+ },
9
+ "homepage": "https://github.com/112516101106/skilltally",
10
+ "repository": "https://github.com/112516101106/skilltally",
11
+ "license": "MIT",
12
+ "hooks": "./hooks/claude-codex-hooks.json"
13
+ }
@@ -0,0 +1,39 @@
1
+ {
2
+ "name": "skilltally",
3
+ "version": "1.0.0",
4
+ "description": "Real-time skill usage tracking via hooks for Antigravity, Claude Code, Codex & Gemini CLI.",
5
+ "author": {
6
+ "name": "112516101106",
7
+ "url": "https://github.com/112516101106"
8
+ },
9
+ "homepage": "https://github.com/112516101106/skilltally",
10
+ "repository": "https://github.com/112516101106/skilltally",
11
+ "license": "MIT",
12
+ "keywords": [
13
+ "skills",
14
+ "analytics",
15
+ "usage",
16
+ "hooks",
17
+ "productivity"
18
+ ],
19
+ "skills": "./skills/",
20
+ "hooks": "./hooks/claude-codex-hooks.json",
21
+ "interface": {
22
+ "displayName": "SkillTally",
23
+ "shortDescription": "Real-time skill usage analytics & Context Tax reporter",
24
+ "longDescription": "Track which agent skills are actually invoked via lightweight PostToolUse hooks and historical log backfill, and find unused skills costing session context tokens.",
25
+ "developerName": "112516101106",
26
+ "category": "Productivity",
27
+ "capabilities": [
28
+ "Lifecycle hooks",
29
+ "Read"
30
+ ],
31
+ "websiteURL": "https://github.com/112516101106/skilltally",
32
+ "defaultPrompt": [
33
+ "Which agent skills do I use the most in the last 30 days?",
34
+ "Show unused skills and how many context tokens disabling them would save",
35
+ "Backfill skill usage history from local agent logs"
36
+ ],
37
+ "brandColor": "#0F766E"
38
+ }
39
+ }
package/CHANGELOG.md ADDED
@@ -0,0 +1,40 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [1.0.0] - 2026-11-19
9
+
10
+ ### Added
11
+ - GitHub Actions CI matrix across macOS, Ubuntu, and Windows on Node.js 18, 20, 22, and 24, plus npm tarball extraction verification.
12
+ - Provenance-enabled npm release workflow (`.github/workflows/release.yml`).
13
+ - Production README documentation and `CHANGELOG.md`.
14
+
15
+ ### Fixed
16
+ - Cross-platform Windows compatibility in Antigravity symlink/junction cleanup, TOML path normalization, and `node --test` test discovery.
17
+
18
+ ## [0.3.0] - 2026-11-19
19
+
20
+ ### Added
21
+ - Gemini CLI support: `gemini-extension.json`, `installGemini`/`uninstallGemini` (`AfterTool` hook in `~/.gemini/settings.json`), `backfillGemini` (`~/.gemini/tmp/*/chats/`), and `doctor` diagnostics.
22
+ - `skilltally timeline` (`--by day|week|month`, `--skill`, ASCII bar chart).
23
+ - `skilltally export` (JSON and RFC-4180 CSV, `-o`/`--output`, `--include-failed`).
24
+ - Automatic monthly archive rotation (`events-YYYY-MM[-N].jsonl`) when `events.jsonl` exceeds 20 MB.
25
+ - `skilltally debug on|off|status` with automatic deletion of `debug.jsonl` on `off`.
26
+
27
+ ## [0.2.0] - 2026-11-19
28
+
29
+ ### Added
30
+ - Idempotent `install`, `uninstall` (`--purge`), and `doctor` commands with automatic host config backups and live hook self-test.
31
+ - Claude Code session backfill (`~/.claude/projects/**/*.jsonl`).
32
+ - Multi-platform plugin manifests (`.claude-plugin/`, `.codex-plugin/`, `.agents/plugins/marketplace.json`, `hooks/claude-codex-hooks.json`).
33
+
34
+ ## [0.1.0] - 2026-11-19
35
+
36
+ ### Added
37
+ - Standalone zero-dependency hook tracker (`bin/track.mjs`) and POSIX fast-path wrapper (`hooks/agy-fast-track.sh`) for Antigravity (`plugin.json` + `hooks.json`).
38
+ - Antigravity (including `antigravity-ide`/`antigravity-cli` and `transcript_full.jsonl`) and Codex (including `.jsonl.zst`) backfill parsers.
39
+ - Skill inventory scanner with frontmatter parsing, disabled-state detection, and Context Tax estimation.
40
+ - Core CLI commands: `stats`, `top`, `unused`, `backfill`, `inventory`, `track`, and bundled `skills/skilltally/SKILL.md`.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 112516101106
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,147 @@
1
- # Temporary Holding Version
1
+ # skilltally
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![CI](https://github.com/112516101106/skilltally/actions/workflows/ci.yml/badge.svg)](https://github.com/112516101106/skilltally/actions/workflows/ci.yml)
4
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
5
+ [![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
6
+ [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-success.svg)](package.json)
7
+
8
+ Real-time skill usage tracking via hooks for **Antigravity**, **Claude Code**, **Codex**, and **Gemini CLI** — 100% local, zero dependencies.
9
+
10
+ Find out which agent skills you actually use, and how much context (`KB` / `~tokens/session`) unused skills and plugins cost you on every turn.
11
+
12
+ ## Quick Start
13
+
14
+ ```bash
15
+ # 1. Detect installed agents and register lightweight PostToolUse/AfterTool hooks
16
+ npx skilltally install --dry-run
17
+ npx skilltally install
18
+
19
+ # 2. Import historical sessions from local logs
20
+ npx skilltally backfill
21
+
22
+ # 3. Verify hook registration and run live self-test
23
+ npx skilltally doctor
24
+
25
+ # 4. Inspect usage and unused context tax
26
+ npx skilltally stats --since 30d
27
+ npx skilltally unused --since 90d
28
+ ```
29
+
30
+ Or ask your coding agent directly: *"Which agent skills do I use the most?"*
31
+
32
+ ## Supported Agents
33
+
34
+ | Agent | Real-time hook | History backfill | Plugin / Extension install | Notes |
35
+ |---|---|---|---|---|
36
+ | **Antigravity** | `PostToolUse` (`read_file\|view_file`) | `~/.gemini/antigravity*/brain/` | Native plugin (`plugin.json` + `hooks.json`) | POSIX fast-path skips Node on misses (~7 ms); reads `transcript_full.jsonl` when truncated |
37
+ | **Claude Code** | `PostToolUse` (`Skill\|Read`, `async: true`) | `~/.claude/projects/**/*.jsonl` | `.claude-plugin/plugin.json` | Collapses `Skill` + `Read` calls within 5 s |
38
+ | **Codex** | `PostToolUse` (async) | `~/.codex/{sessions,archived_sessions}/` | `.codex-plugin/plugin.json` | Supports `.jsonl.zst` archives natively on Node `>= 22.15`; approve via `/hooks` |
39
+ | **Gemini CLI** | `AfterTool` (`activate_skill`) | `~/.gemini/tmp/*/chats/*.{json,jsonl}` | `gemini-extension.json` + `install --host gemini` | `timeout: 5000` ms in `~/.gemini/settings.json` |
40
+
41
+ ## Plugin & Skill Installation
42
+
43
+ If you prefer native plugin managers over `npx skilltally install`:
44
+
45
+ - **Antigravity**: Copy or symlink this repository to `~/.gemini/config/plugins/skilltally` (or run `npx skilltally install --host antigravity`).
46
+ - **Claude Code**:
47
+ ```text
48
+ /plugin marketplace add 112516101106/skilltally
49
+ /plugin install skilltally@skilltally
50
+ ```
51
+ - **Codex**:
52
+ ```bash
53
+ codex plugin marketplace add https://github.com/112516101106/skilltally.git
54
+ codex plugin add skilltally@skilltally
55
+ ```
56
+ Run `codex`, open `/hooks`, and trust the `skilltally` `PostToolUse` hook.
57
+ - **Gemini CLI**:
58
+ ```bash
59
+ gemini extensions install https://github.com/112516101106/skilltally
60
+ npx skilltally install --host gemini
61
+ ```
62
+ - **Companion skill only (`skills.sh`)**:
63
+ ```bash
64
+ npx skills add 112516101106/skilltally
65
+ ```
66
+
67
+ ## Example Output
68
+
69
+ ### `skilltally stats --since 30d`
70
+
71
+ ```text
72
+ skilltally — last 30d (2026-10-20 -> 2026-11-19)
73
+ hosts: antigravity 35 · codex 12
74
+
75
+ # skill activations reads last used hosts
76
+ 1 requesting-code-review 8 10 2026-11-12 14:03 antigravity, codex
77
+ 2 systematic-debugging 5 9 2026-11-10 09:41 codex
78
+ 3 agent-browser 3 4 2026-11-05 12:18 antigravity, codex
79
+
80
+ installed: 214 · used: 22 · unused: 192 -> run `skilltally unused`
81
+ ```
82
+
83
+ ### `skilltally unused --since 90d`
84
+
85
+ ```text
86
+ Unused enabled skills — last 90d (2026-08-21 -> 2026-11-19): 192 (48.2 KB ≈ ~12,340 tok/session)
87
+
88
+ plugin:science 47 skills 14.8 KB ~ 3818 tok/session
89
+ alphagenome-atlas-website-links, alphagenome-single-variant-analysis, … (+41)
90
+ personal 47 skills 10.6 KB ~ 2729 tok/session
91
+ architecture-blueprint-generator, auditing-python-security, … (+41)
92
+
93
+ Tip: disabling an unused plugin removes all of its skill descriptions from every session context.
94
+ ```
95
+
96
+ ## CLI Reference
97
+
98
+ | Command | Description | Key flags |
99
+ |---|---|---|
100
+ | `install` | Install hooks for detected hosts (`runtime/track.mjs` + backups) | `--host all\|antigravity\|claude\|codex\|gemini`, `--dry-run`, `--force`, `--json` |
101
+ | `uninstall` | Remove `skilltally` hooks (preserves all other user hooks) | `--host ...`, `--purge`, `--dry-run`, `--json` |
102
+ | `doctor` | Check Node version, hook paths, Codex trust, events, and live self-test | `--json` |
103
+ | `backfill` | Import historical skill reads/invocations from local logs | `--host ...`, `--since DATE`, `--dry-run`, `--json` |
104
+ | `stats` | Usage table sorted by `activations` (unique `session × skill`) | `--since 30d\|all\|YYYY-MM-DD`, `--host`, `--project`, `--by-source`, `--metric reads`, `--json` |
105
+ | `top` | Top `N` skills | `-n 20`, plus `stats` flags |
106
+ | `unused` | Enabled installed skills with 0 activations and Context Tax breakdown | `--since 90d`, `--host`, `--all`, `--json` |
107
+ | `timeline` | ASCII usage bar chart over time | `--skill <name>`, `--by day\|week\|month`, `--since`, `--host`, `--project`, `--json` |
108
+ | `export` | Export deduplicated events as JSON or RFC-4180 CSV | `--format json\|csv`, `-o <file>`, `--since`, `--host`, `--project`, `--include-failed` |
109
+ | `inventory` | List installed skills, sources, hosts, enabled state, and description sizes | `--no-project`, `--json` |
110
+ | `debug` | Toggle opt-in raw stdin logging (`on \| off \| status`) | `--json` |
111
+
112
+ ## Privacy, Performance & Reliability
113
+
114
+ - **100% local, zero telemetry**: Zero network requests, zero third-party runtime dependencies.
115
+ - **No raw arguments stored**: Only the matched `SKILL.md` path (or `Skill`/`activate_skill` name) and `basename(cwd)` are written to `~/.skilltally/` (`0700` dir, `0600` files). Full `cwd` is omitted unless `store_cwd: true` is set in `~/.skilltally/config.json`.
116
+ - **Safe by contract**: `track.mjs` never throws, always exits `0`, and always writes `{}` to `stdout` so hooks never interrupt an agent turn.
117
+ - **Automatic rotation**: When `events.jsonl` exceeds 20 MB, it rotates automatically to `events-YYYY-MM.jsonl` while reports transparently read all archives.
118
+ - **Config backups**: `install` and `uninstall` back up modified host configs to `~/.skilltally/backups/`.
119
+
120
+ ### Configuration (`~/.skilltally/config.json`)
121
+
122
+ ```json
123
+ {
124
+ "exclude_skills": ["skilltally"],
125
+ "exclude_sources": [],
126
+ "aliases": { "native_swarm": "swarm" },
127
+ "store_cwd": false
128
+ }
129
+ ```
130
+
131
+ ## Troubleshooting
132
+
133
+ - **No events recorded?** Run `npx skilltally doctor` to verify hook paths and run the live pipe self-test.
134
+ - **Codex hooks not firing?** Run `codex` and open `/hooks` to review and trust the `skilltally` `PostToolUse` hook.
135
+ - **Gemini CLI hooks disabled?** Check `"hooksConfig": { "enabled": true }` in `~/.gemini/settings.json`.
136
+ - **Inspecting unknown hook payloads:** Temporarily run `npx skilltally debug on`, trigger a skill once, inspect `~/.skilltally/debug.jsonl`, then run `npx skilltally debug off` (which deletes `debug.jsonl` automatically).
137
+
138
+ ## Development
139
+
140
+ ```bash
141
+ npm test
142
+ npm run check:pack
143
+ ```
144
+
145
+ ## License
146
+
147
+ MIT — [112516101106/skilltally](https://github.com/112516101106/skilltally)
package/bin/cli.mjs ADDED
@@ -0,0 +1,321 @@
1
+ #!/usr/bin/env node
2
+ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
3
+ import { dirname, join } from 'node:path';
4
+ import { fileURLToPath } from 'node:url';
5
+ import { parseArgs } from 'node:util';
6
+ import { runBackfill } from '../src/backfill/index.mjs';
7
+ import { getHomeDir, loadConfig } from '../src/core/config.mjs';
8
+ import { getDebugStatus, setDebugMode } from '../src/core/debug.mjs';
9
+ import { readAllEvents } from '../src/core/store.mjs';
10
+ import { runDoctor } from '../src/install/doctor.mjs';
11
+ import { runInstall, runUninstall } from '../src/install/index.mjs';
12
+ import { scanInventory } from '../src/inventory/scan.mjs';
13
+ import { aggregateStats, parseSince } from '../src/report/aggregate.mjs';
14
+ import { exportEvents } from '../src/report/export.mjs';
15
+ import {
16
+ formatBackfill,
17
+ formatDebug,
18
+ formatDoctor,
19
+ formatInstall,
20
+ formatInventory,
21
+ formatStats,
22
+ formatTimeline,
23
+ formatUninstall,
24
+ formatUnused,
25
+ } from '../src/report/format.mjs';
26
+ import { buildTimeline } from '../src/report/timeline.mjs';
27
+ import { main as runTrack } from './track.mjs';
28
+
29
+ const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
30
+
31
+ function getVersion() {
32
+ try {
33
+ return JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8')).version;
34
+ } catch {
35
+ return '1.0.0';
36
+ }
37
+ }
38
+
39
+ function printHelp() {
40
+ console.log(`skilltally v${getVersion()} — Local skill usage analytics across Antigravity, Claude Code, Codex & Gemini CLI
41
+
42
+ Usage:
43
+ skilltally install [--host all|antigravity|claude|codex|gemini] [--dry-run] [--force] [--json]
44
+ skilltally uninstall [--host all|antigravity|claude|codex|gemini] [--purge] [--dry-run] [--json]
45
+ skilltally doctor [--json]
46
+ skilltally stats [--since 30d|all|YYYY-MM-DD] [--host <h>] [--project <p>] [--by-source] [--metric activations|reads] [--json]
47
+ skilltally top [-n 20] [--since 30d] [--host <h>] [--project <p>] [--by-source] [--metric activations|reads] [--json]
48
+ skilltally unused [--since 90d] [--host <h>] [--all] [--json]
49
+ skilltally timeline [--skill <name>] [--by day|week|month] [--since 30d|all] [--host <h>] [--project <p>] [--json]
50
+ skilltally export [--format json|csv] [-o <file>] [--since all|30d] [--host <h>] [--project <p>] [--include-failed]
51
+ skilltally backfill [--host all|antigravity|codex|claude|gemini] [--since DATE] [--dry-run] [--json]
52
+ skilltally inventory [--no-project] [--json]
53
+ skilltally debug [on|off|status] [--json]
54
+ skilltally track --host <antigravity|claude|codex|gemini|auto>
55
+
56
+ Options:
57
+ -h, --help Show this help
58
+ -v, --version Show version`);
59
+ }
60
+
61
+ function parseCliFlags(argv) {
62
+ return parseArgs({
63
+ args: argv,
64
+ allowPositionals: true,
65
+ strict: false,
66
+ options: {
67
+ help: { type: 'boolean', short: 'h', default: false },
68
+ version: { type: 'boolean', short: 'v', default: false },
69
+ since: { type: 'string' },
70
+ host: { type: 'string' },
71
+ project: { type: 'string' },
72
+ skill: { type: 'string' },
73
+ by: { type: 'string' },
74
+ format: { type: 'string' },
75
+ output: { type: 'string', short: 'o' },
76
+ metric: { type: 'string', default: 'activations' },
77
+ limit: { type: 'string', short: 'n' },
78
+ 'by-source': { type: 'boolean', default: false },
79
+ json: { type: 'boolean', default: false },
80
+ 'dry-run': { type: 'boolean', default: false },
81
+ all: { type: 'boolean', default: false },
82
+ 'no-project': { type: 'boolean', default: false },
83
+ 'include-failed': { type: 'boolean', default: false },
84
+ purge: { type: 'boolean', default: false },
85
+ force: { type: 'boolean', default: false },
86
+ },
87
+ });
88
+ }
89
+
90
+ function run() {
91
+ const argv = process.argv.slice(2);
92
+ const sub = argv[0] && !argv[0].startsWith('-') ? argv[0] : null;
93
+
94
+ if (sub === 'track') {
95
+ try {
96
+ runTrack();
97
+ } catch {}
98
+ process.stdout.write('{}');
99
+ process.exit(0);
100
+ }
101
+
102
+ const { values, positionals } = parseCliFlags(sub ? argv.slice(1) : argv);
103
+
104
+ if (values.version) {
105
+ console.log(getVersion());
106
+ return;
107
+ }
108
+
109
+ if (values.help || !sub) {
110
+ printHelp();
111
+ return;
112
+ }
113
+
114
+ const dataHome = getHomeDir();
115
+ const config = loadConfig(dataHome);
116
+
117
+ if (sub === 'install') {
118
+ const res = runInstall({
119
+ dataHome,
120
+ pkgRoot: pkgDir,
121
+ host: values.host || 'all',
122
+ dryRun: Boolean(values['dry-run']),
123
+ force: Boolean(values.force),
124
+ });
125
+ if (values.json) {
126
+ console.log(JSON.stringify(res, null, 2));
127
+ } else {
128
+ console.log(formatInstall(res));
129
+ }
130
+ if (res.exitCode) process.exitCode = res.exitCode;
131
+ return;
132
+ }
133
+
134
+ if (sub === 'uninstall') {
135
+ const res = runUninstall({
136
+ dataHome,
137
+ host: values.host || 'all',
138
+ purge: Boolean(values.purge),
139
+ dryRun: Boolean(values['dry-run']),
140
+ });
141
+ if (values.json) {
142
+ console.log(JSON.stringify(res, null, 2));
143
+ } else {
144
+ console.log(formatUninstall(res));
145
+ }
146
+ return;
147
+ }
148
+
149
+ if (sub === 'doctor') {
150
+ const report = runDoctor({ dataHome, pkgRoot: pkgDir });
151
+ if (values.json) {
152
+ console.log(JSON.stringify(report, null, 2));
153
+ } else {
154
+ console.log(formatDoctor(report));
155
+ }
156
+ if (!report.ok) process.exitCode = 1;
157
+ return;
158
+ }
159
+
160
+ if (sub === 'debug') {
161
+ const action = (positionals[0] || 'status').toLowerCase();
162
+ let status;
163
+ if (action === 'on') {
164
+ status = setDebugMode(dataHome, true);
165
+ } else if (action === 'off') {
166
+ status = setDebugMode(dataHome, false);
167
+ } else if (action === 'status') {
168
+ status = getDebugStatus(dataHome);
169
+ } else {
170
+ throw new Error(`Invalid debug action "${action}" (expected: on, off, status)`);
171
+ }
172
+ if (values.json) {
173
+ console.log(JSON.stringify(status, null, 2));
174
+ } else {
175
+ console.log(formatDebug(status));
176
+ }
177
+ return;
178
+ }
179
+
180
+ if (sub === 'backfill') {
181
+ const sinceDate = values.since ? parseSince(values.since) : null;
182
+ const summary = runBackfill({
183
+ dataHome,
184
+ host: values.host || 'all',
185
+ since: sinceDate,
186
+ dryRun: Boolean(values['dry-run']),
187
+ });
188
+ if (values.json) {
189
+ console.log(JSON.stringify(summary, null, 2));
190
+ } else {
191
+ console.log(formatBackfill(summary));
192
+ }
193
+ return;
194
+ }
195
+
196
+ if (sub === 'inventory') {
197
+ const inv = scanInventory({ includeProject: !values['no-project'] });
198
+ if (values.json) {
199
+ console.log(JSON.stringify(inv.skills, null, 2));
200
+ } else {
201
+ console.log(formatInventory(inv));
202
+ }
203
+ return;
204
+ }
205
+
206
+ if (sub === 'timeline') {
207
+ const since = values.since ?? '30d';
208
+ const by = values.by ?? 'day';
209
+ const { events } = readAllEvents(dataHome);
210
+ const inventory = scanInventory({ includeProject: true });
211
+ const timeline = buildTimeline({
212
+ events,
213
+ inventory,
214
+ config,
215
+ skill: values.skill || null,
216
+ by,
217
+ since,
218
+ host: values.host || null,
219
+ project: values.project || null,
220
+ });
221
+ if (values.json) {
222
+ console.log(JSON.stringify(timeline, null, 2));
223
+ } else {
224
+ console.log(formatTimeline(timeline));
225
+ }
226
+ return;
227
+ }
228
+
229
+ if (sub === 'export') {
230
+ const since = values.since ?? 'all';
231
+ const format = values.format ?? 'json';
232
+ const { events } = readAllEvents(dataHome);
233
+ const inventory = scanInventory({ includeProject: true });
234
+ const out = exportEvents({
235
+ events,
236
+ inventory,
237
+ config,
238
+ format,
239
+ since,
240
+ host: values.host || null,
241
+ project: values.project || null,
242
+ includeFailed: Boolean(values['include-failed']),
243
+ });
244
+ if (values.output) {
245
+ mkdirSync(dirname(values.output), { recursive: true });
246
+ writeFileSync(values.output, out.content, 'utf8');
247
+ console.log(`Exported ${out.count} ${out.format.toUpperCase()} event(s) to ${values.output}`);
248
+ } else {
249
+ process.stdout.write(out.content);
250
+ }
251
+ return;
252
+ }
253
+
254
+ if (sub === 'stats' || sub === 'top') {
255
+ const since = values.since ?? '30d';
256
+ const limit = values.limit !== undefined ? Number(values.limit) : sub === 'top' ? 20 : null;
257
+ if (limit !== null && (!Number.isFinite(limit) || limit < 1)) {
258
+ throw new Error(`Invalid -n/--limit value: "${values.limit}"`);
259
+ }
260
+ const metric = values.metric === 'reads' ? 'reads' : 'activations';
261
+ const { events, corruptLines } = readAllEvents(dataHome);
262
+ const inventory = scanInventory({ includeProject: true });
263
+ const report = aggregateStats({
264
+ events,
265
+ inventory,
266
+ config,
267
+ since,
268
+ host: values.host || null,
269
+ project: values.project || null,
270
+ bySource: Boolean(values['by-source']),
271
+ metric,
272
+ });
273
+ if (values.json) {
274
+ console.log(JSON.stringify({ ...report, corruptLines }, null, 2));
275
+ } else {
276
+ console.log(
277
+ formatStats(report, {
278
+ limit,
279
+ heading: sub === 'top' ? `skilltally top ${limit}` : 'skilltally',
280
+ bySource: Boolean(values['by-source']),
281
+ })
282
+ );
283
+ if (corruptLines > 0) {
284
+ console.error(`Warning: ignored ${corruptLines} malformed event line(s) in ${dataHome}`);
285
+ }
286
+ }
287
+ return;
288
+ }
289
+
290
+ if (sub === 'unused') {
291
+ const since = values.since ?? '90d';
292
+ const { events } = readAllEvents(dataHome);
293
+ const inventory = scanInventory({ includeProject: true });
294
+ const report = aggregateStats({
295
+ events,
296
+ inventory,
297
+ config,
298
+ since,
299
+ host: values.host || null,
300
+ });
301
+ if (values.json) {
302
+ console.log(
303
+ JSON.stringify({ window: report.window, inventory: report.inventory, unused: report.unused }, null, 2)
304
+ );
305
+ } else {
306
+ console.log(formatUnused(report, { showAll: Boolean(values.all) }));
307
+ }
308
+ return;
309
+ }
310
+
311
+ console.error(`Unknown command: "${sub}"\n`);
312
+ printHelp();
313
+ process.exitCode = 1;
314
+ }
315
+
316
+ try {
317
+ run();
318
+ } catch (err) {
319
+ console.error(`Error: ${err.message}`);
320
+ process.exitCode = 1;
321
+ }