fix(ccusage): support agent-scoped config schema (#1008)

* fix(ccusage): support agent-scoped config schema

Generate the ccusage JSON schema with top-level agent namespaces so configurations can use claude, codex, opencode, amp, and pi sections with defaults and command overrides.

Merge those agent-scoped settings at runtime for namespaced ccusage subcommands, while preserving legacy Claude top-level defaults and command overrides. Add CLI coverage for Codex config discovery through the main ccusage command.

* fix(ccusage): address agent config review

Reject array values in agent namespace config validation before they can be merged as option keys.

Tighten schema generator token argument typing and cover both spaced and colon-delimited namespaced command parsing in tests.

* fix(ccusage): harden config preset validation

* fix(ccusage): ignore unsafe config option keys

* fix(ccusage): pass agent config into all reports

* fix(ccusage): move schema generation to pre-commit

* docs(ccusage): document agent-scoped config

Author: ryoppippi

apps/ccusage/config-schema.json

@@ -47,7 +47,6 @@
 		"generate:schema": "bun scripts/generate-json-schema.ts",
 		"lint": "eslint --cache .",
 		"prepack": "pnpm run build && clean-pkg-json",
-		"prepare": "pnpm run generate:schema || true",
 		"prerelease": "pnpm run lint && pnpm run typecheck && pnpm run build",
 		"start": "bun ./src/index.ts",
 		"test": "TZ=UTC vitest",

apps/ccusage/package.json

@@ -13,12 +13,11 @@
 import process from 'node:process';
 import { Result } from '@praha/byethrow';
 import { $ } from 'bun';
+import { allArgs } from '../src/commands/all.ts';
 // Import command definitions to access their args
 import { subCommandUnion } from '../src/commands/index.ts';
 import { logger } from '../src/logger.ts';
 
-import { sharedArgs } from '../src/shared-args.ts';
-
 /**
  * The filename for the generated JSON Schema file.
  * Used for both root directory and docs/public directory output.
@@ -39,19 +38,33 @@ const COMMAND_EXCLUDE_KEYS: Record<string, string[]> = {
 	blocks: ['live', 'refreshInterval'],
 };
 
+const AGENT_NAMES = ['claude', 'codex', 'opencode', 'amp', 'pi'] as const;
+type AgentName = (typeof AGENT_NAMES)[number];
+type JsonSchemaNode = {
+	[key: string]: unknown;
+	type?: string;
+	properties?: Record<string, JsonSchemaNode>;
+	definitions?: Record<string, JsonSchemaNode>;
+};
+type TokenDefinition = {
+	[key: string]: unknown;
+	type: string;
+	choices?: readonly unknown[];
+	description?: string;
+	default?: unknown;
+};
+type TokenSchema = Record<string, TokenDefinition>;
+
 /**
  * Convert args-tokens schema to JSON Schema format
  */
-function tokensSchemaToJsonSchema(schema: Record<string, any>): Record<string, any> {
-	const properties: Record<string, any> = {};
+function tokensSchemaToJsonSchema(schema: TokenSchema): JsonSchemaNode {
+	const properties: Record<string, JsonSchemaNode> = {};
 
-	for (const [key, arg] of Object.entries(schema)) {
-		// eslint-disable-next-line ts/no-unsafe-assignment
-		const argTyped = arg;
-		const property: Record<string, any> = {};
+	for (const [key, argTyped] of Object.entries(schema)) {
+		const property: JsonSchemaNode = {};
 
 		// Handle type conversion
-		// eslint-disable-next-line ts/no-unsafe-member-access
 		switch (argTyped.type) {
 			case 'boolean':
 				property.type = 'boolean';
@@ -65,9 +78,7 @@ function tokensSchemaToJsonSchema(schema: Record<string, any>): Record<string, a
 				break;
 			case 'enum':
 				property.type = 'string';
-				// eslint-disable-next-line ts/no-unsafe-member-access
 				if (argTyped.choices != null && Array.isArray(argTyped.choices)) {
-					// eslint-disable-next-line ts/no-unsafe-assignment, ts/no-unsafe-member-access
 					property.enum = argTyped.choices;
 				}
 				break;
@@ -76,18 +87,13 @@ function tokensSchemaToJsonSchema(schema: Record<string, any>): Record<string, a
 		}
 
 		// Add description
-		// eslint-disable-next-line ts/no-unsafe-member-access
 		if (argTyped.description != null) {
-			// eslint-disable-next-line ts/no-unsafe-assignment, ts/no-unsafe-member-access
 			property.description = argTyped.description;
-			// eslint-disable-next-line ts/no-unsafe-assignment, ts/no-unsafe-member-access
 			property.markdownDescription = argTyped.description;
 		}
 
 		// Add default value
-		// eslint-disable-next-line ts/no-unsafe-member-access
 		if ('default' in argTyped && argTyped.default !== undefined) {
-			// eslint-disable-next-line ts/no-unsafe-assignment, ts/no-unsafe-member-access
 			property.default = argTyped.default;
 		}
 
@@ -101,42 +107,116 @@ function tokensSchemaToJsonSchema(schema: Record<string, any>): Record<string, a
 	};
 }
 
-/**
- * Create the complete configuration schema from all command definitions
- */
-function createConfigSchemaJson() {
-	// Create schema for default/shared arguments (excluding CLI-only options)
-	const defaultsSchema = Object.fromEntries(
-		Object.entries(sharedArgs).filter(([key]) => !EXCLUDE_KEYS.includes(key)),
+function splitCommandName(name: string): { agent?: AgentName; report: string } {
+	const [prefix, report] = name.split(':');
+	if (report != null && AGENT_NAMES.includes(prefix as AgentName)) {
+		return { agent: prefix as AgentName, report };
+	}
+	return { report: name };
+}
+
+function filterCommandSchema(report: string, schema: TokenSchema): TokenSchema {
+	const commandExcludes = COMMAND_EXCLUDE_KEYS[report] ?? [];
+	return Object.fromEntries(
+		Object.entries(schema).filter(
+			([key]) => !EXCLUDE_KEYS.includes(key) && !commandExcludes.includes(key),
+		),
 	);
+}
 
-	// Create schemas for each command's specific arguments (excluding CLI-only options)
-	const commandSchemas: Record<string, any> = {};
-	for (const [commandName, command] of subCommandUnion) {
-		const commandExcludes = COMMAND_EXCLUDE_KEYS[commandName] ?? [];
-		commandSchemas[commandName] = Object.fromEntries(
-			Object.entries(command.args as Record<string, any>).filter(
-				([key]) => !EXCLUDE_KEYS.includes(key) && !commandExcludes.includes(key),
-			),
-		);
+function commonSchemaProperties(commandSchemas: Record<string, TokenSchema>): TokenSchema {
+	const schemas = Object.values(commandSchemas);
+	const firstSchema = schemas[0];
+	if (firstSchema == null) {
+		return {};
 	}
+	const restSchemas = schemas.slice(1);
+	return Object.fromEntries(
+		Object.entries(firstSchema).filter(([key]) =>
+			restSchemas.every((schema) => Object.hasOwn(schema, key)),
+		),
+	);
+}
 
-	// Convert to JSON Schema format
-
-	const defaultsJsonSchema = tokensSchemaToJsonSchema(defaultsSchema);
-	const commandsJsonSchema = {
+function createCommandsJsonSchema(
+	commandSchemas: Record<string, TokenSchema>,
+	description: string,
+): JsonSchemaNode {
+	return {
 		type: 'object',
 		properties: Object.fromEntries(
 			Object.entries(commandSchemas).map(([name, schema]) => [
 				name,
-				// eslint-disable-next-line ts/no-unsafe-argument
 				tokensSchemaToJsonSchema(schema),
 			]),
 		),
 		additionalProperties: false,
-		description: 'Command-specific configuration overrides',
-		markdownDescription: 'Command-specific configuration overrides',
+		description,
+		markdownDescription: description,
+	};
+}
+
+function createAgentJsonSchema(
+	agentName: AgentName,
+	commandSchemas: Record<string, TokenSchema>,
+): JsonSchemaNode {
+	const agentLabel = agentName === 'pi' ? 'pi-agent' : agentName;
+	return {
+		type: 'object',
+		properties: {
+			defaults: {
+				...tokensSchemaToJsonSchema(commonSchemaProperties(commandSchemas)),
+				description: `Default values for ${agentLabel} commands`,
+				markdownDescription: `Default values for ${agentLabel} commands`,
+			},
+			commands: createCommandsJsonSchema(
+				commandSchemas,
+				`Command-specific configuration overrides for ${agentLabel}`,
+			),
+		},
+		additionalProperties: false,
+		description: `${agentLabel} command configuration`,
+		markdownDescription: `${agentLabel} command configuration`,
 	};
+}
+
+/**
+ * Create the complete configuration schema from all command definitions
+ */
+function createConfigSchemaJson(): JsonSchemaNode {
+	const topLevelCommandSchemas: Record<string, TokenSchema> = {};
+	const agentCommandSchemas = Object.fromEntries(AGENT_NAMES.map((agent) => [agent, {}])) as Record<
+		AgentName,
+		Record<string, TokenSchema>
+	>;
+
+	for (const [commandName, command] of subCommandUnion) {
+		const { agent, report } = splitCommandName(commandName);
+		const commandSchema = filterCommandSchema(report, command.args as TokenSchema);
+		if (agent == null) {
+			topLevelCommandSchemas[report] = commandSchema;
+		} else {
+			agentCommandSchemas[agent][report] = commandSchema;
+		}
+	}
+
+	const legacyTopLevelCommandSchemas = Object.fromEntries(
+		Object.entries(topLevelCommandSchemas).map(([report, schema]) => [
+			report,
+			{
+				...(agentCommandSchemas.claude[report] ?? {}),
+				...schema,
+			},
+		]),
+	);
+	const defaultsJsonSchema = tokensSchemaToJsonSchema({
+		...commonSchemaProperties(agentCommandSchemas.claude),
+		...filterCommandSchema('daily', allArgs as TokenSchema),
+	});
+	const commandsJsonSchema = createCommandsJsonSchema(
+		legacyTopLevelCommandSchemas,
+		'Command-specific configuration overrides for all-agent reports',
+	);
 
 	// Main configuration schema
 	return {
@@ -152,10 +232,15 @@ function createConfigSchemaJson() {
 					},
 					defaults: {
 						...defaultsJsonSchema,
-						description: 'Default values for all commands',
-						markdownDescription: 'Default values for all commands',
+						description: 'Default values for all-agent reports and legacy Claude commands',
+						markdownDescription: 'Default values for all-agent reports and legacy Claude commands',
 					},
 					commands: commandsJsonSchema,
+					claude: createAgentJsonSchema('claude', agentCommandSchemas.claude),
+					codex: createAgentJsonSchema('codex', agentCommandSchemas.codex),
+					opencode: createAgentJsonSchema('opencode', agentCommandSchemas.opencode),
+					amp: createAgentJsonSchema('amp', agentCommandSchemas.amp),
+					pi: createAgentJsonSchema('pi', agentCommandSchemas.pi),
 				},
 				additionalProperties: false,
 			},
@@ -168,15 +253,24 @@ function createConfigSchemaJson() {
 				$schema: 'https://ccusage.com/config-schema.json',
 				defaults: {
 					json: false,
-					mode: 'auto',
 					timezone: 'Asia/Tokyo',
 				},
-				commands: {
-					daily: {
-						instances: true,
+				claude: {
+					defaults: {
+						mode: 'auto',
 					},
-					blocks: {
-						tokenLimit: '500000',
+					commands: {
+						daily: {
+							instances: true,
+						},
+						blocks: {
+							tokenLimit: '500000',
+						},
+					},
+				},
+				codex: {
+					defaults: {
+						speed: 'auto',
 					},
 				},
 			},
@@ -290,6 +384,14 @@ if (import.meta.main) {
 	await generateJsonSchema();
 }
 if (import.meta.vitest != null) {
+	function schemaProperties(schema: JsonSchemaNode): Record<string, JsonSchemaNode> {
+		return schema.properties ?? {};
+	}
+
+	function configSchemaDefinition(schema: JsonSchemaNode): JsonSchemaNode {
+		return schema.definitions?.['ccusage-config'] ?? {};
+	}
+
 	describe('tokensSchemaToJsonSchema', () => {
 		it('should convert boolean args to JSON Schema', () => {
 			const schema = {
@@ -298,10 +400,10 @@ if (import.meta.vitest != null) {
 					description: 'Enable debug mode',
 					default: false,
 				},
-			};
+			} satisfies TokenSchema;
 
 			const jsonSchema = tokensSchemaToJsonSchema(schema);
-			expect((jsonSchema.properties as Record<string, any>).debug).toEqual({
+			expect(schemaProperties(jsonSchema).debug).toEqual({
 				type: 'boolean',
 				description: 'Enable debug mode',
 				markdownDescription: 'Enable debug mode',
@@ -317,10 +419,10 @@ if (import.meta.vitest != null) {
 					choices: ['auto', 'manual'],
 					default: 'auto',
 				},
-			};
+			} satisfies TokenSchema;
 
 			const jsonSchema = tokensSchemaToJsonSchema(schema);
-			expect((jsonSchema.properties as Record<string, any>).mode).toEqual({
+			expect(schemaProperties(jsonSchema).mode).toEqual({
 				type: 'string',
 				enum: ['auto', 'manual'],
 				description: 'Mode selection',
@@ -337,29 +439,62 @@ if (import.meta.vitest != null) {
 			expect(jsonSchema).toBeDefined();
 			expect(jsonSchema.$ref).toBe('#/definitions/ccusage-config');
 			expect(jsonSchema.definitions).toBeDefined();
-			expect(jsonSchema.definitions['ccusage-config']).toBeDefined();
-			expect(jsonSchema.definitions['ccusage-config'].type).toBe('object');
+			expect(configSchemaDefinition(jsonSchema)).toBeDefined();
+			expect(configSchemaDefinition(jsonSchema).type).toBe('object');
 		});
 
 		it('should include all expected properties', () => {
 			const jsonSchema = createConfigSchemaJson();
-			const mainSchema = jsonSchema.definitions['ccusage-config'];
+			const mainSchema = configSchemaDefinition(jsonSchema);
+			const properties = schemaProperties(mainSchema);
+
+			expect(properties).toHaveProperty('$schema');
+			expect(properties).toHaveProperty('defaults');
+			expect(properties).toHaveProperty('commands');
+			expect(properties).toHaveProperty('claude');
+			expect(properties).toHaveProperty('codex');
+		});
 
-			expect(mainSchema.properties).toHaveProperty('$schema');
-			expect(mainSchema.properties).toHaveProperty('defaults');
-			expect(mainSchema.properties).toHaveProperty('commands');
+		it('should keep legacy top-level Claude config properties', () => {
+			const jsonSchema = createConfigSchemaJson();
+			const mainSchema = configSchemaDefinition(jsonSchema);
+			const properties = schemaProperties(mainSchema);
+			const defaultsSchema = properties.defaults ?? {};
+			const commandsSchema = properties.commands ?? {};
+			const dailySchema = schemaProperties(commandsSchema).daily ?? {};
+
+			expect(schemaProperties(defaultsSchema)).toHaveProperty('mode');
+			expect(schemaProperties(dailySchema)).toHaveProperty('instances');
 		});
 
 		it('should include all command schemas', () => {
 			const jsonSchema = createConfigSchemaJson();
-			const commandsSchema = jsonSchema.definitions['ccusage-config'].properties.commands;
-
-			expect(commandsSchema.properties).toHaveProperty('daily');
-			expect(commandsSchema.properties).toHaveProperty('monthly');
-			expect(commandsSchema.properties).toHaveProperty('weekly');
-			expect(commandsSchema.properties).toHaveProperty('session');
-			expect(commandsSchema.properties).toHaveProperty('blocks');
-			expect(commandsSchema.properties).toHaveProperty('statusline');
+			const mainSchema = configSchemaDefinition(jsonSchema);
+			const commandsSchema = schemaProperties(mainSchema).commands ?? {};
+			const commandProperties = schemaProperties(commandsSchema);
+
+			expect(commandProperties).toHaveProperty('daily');
+			expect(commandProperties).toHaveProperty('monthly');
+			expect(commandProperties).toHaveProperty('weekly');
+			expect(commandProperties).toHaveProperty('session');
+			expect(commandProperties).not.toHaveProperty('codex:daily');
+		});
+
+		it('should include agent command schemas under agent namespaces', () => {
+			const jsonSchema = createConfigSchemaJson();
+			const mainSchema = configSchemaDefinition(jsonSchema);
+			const properties = schemaProperties(mainSchema);
+			const claudeCommands = schemaProperties(properties.claude ?? {}).commands ?? {};
+			const codexCommands = schemaProperties(properties.codex ?? {}).commands ?? {};
+			const claudeCommandProperties = schemaProperties(claudeCommands);
+			const codexCommandProperties = schemaProperties(codexCommands);
+
+			expect(claudeCommandProperties).toHaveProperty('daily');
+			expect(claudeCommandProperties).toHaveProperty('blocks');
+			expect(claudeCommandProperties).toHaveProperty('statusline');
+			expect(codexCommandProperties).toHaveProperty('daily');
+			expect(codexCommandProperties).toHaveProperty('monthly');
+			expect(codexCommandProperties).toHaveProperty('session');
 		});
 	});
 }