@dzhechkov/harness-cli 0.3.198 → 0.3.200

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.198",
+  "version": "0.3.200",
   "description": "The dz CLI — install AI skills for Claude Code, Codex, OpenCode, Hermes, OpenClaude, GitHub Copilot. 35 commands, 13 presets, 6 platform targets.",
   "type": "module",
   "license": "MIT",
@@ -37,15 +37,7 @@
     "src",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "tsc -p tsconfig.json --noEmit"
-  },
   "dependencies": {
-    "@dzhechkov/harness-core": "workspace:*",
     "@dzhechkov/harness-presets": "^0.5.0",
     "@dzhechkov/scout": "^0.8.0",
     "@dzhechkov/skills-devops": "^0.3.0",
@@ -61,7 +53,8 @@
     "@dzhechkov/skills-idea2prd": "^0.1.0",
     "@dzhechkov/skills-reverse-engineering": "^0.1.0",
     "@dzhechkov/skills-presentation-storyteller": "^0.1.0",
-    "@dzhechkov/skills-website-cloner": "^0.1.0"
+    "@dzhechkov/skills-website-cloner": "^0.1.0",
+    "@dzhechkov/harness-core": "0.3.100"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
@@ -79,5 +72,12 @@
     "url": "https://github.com/djd1m/dz-harness-hub.git",
     "directory": "packages/@dzhechkov/harness-cli"
   },
-  "homepage": "https://github.com/djd1m/dz-harness-hub/tree/main/packages/@dzhechkov/harness-cli#readme"
-}
+  "homepage": "https://github.com/djd1m/dz-harness-hub/tree/main/packages/@dzhechkov/harness-cli#readme",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/cli.ts

@@ -67,6 +67,8 @@ import {
   statuslineData,
   writeFeatureAdrState,
   computeUsage,
+  deriveUsageCalibration,
+  normalizeClaudeUsageModelKey,
   readUsageLimits,
   queryBookKnowledge,
   loadStorePatternsSync,
@@ -84,7 +86,7 @@ import {
   importBrainSlice,
   registerKusToBrain,
 } from '@dzhechkov/harness-core';
-import type { PatternRecord, TargetName, BookKU, HarmonizeReport } from '@dzhechkov/harness-core';
+import type { ClaudeUsageModel, PatternRecord, TargetName, BookKU, HarmonizeReport, UsageCalibrationPlan } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
 import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, ScoutMemory } from '@dzhechkov/scout';
 
@@ -127,7 +129,7 @@ Usage:
   dz brain init  [--project <dir>] [--k <N>]                           (wire the grounding hook into .claude/settings.json — opt-in)
   dz statusline [--json] [--install] [--project <dir>]                 (live self-learning panel for Claude Code's status bar; reads the CC JSON payload from STDIN)
   dz statusline --fa-record --slug <s> --step "<label>" [--recalled <n>] [--stored <n>] [--mode <m>]   (feature-adr: record live per-run learning state → 📐 panel segment)
-  dz usage [--json] [--project <dir>]                                  (ESTIMATE Claude session (5h-block) + weekly (7d) token usage from local transcripts; exit 0 ALWAYS; pct=null when memory.usage.{sessionTokenLimit,weeklyTokenLimit} unconfigured in .dz/config.json)
+  dz usage [--json] [--project <dir>] | dz usage --calibrate --session <pct> --weekly <pct> [--model fable=<pct>] [--project <dir>]  (ESTIMATE Claude usage from fixed reset windows; optional per-model weekly binding; exit 0 ALWAYS; pct=null when limits unconfigured)
   dz pretrain [--project <dir>]
   dz recommend "<task description>"
   dz compose <preset1+preset2+...> [--target <name>]
@@ -170,12 +172,14 @@ export interface CliIo {
 interface ParsedArgs {
   readonly command: string;
   readonly options: Map<string, string>;
+  readonly optionLists: Map<string, string[]>;
   readonly flags: Set<string>;
 }
 
 /** Parse `<command> [--key value] [--flag]` argv. */
 function parseArgs(argv: string[]): ParsedArgs {
   const options = new Map<string, string>();
+  const optionLists = new Map<string, string[]>();
   const flags = new Set<string>();
   const positional: string[] = [];
 
@@ -186,6 +190,9 @@ function parseArgs(argv: string[]): ParsedArgs {
       const next = argv[index + 1];
       if (next !== undefined && !next.startsWith('--')) {
         options.set(key, next);
+        const list = optionLists.get(key) ?? [];
+        list.push(next);
+        optionLists.set(key, list);
         index += 1;
       } else {
         flags.add(key);
@@ -200,7 +207,7 @@ function parseArgs(argv: string[]): ParsedArgs {
     options.set(`_positional_${pi - 1}`, positional[pi] ?? '');
   }
 
-  return { command: positional[0] ?? '', options, flags };
+  return { command: positional[0] ?? '', options, optionLists, flags };
 }
 
 type Write = (line: string) => void;
@@ -1112,18 +1119,187 @@ function cmdStatusline(
   }
 }
 
+function isJsonRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function usageConfigPath(projectRoot: string): string {
+  return join(projectRoot, '.dz', 'config.json');
+}
+
+function readProjectConfigForUsage(projectRoot: string): { config: Record<string, unknown>; warning?: string } {
+  const path = usageConfigPath(projectRoot);
+  try {
+    if (!existsSync(path)) return { config: {} };
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown;
+    if (isJsonRecord(parsed)) return { config: parsed };
+    return { config: {}, warning: 'existing config is not a JSON object; writing a minimal config' };
+  } catch {
+    return { config: {}, warning: 'existing config could not be parsed; writing a minimal config' };
+  }
+}
+
+function applyUsageCalibrationToConfig(config: Record<string, unknown>, plan: UsageCalibrationPlan): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...config };
+  const memory = isJsonRecord(next['memory']) ? { ...next['memory'] } : {};
+  const usage = isJsonRecord(memory['usage']) ? { ...memory['usage'] } : {};
+
+  for (const change of plan.changes) {
+    if (change.key === 'session') {
+      usage['sessionTokenLimit'] = change.after;
+    } else if (change.key === 'weekly') {
+      usage['weeklyTokenLimit'] = change.after;
+    } else {
+      const model = normalizeClaudeUsageModelKey(change.key);
+      if (model) {
+        const existingByModel = isJsonRecord(usage['weeklyTokenLimitByModel']) ? { ...usage['weeklyTokenLimitByModel'] } : {};
+        existingByModel[model] = change.after;
+        usage['weeklyTokenLimitByModel'] = existingByModel;
+      }
+    }
+  }
+
+  if (plan.changes.length > 0) {
+    usage['calibratedAt'] = plan.after.calibratedAt;
+    usage['source'] = plan.after.source;
+  }
+
+  memory['usage'] = usage;
+  next['memory'] = memory;
+  return next;
+}
+
+function parseUsageModelArgs(modelArgs: readonly string[]): { modelPct: Record<string, unknown>; skipped: string[] } {
+  const modelPct: Record<string, unknown> = {};
+  const skipped: string[] = [];
+  for (const raw of modelArgs) {
+    const eq = raw.indexOf('=');
+    if (eq <= 0 || eq === raw.length - 1) {
+      skipped.push(`model ${raw}: skipped malformed model=pct argument`);
+      continue;
+    }
+    const modelName = raw.slice(0, eq).trim();
+    const model = normalizeClaudeUsageModelKey(modelName);
+    if (!model) {
+      skipped.push(`model ${modelName}: skipped unknown model`);
+      continue;
+    }
+    modelPct[model] = raw.slice(eq + 1).trim();
+  }
+  return { modelPct, skipped };
+}
+
+function writeUsageCalibrationSummary(opts: {
+  projectRoot: string;
+  plan: UsageCalibrationPlan;
+  preSkipped: readonly string[];
+  configWarning?: string | undefined;
+  wrote: boolean;
+  write: Write;
+}): void {
+  opts.write('usage calibrate: estimated local transcript counts; claude.ai/settings/usage is authoritative');
+  opts.write(`usage calibrate: project ${opts.projectRoot}`);
+  if (opts.configWarning) opts.write(`usage calibrate: ${opts.configWarning}`);
+  for (const change of opts.plan.changes) {
+    opts.write(
+      `usage calibrate: ${change.key} tokens=${change.tokens} pct=${change.pct}% limit ${change.before ?? 'null'} -> ${change.after}`,
+    );
+  }
+  const skipped = [...opts.preSkipped, ...opts.plan.skipped];
+  for (const item of skipped) opts.write(`usage calibrate: skipped ${item}`);
+  if (opts.wrote) {
+    opts.write('usage calibrate: wrote .dz/config.json with source claude.ai/settings/usage');
+  } else {
+    opts.write('usage calibrate: no config changes written');
+  }
+}
+
+function cmdUsageCalibrate(
+  options: Map<string, string>,
+  optionLists: Map<string, string[]>,
+  cwd: string,
+  write: Write,
+): number {
+  const projectRoot = resolve(cwd, options.get('project') ?? '.');
+  const suppliedModels = optionLists.get('model') ?? [];
+  const parsedModels = parseUsageModelArgs(suppliedModels);
+  const modelPct = parsedModels.modelPct;
+  const hasModelPct = Object.keys(modelPct).length > 0;
+  const input = {
+    ...(options.has('session') ? { sessionPct: options.get('session') } : {}),
+    ...(options.has('weekly') ? { weeklyPct: options.get('weekly') } : {}),
+    ...(hasModelPct ? { modelPct } : {}),
+    calibratedAt: new Date().toISOString(),
+    source: 'claude.ai/settings/usage' as const,
+  };
+  const missingInputs: string[] = [];
+  if (!options.has('session') && !options.has('weekly') && !hasModelPct) {
+    missingInputs.push('no calibration percentages supplied');
+  }
+
+  try {
+    const current = computeUsage(projectRoot);
+    const before = readUsageLimits(projectRoot);
+    const plan = deriveUsageCalibration(current, before, input);
+    if (plan.changes.length === 0) {
+      writeUsageCalibrationSummary({
+        projectRoot,
+        plan,
+        preSkipped: [...parsedModels.skipped, ...missingInputs],
+        wrote: false,
+        write,
+      });
+      return 0;
+    }
+
+    const existing = readProjectConfigForUsage(projectRoot);
+    const nextConfig = applyUsageCalibrationToConfig(existing.config, plan);
+    try {
+      mkdirSync(join(projectRoot, '.dz'), { recursive: true });
+      writeFileSync(usageConfigPath(projectRoot), JSON.stringify(nextConfig, null, 2) + '\n');
+      writeUsageCalibrationSummary({
+        projectRoot,
+        plan,
+        preSkipped: [...parsedModels.skipped, ...missingInputs],
+        configWarning: existing.warning,
+        wrote: true,
+        write,
+      });
+    } catch {
+      writeUsageCalibrationSummary({
+        projectRoot,
+        plan,
+        preSkipped: [...parsedModels.skipped, ...missingInputs, 'write failed'],
+        configWarning: existing.warning,
+        wrote: false,
+        write,
+      });
+    }
+    return 0;
+  } catch {
+    write('usage calibrate: skipped internal error; no config changes written');
+    return 0;
+  }
+}
+
 /**
- * `dz usage` — print an ESTIMATE of Claude session (active 5h-block) + weekly (rolling 7d) token
- * usage, aggregated READONLY from the local transcript store (see {@link computeUsage}). `--json`
- * emits the single-line contract the feature-adr usage-probe agent parses; the human path prints a
- * compact `session ~74% (resets 19:00) · week ~52% (resets Sat)` or an unconfigured hint.
+ * `dz usage` — print an ESTIMATE of Claude session + weekly usage from fixed reset windows,
+ * aggregated READONLY from the local transcript store (see {@link computeUsage}). `--json` emits
+ * the single-line contract the feature-adr usage-probe agent parses; `--calibrate` is the only
+ * write path and records human-transcribed claude.ai percentages in `.dz/config.json`.
  *
  * **Exit code is 0 ALWAYS** — including on internal error the whole body is guarded and prints the
  * all-null JSON, so a probe can NEVER distinguish "usage unknown" from "command failed" via a
- * non-zero exit (unknown is a first-class value, INV-3). `--project <dir>` scopes ONLY the
- * `.dz/config.json` limits read; the measurement is account-wide (all projects, FR-1.6).
+ * non-zero exit. `--project <dir>` scopes ONLY the `.dz/config.json` read/write; measurement is
+ * account-wide (all projects).
  */
-function cmdUsage(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+function cmdUsage(
+  options: Map<string, string>,
+  optionLists: Map<string, string[]>,
+  flags: Set<string>,
+  cwd: string,
+  write: Write,
+): number {
   const projectRoot = resolve(cwd, options.get('project') ?? '.');
   const nullContract = () =>
     JSON.stringify({
@@ -1136,19 +1312,40 @@ function cmdUsage(options: Map<string, string>, flags: Set<string>, cwd: string,
       estimated: true,
     });
   try {
+    if (flags.has('calibrate')) return cmdUsageCalibrate(options, optionLists, cwd, write);
+
     const u = computeUsage(projectRoot);
     const lim = readUsageLimits(projectRoot);
+    const modelLimits = lim.weeklyTokenLimitByModel;
+    const hasModelLimits = modelLimits !== undefined && Object.keys(modelLimits).length > 0;
     if (flags.has('json')) {
+      const limitsPayload: {
+        session: number | null;
+        weekly: number | null;
+        weeklyByModel?: Partial<Record<ClaudeUsageModel, number>>;
+      } = { session: lim.sessionTokenLimit ?? null, weekly: lim.weeklyTokenLimit ?? null };
+      if (hasModelLimits) limitsPayload.weeklyByModel = { ...modelLimits };
+      const payload: {
+        sessionPct: number | null;
+        weeklyPct: number | null;
+        sessionTokens: number;
+        weeklyTokens: number;
+        resetsAt: { session: string | null; weekly: string | null };
+        limits: typeof limitsPayload;
+        weeklyByModel?: typeof u.weeklyByModel;
+        estimated: true;
+      } = {
+        sessionPct: u.sessionPct,
+        weeklyPct: u.weeklyPct,
+        sessionTokens: u.sessionTokens,
+        weeklyTokens: u.weeklyTokens,
+        resetsAt: { session: u.sessionResetsAt, weekly: u.weeklyResetsAt },
+        limits: limitsPayload,
+        estimated: true,
+      };
+      if (hasModelLimits && u.weeklyByModel !== undefined) payload.weeklyByModel = u.weeklyByModel;
       write(
-        JSON.stringify({
-          sessionPct: u.sessionPct,
-          weeklyPct: u.weeklyPct,
-          sessionTokens: u.sessionTokens,
-          weeklyTokens: u.weeklyTokens,
-          resetsAt: { session: u.sessionResetsAt, weekly: u.weeklyResetsAt },
-          limits: { session: lim.sessionTokenLimit ?? null, weekly: lim.weeklyTokenLimit ?? null },
-          estimated: true,
-        }),
+        JSON.stringify(payload),
       );
       return 0;
     }
@@ -1168,7 +1365,8 @@ function cmdUsage(options: Map<string, string>, flags: Set<string>, cwd: string,
       }
     };
     const s = u.sessionPct === null ? 'n/a' : '~' + u.sessionPct + '%';
-    const w = u.weeklyPct === null ? 'n/a' : '~' + u.weeklyPct + '%';
+    const binding = hasModelLimits && u.weeklyBindingModel !== undefined ? ' ' + u.weeklyBindingModel + '-bound' : '';
+    const w = u.weeklyPct === null ? 'n/a' : '~' + u.weeklyPct + '%' + binding;
     write('usage: session ' + s + ' (resets ' + clock(u.sessionResetsAt) + ') · week ' + w + ' (resets ' + clock(u.weeklyResetsAt) + ') · estimated');
     return 0;
   } catch {
@@ -1180,7 +1378,7 @@ function cmdUsage(options: Map<string, string>, flags: Set<string>, cwd: string,
 }
 
 async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): Promise<number> {
-  const projectRoot = options.get('project') ?? cwd;
+  const projectRoot = resolve(cwd, options.get('project') ?? '.');
 
   // Vector tier (dz-rvf-vector-bridge FR-1): best-effort mirror AFTER the lexical write is
   // durable (I-3). Auto-gated on the agentdb memory backend / an explicit vector-engine config
@@ -3461,7 +3659,7 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
       return '';
     }
   };
-  const { command, options, flags } = parseArgs(argv);
+  const { command, options, optionLists, flags } = parseArgs(argv);
 
   if (command === '' || command === 'help' || flags.has('help')) {
     write(USAGE);
@@ -3482,7 +3680,7 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
       case 'create-skill':
         return cmdCreateSkill(options, flags, cwd, write);
       case 'info':
-        return cmdInfo(options, { command, options, flags }, cwd, write);
+        return cmdInfo(options, { command, options, optionLists, flags }, cwd, write);
       case 'scout':
         return await cmdScout(options, flags, cwd, write);
       case 'workflow':
@@ -3508,7 +3706,7 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
       case 'statusline':
         return cmdStatusline(options, flags, cwd, write, readStdin);
       case 'usage':
-        return cmdUsage(options, flags, cwd, write);
+        return cmdUsage(options, optionLists, flags, cwd, write);
       case 'setup':
         return await cmdSetup(options, flags, cwd, write);
       case 'pretrain':