@jeffreyjyz/mpc 0.0.0-stage → 0.1.0

package/src/constants/cli.ts

@@ -0,0 +1,153 @@
+import type { Format, Metric } from "~/cli/options.ts";
+import { SHAPE_AUTO } from "~/constants/shape.ts";
+import {
+	DETAIL_COLUMNS,
+	MEDIUM_COLUMNS,
+	MINIMAL_COLUMNS,
+} from "~/constants/view.ts";
+
+/** Workload defaults asserted by `--in` / `--cache` / `--out` when unset. */
+export const OPTION_DEFAULTS = {
+	input: 800,
+	cacheRead: 50_000,
+	output: 200,
+};
+
+/**
+ * `--bench` default is contextual: the AA API gives full coverage when a key
+ * is available (`AA_API_KEY` / `--aa-key`), so it leads there; otherwise the
+ * CommandCode scrape does.
+ */
+export const BENCH_DEFAULT = { keyed: "aa", keyless: "cc" } as const;
+
+/** The raw CLI bag defaults, before config/plugin layering. */
+export const ARG_DEFAULTS = {
+	ccPlan: "goat",
+	in: 800,
+	cache: 50_000,
+	out: 200,
+	reasoning: 0,
+	cacheWrite: 0,
+	shape: SHAPE_AUTO,
+	metric: "val",
+	only: "all",
+	bench: BENCH_DEFAULT.keyless,
+	benchWeight: 0.35,
+	tpsWeight: 0.1,
+	costThresholds: [30, 60],
+	valThresholds: [40, 70],
+	scale: "log",
+	format: "table",
+} as const;
+
+export const METRICS: Metric[] = ["val", "cost", "perreq", "req", "name"];
+export const FORMATS: Format[] = ["table", "json", "csv", "md"];
+
+// cac registers `--help`/`--version` **and** their `-h`/`-v` aliases as separate
+// keys, so all four must be tolerated here; `run` then returns before any work.
+export const INTERNAL = new Set(["--", "help", "h", "version", "v"]);
+
+export const KNOWN = new Set([
+	"ccPlan",
+	"in",
+	"cache",
+	"out",
+	"reasoning",
+	"cacheWrite",
+	"shape",
+	"since",
+	"metric",
+	"model",
+	"only",
+	"fit",
+	"bench",
+	"benchWeight",
+	"tpsWeight",
+	"benchName",
+	"aaKey",
+	"fallback",
+	"refresh",
+	"ability",
+	"peak",
+	"asc",
+	"json",
+	"detail",
+	"minimal",
+	"medium",
+	"width",
+	"columns",
+	"color",
+	"check",
+	"config",
+	"printConfig",
+	"usage",
+	"usageFile",
+	"usageLog",
+	"usageDb",
+	"usageMonths",
+	"usageWindow",
+	"plugins",
+	"plugin",
+	"preset",
+	"presets",
+	"format",
+	"scale",
+	"valWeights",
+	"inheritSuffixes",
+	"window",
+	"costThresholds",
+	"valThresholds",
+]);
+
+/**
+ * Flags cac declares with a required value (`--x <v>`). Given without one, cac
+ * yields the boolean `true`, which `String(...)` would quietly turn into the
+ * literal "true" and be used as the value.
+ *
+ * Two are deliberately absent: `config` (`--no-config` makes `true` its
+ * *default*, so a bare `--config` cannot be told from "use the default path")
+ * and `shape` (a bare `--shape` means `measured`, handled in `map.ts`).
+ */
+export const VALUED = new Set([
+	"ccPlan",
+	"in",
+	"cache",
+	"out",
+	"reasoning",
+	"cacheWrite",
+	"since",
+	"metric",
+	"model",
+	"only",
+	"width",
+	"columns",
+	"preset",
+	"bench",
+	"benchWeight",
+	"tpsWeight",
+	"valWeights",
+	"scale",
+	"inheritSuffixes",
+	"window",
+	"costThresholds",
+	"valThresholds",
+	"benchName",
+	"aaKey",
+	"format",
+	"color",
+	"plugin",
+	"usageFile",
+	"usageWindow",
+	"usageDb",
+	"usageLog",
+	"usageMonths",
+]);
+
+export const TIERS = ["minimal", "medium", "detail"] as const;
+export type Tier = (typeof TIERS)[number];
+
+export const SETS: Record<Tier, string[]> = {
+	minimal: MINIMAL_COLUMNS,
+	medium: MEDIUM_COLUMNS,
+	detail: DETAIL_COLUMNS,
+};

package/src/constants/data.ts

@@ -0,0 +1,30 @@
+/**
+ * Marks a text-node boundary inside a scraped cell, so "$60" + "4x" stays two
+ * tokens instead of collapsing into an ambiguous "$604x".
+ */
+export const BOUNDARY = "\u0001";
+
+/**
+ * Canonical keys that differ only by vendor/branding between the two catalogs.
+ * Keys are already lowercased and stripped of punctuation; map the variant onto
+ * the shared canonical form. Applied after normalizeKey's base cleaning.
+ */
+export const ALIASES: Record<string, string> = {
+	// CommandCode prefixes these with "Tencent"; OpenCode Go does not.
+	tencenthy3: "hy3",
+	tencenthy4preview: "hy4preview",
+	// CommandCode writes "(exp)"; OpenCode Go writes "-exp".
+	deepseekv4flashvision: "deepseekv4flashvisionexp",
+	// Alibaba's "Qwen3.8-Flash-Next" is the release name of the model
+	// CommandCode lists as "Qwen 3.8 Flash": same creator, same $0.47 output
+	// price and release window, CommandCode has no "Next" row, and Artificial
+	// Analysis has no plain "Flash" one. Without this the row has no ability or
+	// speed at all, since neither index scores it under the marketing name.
+	qwen38flashnext: "qwen38flash",
+};
+
+/** The chip text of a promotion: "-40%", "-98%", "Free", "2x usage". */
+export const BADGE = /^-?\d+(?:\.\d+)?%$|^free$|^\d+x(?:\s+usage)?$/i;
+
+/** How CommandCode prints the deal's window beside the chip. */
+export const ENDS = /^(?:ends|through|until)\b/i;

package/src/constants/scoring.ts

@@ -0,0 +1,22 @@
+import type { ScoreConfig } from "~/cli/engine/score.ts";
+
+/** Tokens per million, the denominator of every per-M-token rate. */
+export const PER_MILLION = 1_000_000;
+
+/** Speed-variant suffixes that share the base model's weights. */
+export const SPEED_SUFFIXES = ["ultraspeed", "highspeed", "fastx", "fast"];
+
+/**
+ * Throughput a speed variant without its own figure borrows from its base.
+ * Serving differs, so the base's number is not inherited verbatim, but leaving
+ * the variant at `null` scores it at the neutral 0.5 — as if a "Fast" model
+ * were mid-pack on speed, which is what made DeepSeek V4.1 Flash Fast rank
+ * below its slower base. A speed tier is multiples of its base, so claim 2x.
+ */
+export const SPEED_TPS_FACTOR = 2;
+
+export const DEFAULT_SCORE: ScoreConfig = {
+	abilityWeight: 0.35,
+	tpsWeight: 0.1,
+	scale: "log",
+};

package/src/constants/shape.ts

@@ -0,0 +1,19 @@
+/**
+ * `--shape` specs. `auto` (the default) measures with reqshape but only trusts
+ * it once the sample is big enough; `measured` forces it; `off` keeps the fixed
+ * workload. Anything else is a path to a saved payload.
+ */
+export const SHAPE_AUTO = "auto";
+export const SHAPE_MEASURED = "measured";
+export const SHAPE_OFF = "off";
+
+/** Fewest reqs for `auto` to prefer reqshape's profile over the fixed workload. */
+export const SHAPE_MIN_REQS = 500;
+
+/**
+ * Env marker set on the reqshape child. reqshape runs `mpc --json`, so without
+ * it a nested mpc would measure all over again; a process that sees it keeps
+ * the fixed workload. This breaks the cycle for callers that do not pass
+ * `--shape off` (e.g. a published sibling still pinned to the old default).
+ */
+export const SHAPE_GUARD_ENV = "MPC_SHAPE_RESOLVING";

package/src/constants/sources.ts

@@ -0,0 +1,69 @@
+interface CcPlanDef {
+	/** cmduse plan name. */
+	cmduse: string;
+	label: string;
+	/** Docs page slug under /docs/plans/. */
+	slug: string;
+	/** Allowance column header; omitted when the page publishes no credits column. */
+	creditHeader?: RegExp;
+	/**
+	 * Allowance for models the docs list without an explicit credits row.
+	 * GOAT/Pro: the standard 2x rate ($20 / $30). Go: the whole $10 plan pool,
+	 * since Go publishes no per-model allowances.
+	 */
+	standardAllowance?: number;
+	/** Parse the model list from a `role="row"` div grid instead of <table>. */
+	grid?: boolean;
+}
+
+export const CC_PLANS: Record<string, CcPlanDef> = {
+	go: {
+		cmduse: "Go",
+		label: "Go",
+		slug: "go",
+		standardAllowance: 10,
+	},
+	goat: {
+		cmduse: "GOAT",
+		label: "GOAT",
+		slug: "goat",
+		creditHeader: /monthly credit/i,
+		standardAllowance: 20,
+	},
+	pro: {
+		cmduse: "Pro",
+		label: "Pro",
+		slug: "pro",
+		creditHeader: /monthly credit/i,
+		standardAllowance: 30,
+	},
+	max10: {
+		cmduse: "Max 10x",
+		label: "Max 10x",
+		slug: "max",
+		creditHeader: /max\s*10/i,
+	},
+	max20: {
+		cmduse: "Max 20x",
+		label: "Max 20x",
+		slug: "max",
+		creditHeader: /max\s*20/i,
+	},
+};
+
+export const DOC_URL = "https://opencode.ai/docs/go/";
+export const OC_MODELS_URL = "https://opencode.ai/zen/go/v1/models";
+export const PRICE_PER_MONTH = 10;
+
+export const API_URL = "https://artificialanalysis.ai/api/v2/data/llms/models";
+export const AA_MODELS_URL = "https://artificialanalysis.ai/models";
+
+// CommandCode only publishes Intelligence and Tok/s on the GOAT/Pro catalogs.
+export const PAGES = [
+	"https://commandcode.ai/docs/plans/goat",
+	"https://commandcode.ai/docs/plans/pro",
+];
+export const TPS_HEADER = /tok\s*\/?\s*s|tokens?\s*per\s*sec/i;
+
+/** How long a cached benchmark result is considered fresh, in milliseconds. */
+export const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;

package/src/constants/view.ts

@@ -0,0 +1,161 @@
+import type { ProviderId } from "~/types.ts";
+import { CC_COLUMNS } from "~/view/columns/cc.ts";
+import { OC_COLUMNS } from "~/view/columns/oc.ts";
+
+/**
+ * SGR codes with **one meaning each**. `green` = favourable (cheaper side, free,
+ * a good score), `yellow` = middling score, `dim` = absent value or a structural
+ * annotation — never a quality and never a side. Provider identity is
+ * `PROVIDER_COLOR`, kept out of this scale so cyan never means "ability" too.
+ */
+export const SGR = {
+	bold: "1",
+	dim: "2",
+	red: "31",
+	green: "32",
+	yellow: "33",
+} as const;
+
+/** Provider identity colour (bold), for banners, headers and a winning cell. */
+export const PROVIDER_COLOR: Record<ProviderId, string> = {
+	"oc-go": "1;36",
+	cc: "1;35",
+};
+
+/** The same identity as a quiet tint, for a provider's whole column set. */
+export const PROVIDER_TINT: Record<ProviderId, string> = {
+	"oc-go": "36",
+	cc: "35",
+};
+
+export const GAP = "  ";
+export const BAR = " │ ";
+export const BAR_RULE = "─┼─";
+
+/** Fewest columns that still answer "which model, how many requests, who wins". */
+export const MINIMAL_COLUMNS = ["model", "oc-reqmo", "cc-reqmo", "win", "val"];
+
+/** The everyday middle set: allowance plus the three rate views per side. */
+export const MEDIUM_COLUMNS = [
+	"model",
+	"oc-allow",
+	"oc-reqmo",
+	"oc-per1k",
+	"oc-reqdollar",
+	"cc-allow",
+	"cc-reqmo",
+	"cc-per1k",
+	"cc-reqdollar",
+	"win",
+	"cost",
+	"val",
+];
+
+/** Every column: the width-trimmed default, and `--detail` untrimmed. */
+export const DETAIL_COLUMNS = [
+	"model",
+	"oc-rates",
+	"oc-allow",
+	"oc-req5h",
+	"oc-reqwk",
+	"oc-reqmo",
+	"oc-per1k",
+	"oc-reqdollar",
+	"cc-rates",
+	"cc-allow",
+	"cc-req5h",
+	"cc-reqwk",
+	"cc-reqmo",
+	"cc-per1k",
+	"cc-reqdollar",
+	"ability",
+	"tps",
+	"deal",
+	"win",
+	"cost",
+	"val",
+];
+
+/** Every column the table can render, keyed by the id used with --columns. */
+export const COLUMN_IDS = [
+	"model",
+	...Object.keys(OC_COLUMNS),
+	...Object.keys(CC_COLUMNS),
+	"win",
+	"cost",
+	"ability",
+	"tps",
+	"deal",
+	"val",
+];
+
+export const LEGEND: [string, string][] = [
+	["rates", "token price per 1M tokens, in/out/cache"],
+	["allow", "monthly credits this plan gives the model"],
+	["5h wk mo", "requests the rolling 5-hour / weekly / monthly window buys"],
+	["$/1K", "your cost per 1,000 requests, at the plan's price"],
+	["req/$", "requests one dollar of subscription buys"],
+	[
+		"DEAL",
+		"active CommandCode promotion: -98%, Free, 2x usage (expiry line is in --json)",
+	],
+	[
+		"WIN",
+		"cheaper side: OC / CC / tie · 'x only' = only that provider has it",
+	],
+	["ability", "benchmark score for the model (source above)"],
+	["tps", "output tokens per second (source above)"],
+	["COST", "0-100 volume index: requests/mo, lower is better (no ability)"],
+	[
+		"VAL",
+		"0-100 ability-aware value: ability + speed + volume + cache + output",
+	],
+];
+
+export const CSV_HEADER = [
+	"model",
+	"plan",
+	"allowance",
+	"req_month",
+	"usd_per_1k",
+	"usd_per_request",
+	"ability",
+	"tps",
+	"cost_index",
+	"val_index",
+];
+
+export const HEADERS = [
+	"MODEL",
+	"your req",
+	"your $",
+	"CC $/req",
+	"CC $/mo",
+	"OC $/req",
+	"OC $/mo",
+	"cheaper",
+	"flag",
+];
+
+export const COLUMN_HELP = `Available columns (--columns a,b,c):
+  model            model name
+  oc-rates         OpenCode in/out/cache token rates ($/M)
+  oc-allow         OpenCode monthly allowance for the model
+  oc-req5h         requests the OpenCode 5-hour window allows
+  oc-reqwk         requests the OpenCode weekly window allows
+  oc-reqmo         requests the OpenCode monthly allowance buys
+  oc-per1k         OpenCode cost per 1,000 requests
+  oc-reqdollar     OpenCode requests per $1 of subscription
+  cc-*             the same set for the CommandCode plan
+  ability          benchmark score for the model
+  tps              output tokens per second
+  deal             active CommandCode promotion (-98%, Free, 2x usage)
+  win              side with the lower per-request cost
+  cost             0-100 cost index, lower is better
+  val              0-100 ability-aware value score
+
+Presets: default   = every column, trimmed to the terminal width (--no-fit keeps them all)
+         --minimal = model + req/mo both sides + win + val
+         --medium  = allowance and the rate views per side + win + cost + val
+         --detail  = every column, untrimmed (for copy/paste or agents)
+         --columns = an exact list; bypasses presets and trimming`;

package/src/data/bench/cc.ts

@@ -0,0 +1,26 @@
+import { PAGES, TPS_HEADER } from "~/constants/sources.ts";
+import {
+	extractNumericColumn,
+	fetchText,
+	parseTables,
+} from "~/data/scrape/index.ts";
+import { type BenchData, emptyData } from "./types.ts";
+
+export async function loadCc(): Promise<BenchData> {
+	const pages = await Promise.all(
+		PAGES.map(async (url) => parseTables(await fetchText(url))),
+	);
+	const data = emptyData();
+	for (const tables of pages) {
+		for (const [key, score] of extractNumericColumn(
+			tables,
+			/intelligence/i,
+		)) {
+			if (!data.intelligence.has(key)) data.intelligence.set(key, score);
+		}
+		for (const [key, tps] of extractNumericColumn(tables, TPS_HEADER)) {
+			if (!data.tps.has(key)) data.tps.set(key, tps);
+		}
+	}
+	return data;
+}

package/src/data/bench/index.ts

@@ -0,0 +1,126 @@
+import { loadCc } from "./cc.ts";
+import { loadAaFallback, loadAaWeb, resolvePrimary } from "./resolve.ts";
+import { fillFromCache, readAbilityCache, writeAbilityCache } from "./store.ts";
+import type { AbilityOptions, AbilityResult } from "./types.ts";
+
+export type {
+	AbilityOptions,
+	AbilityResult,
+	AbilitySource,
+	BenchData,
+} from "./types.ts";
+
+function merge(
+	into: Map<string, number>,
+	from: Map<string, number>,
+	keys?: Set<string>,
+): number {
+	let added = 0;
+	for (const [key, score] of from) {
+		if (keys && !keys.has(key)) continue;
+		if (!into.has(key)) {
+			into.set(key, score);
+			added++;
+		}
+	}
+	return added;
+}
+
+function prune(map: Map<string, number>, keys?: Set<string>): void {
+	if (!keys) return;
+	for (const key of [...map.keys()]) if (!keys.has(key)) map.delete(key);
+}
+
+/**
+ * Load benchmark scores. The chosen source leads; unless --no-fallback, any
+ * model it misses is filled from the other sources so a model scored anywhere
+ * shows a value. The whole result is cached: a source that is down — or a page
+ * that silently dropped a column — falls back to the last good run rather than
+ * blanking a column.
+ */
+export async function loadAbility(
+	opts: AbilityOptions,
+): Promise<AbilityResult> {
+	let live: AbilityResult;
+	try {
+		live = await loadLiveAbility(opts);
+	} catch (error) {
+		// Refresh must not strand the caller: an outage still has the cache.
+		const cached = await readAbilityCache(false);
+		if (!cached) throw error;
+		return {
+			...cached,
+			label: "cached (benchmark sources unavailable)",
+			note:
+				error instanceof Error
+					? error.message.slice(0, 120)
+					: undefined,
+		};
+	}
+	const cached = await readAbilityCache(Boolean(opts.refresh));
+	const filled = cached ? fillFromCache(live, cached) : 0;
+	await writeAbilityCache(live);
+	if (filled === 0) return live;
+	return {
+		...live,
+		note: [live.note, `${filled} values from the last cached run`]
+			.filter(Boolean)
+			.join(", "),
+	};
+}
+
+async function loadLiveAbility(opts: AbilityOptions): Promise<AbilityResult> {
+	const primary = await resolvePrimary(opts);
+	// CommandCode and Artificial Analysis publish the same intelligence index, so
+	// a CC primary normally needs no second round-trip. That premise only covered
+	// the index though: CC's plan pages dropped their `Tok/s` column (Sep 2026),
+	// so a CC primary with no speed values has to ask AA after all — otherwise
+	// every model reports speed null and the consumers drop the row.
+	const needsSpeed = primary.data.tps.size === 0;
+	if (!opts.fallback || (primary.scheme === "cc" && !needsSpeed)) {
+		return { ...primary.data, label: primary.label };
+	}
+
+	const fills: string[] = [];
+	// The API leads, so give the same benchmark's keyless page scrape a second
+	// look (cached, free when warm) before the cross-source fallback.
+	if (primary.scheme === "aa") {
+		const web = await loadAaWeb(opts);
+		const added = merge(
+			primary.data.intelligence,
+			web.intelligence,
+			opts.keys,
+		);
+		if (added > 0) fills.push(`${added} values from AA web scrape`);
+	}
+	{
+		const cc = await loadCc();
+		const added =
+			merge(primary.data.intelligence, cc.intelligence, opts.keys) +
+			merge(primary.data.tps, cc.tps, opts.keys);
+		if (added > 0) fills.push(`${added} values from CommandCode`);
+	}
+	if (primary.scheme !== "aa-web" && primary.scheme !== "aa") {
+		const fallback = await loadAaFallback(opts);
+		const added =
+			merge(
+				primary.data.intelligence,
+				fallback.data.intelligence,
+				opts.keys,
+			) + merge(primary.data.tps, fallback.data.tps, opts.keys);
+		if (added > 0) {
+			fills.push(
+				`${added} values from Artificial Analysis (${fallback.how})`,
+			);
+		}
+	}
+
+	prune(primary.data.intelligence, opts.keys);
+	prune(primary.data.tps, opts.keys);
+
+	return {
+		...primary.data,
+		label: primary.label,
+		note: fills.length > 0 ? `filled ${fills.join(", ")}` : undefined,
+	};
+}