fix: align ClaudeCode/Codex/OpenCode/Amp/Pi JSON outputs for scripting

apps/amp/src/commands/daily.ts

@@ -48,11 +48,22 @@ export const dailyCommand = define({
 		const { events } = await loadAmpUsageEvents();
 
 		if (events.length === 0) {
-			const output = jsonOutput
-				? JSON.stringify({ daily: [], totals: null })
-				: 'No Amp usage data found.';
-			// eslint-disable-next-line no-console
-			console.log(output);
+			if (jsonOutput) {
+				const emptyTotals = {
+					inputTokens: 0,
+					outputTokens: 0,
+					cacheCreationTokens: 0,
+					cacheReadTokens: 0,
+					totalTokens: 0,
+					credits: 0,
+					totalCost: 0,
+				};
+				// eslint-disable-next-line no-console
+				console.log(JSON.stringify({ daily: [], totals: emptyTotals }, null, 2));
+			} else {
+				// eslint-disable-next-line no-console
+				console.log('No Amp usage data found.');
+			}
 			return;
 		}
 
@@ -98,7 +109,7 @@ export const dailyCommand = define({
 				modelsSet.add(event.model);
 			}
 
-			const totalTokens = inputTokens + outputTokens;
+			const totalTokens = inputTokens + outputTokens + cacheCreationTokens + cacheReadTokens;
 
 			dailyData.push({
 				date,

apps/amp/src/commands/monthly.ts

@@ -48,11 +48,25 @@ export const monthlyCommand = define({
 		const { events } = await loadAmpUsageEvents();
 
 		if (events.length === 0) {
-			const output = jsonOutput
-				? JSON.stringify({ monthly: [], totals: null })
-				: 'No Amp usage data found.';
-			// eslint-disable-next-line no-console
-			console.log(output);
+			if (jsonOutput) {
+				const emptyOutput = {
+					monthly: [],
+					totals: {
+						inputTokens: 0,
+						outputTokens: 0,
+						cacheCreationTokens: 0,
+						cacheReadTokens: 0,
+						totalTokens: 0,
+						credits: 0,
+						totalCost: 0,
+					},
+				};
+				// eslint-disable-next-line no-console
+				console.log(JSON.stringify(emptyOutput, null, 2));
+			} else {
+				// eslint-disable-next-line no-console
+				console.log('No Amp usage data found.');
+			}
 			return;
 		}
 
@@ -98,7 +112,7 @@ export const monthlyCommand = define({
 				modelsSet.add(event.model);
 			}
 
-			const totalTokens = inputTokens + outputTokens;
+			const totalTokens = inputTokens + outputTokens + cacheCreationTokens + cacheReadTokens;
 
 			monthlyData.push({
 				month,

apps/amp/src/commands/session.ts

@@ -47,11 +47,22 @@ export const sessionCommand = define({
 		const { events, threads } = await loadAmpUsageEvents();
 
 		if (events.length === 0) {
-			const output = jsonOutput
-				? JSON.stringify({ sessions: [], totals: null })
-				: 'No Amp usage data found.';
-			// eslint-disable-next-line no-console
-			console.log(output);
+			if (jsonOutput) {
+				const emptyTotals = {
+					inputTokens: 0,
+					outputTokens: 0,
+					cacheCreationTokens: 0,
+					cacheReadTokens: 0,
+					totalTokens: 0,
+					credits: 0,
+					totalCost: 0,
+				};
+				// eslint-disable-next-line no-console
+				console.log(JSON.stringify({ sessions: [], totals: emptyTotals }, null, 2));
+			} else {
+				// eslint-disable-next-line no-console
+				console.log('No Amp usage data found.');
+			}
 			return;
 		}
 
@@ -104,7 +115,7 @@ export const sessionCommand = define({
 				}
 			}
 
-			const totalTokens = inputTokens + outputTokens;
+			const totalTokens = inputTokens + outputTokens + cacheCreationTokens + cacheReadTokens;
 			const threadInfo = threads.get(threadId);
 
 			sessionData.push({

apps/amp/src/data-loader.ts

@@ -157,7 +157,7 @@ function convertLedgerEventToUsageEvent(
 		outputTokens,
 		cacheCreationInputTokens,
 		cacheReadInputTokens,
-		totalTokens: inputTokens + outputTokens,
+		totalTokens: inputTokens + outputTokens + cacheCreationInputTokens + cacheReadInputTokens,
 	};
 }
 
@@ -330,6 +330,7 @@ if (import.meta.vitest != null) {
 			expect(event.outputTokens).toBe(50);
 			expect(event.cacheCreationInputTokens).toBe(500);
 			expect(event.cacheReadInputTokens).toBe(200);
+			expect(event.totalTokens).toBe(850);
 			expect(event.credits).toBe(1.5);
 
 			expect(threads.get('T-test-thread-123')).toEqual({

apps/ccusage/src/_macro.ts

@@ -13,6 +13,10 @@ function isClaudeModel(modelName: string, _pricing: LiteLLMModelPricing): boolea
 	);
 }
 
+/**
+ * Fetch and cache Claude model pricing data from LiteLLM.
+ * @returns Pricing dataset filtered to Claude models
+ */
 export async function prefetchClaudePricing(): Promise<Record<string, LiteLLMModelPricing>> {
 	try {
 		const dataset = await fetchLiteLLMPricingDataset();

apps/ccusage/src/_types.ts

@@ -12,18 +12,27 @@ export const modelNameSchema = v.pipe(
 	v.brand('ModelName'),
 );
 
+/**
+ * Schema for Claude session identifiers.
+ */
 export const sessionIdSchema = v.pipe(
 	v.string(),
 	v.minLength(1, 'Session ID cannot be empty'),
 	v.brand('SessionId'),
 );
 
+/**
+ * Schema for API request identifiers.
+ */
 export const requestIdSchema = v.pipe(
 	v.string(),
 	v.minLength(1, 'Request ID cannot be empty'),
 	v.brand('RequestId'),
 );
 
+/**
+ * Schema for Claude message identifiers.
+ */
 export const messageIdSchema = v.pipe(
 	v.string(),
 	v.minLength(1, 'Message ID cannot be empty'),
@@ -32,53 +41,77 @@ export const messageIdSchema = v.pipe(
 
 // Date and timestamp schemas
 const isoTimestampRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+/**
+ * Schema for ISO-8601 timestamps stored in usage entries.
+ */
 export const isoTimestampSchema = v.pipe(
 	v.string(),
 	v.regex(isoTimestampRegex, 'Invalid ISO timestamp'),
 	v.brand('ISOTimestamp'),
 );
 
 const yyyymmddRegex = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * Schema for daily usage date keys (YYYY-MM-DD).
+ */
 export const dailyDateSchema = v.pipe(
 	v.string(),
 	v.regex(yyyymmddRegex, 'Date must be in YYYY-MM-DD format'),
 	v.brand('DailyDate'),
 );
 
+/**
+ * Schema for activity date values (YYYY-MM-DD).
+ */
 export const activityDateSchema = v.pipe(
 	v.string(),
 	v.regex(yyyymmddRegex, 'Date must be in YYYY-MM-DD format'),
 	v.brand('ActivityDate'),
 );
 
 const yyyymmRegex = /^\d{4}-\d{2}$/;
+/**
+ * Schema for monthly usage date keys (YYYY-MM).
+ */
 export const monthlyDateSchema = v.pipe(
 	v.string(),
 	v.regex(yyyymmRegex, 'Date must be in YYYY-MM format'),
 	v.brand('MonthlyDate'),
 );
 
+/**
+ * Schema for weekly usage date keys (week start date).
+ */
 export const weeklyDateSchema = v.pipe(
 	v.string(),
 	v.regex(yyyymmddRegex, 'Date must be in YYYY-MM-DD format'),
 	v.brand('WeeklyDate'),
 );
 
 const filterDateRegex = /^\d{8}$/;
+/**
+ * Schema for CLI filter dates in YYYYMMDD format.
+ */
 export const filterDateSchema = v.pipe(
 	v.string(),
 	v.regex(filterDateRegex, 'Date must be in YYYYMMDD format'),
 	v.brand('FilterDate'),
 );
 
 // Other domain-specific schemas
+/**
+ * Schema for local project paths used to group sessions.
+ */
 export const projectPathSchema = v.pipe(
 	v.string(),
 	v.minLength(1, 'Project path cannot be empty'),
 	v.brand('ProjectPath'),
 );
 
 const versionRegex = /^\d+\.\d+\.\d+/;
+/**
+ * Schema for Claude Code version strings.
+ */
 export const versionSchema = v.pipe(
 	v.string(),
 	v.regex(versionRegex, 'Invalid version format'),
@@ -107,22 +140,58 @@ export type Version = v.InferOutput<typeof versionSchema>;
  * These functions should be used when converting plain strings to branded types
  */
 export const createModelName = (value: string): ModelName => v.parse(modelNameSchema, value);
+/**
+ * Parse and brand a session identifier string.
+ */
 export const createSessionId = (value: string): SessionId => v.parse(sessionIdSchema, value);
+/**
+ * Parse and brand a request identifier string.
+ */
 export const createRequestId = (value: string): RequestId => v.parse(requestIdSchema, value);
+/**
+ * Parse and brand a message identifier string.
+ */
 export const createMessageId = (value: string): MessageId => v.parse(messageIdSchema, value);
+/**
+ * Parse and brand an ISO timestamp string.
+ */
 export function createISOTimestamp(value: string): ISOTimestamp {
 	return v.parse(isoTimestampSchema, value);
 }
+/**
+ * Parse and brand a daily date (YYYY-MM-DD).
+ */
 export const createDailyDate = (value: string): DailyDate => v.parse(dailyDateSchema, value);
+/**
+ * Parse and brand an activity date (YYYY-MM-DD).
+ */
 export function createActivityDate(value: string): ActivityDate {
 	return v.parse(activityDateSchema, value);
 }
+/**
+ * Parse and brand a monthly date (YYYY-MM).
+ */
 export const createMonthlyDate = (value: string): MonthlyDate => v.parse(monthlyDateSchema, value);
+/**
+ * Parse and brand a weekly date (week start).
+ */
 export const createWeeklyDate = (value: string): WeeklyDate => v.parse(weeklyDateSchema, value);
+/**
+ * Parse and brand a filter date (YYYYMMDD).
+ */
 export const createFilterDate = (value: string): FilterDate => v.parse(filterDateSchema, value);
+/**
+ * Parse and brand a project path string.
+ */
 export const createProjectPath = (value: string): ProjectPath => v.parse(projectPathSchema, value);
+/**
+ * Parse and brand a Claude Code version string.
+ */
 export const createVersion = (value: string): Version => v.parse(versionSchema, value);
 
+/**
+ * Parse a bucket key into a weekly or monthly date bucket.
+ */
 export function createBucket(value: string): Bucket {
 	const weeklyResult = v.safeParse(weeklyDateSchema, value);
 	if (weeklyResult.success) {

apps/ccusage/src/_utils.ts

@@ -2,6 +2,10 @@ import { stat, utimes, writeFile } from 'node:fs/promises';
 import { Result } from '@praha/byethrow';
 import { createFixture } from 'fs-fixture';
 
+/**
+ * Exhaustive-check helper for unreachable code paths.
+ * @param value - Value that should never occur
+ */
 export function unreachable(value: never): never {
 	throw new Error(`Unreachable code reached with value: ${value as any}`);
 }

apps/ccusage/src/commands/blocks.ts

@@ -117,6 +117,9 @@ function parseTokenLimit(value: string | undefined, maxFromAll: number): number
 	return Number.isNaN(limit) ? undefined : limit;
 }
 
+/**
+ * CLI command for 5-hour billing block reports.
+ */
 export const blocksCommand = define({
 	name: 'blocks',
 	description: 'Show usage report grouped by session billing blocks',

apps/ccusage/src/commands/daily.ts

@@ -21,6 +21,9 @@ import { loadDailyUsageData } from '../data-loader.ts';
 import { detectMismatches, printMismatchReport } from '../debug.ts';
 import { log, logger } from '../logger.ts';
 
+/**
+ * CLI command for daily usage reports.
+ */
 export const dailyCommand = define({
 	name: 'daily',
 	description: 'Show usage report grouped by date',
@@ -82,7 +85,17 @@ export const dailyCommand = define({
 
 		if (dailyData.length === 0) {
 			if (useJson) {
-				log(JSON.stringify([]));
+				const totals = createTotalsObject({
+					inputTokens: 0,
+					outputTokens: 0,
+					cacheCreationTokens: 0,
+					cacheReadTokens: 0,
+					totalCost: 0,
+				});
+				const jsonOutput = mergedOptions.instances
+					? { projects: {}, totals }
+					: { daily: [], totals };
+				log(JSON.stringify(jsonOutput, null, 2));
 			} else {
 				logger.warn('No Claude usage data found.');
 			}

apps/ccusage/src/commands/index.ts

@@ -48,6 +48,9 @@ for (const [name, command] of subCommandUnion) {
  */
 const mainCommand = dailyCommand;
 
+/**
+ * Execute the ccusage CLI with the configured subcommands.
+ */
 export async function run(): Promise<void> {
 	// When invoked through npx, the binary name might be passed as the first argument
 	// Filter it out if it matches the expected binary name

apps/ccusage/src/commands/monthly.ts

@@ -19,6 +19,9 @@ import { loadMonthlyUsageData } from '../data-loader.ts';
 import { detectMismatches, printMismatchReport } from '../debug.ts';
 import { log, logger } from '../logger.ts';
 
+/**
+ * CLI command for monthly usage reports.
+ */
 export const monthlyCommand = define({
 	name: 'monthly',
 	description: 'Show usage report grouped by month',