@dataworks-technology/cli 1.2.0 → 1.4.0

package/dist/lib/agent-install.js

@@ -0,0 +1,196 @@
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const marketplaceName = "dataworks-cli";
+const pluginId = `dataworks@${marketplaceName}`;
+export const supportedAgentClients = ["codex", "claude-code"];
+export function dataworksPackageRoot() {
+    return fileURLToPath(new URL("../../", import.meta.url));
+}
+function defaultRunner(command, args) {
+    const result = spawnSync(command, [...args], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        error: result.error,
+    };
+}
+function executable(client) {
+    return client === "codex" ? "codex" : "claude";
+}
+function failureMessage(result) {
+    return (result.stderr.trim() ||
+        result.stdout.trim() ||
+        result.error?.message ||
+        "The client command failed without an error message.");
+}
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function codexMarketplaceRoot(payload) {
+    if (!payload || typeof payload !== "object")
+        return undefined;
+    const marketplaces = payload.marketplaces;
+    if (!Array.isArray(marketplaces))
+        return undefined;
+    const entry = marketplaces.find((candidate) => !!candidate &&
+        typeof candidate === "object" &&
+        candidate.name === marketplaceName);
+    return entry?.root;
+}
+function claudeMarketplace(payload) {
+    if (!Array.isArray(payload))
+        return { exists: false };
+    const entry = payload.find((candidate) => !!candidate &&
+        typeof candidate === "object" &&
+        candidate.name === marketplaceName);
+    return {
+        exists: !!entry,
+        root: entry?.path ?? entry?.installLocation,
+    };
+}
+function pluginIsInstalled(client, payload) {
+    const entries = client === "codex" && payload && typeof payload === "object"
+        ? payload.installed
+        : payload;
+    if (!Array.isArray(entries))
+        return false;
+    return entries.some((entry) => {
+        if (!entry || typeof entry !== "object")
+            return false;
+        const item = entry;
+        return (item.id === pluginId ||
+            item.pluginId === pluginId ||
+            (item.name === "dataworks" &&
+                (item.marketplace === marketplaceName ||
+                    item.marketplaceName === marketplaceName)));
+    });
+}
+function unavailable(client) {
+    const binary = executable(client);
+    return {
+        client,
+        status: "unavailable",
+        message: `${binary} is not installed or is not available on PATH.`,
+        nextStep: `Install ${client === "codex" ? "Codex" : "Claude Code"}, then run \`dw agents install ${client}\` again.`,
+    };
+}
+function failed(client, result, nextStep) {
+    return {
+        client,
+        status: "failed",
+        message: failureMessage(result),
+        nextStep,
+    };
+}
+function installCodex(options) {
+    const { run, packageRoot, force } = options;
+    const list = run("codex", ["plugin", "marketplace", "list", "--json"]);
+    if (list.status !== 0) {
+        return failed("codex", list, "Run `codex plugin marketplace list` to inspect the Codex plugin configuration, then retry.");
+    }
+    const listedRoot = codexMarketplaceRoot(parseJson(list.stdout));
+    const currentRoot = listedRoot ? resolve(listedRoot) : undefined;
+    if (currentRoot && currentRoot !== packageRoot) {
+        if (!force) {
+            return {
+                client: "codex",
+                status: "failed",
+                message: `The ${marketplaceName} marketplace already points to ${currentRoot}.`,
+                nextStep: "Run `dw agents install codex --force` to replace the stale marketplace registration.",
+            };
+        }
+        const remove = run("codex", ["plugin", "marketplace", "remove", marketplaceName]);
+        if (remove.status !== 0) {
+            return failed("codex", remove, "Run `codex plugin marketplace list` to inspect the conflicting registration.");
+        }
+    }
+    if (!currentRoot || currentRoot !== packageRoot) {
+        const addMarketplace = run("codex", [
+            "plugin",
+            "marketplace",
+            "add",
+            packageRoot,
+            "--json",
+        ]);
+        if (addMarketplace.status !== 0) {
+            return failed("codex", addMarketplace, `Run \`codex plugin marketplace add ${packageRoot}\`, then retry.`);
+        }
+    }
+    const before = run("codex", ["plugin", "list", "--json"]);
+    const alreadyInstalled = before.status === 0 && pluginIsInstalled("codex", parseJson(before.stdout));
+    const install = run("codex", ["plugin", "add", pluginId, "--json"]);
+    if (install.status !== 0) {
+        return failed("codex", install, `Run \`codex plugin add ${pluginId}\`, then retry.`);
+    }
+    return {
+        client: "codex",
+        status: alreadyInstalled ? "updated" : "installed",
+        message: "The Dataworks skill and query_metrics MCP server are enabled.",
+        nextStep: "Start a new Codex thread before asking a Dataworks metrics question.",
+    };
+}
+function installClaudeCode(options) {
+    const { run, packageRoot, force } = options;
+    const list = run("claude", ["plugin", "marketplace", "list", "--json"]);
+    if (list.status !== 0) {
+        return failed("claude-code", list, "Run `claude plugin marketplace list --json` to inspect the Claude Code plugin configuration, then retry.");
+    }
+    const marketplace = claudeMarketplace(parseJson(list.stdout));
+    const currentRoot = marketplace.root ? resolve(marketplace.root) : undefined;
+    if (marketplace.exists && currentRoot && currentRoot !== packageRoot && !force) {
+        return {
+            client: "claude-code",
+            status: "failed",
+            message: `The ${marketplaceName} marketplace already points to ${currentRoot}.`,
+            nextStep: "Run `dw agents install claude-code --force` to replace the stale marketplace registration.",
+        };
+    }
+    if (marketplace.exists && force) {
+        const remove = run("claude", ["plugin", "marketplace", "remove", marketplaceName]);
+        if (remove.status !== 0) {
+            return failed("claude-code", remove, "Run `claude plugin marketplace list --json` to inspect the conflicting registration.");
+        }
+    }
+    if (!marketplace.exists || force) {
+        const addMarketplace = run("claude", ["plugin", "marketplace", "add", packageRoot]);
+        if (addMarketplace.status !== 0) {
+            return failed("claude-code", addMarketplace, `Run \`claude plugin marketplace add ${packageRoot}\`, then retry.`);
+        }
+    }
+    const before = run("claude", ["plugin", "list", "--json"]);
+    const alreadyInstalled = before.status === 0 && pluginIsInstalled("claude-code", parseJson(before.stdout));
+    const action = alreadyInstalled ? "update" : "install";
+    const install = run("claude", ["plugin", action, pluginId, "--scope", "user"]);
+    if (install.status !== 0) {
+        return failed("claude-code", install, `Run \`claude plugin ${action} ${pluginId} --scope user\`, then retry.`);
+    }
+    return {
+        client: "claude-code",
+        status: alreadyInstalled ? "updated" : "installed",
+        message: "The Dataworks skill and query_metrics MCP server are enabled.",
+        nextStep: "Run `/reload-plugins` in Claude Code, or start a new session.",
+    };
+}
+export function installAgentIntegration(client, options = {}) {
+    const resolved = {
+        force: options.force ?? false,
+        packageRoot: resolve(options.packageRoot ?? dataworksPackageRoot()),
+        run: options.run ?? defaultRunner,
+    };
+    const binary = executable(client);
+    const detected = resolved.run(binary, ["--version"]);
+    if (detected.status !== 0 || detected.error)
+        return unavailable(client);
+    return client === "codex" ? installCodex(resolved) : installClaudeCode(resolved);
+}
+//# sourceMappingURL=agent-install.js.map

package/dist/lib/agent-install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-install.js","sourceRoot":"","sources":["../../src/lib/agent-install.ts"],"names":[],"mappings":"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"}

package/dist/lib/agent-reminder.d.ts

@@ -0,0 +1,17 @@
+export interface AgentReminderPreferences {
+    disabled: boolean;
+    configured: boolean;
+    lastShownAt?: string;
+}
+export interface AgentReminderContext {
+    argv: readonly string[];
+    isTTY: boolean;
+    now?: Date;
+    disabledByEnvironment?: boolean;
+}
+export declare function agentReminderPath(): string;
+export declare function readAgentReminderPreferences(): Promise<AgentReminderPreferences>;
+export declare function shouldShowAgentReminder(preferences: AgentReminderPreferences, context: AgentReminderContext): boolean;
+export declare function maybeShowAgentReminder(argv: readonly string[]): Promise<void>;
+export declare function configureAgentReminder(action: "disable" | "enable" | "configured"): Promise<AgentReminderPreferences>;
+//# sourceMappingURL=agent-reminder.d.ts.map

package/dist/lib/agent-reminder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-reminder.d.ts","sourceRoot":"","sources":["../../src/lib/agent-reminder.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAOD,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAsB,4BAA4B,IAAI,OAAO,CAAC,wBAAwB,CAAC,CAetF;AAYD,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,wBAAwB,EACrC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAUT;AAED,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBnF;AAED,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,YAAY,GAC1C,OAAO,CAAC,wBAAwB,CAAC,CAUnC"}

package/dist/lib/agent-reminder.js

@@ -0,0 +1,81 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { configPath } from "./config-store.js";
+const reminderIntervalMs = 24 * 60 * 60 * 1000;
+const defaultPreferences = {
+    disabled: false,
+    configured: false,
+};
+export function agentReminderPath() {
+    return join(dirname(configPath()), "agent-reminder.json");
+}
+export async function readAgentReminderPreferences() {
+    try {
+        const stored = JSON.parse(await readFile(agentReminderPath(), "utf8"));
+        return {
+            disabled: stored.disabled === true,
+            configured: stored.configured === true,
+            lastShownAt: typeof stored.lastShownAt === "string" ? stored.lastShownAt : undefined,
+        };
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return { ...defaultPreferences };
+        throw error;
+    }
+}
+async function writeAgentReminderPreferences(preferences) {
+    const path = agentReminderPath();
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(preferences, null, 2)}\n`, {
+        mode: 0o600,
+    });
+}
+export function shouldShowAgentReminder(preferences, context) {
+    if (!context.isTTY || context.disabledByEnvironment)
+        return false;
+    if (preferences.disabled || preferences.configured)
+        return false;
+    if (context.argv.includes("--json"))
+        return false;
+    if (context.argv[0] === "agents")
+        return false;
+    if (!preferences.lastShownAt)
+        return true;
+    const lastShown = Date.parse(preferences.lastShownAt);
+    if (!Number.isFinite(lastShown))
+        return true;
+    return (context.now ?? new Date()).getTime() - lastShown >= reminderIntervalMs;
+}
+export async function maybeShowAgentReminder(argv) {
+    try {
+        const preferences = await readAgentReminderPreferences();
+        if (!shouldShowAgentReminder(preferences, {
+            argv,
+            isTTY: process.stderr.isTTY === true,
+            disabledByEnvironment: process.env.DW_NO_AGENT_REMINDER === "1",
+        })) {
+            return;
+        }
+        process.stderr.write("Tip: enable Dataworks in Codex or Claude Code with `dw agents install`.\n" +
+            "Hide this reminder with `dw agents reminder disable`.\n");
+        await writeAgentReminderPreferences({
+            ...preferences,
+            lastShownAt: new Date().toISOString(),
+        });
+    }
+    catch {
+        // A reminder must never block or fail the requested CLI command.
+    }
+}
+export async function configureAgentReminder(action) {
+    const current = await readAgentReminderPreferences();
+    const preferences = action === "disable"
+        ? { ...current, disabled: true }
+        : action === "configured"
+            ? { ...current, configured: true }
+            : { disabled: false, configured: false };
+    await writeAgentReminderPreferences(preferences);
+    return preferences;
+}
+//# sourceMappingURL=agent-reminder.js.map

package/dist/lib/agent-reminder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-reminder.js","sourceRoot":"","sources":["../../src/lib/agent-reminder.ts"],"names":[],"mappings":"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"}

package/dist/lib/command.d.ts

@@ -1,6 +1,7 @@
 import { Command } from "@oclif/core";
 import type { CommandError } from "@oclif/core/interfaces";
 export declare abstract class DataworksCommand extends Command {
+    protected init(): Promise<void>;
     protected catch(error: CommandError): Promise<void>;
 }
 //# sourceMappingURL=command.d.ts.map

package/dist/lib/command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/lib/command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAG3D,8BAAsB,gBAAiB,SAAQ,OAAO;cAC3B,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAiBnE"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/lib/command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAI3D,8BAAsB,gBAAiB,SAAQ,OAAO;cAC3B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;cAKrB,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAiBnE"}

package/dist/lib/command.js

@@ -1,6 +1,11 @@
 import { Command } from "@oclif/core";
 import { toCliError } from "./errors.js";
+import { maybeShowAgentReminder } from "./agent-reminder.js";
 export class DataworksCommand extends Command {
+    async init() {
+        await super.init();
+        await maybeShowAgentReminder(this.argv);
+    }
     async catch(error) {
         const cliError = toCliError(error);
         if (this.argv.includes("--json")) {

package/dist/lib/command.js.map

@@ -1 +1 @@
-{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/lib/command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEtC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,OAAgB,gBAAiB,SAAQ,OAAO;IACjC,KAAK,CAAC,KAAK,CAAC,KAAmB;QAChD,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,IAAI,CAAC,SAAS,CAAC;gBAChB,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ,CAAC,IAAI;oBACnB,OAAO,EAAE,QAAQ,CAAC,OAAO;oBACzB,OAAO,EAAE,QAAQ,CAAC,OAAO;iBAC1B;aACF,CAAC,IAAI,CACP,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,QAAQ,CAAC,IAAI,MAAM,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;QAC1E,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;IACvC,CAAC;CACF"}
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/lib/command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEtC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,MAAM,OAAgB,gBAAiB,SAAQ,OAAO;IACjC,KAAK,CAAC,IAAI;QAC3B,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,MAAM,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;IAEkB,KAAK,CAAC,KAAK,CAAC,KAAmB;QAChD,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,IAAI,CAAC,SAAS,CAAC;gBAChB,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ,CAAC,IAAI;oBACnB,OAAO,EAAE,QAAQ,CAAC,OAAO;oBACzB,OAAO,EAAE,QAAQ,CAAC,OAAO;iBAC1B;aACF,CAAC,IAAI,CACP,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,QAAQ,CAAC,IAAI,MAAM,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;QAC1E,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;IACvC,CAAC;CACF"}

package/dist/lib/metric-names.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Metric name resolution for the CLI and the MCP `query_metrics` tool.
+ *
+ * The canonical names and categories come from src/generated/metrics.ts, which is
+ * generated from @dataworks/sdk — edit the SDK, not this file, to add a metric.
+ * What lives here is the CLI-owned layer the SDK does not define: the everyday
+ * wordings a user or model is likely to type, and display units.
+ */
+import { allMetricNames, metricCategories, metricLabels, type MetricCategory } from "../generated/metrics.js";
+export { allMetricNames, metricCategories, metricLabels, type MetricCategory };
+/** Normalize wording to a lookup key: "Heart Rate" and "heart-rate" both give "heartrate". */
+export declare function compactMetricName(value: string): string;
+export interface ResolvedMetricName {
+    canonical: string;
+    category: MetricCategory;
+    unit: string | null;
+}
+/** Resolve a canonical name or alias; undefined for an unknown or custom metric. */
+export declare function resolveMetricName(requested: string): ResolvedMetricName | undefined;
+/** Every accepted spelling, for docs and error details. */
+export declare function metricAliases(): string[];
+/**
+ * Canonical names closest to what was asked for, so an unknown metric can point at
+ * the real spelling instead of only being rejected.
+ */
+export declare function suggestMetricNames(requested: string, limit?: number): string[];
+/** Compact catalogue listing for tool descriptions and skill docs. */
+export declare function metricCatalogSummary(): string;
+//# sourceMappingURL=metric-names.d.ts.map

package/dist/lib/metric-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-names.d.ts","sourceRoot":"","sources":["../../src/lib/metric-names.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,cAAc,EACd,gBAAgB,EAEhB,YAAY,EACZ,KAAK,cAAc,EACpB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,KAAK,cAAc,EAAE,CAAC;AA+F/E,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKvD;AAOD,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,cAAc,CAAC;IACzB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAQnF;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAExC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,MAAM,EAAE,CAyBzE;AASD,sEAAsE;AACtE,wBAAgB,oBAAoB,IAAI,MAAM,CAI7C"}

package/dist/lib/metric-names.js

@@ -0,0 +1,171 @@
+/**
+ * Metric name resolution for the CLI and the MCP `query_metrics` tool.
+ *
+ * The canonical names and categories come from src/generated/metrics.ts, which is
+ * generated from @dataworks/sdk — edit the SDK, not this file, to add a metric.
+ * What lives here is the CLI-owned layer the SDK does not define: the everyday
+ * wordings a user or model is likely to type, and display units.
+ */
+import { allMetricNames, metricCategories, metricCategoryByName, metricLabels, } from "../generated/metrics.js";
+export { allMetricNames, metricCategories, metricLabels };
+/**
+ * Units for metrics whose scale the catalogue states explicitly, either in the
+ * SDK's category comments or its label text. Metrics whose unit upstream leaves
+ * unstated are omitted and report `null` rather than a guess.
+ */
+const METRIC_UNITS = {
+    heartrate: "bpm",
+    "net-time": "s",
+    "checkpoint-time": "s",
+    "leg-time": "s",
+    "sub-time": "s",
+    "time-to-leader": "s",
+    "total-drafting-seconds": "s",
+    distance: "km",
+    "distance-swim": "km",
+    "distance-bike": "km",
+    "distance-run": "km",
+    speed: "km/h",
+    "speed-bike": "km/h",
+    pace: "sec/km",
+    "pace-swim": "sec/km",
+    "pace-run": "sec/km",
+    "heading-degrees": "degrees",
+};
+/**
+ * Everyday wordings that do not match a canonical name once punctuation and case
+ * are stripped. Canonical names register themselves, so "heart rate" already
+ * resolves to `heartrate` without an entry here.
+ */
+const EXTRA_ALIASES = {
+    // GPS
+    gps: "latlong",
+    gpsposition: "latlong",
+    location: "latlong",
+    position: "latlong",
+    coordinates: "latlong",
+    coords: "latlong",
+    // Heart rate
+    hr: "heartrate",
+    bpm: "heartrate",
+    pulse: "heartrate",
+    heartbeat: "heartrate",
+    // Power
+    watts: "power",
+    pwr: "power",
+    cyclingpower: "power-cycling",
+    bikepower: "power-cycling",
+    instantpower: "pwr_instant",
+    // Cadence
+    rpm: "cadence",
+    cyclingcadence: "cadence-cycling",
+    bikecadence: "cadence-cycling",
+    // Speed and elevation
+    velocity: "speed",
+    bikespeed: "speed-bike",
+    elevation: "altitude",
+    height: "altitude",
+    // Timing
+    finishtime: "net-time",
+    totaltime: "net-time",
+    splittime: "sub-time",
+    // Distance
+    swimdistance: "distance-swim",
+    bikedistance: "distance-bike",
+    rundistance: "distance-run",
+    // Pace
+    swimpace: "pace-swim",
+    runpace: "pace-run",
+    // Misc
+    placing: "rank",
+    ranking: "rank",
+    drafting: "is-drafting",
+    energy: "active-energy-burned",
+    calories: "active-energy-burned",
+};
+/**
+ * Umbrella words that name a family of metrics rather than one, so they cannot be
+ * resolved but can still be answered with candidates. `timing` earns its place:
+ * the CLI used to accept it as a metric name that no catalogue entry ever matched.
+ */
+const CONCEPT_SUGGESTIONS = {
+    timing: ["net-time", "checkpoint-time", "leg-time", "sub-time"],
+    time: ["net-time", "checkpoint-time", "leg-time", "sub-time"],
+    split: ["sub-time", "leg-time"],
+    splits: ["sub-time", "leg-time"],
+    duration: ["net-time", "leg-time"],
+    gap: ["gap-to-leader", "gap-to-ahead", "time-to-leader"],
+    zone: ["heartrate", "power"],
+    zones: ["heartrate", "power"],
+};
+/** Normalize wording to a lookup key: "Heart Rate" and "heart-rate" both give "heartrate". */
+export function compactMetricName(value) {
+    return value
+        .trim()
+        .toLocaleLowerCase()
+        .replaceAll(/[^a-z0-9]/g, "");
+}
+const ALIASES = {
+    ...Object.fromEntries(allMetricNames.map((name) => [compactMetricName(name), name])),
+    ...EXTRA_ALIASES,
+};
+/** Resolve a canonical name or alias; undefined for an unknown or custom metric. */
+export function resolveMetricName(requested) {
+    const canonical = ALIASES[compactMetricName(requested)];
+    if (!canonical)
+        return undefined;
+    const category = metricCategoryByName[canonical];
+    // Only reachable if an EXTRA_ALIASES entry outlives the metric it points at, in
+    // which case falling through to the unknown-metric path beats a bad query.
+    if (!category)
+        return undefined;
+    return { canonical, category, unit: METRIC_UNITS[canonical] ?? null };
+}
+/** Every accepted spelling, for docs and error details. */
+export function metricAliases() {
+    return Object.keys(ALIASES).sort();
+}
+/**
+ * Canonical names closest to what was asked for, so an unknown metric can point at
+ * the real spelling instead of only being rejected.
+ */
+export function suggestMetricNames(requested, limit = 5) {
+    const needle = compactMetricName(requested);
+    if (!needle)
+        return [];
+    const requestedTokens = new Set(requested
+        .toLocaleLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((token) => token.length > 2));
+    const concepts = new Set([needle, ...requestedTokens].flatMap((token) => CONCEPT_SUGGESTIONS[token] ?? []));
+    const scored = allMetricNames
+        .map((name) => {
+        const haystack = compactMetricName(name);
+        let score = 0;
+        if (haystack.startsWith(needle) || needle.startsWith(haystack))
+            score = 3;
+        else if (haystack.includes(needle) || needle.includes(haystack))
+            score = 2;
+        else if (concepts.has(name))
+            score = 2;
+        else if (sharesToken(name, requestedTokens))
+            score = 1;
+        return { name, score };
+    })
+        .filter((entry) => entry.score > 0);
+    scored.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+    return scored.slice(0, limit).map((entry) => entry.name);
+}
+function sharesToken(metric, requestedTokens) {
+    return metric
+        .toLocaleLowerCase()
+        .split(/[^a-z0-9]+/)
+        .some((token) => token.length > 2 && requestedTokens.has(token));
+}
+/** Compact catalogue listing for tool descriptions and skill docs. */
+export function metricCatalogSummary() {
+    return Object.keys(metricCategories)
+        .map((category) => `${category}: ${metricCategories[category].join(", ")}`)
+        .join(". ");
+}
+//# sourceMappingURL=metric-names.js.map

package/dist/lib/metric-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-names.js","sourceRoot":"","sources":["../../src/lib/metric-names.ts"],"names":[],"mappings":"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"}

package/dist/lib/query-metrics.d.ts

@@ -0,0 +1,73 @@
+import { executeGraphql } from "./graphql-transport.js";
+import { type MetricCategory } from "./metric-names.js";
+import { requireSession } from "./session.js";
+export type { MetricCategory };
+export interface QueryMetricsInput {
+    athleteId?: string;
+    athleteName?: string;
+    metric: string;
+    metricCategory?: MetricCategory;
+    limit?: number;
+    order?: "newest" | "oldest";
+    from?: string;
+    to?: string;
+    eventId?: string;
+    datasetDatasourceId?: string;
+    tenantId?: string;
+    timeoutMs?: number;
+}
+export interface MetricPosition {
+    latitude: number;
+    longitude: number;
+}
+export interface MetricRow {
+    timestamp: string | number | null;
+    timestampIso: string | null;
+    athleteId: string | null;
+    metric: string | null;
+    value: unknown;
+    unit: string | null;
+    position: MetricPosition | null;
+    eventId: string | null;
+    datasetDatasourceId: string | null;
+}
+export interface QueryMetricsOutput {
+    environment: "uat" | "live";
+    tenantId: string;
+    athlete: {
+        publicId: string;
+        name: string | null;
+        matchedBy: "public_id" | "name" | "partial_name";
+    };
+    metric: {
+        requested: string;
+        canonical: string;
+        category: MetricCategory;
+        unit: string | null;
+    };
+    filters: {
+        eventId: string | null;
+        datasetDatasourceId: string | null;
+        from: string | null;
+        to: string | null;
+    };
+    order: "newest" | "oldest";
+    limit: number;
+    count: number;
+    rowCount: number;
+    status: string;
+    queryExecutionId: string | null;
+    queryTimeMs: number | null;
+    rows: MetricRow[];
+}
+export interface QueryMetricsDependencies {
+    graphql: typeof executeGraphql;
+    session: typeof requireSession;
+    sleep: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+    now: () => number;
+}
+export declare function queryMetrics(input: QueryMetricsInput, options?: {
+    dependencies?: Partial<QueryMetricsDependencies>;
+    signal?: AbortSignal;
+}): Promise<QueryMetricsOutput>;
+//# sourceMappingURL=query-metrics.d.ts.map

package/dist/lib/query-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-metrics.d.ts","sourceRoot":"","sources":["../../src/lib/query-metrics.ts"],"names":[],"mappings":"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"}