@jeffreyjyz/mpc 0.0.0-stage → 0.1.0

package/src/cli/parse/cac.ts

@@ -0,0 +1,114 @@
+import { cac } from "cac";
+import type { Options } from "~/cli/options.ts";
+import pkg from "../../../package.json" with { type: "json" };
+import { type Bag, toOptions } from "./map.ts";
+
+/** Raw CLI bag: exactly what the user typed, no config, no defaults. */
+export function parseFlags(argv: string[]): Bag {
+	const cli = cac("mpc");
+	cli.option(
+		"--cc-plan <id>",
+		"CommandCode plan: go, goat, pro, max10, max20",
+	)
+		.option("--in <n>", "input tokens per request")
+		.option("--cache <n>", "cache-read tokens per request")
+		.option("--out <n>", "output tokens per request")
+		.option(
+			"--reasoning <n>",
+			"reasoning tokens, billed at the output rate",
+		)
+		.option("--cache-write <n>", "cache-write tokens per request")
+		.option(
+			"--shape <spec>",
+			"auto | measured | <file> | off: reqshape shape (auto = measured with enough data)",
+		)
+		.option(
+			"--since <date>",
+			"measured shape: only requests on or after this date",
+		)
+		.option("--metric <name>", "val | cost | perreq | req | name")
+		.option("--model <re>", "only rows whose name matches")
+		.option("--only <scope>", "both | all")
+		.option(
+			"--minimal",
+			"fewest columns: model + req/mo each side + win + val",
+		)
+		.option(
+			"--medium",
+			"allowance and the rate views per side + win + cost + val",
+		)
+		.option(
+			"--no-fit",
+			"keep the preset's full width, do not trim to the terminal",
+		)
+		.option("--detail", "every column, untrimmed")
+		.option("--width <n>", "force table width")
+		.option(
+			"--columns <ids>",
+			"comma-separated columns (--columns help to list)",
+		)
+		.option("--preset <name>", "named column preset from config")
+		.option(
+			"--bench <src>",
+			"cc | aa | aa-web | file:<path> | url:<url> (aa with a key, else cc)",
+		)
+		.option("--bench-weight <n>", "ability share of VAL")
+		.option("--tps-weight <n>", "speed share of VAL")
+		.option("--val-weights <w>", "ability,tps,volume,cache,output shares")
+		.option("--scale <mode>", "log | linear for skewed terms")
+		.option(
+			"--inherit-suffixes <s>",
+			"comma-separated speed-variant suffixes",
+		)
+		.option("--window <pair>", "override five-hour,weekly window ratios")
+		.option("--cost-thresholds <p>", "green,yellow COST cut-offs")
+		.option("--val-thresholds <p>", "yellow,green VAL cut-offs")
+		.option("--bench-name <label>", "footer label for the source")
+		.option("--aa-key <key>", "Artificial Analysis key (else AA_API_KEY)")
+		.option("--no-fallback", "do not fill misses from other sources")
+		.option("--refresh", "ignore the aa-web cache")
+		.option("--no-ability", "hide ability and VAL")
+		.option("--peak", "peak-rate rows (OpenCode DeepSeek)")
+		.option("--asc", "flip the default sort direction")
+		.option("--json", "machine-readable output")
+		.option("--format <name>", "table | json | csv | md")
+		.option("--color <mode>", "auto | always | never")
+		.option("--check", "validate live sources and exit")
+		.option(
+			"--config <path>",
+			"config file (default: ~/.config/mpc/config.json)",
+		)
+		.option("--no-config", "ignore the config file")
+		.option("--plugin <paths>", "extra config plugins, comma-separated")
+		.option("--print-config", "print the effective settings and exit")
+		.option(
+			"--usage",
+			"project your real usage from cmduse onto both plans",
+		)
+		.option("--usage-file <path>", "read usage from a JSON file instead")
+		.option(
+			"--usage-window <w>",
+			"usage range: period | all | <n>d (default period)",
+		)
+		.option(
+			"--usage-db <path>",
+			"opencode message store (default ~/.local/share/opencode/opencode.db)",
+		)
+		.option(
+			"--usage-log <path>",
+			"provider usage log (default ~/.cache/mpc/usage.jsonl)",
+		)
+		.option(
+			"--usage-months <n>",
+			"treat the logged usage as covering N months",
+		);
+	cli.help();
+	cli.version(pkg.version);
+	const parsed = cli.parse(["node", "mpc", ...argv], { run: false });
+	return (parsed.options ?? {}) as Bag;
+}
+
+/** CLI-only options, with defaults. Config is applied by resolveOptions. */
+export function parseArgs(argv: string[]): Options {
+	return toOptions(parseFlags(argv));
+}

package/src/cli/parse/fields.ts

@@ -0,0 +1,65 @@
+import type { ColorMode } from "~/cli/options.ts";
+import type { Bag } from "./validate.ts";
+
+/** Comma-separated or repeated flag, read as numbers. */
+export function numbers(bag: Bag, key: string): number[] | undefined {
+	const value = bag[key];
+	if (value === undefined || value === false) return undefined;
+	const parts = Array.isArray(value) ? value : String(value).split(",");
+	const nums = parts.map((part) => Number(part));
+	if (nums.some((n) => !Number.isFinite(n))) {
+		throw new Error(
+			`--${key} expects comma-separated numbers, got "${value}"`,
+		);
+	}
+	return nums;
+}
+
+/** Comma-separated or repeated flag, read as trimmed words. */
+export function words(bag: Bag, key: string): string[] {
+	const value = bag[key];
+	if (value === undefined || value === false) return [];
+	const parts = Array.isArray(value) ? value : String(value).split(",");
+	return parts.map((part) => String(part).trim()).filter(Boolean);
+}
+
+/** Named column presets from config: name -> column ids. */
+export function presets(bag: Bag): Record<string, string[]> {
+	const value = bag.presets;
+	if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+	const out: Record<string, string[]> = {};
+	for (const [name, ids] of Object.entries(
+		value as Record<string, unknown>,
+	)) {
+		out[name] = Array.isArray(ids)
+			? ids.map((id) => String(id).trim())
+			: String(ids)
+					.split(",")
+					.map((id) => id.trim())
+					.filter(Boolean);
+	}
+	return out;
+}
+
+export function usageWindow(value: unknown): "period" | "all" | `${number}d` {
+	if (value === "all") return "all";
+	if (typeof value === "string" && /^\d+d$/.test(value)) {
+		return value as `${number}d`;
+	}
+	return "period";
+}
+
+export function colorMode(value: unknown): ColorMode {
+	if (value === false || value === "never") return "never";
+	if (value === "always") return "always";
+	return "auto";
+}
+
+/** A two-number pair, e.g. window ratios or colour thresholds. */
+export function pair(value: unknown, name: string): [number, number] {
+	const nums = numbers({ v: value }, "v");
+	if (nums?.length !== 2) {
+		throw new Error(`--${name} expects two comma-separated numbers`);
+	}
+	return [nums[0] ?? 0, nums[1] ?? 0];
+}

package/src/cli/parse/map.ts

@@ -0,0 +1,116 @@
+import {
+	type Format,
+	type Metric,
+	type Options,
+	parseFormat,
+	parseMetric,
+	parseOnly,
+	type ScaleMode,
+} from "~/cli/options.ts";
+import { ARG_DEFAULTS, BENCH_DEFAULT } from "~/constants/cli.ts";
+import { SHAPE_MEASURED } from "~/constants/shape.ts";
+import {
+	colorMode,
+	numbers,
+	pair,
+	presets,
+	usageWindow,
+	words,
+} from "./fields.ts";
+import { assertKnown, assertValues, type Bag, int, share } from "./validate.ts";
+
+export type { Bag } from "./validate.ts";
+
+const pick = (bag: Bag, key: string): unknown =>
+	bag[key] === undefined
+		? ARG_DEFAULTS[key as keyof typeof ARG_DEFAULTS]
+		: bag[key];
+
+/** `--bench` default is contextual: the AA API leads only when a key exists. */
+function benchDefault(bag: Bag): string {
+	const keyed = bag.aaKey !== undefined || Boolean(process.env.AA_API_KEY);
+	return keyed ? BENCH_DEFAULT.keyed : BENCH_DEFAULT.keyless;
+}
+
+/** Reduce the merged bag (plugins < config < CLI) to Options. */
+export function toOptions(bag: Bag): Options {
+	assertKnown(bag);
+	assertValues(bag);
+	const columns = bag.columns === undefined ? undefined : String(bag.columns);
+	const window = numbers(bag, "window");
+	return {
+		ccPlan: String(pick(bag, "ccPlan")),
+		workload: {
+			input: int("in", pick(bag, "in")),
+			cacheRead: int("cache", pick(bag, "cache")),
+			output: int("out", pick(bag, "out")),
+			reasoning: int("reasoning", pick(bag, "reasoning")),
+			cacheWrite: int("cache-write", pick(bag, "cacheWrite")),
+		},
+		// A bare `--shape` means "measure it" (`cac` yields `true`); no flag at
+		// all leaves the default (`auto`, which trusts reqshape when it has data).
+		shape: bag.shape === true ? SHAPE_MEASURED : String(pick(bag, "shape")),
+		since: bag.since === undefined ? undefined : String(bag.since),
+		metric: parseMetric(String(pick(bag, "metric"))) as Metric,
+		model: bag.model === undefined ? undefined : String(bag.model),
+		only: parseOnly(String(pick(bag, "only"))),
+		columns:
+			columns === undefined
+				? undefined
+				: columns
+						.split(",")
+						.map((c) => c.trim())
+						.filter(Boolean),
+		preset: bag.preset === undefined ? undefined : String(bag.preset),
+		presets: presets(bag),
+		detail: bag.detail === true,
+		minimal: bag.minimal === true,
+		medium: bag.medium === true,
+		// Width 0 is meaningless and silently disabled trimming; cac coerces a
+		// blank `--width ""` to 0, so require at least one column.
+		width: bag.width === undefined ? undefined : int("width", bag.width, 1),
+		fit: bag.fit !== false,
+		bench: bag.bench === undefined ? benchDefault(bag) : String(bag.bench),
+		benchWeight: share("bench-weight", pick(bag, "benchWeight")),
+		tpsWeight: share("tps-weight", pick(bag, "tpsWeight")),
+		valWeights: numbers(bag, "valWeights"),
+		scale: String(pick(bag, "scale")) as ScaleMode,
+		// Absent means "use the built-in suffixes"; an empty list means "inherit
+		// nothing", which is why this must stay undefined rather than become []:
+		// the lookups read an empty array as a deliberate opt-out.
+		inheritSuffixes: (() => {
+			const suffixes = words(bag, "inheritSuffixes");
+			return suffixes.length > 0 ? suffixes : undefined;
+		})(),
+		window:
+			window && window.length === 2
+				? [window[0] ?? 0, window[1] ?? 0]
+				: undefined,
+		costThresholds: pair(pick(bag, "costThresholds"), "cost-thresholds"),
+		valThresholds: pair(pick(bag, "valThresholds"), "val-thresholds"),
+		benchName:
+			bag.benchName === undefined ? undefined : String(bag.benchName),
+		aaKey: bag.aaKey === undefined ? undefined : String(bag.aaKey),
+		noFallback: bag.fallback === false,
+		refresh: bag.refresh === true,
+		noAbility: bag.ability === false,
+		peak: bag.peak === true,
+		asc: bag.asc === true,
+		json: bag.json === true,
+		format: parseFormat(
+			bag.format === undefined ? "table" : String(bag.format),
+		) as Format,
+		colorMode: colorMode(bag.color),
+		check: bag.check === true,
+		printConfig: bag.printConfig === true,
+		usage: bag.usage === true,
+		usageFile:
+			bag.usageFile === undefined ? undefined : String(bag.usageFile),
+		usageLog: bag.usageLog === undefined ? undefined : String(bag.usageLog),
+		usageDb: bag.usageDb === undefined ? undefined : String(bag.usageDb),
+		usageMonths:
+			bag.usageMonths === undefined ? 1 : Number(bag.usageMonths),
+		usageWindow: usageWindow(bag.usageWindow),
+		plugins: words(bag, "plugins"),
+	};
+}

package/src/cli/parse/plugins.ts

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import type { Bag } from "./validate.ts";
+
+/** A plugin's default export may be an object or a (possibly async) factory. */
+type PluginFactory = (ctx: PluginContext) => Bag | Promise<Bag>;
+
+export interface PluginContext {
+	env: Record<string, string | undefined>;
+	cwd: string;
+	configDir: string;
+}
+
+function qualify(spec: string, relativeTo: string): string {
+	if (spec.startsWith(".") || isAbsolute(spec)) {
+		return isAbsolute(spec) ? spec : join(relativeTo, spec);
+	}
+	return spec; // bare specifier: resolve as a package
+}
+
+function asBag(value: unknown, spec: string): Bag {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error(`plugin ${spec} must export a config object`);
+	}
+	return value as Bag;
+}
+
+async function loadOne(spec: string, relativeTo: string): Promise<Bag> {
+	const target = qualify(spec, relativeTo);
+	const ctx: PluginContext = {
+		env: process.env,
+		cwd: process.cwd(),
+		configDir: relativeTo,
+	};
+
+	if (
+		target.endsWith(".json") ||
+		(existsSync(target) && target.endsWith(".json"))
+	) {
+		return asBag(JSON.parse(readFileSync(target, "utf8")), spec);
+	}
+	try {
+		const mod = (await import(target)) as { default?: unknown };
+		const exported = mod.default ?? mod;
+		const value =
+			typeof exported === "function"
+				? await (exported as PluginFactory)(ctx)
+				: exported;
+		return asBag(value, spec);
+	} catch (error) {
+		throw new Error(
+			`plugin ${spec} failed: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+}
+
+/** Load plugins in order and layer them: later plugins win over earlier ones. */
+export async function loadPlugins(
+	specs: string[],
+	relativeTo: string,
+): Promise<Bag> {
+	const merged: Bag = {};
+	for (const spec of specs) {
+		Object.assign(merged, await loadOne(spec, relativeTo));
+	}
+	return merged;
+}

package/src/cli/parse/validate.ts

@@ -0,0 +1,60 @@
+import { INTERNAL, KNOWN, VALUED } from "~/constants/cli.ts";
+
+export type Bag = Record<string, unknown>;
+
+// `Number("")` is 0 and `Number(true)` is 1, so a blank or bare flag would be
+// coerced into a plausible-looking value (`--out ""` silently priced every model
+// with zero output tokens, `--width ""` became 0 and disabled trimming). Reject
+// both shapes before the conversion; a bare boolean is also caught by
+// `assertValues`, but config/plugin layers reach here without that guard.
+export function int(name: string, value: unknown, min = 0): number {
+	const want = min === 0 ? "a non-negative integer" : `an integer ≥ ${min}`;
+	if (value === true || value === "" || Number(value) < min) {
+		throw new Error(`--${name} expects ${want}, got "${value}"`);
+	}
+	const n = Number(value);
+	if (!Number.isFinite(n) || !Number.isInteger(n)) {
+		throw new Error(`--${name} expects ${want}, got "${value}"`);
+	}
+	return n;
+}
+
+export function share(name: string, value: unknown): number {
+	if (value === true || value === "") {
+		throw new Error(`--${name} expects a number between 0 and 1`);
+	}
+	const n = Number(value);
+	if (!Number.isFinite(n) || n < 0 || n > 1) {
+		throw new Error(`--${name} expects a number between 0 and 1`);
+	}
+	return n;
+}
+
+/** Reject undeclared flags before mapping. */
+export function assertKnown(bag: Bag): void {
+	const extra = Object.keys(bag).filter(
+		(key) => !KNOWN.has(key) && !INTERNAL.has(key),
+	);
+	if (extra.length > 0) {
+		throw new Error(
+			`unknown flag "--${extra[0]}" — see --help for the full list`,
+		);
+	}
+}
+
+/** camelCase key -> the `--kebab-case` spelling the user typed. */
+function flag(key: string): string {
+	return `--${key.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`)}`;
+}
+
+/** Reject a value-taking flag used bare (`--shape` with no argument). */
+export function assertValues(bag: Bag): void {
+	const bare = Object.keys(bag).filter(
+		(key) => VALUED.has(key) && bag[key] === true,
+	);
+	if (bare.length > 0) {
+		throw new Error(
+			`${flag(String(bare[0]))} expects a value — see --help`,
+		);
+	}
+}

package/src/cli/run.ts

@@ -0,0 +1,151 @@
+#!/usr/bin/env bun
+import { COLUMN_HELP, COLUMN_IDS } from "~/constants/view.ts";
+import { loadUsage } from "~/data/usage/index.ts";
+import { renderUsage } from "~/view/layout/usage.ts";
+import {
+	fitColumns,
+	renderCsv,
+	renderJson,
+	renderMarkdown,
+	renderText,
+	setColorMode,
+	setThresholds,
+	tally,
+} from "~/view/render.ts";
+import { describeConfig, resolveBag } from "./config.ts";
+import { project } from "./engine/project.ts";
+import { runCheck } from "./flow/check.ts";
+import { collect } from "./flow/collect.ts";
+import { resolveColumns, trimsToWidth } from "./flow/columns.ts";
+import { matches, sortRows } from "./flow/sort.ts";
+import { toOptions } from "./parse/map.ts";
+import { assertKnown, assertValues } from "./parse/validate.ts";
+
+export type { Metric, Options } from "./options.ts";
+export { parseArgs } from "./parse/cac.ts";
+
+export async function run(argv: string[]): Promise<number> {
+	const bag = await resolveBag(argv);
+	// cac prints the help text / version line itself and returns the parsed bag
+	// (with the `h`/`v` aliases) instead of exiting, so stop here — otherwise the
+	// full table would print after the help, and the aliases would trip assertKnown.
+	if (
+		bag.help === true ||
+		bag.h === true ||
+		bag.version === true ||
+		bag.v === true
+	) {
+		return 0;
+	}
+	if (bag.printConfig === true) {
+		// This is the one mode meant to check a config, so a typo must fail here
+		// rather than on the next real run.
+		assertKnown(bag);
+		assertValues(bag);
+		process.stdout.write(describeConfig(bag));
+		return 0;
+	}
+	const options = toOptions(bag);
+	if (options.columns?.includes("help")) {
+		console.log(COLUMN_HELP);
+		return 0;
+	}
+
+	setColorMode(options.colorMode);
+	setThresholds(options.costThresholds, options.valThresholds);
+
+	const requested = resolveColumns(options);
+	const unknown = requested.filter((id) => !COLUMN_IDS.includes(id));
+	if (unknown.length > 0) {
+		throw new Error(
+			`unknown column(s): ${unknown.join(", ")} — valid: ${COLUMN_IDS.join(", ")}`,
+		);
+	}
+
+	const {
+		ocEntries,
+		ccEntries,
+		ocPlanInfo,
+		ccPlanInfo,
+		rows,
+		ability,
+		workloads,
+		shapeNote,
+	} = await collect(options);
+	if (options.check) {
+		return runCheck(options, ocEntries, ccEntries, rows, ability);
+	}
+
+	if (options.usage) {
+		const usage = await loadUsage(
+			options.usageFile,
+			options.usageWindow,
+			options.usageLog,
+			options.usageDb,
+		);
+		const projection = project(
+			usage.entries,
+			{ "oc-go": ocEntries, cc: ccEntries },
+			{ "oc-go": ocPlanInfo, cc: ccPlanInfo },
+			{ months: options.usageMonths },
+		);
+		if (options.format === "json" || options.json) {
+			console.log(
+				JSON.stringify({ source: usage.label, ...projection }, null, 2),
+			);
+			return 0;
+		}
+		renderUsage(projection, {
+			label: usage.label,
+			window: usage.window,
+			account: usage.account,
+			months: options.usageMonths,
+			plans: { "oc-go": ocPlanInfo, cc: ccPlanInfo },
+		});
+		return 0;
+	}
+
+	const result = sortRows(
+		rows.filter(
+			(r) =>
+				matches(r, options.model) &&
+				(options.only === "all" || (r.oc && r.cc)),
+		),
+		options.metric,
+		options.asc,
+	);
+	const meta = {
+		ocPlan: ocPlanInfo,
+		ccPlan: ccPlanInfo,
+		workloads,
+		abilityLabel: options.noAbility
+			? undefined
+			: (options.benchName ?? ability.label),
+		abilityNote: options.noAbility ? undefined : ability.note,
+		shapeNote,
+		window: options.window,
+	};
+
+	if (options.format === "json" || options.json) {
+		console.log(renderJson(result, meta));
+		return 0;
+	}
+	if (options.format === "csv") {
+		process.stdout.write(renderCsv(result, tally(result)));
+		return 0;
+	}
+	if (options.format === "md") {
+		process.stdout.write(renderMarkdown(result, [ocPlanInfo, ccPlanInfo]));
+		return 0;
+	}
+
+	const limit = options.width ?? process.stdout.columns ?? 120;
+	const fitted = trimsToWidth(options)
+		? fitColumns(result, requested, limit)
+		: { ids: requested, dropped: [] as string[] };
+	renderText(result, meta, fitted.ids, fitted.dropped);
+	console.log(
+		`\n${result.length} models · OpenCode Go vs CommandCode ${ccPlanInfo.label} · ${ocEntries.length} OpenCode / ${ccEntries.length} CommandCode entries`,
+	);
+	return 0;
+}