@osovv/vv-opencode 1.2.10 → 1.3.0

package/dist/lib/analytics/metrics.js

@@ -0,0 +1,162 @@
+// FILE: src/lib/analytics/metrics.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Pure analytics dedupe, filtering, grouping, metric computation, and CLI formatting helpers with UTC-deterministic time buckets.
+//   SCOPE: Last-write-wins dedupe by partID, ISO week bucketing, group key extraction, token-weighted cache hit rate and coverage, inclusive range/project filters, relative and absolute date parsing, and compact display formatting.
+//   DEPENDS: [src/lib/analytics/types.ts]
+//   LINKS: [M-ANALYTICS-TYPES, M-CLI-ANALYTICS, M-TUI-ANALYTICS-INDICATOR]
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   dedupeUsageRecords - Keeps the last occurrence of each partID in array order.
+//   isoWeekKey - ISO week key "YYYY-Wnn" for a UTC timestamp.
+//   groupKeyOf - Group key extraction for a usage record.
+//   computeGroupedMetrics - Aggregates deduped usage records into per-group metrics.
+//   UsageFilter - Inclusive date-range and project-substring filter shape.
+//   filterUsageRecords - Applies inclusive date-range and project-substring filters.
+//   parseSinceUntil - Parses relative and absolute --since/--until values.
+//   formatTokenCount - Compact human token count formatting.
+//   formatHitRate - Percentage or "n/a" formatting for nullable hit rates.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [2026-08-19-cache-hit-rate-analytics - Added pure analytics metrics and formatting helpers.]
+// END_CHANGE_SUMMARY
+const DAY_MS = 86_400_000;
+// START_BLOCK_DEDUPE
+/** Keeps only the last occurrence of each partID in array order (last-write-wins). */
+export function dedupeUsageRecords(records) {
+    const byPart = new Map();
+    for (const record of records)
+        byPart.set(record.partID, record);
+    return [...byPart.values()];
+}
+// END_BLOCK_DEDUPE
+// START_BLOCK_TIME_BUCKETS
+/** ISO week key "YYYY-Wnn" for a UTC timestamp. */
+export function isoWeekKey(ts) {
+    const date = new Date(ts);
+    const dayNr = (date.getUTCDay() + 6) % 7;
+    date.setUTCDate(date.getUTCDate() - dayNr + 3);
+    const year = date.getUTCFullYear();
+    const firstThursday = new Date(Date.UTC(year, 0, 4));
+    const firstDayNr = (firstThursday.getUTCDay() + 6) % 7;
+    firstThursday.setUTCDate(firstThursday.getUTCDate() - firstDayNr + 3);
+    const week = 1 + Math.round((date.getTime() - firstThursday.getTime()) / (7 * DAY_MS));
+    return `${year}-W${String(week).padStart(2, "0")}`;
+}
+/** Group key extraction; day/week/month buckets are UTC-based. */
+export function groupKeyOf(record, groupBy) {
+    switch (groupBy) {
+        case "session":
+            return record.sessionID;
+        case "day":
+            return record.ts.slice(0, 10);
+        case "week":
+            return isoWeekKey(record.ts);
+        case "month":
+            return record.ts.slice(0, 7);
+        case "model":
+            return `${record.providerID}/${record.modelID}`;
+        case "provider":
+            return record.providerID;
+        case "project":
+            return record.projectDirectory;
+        case "vvoc":
+            return record.vvocVersion;
+        case "opencode":
+            return record.opencodeVersion;
+    }
+}
+// END_BLOCK_TIME_BUCKETS
+// START_BLOCK_GROUPED_METRICS
+/**
+ * Aggregates usage records into per-group metrics.
+ * hitRate = sum(cacheRead) / sum(cacheRead + cacheWrite + input) over eligible
+ * steps (cacheRead + cacheWrite > 0); null when a group has no eligible steps.
+ */
+export function computeGroupedMetrics(usage, groupBy) {
+    const groups = new Map();
+    for (const record of usage) {
+        const key = groupKeyOf(record, groupBy);
+        const group = groups.get(key) ?? {
+            key,
+            steps: 0,
+            eligibleSteps: 0,
+            coverage: 0,
+            hitRate: null,
+            cacheRead: 0,
+            cacheWrite: 0,
+            input: 0,
+            output: 0,
+            reasoning: 0,
+        };
+        group.steps += 1;
+        group.cacheRead += record.tokens.cacheRead;
+        group.cacheWrite += record.tokens.cacheWrite;
+        group.input += record.tokens.input;
+        group.output += record.tokens.output;
+        group.reasoning += record.tokens.reasoning;
+        if (record.tokens.cacheRead + record.tokens.cacheWrite > 0)
+            group.eligibleSteps += 1;
+        groups.set(key, group);
+    }
+    for (const group of groups.values()) {
+        group.coverage = group.steps > 0 ? group.eligibleSteps / group.steps : 0;
+        const denominator = group.cacheRead + group.cacheWrite + group.input;
+        group.hitRate =
+            group.eligibleSteps > 0 && denominator > 0 ? group.cacheRead / denominator : null;
+    }
+    return [...groups.values()];
+}
+/** Applies inclusive date-range and project-substring filters. */
+export function filterUsageRecords(usage, filter) {
+    const untilUpper = filter.until ? `${filter.until}T23:59:59.999Z` : undefined;
+    const needle = filter.project?.toLowerCase();
+    return usage.filter((record) => {
+        if (filter.since && record.ts < `${filter.since}T00:00:00.000Z`)
+            return false;
+        if (untilUpper && record.ts > untilUpper)
+            return false;
+        if (needle && !record.projectDirectory.toLowerCase().includes(needle))
+            return false;
+        return true;
+    });
+}
+/**
+ * Parses a --since/--until value. Relative "Nd"/"Nw"/"Nm" resolve against `now`
+ * as a UTC date string; absolute "YYYY-MM-DD" passes through. Returns undefined
+ * for undefined input and null for unparseable input.
+ */
+export function parseSinceUntil(raw, now) {
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim().toLowerCase();
+    const relative = /^(\d+)([dwm])$/.exec(trimmed);
+    if (relative) {
+        const amount = Number(relative[1]);
+        const unitMs = relative[2] === "d" ? DAY_MS : relative[2] === "w" ? 7 * DAY_MS : 30 * DAY_MS;
+        return new Date(now.getTime() - amount * unitMs).toISOString().slice(0, 10);
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(trimmed))
+        return trimmed;
+    return null;
+}
+// END_BLOCK_FILTERS
+// START_BLOCK_FORMATTERS
+/** Compact human token count: 999 -> "999"; 1234 -> "1.2k"; 2100000 -> "2.1M". */
+export function formatTokenCount(value) {
+    if (value < 1000)
+        return String(value);
+    if (value < 1_000_000)
+        return `${(value / 1000).toFixed(1)}k`;
+    return `${(value / 1_000_000).toFixed(1)}M`;
+}
+/** "n/a" for null; otherwise a percentage with one decimal. */
+export function formatHitRate(rate) {
+    return rate === null ? "n/a" : `${(rate * 100).toFixed(1)}%`;
+}
+// END_BLOCK_FORMATTERS
+//# sourceMappingURL=metrics.js.map

package/dist/lib/analytics/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../../src/lib/analytics/metrics.ts"],"names":[],"mappings":"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"}

package/dist/lib/analytics/store.d.ts

@@ -0,0 +1,20 @@
+import type { AnalyticsRecord } from "./types.js";
+/** Resolves the analytics store directory inside the global vvoc data root. */
+export declare function getAnalyticsDir(dataHomeOverride?: string): string;
+/** Monthly file name for a record timestamp: usage-YYYY-MM.jsonl. */
+export declare function resolveAnalyticsFileName(ts: string): string;
+/**
+ * Appends one record as a JSON line to the monthly file.
+ * Creates the analytics directory when missing; never rewrites existing lines.
+ */
+export declare function appendAnalyticsRecord(record: AnalyticsRecord, options?: {
+    dataHomeOverride?: string;
+}): Promise<void>;
+/**
+ * Reads every usage-*.jsonl file (sorted by file name ascending) and returns
+ * parsed records in file-then-line order. Empty and unparsable lines are
+ * skipped without failing. A missing directory returns an empty array.
+ */
+export declare function readAnalyticsRecords(options?: {
+    dataHomeOverride?: string;
+}): Promise<AnalyticsRecord[]>;

package/dist/lib/analytics/store.js

@@ -0,0 +1,81 @@
+// FILE: src/lib/analytics/store.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Append-only monthly JSONL persistence for analytics records under the global vvoc data root.
+//   SCOPE: Analytics directory resolution, monthly file naming, record appending with idempotent directory creation, and tolerant chronological reads.
+//   DEPENDS: [node:fs/promises, node:path, src/lib/vvoc-paths.ts, src/lib/analytics/types.ts]
+//   LINKS: [M-ANALYTICS-TYPES, M-PLUGIN-ANALYTICS, M-CLI-ANALYTICS]
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   getAnalyticsDir - Resolves the analytics store directory inside the global vvoc data root.
+//   resolveAnalyticsFileName - Monthly file name for a record timestamp.
+//   appendAnalyticsRecord - Appends one record as a JSON line to the monthly file.
+//   readAnalyticsRecords - Reads all usage-*.jsonl records in tolerant chronological order.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [2026-08-19-cache-hit-rate-analytics - Added append-only monthly JSONL analytics store.]
+// END_CHANGE_SUMMARY
+import { appendFile, mkdir, readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getGlobalVvocDataDir } from "../vvoc-paths.js";
+const ANALYTICS_FILE_PATTERN = /^usage-\d{4}-\d{2}\.jsonl$/;
+// START_BLOCK_ANALYTICS_DIR
+/** Resolves the analytics store directory inside the global vvoc data root. */
+export function getAnalyticsDir(dataHomeOverride) {
+    return join(getGlobalVvocDataDir(dataHomeOverride), "analytics");
+}
+/** Monthly file name for a record timestamp: usage-YYYY-MM.jsonl. */
+export function resolveAnalyticsFileName(ts) {
+    return `usage-${ts.slice(0, 7)}.jsonl`;
+}
+// END_BLOCK_ANALYTICS_DIR
+// START_BLOCK_ANALYTICS_APPEND
+/**
+ * Appends one record as a JSON line to the monthly file.
+ * Creates the analytics directory when missing; never rewrites existing lines.
+ */
+export async function appendAnalyticsRecord(record, options = {}) {
+    const dir = getAnalyticsDir(options.dataHomeOverride);
+    await mkdir(dir, { recursive: true });
+    const file = join(dir, resolveAnalyticsFileName(record.ts));
+    await appendFile(file, `${JSON.stringify(record)}\n`, "utf8");
+}
+// END_BLOCK_ANALYTICS_APPEND
+// START_BLOCK_ANALYTICS_READ
+/**
+ * Reads every usage-*.jsonl file (sorted by file name ascending) and returns
+ * parsed records in file-then-line order. Empty and unparsable lines are
+ * skipped without failing. A missing directory returns an empty array.
+ */
+export async function readAnalyticsRecords(options = {}) {
+    const dir = getAnalyticsDir(options.dataHomeOverride);
+    let files;
+    try {
+        files = (await readdir(dir)).filter((name) => ANALYTICS_FILE_PATTERN.test(name)).sort();
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const file of files) {
+        const text = await readFile(join(dir, file), "utf8");
+        for (const line of text.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                records.push(JSON.parse(trimmed));
+            }
+            catch {
+                // Corrupt or partially written line: skip.
+            }
+        }
+    }
+    return records;
+}
+// END_BLOCK_ANALYTICS_READ
+//# sourceMappingURL=store.js.map

package/dist/lib/analytics/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/lib/analytics/store.ts"],"names":[],"mappings":"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"}

package/dist/lib/analytics/types.d.ts

@@ -0,0 +1,67 @@
+/** Token counters for one completed model step. All values are non-negative integers. */
+export type UsageTokens = {
+    /** Fresh (uncached) input tokens reported by the provider. */
+    input: number;
+    /** Output tokens as reported by the provider. */
+    output: number;
+    /** Reasoning tokens reported separately by the provider. */
+    reasoning: number;
+    /** Tokens served from the provider prompt cache. */
+    cacheRead: number;
+    /** Tokens written into the provider prompt cache this step. */
+    cacheWrite: number;
+};
+/** One persisted step-finish observation. Readers dedupe by partID last-write-wins. */
+export type UsageRecord = {
+    kind: "usage";
+    /** ISO timestamp of the observation (event delivery time, UTC). */
+    ts: string;
+    projectID: string;
+    projectDirectory: string;
+    sessionID: string;
+    messageID: string;
+    partID: string;
+    providerID: string;
+    modelID: string;
+    agent: string;
+    tokens: UsageTokens;
+    /** Cost recorded by OpenCode for the step; 0 when unrecorded. */
+    cost: number;
+    vvocVersion: string;
+    /** Best-effort OpenCode version; "unknown" when unresolved. */
+    opencodeVersion: string;
+};
+/** Latest known session metadata. Readers dedupe by sessionID last-write-wins. */
+export type SessionRecord = {
+    kind: "session";
+    ts: string;
+    sessionID: string;
+    projectID: string;
+    title: string;
+};
+export type AnalyticsRecord = UsageRecord | SessionRecord;
+/** Grouping keys supported by `vvoc analytics cache-hit-rate --group-by`. */
+export type AnalyticsGroupKey = "session" | "day" | "week" | "month" | "model" | "provider" | "project" | "vvoc" | "opencode";
+/** Aggregated metrics for one group. hitRate is null when no eligible steps exist. */
+export type GroupedMetrics = {
+    key: string;
+    steps: number;
+    eligibleSteps: number;
+    /** eligibleSteps / steps; 0 when steps === 0. */
+    coverage: number;
+    /** Token-weighted cache hit rate over eligible steps; null when eligibleSteps === 0. */
+    hitRate: number | null;
+    cacheRead: number;
+    cacheWrite: number;
+    input: number;
+    output: number;
+    reasoning: number;
+};
+/** Rolling per-session sums used by the live TUI indicator. */
+export type IndicatorTokens = {
+    steps: number;
+    eligibleSteps: number;
+    cacheRead: number;
+    cacheWrite: number;
+    input: number;
+};

package/dist/lib/analytics/types.js

@@ -0,0 +1,26 @@
+// FILE: src/lib/analytics/types.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Define the canonical analytics record and metric types shared by the store, metrics, server plugin, CLI, and TUI indicator.
+//   SCOPE: Usage/session persistence record shapes, grouping keys, grouped metric aggregation shape, and indicator token counters.
+//   DEPENDS: [none]
+//   LINKS: [M-ANALYTICS-STORE, M-ANALYTICS-METRICS, M-PLUGIN-ANALYTICS, M-CLI-ANALYTICS, M-TUI-ANALYTICS-INDICATOR]
+//   ROLE: TYPES
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   UsageTokens - Token counters for one completed model step.
+//   UsageRecord - One persisted step-finish observation deduped by partID last-write-wins.
+//   SessionRecord - Latest known session metadata deduped by sessionID last-write-wins.
+//   AnalyticsRecord - Union of persistable analytics record kinds.
+//   AnalyticsGroupKey - Grouping keys supported by the analytics CLI.
+//   GroupedMetrics - Aggregated metrics for one group with nullable hit rate.
+//   IndicatorTokens - Rolling per-session sums used by the live TUI indicator.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [2026-08-19-cache-hit-rate-analytics - Added canonical analytics record and metric types.]
+// END_CHANGE_SUMMARY
+export {};
+//# sourceMappingURL=types.js.map

package/dist/lib/analytics/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/analytics/types.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,iBAAiB;AACjB,wBAAwB;AACxB,yIAAyI;AACzI,mIAAmI;AACnI,oBAAoB;AACpB,oHAAoH;AACpH,gBAAgB;AAChB,sBAAsB;AACtB,sBAAsB;AACtB,EAAE;AACF,mBAAmB;AACnB,+DAA+D;AAC/D,2FAA2F;AAC3F,wFAAwF;AACxF,mEAAmE;AACnE,sEAAsE;AACtE,8EAA8E;AAC9E,+EAA+E;AAC/E,iBAAiB;AACjB,EAAE;AACF,uBAAuB;AACvB,4GAA4G;AAC5G,qBAAqB"}

package/dist/lib/managed-skills.d.ts

@@ -1,4 +1,4 @@
-export declare const MANAGED_SKILL_NAMES: readonly ["vv-spec", "vv-plan", "vv-review", "vv-execute", "vv-reflect", "vv-handoff"];
+export declare const MANAGED_SKILL_NAMES: readonly ["vv-spec", "vv-plan", "vv-review", "vv-execute", "vv-reflect", "vv-handoff", "vvoc-usage-analytics"];
 export type ManagedSkillName = (typeof MANAGED_SKILL_NAMES)[number];
 export declare function getManagedSkillFilePath(skillsDirPath: string, name: ManagedSkillName): string;
 export declare function loadManagedSkillTemplate(name: ManagedSkillName): Promise<string>;

package/dist/lib/managed-skills.js

@@ -10,7 +10,7 @@
 // END_MODULE_CONTRACT
 //
 // START_MODULE_MAP
-//   MANAGED_SKILL_NAMES - Canonical vvoc-managed skill names, including vv-reflect and vv-handoff.
+//   MANAGED_SKILL_NAMES - Canonical vvoc-managed skill names: vv-* work-protocol skills plus vvoc-* tooling skills.
 //   ManagedSkillName - Type for vvoc-managed skill names.
 //   getManagedSkillFilePath - Resolves the skill file path inside a vvoc skills directory.
 //   loadManagedSkillTemplate - Loads the bundled skill template for a managed skill.
@@ -20,7 +20,7 @@
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v0.5.3 - Added vv-handoff to the canonical managed skill set.]
+//   LAST_CHANGE: [2026-08-19-usage-analytics-skill - Added the vvoc-usage-analytics tooling skill (first vvoc-* managed skill).]
 // END_CHANGE_SUMMARY
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -32,6 +32,7 @@ export const MANAGED_SKILL_NAMES = [
     "vv-execute",
     "vv-reflect",
     "vv-handoff",
+    "vvoc-usage-analytics",
 ];
 export function getManagedSkillFilePath(skillsDirPath, name) {
     return join(skillsDirPath, name, "SKILL.md");

package/dist/lib/managed-skills.js.map

@@ -1 +1 @@
-{"version":3,"file":"managed-skills.js","sourceRoot":"","sources":["../../src/lib/managed-skills.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"managed-skills.js","sourceRoot":"","sources":["../../src/lib/managed-skills.ts"],"names":[],"mappings":"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"}

package/dist/lib/opencode.d.ts

@@ -157,6 +157,8 @@ export declare function inspectOpenCodeRuntime(run?: () => Promise<{
     stderr: string;
 }>): Promise<OpenCodeRuntimeInspection>;
 export declare function isTuiOpenCodeVersionCompatible(version: string): boolean;
+/** Extracts the first semantic version found in `opencode --version` output. */
+export declare function extractOpenCodeVersion(output: string): string | undefined;
 export declare function inspectInstallation(paths: ResolvedPaths, options?: {
     runtime?: OpenCodeRuntimeInspection;
 }): Promise<InstallationInspection>;

package/dist/lib/opencode.js

@@ -51,6 +51,7 @@
 //   writeManagedAgentModel - Writes or removes a bundled vvoc-managed OpenCode agent model override in OpenCode config.
 //   writeGuardianConfig - Writes the guardian section into the canonical vvoc.json document.
 //   inspectOpenCodeRuntime - Reads the installed OpenCode version and evaluates TUI compatibility.
+//   extractOpenCodeVersion - Extracts the first semantic version found in `opencode --version` output.
 //   isTuiOpenCodeVersionCompatible - Compares an OpenCode version with the managed TUI minimum.
 //   inspectInstallation - Reads current OpenCode/vvoc installation state for status and doctor commands.
 //   inspectInstallationForScope - Reads installation state using strict/effective layered source resolution.
@@ -64,7 +65,7 @@
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v1.4.0 - Hardened ensureManagedSkillSymlink: a non-symlink at the managed path is treated as user-owned and skipped instead of unlinked, and an already-correct vvoc link is kept rather than recreated.]
+//   LAST_CHANGE: [2026-08-19-cache-hit-rate-analytics - Exported extractOpenCodeVersion for analytics attribution.]
 // END_CHANGE_SUMMARY
 import { applyEdits, format, modify, parse } from "jsonc-parser";
 import { lstat, mkdir, readFile, readlink, symlink, unlink, writeFile } from "node:fs/promises";
@@ -689,7 +690,8 @@ async function runOpenCodeVersionCommand() {
     ]);
     return { exitCode, stdout, stderr };
 }
-function extractOpenCodeVersion(output) {
+/** Extracts the first semantic version found in `opencode --version` output. */
+export function extractOpenCodeVersion(output) {
     const match = output.match(/(?:^|\s)v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)(?=\s|$)/);
     return match?.[1];
 }