dsh-token-chart 0.0.0-stage → 0.1.0

package/lib/types/store.d.ts

@@ -0,0 +1,72 @@
+import type { Buckets, SessionEvent, TurnRecord, TurnRow } from './types.ts';
+/** Serialised store file. */
+export interface StoreDocument {
+    version: number;
+    savedAt: number;
+    retentionDays: number;
+    sessions: Array<{
+        id: string;
+        turns: Array<Record<string, unknown>>;
+    }>;
+}
+/**
+ * Rolling usage store: session → turn → bucket totals, with the same
+ * replacement semantics the shipped `tokenUsage` projection uses, so the
+ * numbers a reader sees here agree with the product's own "用量" pill.
+ */
+/** One session's turns, keyed by turn number. */
+export interface SessionRecord {
+    turns: Map<number, TurnRecord>;
+}
+export declare class UsageStore {
+    #private;
+    /** Session id → its turns. */
+    readonly sessions: Map<string, SessionRecord>;
+    /** One session record, created on demand. */
+    session(sessionId: string): SessionRecord;
+    /**
+     * Fold one committed session event into the store.
+     *
+     * Mirrors `@deepseek-ai/dsh-token-meter`'s `tokenUsage` projection — each
+     * settlement contributes the last usage sample in its stream, a resample of
+     * the same slot replaces rather than adds, and `llm/retry-started` opens a new
+     * slot so a retried attempt bills again — but stores one bucket set per
+     * `(step, attempt)` instead of a single running slot. That difference is what
+     * makes the fold idempotent: folding the same log twice yields the same
+     * totals, which the product's single-slot fold does not survive.
+     * @param sessionId - the session the event was committed to.
+     * @param event - one durable session event.
+     * @returns whether the store changed.
+     */
+    apply(sessionId: string, event: SessionEvent): boolean;
+    /**
+     * The session's whole-window totals, folded from the per-slot buckets.
+     *
+     * This is deliberately not "the sum of the turn rows a reader sees": it is
+     * one fold over every settled (turn, step, attempt) of the session, which is
+     * the same rule the product's own `tokenUsage` projection applies. The two
+     * agree by construction, but the intent — and any future change — belongs
+     * here, not in the presentation layer.
+     * @param sessionId - the session to total.
+     */
+    sessionTotals(sessionId: string): Buckets;
+    /** Drop turns older than the retention window and empty sessions. */
+    prune(now?: number): boolean;
+    /** Every turn of every session inside the retention window, oldest first. */
+    turns(): TurnRow[];
+    /** Per-turn rows of one session, ordered by turn. */
+    sessionTurns(sessionId: string): TurnRow[];
+    hasSession(sessionId: string): boolean;
+    /** Serialize the retention window to plain JSON. */
+    toJSON(): StoreDocument;
+    /**
+     * Restore a serialized store, dropping anything outside the window.
+     *
+     * A document from an older schema is discarded rather than interpreted: the
+     * activation-time backfill rebuilds it from the session logs, and guessing at
+     * a superseded layout is exactly how a total drifts.
+     * @param document - the parsed store file.
+     * @returns whether the document was accepted.
+     */
+    load(document: unknown): boolean;
+}

package/lib/types/types.d.ts

@@ -0,0 +1,230 @@
+/**
+ * The contract both halves share: preference shape, usage buckets, and the
+ * JSON reports the browser half consumes.
+ *
+ * The browser half imports the same file, so nothing here may reference Node
+ * or DOM globals.
+ *
+ * @module dsh-token-chart/types
+ */
+/** Provider-reported usage for one settlement, already normalised. */
+export interface Buckets {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+/** Buckets plus the two derived numbers every surface shows. */
+export interface Derived extends Buckets {
+    /** `input + cacheRead + cacheWrite` — what the provider bills as prompt. */
+    cache: number;
+    /** billed input + output. */
+    total: number;
+    /** `cacheRead / (input + cacheRead + cacheWrite)`. */
+    cacheHitRate: number;
+}
+export type MetricId = 'input' | 'output' | 'cache' | 'total';
+export type ChartId = 'bar' | 'line' | 'pie' | 'table' | 'multi-bar' | 'multi-line' | 'bar-line';
+/** User-facing preferences, stored on the Host and mirrored in the page. */
+export interface Prefs {
+    sessionChart: ChartId;
+    dailyChart: ChartId;
+    sessionMetrics: MetricId[];
+    dailyMetrics: MetricId[];
+    showTable: boolean;
+    showCacheHitRate: boolean;
+    interceptUsageButton: boolean;
+}
+/** One usage chunk as a provider reports it. */
+export interface UsageSample {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    totalTokens?: number;
+}
+/** One committed session event, structurally narrowed to what the fold reads. */
+export interface SessionEvent {
+    type?: string;
+    seq?: number;
+    time?: number;
+    data?: {
+        turn?: number;
+        step?: number;
+        stream?: readonly unknown[];
+        usage?: UsageSample;
+        message?: {
+            source?: {
+                provider?: string;
+                model?: string;
+            };
+        };
+        [key: string]: unknown;
+    };
+}
+/** Per-turn store record: one bucket slot per settled `(step, attempt)`. */
+export interface TurnRecord {
+    turn: number;
+    time: number;
+    lastTime: number;
+    slots: Map<string, Buckets>;
+    attempts: Map<number, number>;
+    totals: Buckets;
+    routes: string[];
+}
+/** A turn as the reports expose it (slot bookkeeping stays inside the store). */
+export interface TurnRow {
+    sessionId: string;
+    turn: number;
+    time: number;
+    lastTime: number;
+    totals: Buckets;
+    routes: string[];
+}
+/** One calendar day of the daily panel. */
+export interface DayBucket extends Derived {
+    key: string;
+    label: string;
+    turns: number;
+    sessions: number;
+}
+/** One point of the "today" chart: a single turn, in time order. */
+export interface Point extends Derived {
+    time: number;
+    label: string;
+    day: string;
+    sessionId: string;
+    turn: number;
+}
+/** Cross-check of our fold against the product's own `tokenUsage` projection. */
+export interface CrossCheck {
+    source: 'sessionProjection' | 'unavailable';
+    total?: number;
+    matches?: boolean;
+}
+/** `GET /session` payload. */
+export interface SessionReport {
+    sessionId: string;
+    turns: Array<Derived & {
+        turn: number;
+        time: number;
+        label: string;
+        routes: string[];
+    }>;
+    totals: Derived & {
+        turns: number;
+        firstTime: number;
+        lastTime: number;
+        routes: string[];
+    };
+    crossCheck: CrossCheck;
+}
+/** `GET /overview` payload. */
+export interface OverviewReport {
+    range: string;
+    days: number;
+    floor: number;
+    generatedAt: number;
+    retentionDays: number;
+    buckets: DayBucket[];
+    points: Point[];
+    totals: Derived & {
+        turns: number;
+        sessions: number;
+    };
+}
+/** `GET /version` payload. */
+export interface VersionReport {
+    name: string;
+    version: string;
+    registry: string;
+    status: 'ok' | 'unpublished' | 'error' | 'unknown';
+    latest: string | null;
+    updateAvailable: boolean;
+    checkedAt: number;
+    install: {
+        kind: 'registry' | 'local' | 'unknown';
+        spec: string;
+    };
+    run: UpdateRun;
+}
+/** State of the one update attempt this Host may be running. */
+export interface UpdateRun {
+    phase: 'idle' | 'running' | 'done' | 'failed' | 'manual';
+    startedAt: number;
+    finishedAt: number;
+    message: string;
+    error: string;
+}
+/** Uniform success/failure envelope of every route. */
+export type ApiEnvelope<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        command?: string;
+    };
+};
+/** Logger face a Host plugin may rely on. */
+export interface Logger {
+    info?: (...args: unknown[]) => void;
+    warn?: (...args: unknown[]) => void;
+}
+/** `ctx.sessionQuery` — read committed session logs for the backfill. */
+export interface SessionQueryLike {
+    listSessions: () => Promise<Array<{
+        header?: {
+            id?: string;
+        };
+    }>>;
+    readSession: (sessionId: string) => Promise<{
+        events?: SessionEvent[];
+    } | undefined>;
+}
+/** `ctx.sessions` — live Session objects, needed by the projection cross-check. */
+export interface SessionsLike {
+    get: (sessionId: string) => unknown;
+}
+/** `ctx.sessionProjections` — read the product's own fold for one session. */
+export interface SessionProjectionsLike {
+    stateOf: (session: unknown, key: string) => {
+        totals?: Record<string, number>;
+    } | undefined;
+}
+/** `ctx.pluginManager` — the install path shared with `dsh plugin add`. */
+export interface PluginManagerLike {
+    installBundle: (spec: string, options?: Record<string, unknown>) => Promise<{
+        application?: string;
+    } | undefined>;
+}
+/** Minimal HTTP request/response faces the routes need. */
+export interface HttpRequest {
+    method?: string;
+    url?: string;
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+}
+export interface HttpResponse {
+    statusCode: number;
+    setHeader: (name: string, value: string) => void;
+    end: (body?: string) => void;
+}
+/** Where the Host registers a route. */
+export interface WebServerLike {
+    register: (route: {
+        kind: 'prefix' | 'exact';
+        path: string;
+        handler: (req: HttpRequest, res: HttpResponse) => void | Promise<void>;
+    }) => () => void;
+}
+/** The Cordis context surface this plugin uses, typed structurally. */
+export interface HostContext {
+    logger?: Logger;
+    effect: (callback: () => unknown, description?: string) => unknown;
+    on: (name: string, callback: (...args: any[]) => void) => () => void;
+    inject: (deps: string[], callback: (services: Record<string, any>) => unknown) => unknown;
+    pluginManager?: PluginManagerLike;
+    webServer?: WebServerLike;
+}

package/lib/types/update.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Compare two dotted versions, tolerating a prerelease suffix.
+ *
+ * `1.2.0` outranks `1.2.0-rc.1`, and a missing numeric segment counts as 0, so
+ * the check never offers a downgrade for tags like `0.2.0-rc.2` + `0.2.0`.
+ * @param left - the version in hand.
+ * @param right - the candidate version.
+ * @returns -1, 0 or 1 for left < right, equal, left > right.
+ */
+export declare function compareVersions(left: unknown, right: unknown): -1 | 0 | 1;
+/** The registry the profile installs from, read from its `.npmrc` when present. */
+export declare function profileRegistry(): string;
+/** The package's own manifest, read next to this module. */
+export declare function readOwnManifest(): Promise<{
+    name: string;
+    version: string;
+}>;
+/**
+ * Ask a registry for a package's `latest` dist-tag.
+ * @param packageName - the package to look up.
+ * @param registry - registry base URL.
+ * @returns the version string, or undefined when the registry has no such package.
+ */
+export declare function fetchLatestVersion(packageName: string, registry?: string): Promise<string | undefined>;

package/lib/types.js

@@ -0,0 +1,10 @@
+/**
+ * The contract both halves share: preference shape, usage buckets, and the
+ * JSON reports the browser half consumes.
+ *
+ * The browser half imports the same file, so nothing here may reference Node
+ * or DOM globals.
+ *
+ * @module dsh-token-chart/types
+ */
+export {};

package/lib/update.js

@@ -0,0 +1,110 @@
+/**
+ * Version comparison and the registry lookup behind the update check.
+ *
+ * @module dsh-token-chart/update
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { DEFAULT_REGISTRY, PACKAGE_NAME, UPDATE_FETCH_TIMEOUT_MS } from './constants.js';
+/**
+ * Compare two dotted versions, tolerating a prerelease suffix.
+ *
+ * `1.2.0` outranks `1.2.0-rc.1`, and a missing numeric segment counts as 0, so
+ * the check never offers a downgrade for tags like `0.2.0-rc.2` + `0.2.0`.
+ * @param left - the version in hand.
+ * @param right - the candidate version.
+ * @returns -1, 0 or 1 for left < right, equal, left > right.
+ */
+export function compareVersions(left, right) {
+    const parse = (value) => {
+        const text = String(value ?? '')
+            .trim()
+            .replace(/^v/, '');
+        const [core, ...rest] = text.split('-');
+        const numbers = core.split('.').map((part) => {
+            const parsed = Number.parseInt(part, 10);
+            return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : 0;
+        });
+        while (numbers.length < 3)
+            numbers.push(0);
+        return { numbers, prerelease: rest.join('-') };
+    };
+    const a = parse(left);
+    const b = parse(right);
+    for (let index = 0; index < 3; index += 1) {
+        if (a.numbers[index] !== b.numbers[index])
+            return a.numbers[index] < b.numbers[index] ? -1 : 1;
+    }
+    if (a.prerelease === b.prerelease)
+        return 0;
+    if (a.prerelease === '')
+        return 1;
+    if (b.prerelease === '')
+        return -1;
+    return a.prerelease < b.prerelease ? -1 : 1;
+}
+/** The registry the profile installs from, read from its `.npmrc` when present. */
+export function profileRegistry() {
+    const dir = process.env.DSH_PROFILE_DIR;
+    if (typeof dir !== 'string' || dir.trim() === '')
+        return DEFAULT_REGISTRY;
+    try {
+        const text = readFileSync(path.join(dir.trim(), '.npmrc'), 'utf8');
+        const match = /^\s*registry\s*=\s*(\S+)\s*$/m.exec(text);
+        if (match === null)
+            return DEFAULT_REGISTRY;
+        return match[1].endsWith('/') ? match[1] : `${match[1]}/`;
+    }
+    catch {
+        return DEFAULT_REGISTRY;
+    }
+}
+/** The package's own manifest, read next to this module. */
+export async function readOwnManifest() {
+    // The Host artifact lives in `lib/`, one level below the package root, while a
+    // source-mode run sits in `src/`. Try the package root first, then the module's
+    // own directory, so neither layout silently falls back to a placeholder version.
+    const candidates = [new URL('../package.json', import.meta.url), new URL('./package.json', import.meta.url)];
+    for (const url of candidates) {
+        try {
+            const parsed = JSON.parse(await readFile(url, 'utf8'));
+            if (typeof parsed.version === 'string' && parsed.version !== '') {
+                return { name: String(parsed.name ?? PACKAGE_NAME), version: parsed.version };
+            }
+        }
+        catch {
+            /* try the next candidate */
+        }
+    }
+    return { name: PACKAGE_NAME, version: '0.0.0' };
+}
+/**
+ * Ask a registry for a package's `latest` dist-tag.
+ * @param packageName - the package to look up.
+ * @param registry - registry base URL.
+ * @returns the version string, or undefined when the registry has no such package.
+ */
+export async function fetchLatestVersion(packageName, registry = DEFAULT_REGISTRY) {
+    const base = registry.endsWith('/') ? registry : `${registry}/`;
+    const url = `${base}${encodeURIComponent(packageName).replace('%40', '@')}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), UPDATE_FETCH_TIMEOUT_MS);
+    try {
+        const response = await fetch(url, {
+            signal: controller.signal,
+            headers: { accept: 'application/vnd.npm.install-v1+json, application/json' },
+        });
+        if (response.status === 404)
+            return undefined;
+        if (!response.ok)
+            throw new Error(`registry answered ${response.status}`);
+        const body = (await response.json());
+        const latest = body['dist-tags']?.latest;
+        return typeof latest === 'string' && latest !== '' ? latest : undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/* ------------------------------------------------------------------ paths */

package/locale/en.json

@@ -0,0 +1,4 @@
+{
+  "title": "Token usage charts",
+  "description": "Token usage statistics and visualization: a per-session drawer, a today / last 3 days / last 7 days panel, and configurable chart forms."
+}

package/locale/zh.json

@@ -0,0 +1,4 @@
+{
+  "title": "Token 用量图表",
+  "description": "统计并可视化 Token 用量：会话用量抽屉、今天 / 近 3 天 / 近 7 天面板，以及可自由配置的图表形式。"
+}

package/package.json

@@ -1,6 +1,112 @@
 {
   "name": "dsh-token-chart",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Token usage statistics and chart visualization for DeepSeek Harness: per-session drawer, today / last 3 / last 7 days panel, and chart configuration.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": "./lib/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "icon.svg",
+    "locale",
+    "README.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-sidebar",
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
+    }
+  },
+  "meta": {
+    "title": "Token 用量图表",
+    "description": "统计并可视化 Token 用量：会话抽屉、今天 / 近 3 天 / 近 7 天面板与图表配置。"
+  },
+  "icon": "./icon.svg",
+  "engines": {
+    "node": ">=20",
+    "dsh": ">=0.2.0-rc.2"
+  },
+  "author": "lugezuishuai",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lugezuishuai/dsh-token-chart.git"
+  },
+  "homepage": "https://github.com/lugezuishuai/dsh-token-chart#readme",
+  "bugs": {
+    "url": "https://github.com/lugezuishuai/dsh-token-chart/issues"
+  },
+  "keywords": [
+    "deepseek",
+    "harness",
+    "dsh",
+    "dsh-plugin",
+    "token",
+    "usage",
+    "dashboard",
+    "echarts"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "clean": "node -e \"require('node:fs').rmSync('lib',{recursive:true,force:true})\"",
+    "build": "npm run clean && npm run build:host && npm run build:styles && npm run build:client && npm run build:chunk",
+    "build:host": "tsc -p tsconfig.json",
+    "build:styles": "node scripts/build-styles.mjs",
+    "build:client": "node scripts/build-client.mjs",
+    "build:chunk": "node scripts/build-chunk.mjs",
+    "prepare": "npm run build",
+    "prepack": "npm run build && node scripts/preflight.mjs",
+    "prepublishOnly": "node scripts/preflight.mjs",
+    "preflight": "node scripts/preflight.mjs",
+    "check": "npm run typecheck && npm run build && node scripts/preflight.mjs && npm run test:host",
+    "test": "vitest run",
+    "test:host": "vitest run --project host",
+    "test:client": "vitest run --project client",
+    "test:watch": "vitest",
+    "format": "prettier --write 'src/**/*.{ts,tsx}' 'tests/**/*.mjs' 'scripts/**/*.mjs'"
+  },
+  "devDependencies": {
+    "@tailwindcss/cli": "^4.3.3",
+    "@types/node": "^26.6.4",
+    "@types/react": "^18.3.31",
+    "@types/react-dom": "^18.3.7",
+    "echarts": "^6.1.0",
+    "esbuild": "^0.28.2",
+    "jsdom": "^30.1.1",
+    "less": "^4.9.1",
+    "prettier": "^3.9.9",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  }
+}