@framedash/cli 0.1.1 → 0.1.3

package/dist/lib/oauth/token-store.js

@@ -0,0 +1,164 @@
+import { randomBytes } from "node:crypto";
+import { chmodSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/** Resolve the credentials file path (honors XDG_CONFIG_HOME at call time). */
+export function credentialsFilePath() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    const configHome = xdg && xdg.trim() !== "" ? xdg : join(homedir(), ".config");
+    return join(configHome, "framedash", "credentials.json");
+}
+function isStoredTokenEntry(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const entry = value;
+    return (typeof entry.access_token === "string" &&
+        entry.access_token !== "" &&
+        typeof entry.refresh_token === "string" &&
+        entry.refresh_token !== "" &&
+        typeof entry.expires_at === "number" &&
+        Number.isFinite(entry.expires_at) &&
+        typeof entry.scope === "string");
+}
+/**
+ * Read the whole token store. Missing, unreadable, or corrupt files -- and
+ * individual malformed entries -- degrade to "absent" rather than throwing:
+ * the caller then falls back to other credential sources or asks the user to
+ * log in again.
+ */
+export function readTokenStore() {
+    let raw;
+    try {
+        raw = readFileSync(credentialsFilePath(), "utf8");
+    }
+    catch {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return {};
+    }
+    const store = {};
+    for (const [origin, entry] of Object.entries(parsed)) {
+        if (isStoredTokenEntry(entry)) {
+            store[origin] = entry;
+        }
+    }
+    return store;
+}
+/** Read the stored entry for one base-URL origin, if any. */
+export function readStoredEntry(origin) {
+    const store = readTokenStore();
+    // Own-property guard: a prototype-chain key (e.g. "toString") must never
+    // masquerade as a stored entry.
+    return Object.hasOwn(store, origin) ? store[origin] : undefined;
+}
+/**
+ * Reap orphaned credentials.json.*.tmp files left by crashed writes -- they
+ * hold the same token material as the store itself. Called from every write
+ * and from clearTokenStore, so any mutation heals a previous crash.
+ */
+function reapOrphanTmps() {
+    const filePath = credentialsFilePath();
+    const base = `${filePath}.`;
+    let names;
+    try {
+        names = readdirSync(dirname(filePath));
+    }
+    catch {
+        return; // Config dir itself is gone: nothing to reap.
+    }
+    for (const name of names) {
+        const full = join(dirname(filePath), name);
+        if (full.startsWith(base) && full.endsWith(".tmp")) {
+            // Best-effort: reaping runs AFTER the atomic rename has already
+            // committed the real write, so a cleanup failure (locked file on
+            // Windows, odd FS state) must never propagate and make a successful
+            // saveStoredEntry look failed. recursive covers a dir-shaped orphan.
+            try {
+                rmSync(full, { force: true, recursive: true });
+            }
+            catch {
+                // Leave the orphan; the next mutation will retry the reap.
+            }
+        }
+    }
+}
+/**
+ * Persist the whole store atomically: write a temp file in the target
+ * directory, then rename over the destination (rename replaces existing
+ * files on both POSIX and Windows), so readers always see a complete JSON
+ * document. Concurrent writers are last-writer-wins by design (see the
+ * concurrency model note above).
+ */
+function writeTokenStore(store) {
+    const filePath = credentialsFilePath();
+    const dir = dirname(filePath);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        // mkdirSync's mode only applies on creation; tighten a pre-existing
+        // directory too so credentials.json never sits in a world-readable dir.
+        // Best-effort no-op on Windows.
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        // Best effort only.
+    }
+    const tmpPath = `${filePath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    try {
+        writeFileSync(tmpPath, `${JSON.stringify(store, null, "\t")}\n`, { mode: 0o600 });
+        renameSync(tmpPath, filePath);
+    }
+    catch (err) {
+        rmSync(tmpPath, { force: true });
+        throw err;
+    }
+    try {
+        // Re-assert the mode in case the file pre-existed with wider permissions;
+        // best-effort no-op on Windows.
+        chmodSync(filePath, 0o600);
+    }
+    catch {
+        // Best effort only.
+    }
+    reapOrphanTmps();
+}
+/**
+ * Insert or replace the entry for an origin (atomic write). Async signature
+ * kept for call-site stability even though the body is synchronous.
+ */
+export async function saveStoredEntry(origin, entry) {
+    const store = readTokenStore();
+    store[origin] = entry;
+    writeTokenStore(store);
+}
+/** Remove the entry for an origin. Returns true if an entry was removed. */
+export async function deleteStoredEntry(origin) {
+    const store = readTokenStore();
+    // Object.hasOwn (not `in`): prototype-chain keys are not stored entries
+    // and must not trigger a rewrite.
+    if (!Object.hasOwn(store, origin))
+        return false;
+    delete store[origin];
+    writeTokenStore(store);
+    return true;
+}
+/**
+ * Delete the whole credentials file (logout --all), including any orphaned
+ * credentials.json.*.tmp files a crashed write left behind -- those hold the
+ * same token material as the store itself.
+ */
+export async function clearTokenStore() {
+    // recursive so a credentials path that is unexpectedly a directory
+    // (corruption / manual tampering) is still removed rather than throwing
+    // and blocking logout --all from clearing on-disk token material.
+    rmSync(credentialsFilePath(), { force: true, recursive: true });
+    reapOrphanTmps();
+}
+//# sourceMappingURL=token-store.js.map

package/dist/lib/oauth/token-store.js.map

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

package/dist/lib/perf-diff-eval.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Pure regression-gate logic for `framedash perf-diff`, kept free of I/O so the
+ * CI pass/fail decision is unit-testable. The shapes mirror the builds/compare
+ * API response (apps/web .../builds/compare); the CLI cannot import the web
+ * app's types, so they are restated here.
+ */
+/** Lower-is-better performance metrics perf-diff can gate on. */
+export type RegressionMetric = "frame_time" | "memory" | "gpu_time";
+export declare const REGRESSION_METRICS: readonly RegressionMetric[];
+export declare function isRegressionMetric(value: string): value is RegressionMetric;
+/** One metric's diff, as returned by the builds/compare API. */
+export interface ApiMetricDiff {
+    metric: RegressionMetric;
+    baselineP50: number | null;
+    candidateP50: number | null;
+    /** Signed percent change of candidate P50 vs baseline P50; null = not comparable. */
+    diffPct: number | null;
+    isRegression: boolean;
+    baselineTail: number | null;
+    candidateTail: number | null;
+}
+export interface ApiBuildComparison {
+    baseline: {
+        build_id: string;
+    };
+    candidate: {
+        build_id: string;
+    };
+    diffs: ApiMetricDiff[];
+}
+export interface RegressionVerdict {
+    /** True when at least one evaluated metric regressed beyond the threshold. */
+    failed: boolean;
+    /** Metrics that regressed beyond the threshold. */
+    offenders: ApiMetricDiff[];
+    /** Metrics actually evaluated (matching the metric filter, with comparable data). */
+    evaluated: ApiMetricDiff[];
+}
+export interface EvaluateOptions {
+    /** Restrict the gate to a single metric; default checks all. */
+    metric?: RegressionMetric;
+    /**
+     * A metric fails only when its P50 worsened by MORE than this percentage,
+     * letting CI tolerate run-to-run noise. Default 0 = any worsening fails.
+     */
+    thresholdPct?: number;
+}
+/**
+ * Decide whether a build comparison should fail a CI gate. All regression
+ * metrics are lower-is-better, so a positive diffPct (candidate P50 above
+ * baseline) is a regression. A null diffPct (no baseline data, or a metric
+ * unavailable on the platform, e.g. GPU timing) is not comparable and is
+ * skipped -- neither an offender nor counted as evaluated.
+ */
+export declare function evaluateRegression(comparison: ApiBuildComparison, options?: EvaluateOptions): RegressionVerdict;
+/** A one-line human summary of a single metric diff (for CI logs). */
+export declare function formatMetricDiff(d: ApiMetricDiff): string;
+//# sourceMappingURL=perf-diff-eval.d.ts.map

package/dist/lib/perf-diff-eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-diff-eval.d.ts","sourceRoot":"","sources":["../../src/lib/perf-diff-eval.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iEAAiE;AACjE,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEpE,eAAO,MAAM,kBAAkB,EAAE,SAAS,gBAAgB,EAAyC,CAAC;AAEpG,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,gBAAgB,CAE3E;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC7B,MAAM,EAAE,gBAAgB,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qFAAqF;IACrF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IAClC,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,SAAS,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAChC,KAAK,EAAE,aAAa,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IACjC,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;IAChB,mDAAmD;IACnD,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,qFAAqF;IACrF,SAAS,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC/B,gEAAgE;IAChE,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CACjC,UAAU,EAAE,kBAAkB,EAC9B,OAAO,GAAE,eAAoB,GAC3B,iBAAiB,CAmBnB;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAQzD"}

package/dist/lib/perf-diff-eval.js

@@ -0,0 +1,49 @@
+/**
+ * Pure regression-gate logic for `framedash perf-diff`, kept free of I/O so the
+ * CI pass/fail decision is unit-testable. The shapes mirror the builds/compare
+ * API response (apps/web .../builds/compare); the CLI cannot import the web
+ * app's types, so they are restated here.
+ */
+export const REGRESSION_METRICS = ["frame_time", "memory", "gpu_time"];
+export function isRegressionMetric(value) {
+    return REGRESSION_METRICS.includes(value);
+}
+/**
+ * Decide whether a build comparison should fail a CI gate. All regression
+ * metrics are lower-is-better, so a positive diffPct (candidate P50 above
+ * baseline) is a regression. A null diffPct (no baseline data, or a metric
+ * unavailable on the platform, e.g. GPU timing) is not comparable and is
+ * skipped -- neither an offender nor counted as evaluated.
+ */
+export function evaluateRegression(comparison, options = {}) {
+    // Clamp a non-finite or negative threshold to 0 (the strictest gate) so a bad
+    // value fails safe rather than silently disabling the gate -- `x > Infinity`
+    // and `x > NaN` are both always false, which would pass every regression. The
+    // command validates --threshold too; this keeps the exported helper robust on
+    // its own.
+    const threshold = Number.isFinite(options.thresholdPct) && options.thresholdPct >= 0
+        ? options.thresholdPct
+        : 0;
+    // Defensive: a malformed response (missing diffs) yields no evaluable metrics,
+    // which the caller treats as "nothing comparable" -> fail-closed. `typeof ===
+    // "number"` (not `!== null`) also skips an undefined/missing diffPct safely.
+    const diffs = Array.isArray(comparison?.diffs) ? comparison.diffs : [];
+    const evaluated = diffs.filter((d) => (!options.metric || d.metric === options.metric) && typeof d.diffPct === "number");
+    const offenders = evaluated.filter((d) => d.diffPct > threshold);
+    return { failed: offenders.length > 0, offenders, evaluated };
+}
+/** A one-line human summary of a single metric diff (for CI logs). */
+export function formatMetricDiff(d) {
+    // `typeof !== "number"` covers a null OR an undefined/missing diffPct, so the
+    // toFixed() below can never throw on a malformed row.
+    if (typeof d.diffPct !== "number")
+        return `${d.metric}: no comparable data`;
+    const sign = d.diffPct >= 0 ? "+" : "";
+    return `${d.metric}: ${sign}${d.diffPct.toFixed(1)}% (P50 ${fmtValue(d.baselineP50)} -> ${fmtValue(d.candidateP50)})`;
+}
+function fmtValue(value) {
+    // `typeof !== "number"` covers null AND a missing/undefined value on a
+    // malformed row, so toFixed() can never throw here.
+    return typeof value !== "number" ? "n/a" : value.toFixed(2);
+}
+//# sourceMappingURL=perf-diff-eval.js.map

package/dist/lib/perf-diff-eval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-diff-eval.js","sourceRoot":"","sources":["../../src/lib/perf-diff-eval.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,CAAC,MAAM,kBAAkB,GAAgC,CAAC,YAAY,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;AAEpG,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC/C,OAAQ,kBAAwC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AAuCD;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CACjC,UAA8B,EAC9B,UAA2B,EAAE;IAE7B,8EAA8E;IAC9E,6EAA6E;IAC7E,8EAA8E;IAC9E,8EAA8E;IAC9E,WAAW;IACX,MAAM,SAAS,GACd,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,YAAY,CAAC,IAAK,OAAO,CAAC,YAAuB,IAAI,CAAC;QAC7E,CAAC,CAAE,OAAO,CAAC,YAAuB;QAClC,CAAC,CAAC,CAAC,CAAC;IACN,+EAA+E;IAC/E,8EAA8E;IAC9E,6EAA6E;IAC7E,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAC7B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CACxF,CAAC;IACF,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAC,CAAC,OAAkB,GAAG,SAAS,CAAC,CAAC;IAC7E,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;AAC/D,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAAC,CAAgB;IAChD,8EAA8E;IAC9E,sDAAsD;IACtD,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC,CAAC,MAAM,sBAAsB,CAAC;IAC5E,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACvC,OAAO,GAAG,CAAC,CAAC,MAAM,KAAK,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,QAAQ,CACjG,CAAC,CAAC,YAAY,CACd,GAAG,CAAC;AACN,CAAC;AAED,SAAS,QAAQ,CAAC,KAAgC;IACjD,uEAAuE;IACvE,oDAAoD;IACpD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC7D,CAAC"}

package/dist/lib/run-command.js

@@ -20,12 +20,12 @@ export async function runCommand(opts, handler) {
     if (opts.noProject) {
         const baseConfig = resolveConfigWithoutProject(typedValues);
         const config = { ...baseConfig, projectId: "" };
-        const client = createClient(config.baseUrl, config.apiKey, "");
+        const client = createClient(config.baseUrl, config.credential, "");
         await handler({ config, client, values: typedValues, positionals });
     }
     else {
         const config = resolveConfig(typedValues);
-        const client = createClient(config.baseUrl, config.apiKey, config.projectId);
+        const client = createClient(config.baseUrl, config.credential, config.projectId);
         await handler({ config, client, values: typedValues, positionals });
     }
 }

package/dist/lib/run-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"run-command.js","sourceRoot":"","sources":["../../src/lib/run-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,SAAS,EAAE,MAAM,WAAW,CAAC;AAE5D,OAAO,EAEN,cAAc,EACd,aAAa,EACb,2BAA2B,GAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAiBzC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC/B,IAAoB,EACpB,OAA+C;IAE/C,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC;QACzC,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,EAAE,GAAG,cAAc,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE;QAC/C,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,IAAI,KAAK;KAChD,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QACjB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACf,OAAO;IACR,CAAC;IAED,MAAM,WAAW,GAAG,MAAsD,CAAC;IAE3E,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACpB,MAAM,UAAU,GAAG,2BAA2B,CAAC,WAAW,CAAC,CAAC;QAC5D,MAAM,MAAM,GAAc,EAAE,GAAG,UAAU,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;QAC3D,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC/D,MAAM,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC;IACrE,CAAC;SAAM,CAAC;QACP,MAAM,MAAM,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QAC7E,MAAM,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC;IACrE,CAAC;AACF,CAAC;AAID;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC9B,IAAY,EACZ,IAAY,EACZ,WAA0B;IAE1B,OAAO,KAAK,EAAE,IAAc,EAAiB,EAAE;QAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAE3B,IAAI,CAAC,UAAU,IAAI,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;YACnE,GAAG,CAAC,IAAI,CAAC,CAAC;YACV,OAAO;QACR,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,UAAU,CAAC,EAAE,CAAC;YAC7C,KAAK,CAAC,WAAW,IAAI,gBAAgB,UAAU,EAAE,CAAC,CAAC;YACnD,GAAG,CAAC,IAAI,CAAC,CAAC;YACV,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAChB,OAAO;QACR,CAAC;QAED,+EAA+E;QAC/E,MAAM,WAAW,CAAC,UAAU,CAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC,CAAC;AACH,CAAC"}
+{"version":3,"file":"run-command.js","sourceRoot":"","sources":["../../src/lib/run-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,SAAS,EAAE,MAAM,WAAW,CAAC;AAE5D,OAAO,EAEN,cAAc,EACd,aAAa,EACb,2BAA2B,GAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAiBzC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC/B,IAAoB,EACpB,OAA+C;IAE/C,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC;QACzC,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,EAAE,GAAG,cAAc,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE;QAC/C,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,IAAI,KAAK;KAChD,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QACjB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACf,OAAO;IACR,CAAC;IAED,MAAM,WAAW,GAAG,MAAsD,CAAC;IAE3E,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACpB,MAAM,UAAU,GAAG,2BAA2B,CAAC,WAAW,CAAC,CAAC;QAC5D,MAAM,MAAM,GAAc,EAAE,GAAG,UAAU,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;QAC3D,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QACnE,MAAM,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC;IACrE,CAAC;SAAM,CAAC;QACP,MAAM,MAAM,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACjF,MAAM,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC;IACrE,CAAC;AACF,CAAC;AAID;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC9B,IAAY,EACZ,IAAY,EACZ,WAA0B;IAE1B,OAAO,KAAK,EAAE,IAAc,EAAiB,EAAE;QAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAE3B,IAAI,CAAC,UAAU,IAAI,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;YACnE,GAAG,CAAC,IAAI,CAAC,CAAC;YACV,OAAO;QACR,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,UAAU,CAAC,EAAE,CAAC;YAC7C,KAAK,CAAC,WAAW,IAAI,gBAAgB,UAAU,EAAE,CAAC,CAAC;YACnD,GAAG,CAAC,IAAI,CAAC,CAAC;YACV,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAChB,OAAO;QACR,CAAC;QAED,+EAA+E;QAC/E,MAAM,WAAW,CAAC,UAAU,CAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC,CAAC;AACH,CAAC"}

package/dist/lib/run-profile-test-lib.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Pure helpers for `framedash run-profile-test`, kept free of process/network
+ * I/O so the env-contract and ingest-wait logic is unit-testable. The command
+ * (commands/run-profile-test.ts) layers git resolution, the child-process
+ * spawn, and the perf-diff gate around these.
+ */
+/**
+ * The FRAMEDASH_* environment contract the SDK's
+ * BeginAutomatedSessionFromEnvironment() reads to stamp the automated session.
+ * The build id becomes the first-class `build_id`; branch/commit/scenario ride
+ * the attributes map as ci.branch / ci.commit / ci.scenario.
+ */
+export declare const ENV_BUILD_ID = "FRAMEDASH_BUILD_ID";
+export declare const ENV_GIT_BRANCH = "FRAMEDASH_GIT_BRANCH";
+export declare const ENV_GIT_COMMIT = "FRAMEDASH_GIT_COMMIT";
+export declare const ENV_TEST_SCENARIO = "FRAMEDASH_TEST_SCENARIO";
+/**
+ * The full FRAMEDASH_* session contract. The runner is authoritative for all of
+ * these: it clears any it does not set so the launched game can never inherit a
+ * stale value (e.g. a FRAMEDASH_GIT_BRANCH left in the CI environment) when the
+ * current run omits that field.
+ */
+export declare const SESSION_ENV_KEYS: readonly ["FRAMEDASH_BUILD_ID", "FRAMEDASH_GIT_BRANCH", "FRAMEDASH_GIT_COMMIT", "FRAMEDASH_TEST_SCENARIO"];
+/** Resolved build identity stamped onto the profiling run. */
+export interface ProfileIdentity {
+    /** Becomes FRAMEDASH_BUILD_ID and the perf-diff candidate; always set. */
+    buildId: string;
+    /** FRAMEDASH_GIT_BRANCH (ci.branch); omitted from the env when empty. */
+    branch?: string;
+    /** FRAMEDASH_GIT_COMMIT (ci.commit); omitted when empty. */
+    commit?: string;
+    /** FRAMEDASH_TEST_SCENARIO (ci.scenario); omitted when empty. */
+    scenario?: string;
+}
+/** Raw identity flags as parsed from the command line (any may be unset). */
+export interface IdentityInputs {
+    buildId?: string;
+    branch?: string;
+    commit?: string;
+    scenario?: string;
+}
+/** Git fallbacks (best-effort `git rev-parse` outputs; either may be unset). */
+export interface GitFallbacks {
+    branch?: string;
+    commit?: string;
+}
+/**
+ * Resolve the build identity from explicit flags, falling back to git. The
+ * build id defaults to the resolved commit, so a CI run that sets only --commit
+ * (or relies on the git fallback) still gets a stable, first-class build_id.
+ * Returns null when no build id can be determined, so the caller can error out
+ * before launching the game.
+ */
+export declare function resolveProfileIdentity(flags: IdentityInputs, git: GitFallbacks): ProfileIdentity | null;
+/**
+ * The FRAMEDASH_* variables to overlay onto the child process environment. Only
+ * non-empty values are included so the SDK's env reader never picks up a blank
+ * branch/commit/scenario and stamps an empty ci.* tag.
+ */
+export declare function buildSessionEnv(identity: ProfileIdentity): Record<string, string>;
+/** Result of validating a "seconds" CLI option value. */
+export type SecondsValidation = {
+    value: number;
+} | {
+    error: string;
+};
+/**
+ * Validate a seconds-valued option. Returns the parsed number, or an error
+ * message describing why it is invalid (the caller adds the --flag prefix and
+ * decides how to surface it). A non-string value (unset, or the boolean parseArgs
+ * yields for a value-less flag) falls back to `fallback`. With `allowZero` the
+ * value may be 0 (used by --command-timeout, where 0 disables the bound);
+ * otherwise it must be strictly positive (as --ingest-timeout / --poll-interval
+ * require).
+ */
+export declare function validateSeconds(value: string | boolean | undefined, fallback: number, opts?: {
+    allowZero?: boolean;
+    max?: number;
+}): SecondsValidation;
+/**
+ * Platform-specific plan for terminating a launched process TREE by pid. A plain
+ * kill of the direct child orphans its grandchildren (a Unity/UE5 player launched
+ * via the shell spawns helper processes that survive), so on win32 we shell out
+ * to `taskkill /T /F` (whole tree, forced) and on POSIX we signal the child's
+ * process GROUP (the negative pid, valid because the child is spawned detached
+ * into its own group). Pure so the argv/decision is unit-testable without
+ * spawning anything.
+ */
+export type TreeKillPlan = {
+    platform: "win32";
+    command: "taskkill";
+    args: string[];
+} | {
+    platform: "posix";
+    groupPid: number;
+} | {
+    platform: "noop";
+};
+export declare function planTreeKill(platform: NodeJS.Platform, pid: number | undefined): TreeKillPlan;
+/** Minimal shape of a builds-list row (mirrors apps/web BuildInfo). */
+export interface BuildListEntry {
+    build_id: string;
+    /**
+     * Perf-event count. ClickHouse `count()` is a UInt64, which the JSON format
+     * serializes as a quoted string by default, so this can arrive as a number OR
+     * a numeric string -- buildEventCount() normalizes it.
+     */
+    event_count?: number | string;
+}
+/**
+ * The perf-bearing event count currently reported for a build_id, or 0 when the
+ * build is absent (or the row has no usable count). Normalizes the value with
+ * Number() so a JSON-quoted UInt64 string compares numerically, not
+ * lexicographically (otherwise "10" > "9" would be false). Used to snapshot the
+ * candidate's count before a run so the wait can require it to grow.
+ */
+export declare function buildEventCount(builds: BuildListEntry[] | null | undefined, buildId: string): number;
+/**
+ * True once the candidate build_id has produced MORE than `minEventCount`
+ * perf-bearing events. With the default 0 this means "present with any events".
+ * Passing the build's pre-run count makes the wait require fresh events from
+ * THIS run, so a CI re-run for the same build_id is not satisfied by old data.
+ */
+export declare function hasIngestedBuild(builds: BuildListEntry[] | null | undefined, buildId: string, minEventCount?: number): boolean;
+/** Injected dependencies for waitForIngest (so the poll loop is unit-testable). */
+export interface WaitForIngestDeps {
+    /** Fetch the current builds list (one poll). */
+    fetchBuilds: () => Promise<BuildListEntry[]>;
+    /** Candidate build_id to wait for. */
+    buildId: string;
+    /**
+     * Require the candidate's event count to exceed this value (its count before
+     * the run), so the wait confirms fresh events rather than pre-existing data.
+     * Defaults to 0 ("present with any events").
+     */
+    minEventCount?: number;
+    /** Give up after this many milliseconds. */
+    timeoutMs: number;
+    /** Delay between polls, in milliseconds. */
+    intervalMs: number;
+    /** Sleep helper (injected so tests can advance a fake clock). */
+    sleep: (ms: number) => Promise<void>;
+    /** Monotonic clock in milliseconds (injected for the same reason). */
+    now: () => number;
+    /** Optional per-attempt hook (for progress logging). */
+    onPoll?: (attempt: number) => void;
+}
+/**
+ * Poll the builds list until the candidate build's perf data has landed, or the
+ * timeout elapses. Returns true if the build appeared, false on timeout. Always
+ * polls at least once (so timeoutMs=0 still makes a single attempt). A transient
+ * fetch error (ingest / ClickHouse lag) is swallowed and retried until the
+ * deadline rather than failing the whole run on a blip.
+ */
+export declare function waitForIngest(deps: WaitForIngestDeps): Promise<boolean>;
+//# sourceMappingURL=run-profile-test-lib.d.ts.map

package/dist/lib/run-profile-test-lib.d.ts.map

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

package/dist/lib/run-profile-test-lib.js

@@ -0,0 +1,171 @@
+/**
+ * Pure helpers for `framedash run-profile-test`, kept free of process/network
+ * I/O so the env-contract and ingest-wait logic is unit-testable. The command
+ * (commands/run-profile-test.ts) layers git resolution, the child-process
+ * spawn, and the perf-diff gate around these.
+ */
+/**
+ * The FRAMEDASH_* environment contract the SDK's
+ * BeginAutomatedSessionFromEnvironment() reads to stamp the automated session.
+ * The build id becomes the first-class `build_id`; branch/commit/scenario ride
+ * the attributes map as ci.branch / ci.commit / ci.scenario.
+ */
+export const ENV_BUILD_ID = "FRAMEDASH_BUILD_ID";
+export const ENV_GIT_BRANCH = "FRAMEDASH_GIT_BRANCH";
+export const ENV_GIT_COMMIT = "FRAMEDASH_GIT_COMMIT";
+export const ENV_TEST_SCENARIO = "FRAMEDASH_TEST_SCENARIO";
+/**
+ * The full FRAMEDASH_* session contract. The runner is authoritative for all of
+ * these: it clears any it does not set so the launched game can never inherit a
+ * stale value (e.g. a FRAMEDASH_GIT_BRANCH left in the CI environment) when the
+ * current run omits that field.
+ */
+export const SESSION_ENV_KEYS = [
+    ENV_BUILD_ID,
+    ENV_GIT_BRANCH,
+    ENV_GIT_COMMIT,
+    ENV_TEST_SCENARIO,
+];
+function clean(value) {
+    // Guard the type defensively: parseArgs only yields strings for these flags,
+    // but a non-string (boolean/null) must not crash .trim().
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * Resolve the build identity from explicit flags, falling back to git. The
+ * build id defaults to the resolved commit, so a CI run that sets only --commit
+ * (or relies on the git fallback) still gets a stable, first-class build_id.
+ * Returns null when no build id can be determined, so the caller can error out
+ * before launching the game.
+ */
+export function resolveProfileIdentity(flags, git) {
+    const commit = clean(flags.commit) ?? clean(git.commit);
+    const buildId = clean(flags.buildId) ?? commit;
+    if (!buildId)
+        return null;
+    return {
+        buildId,
+        branch: clean(flags.branch) ?? clean(git.branch),
+        commit,
+        scenario: clean(flags.scenario),
+    };
+}
+/**
+ * The FRAMEDASH_* variables to overlay onto the child process environment. Only
+ * non-empty values are included so the SDK's env reader never picks up a blank
+ * branch/commit/scenario and stamps an empty ci.* tag.
+ */
+export function buildSessionEnv(identity) {
+    const env = { [ENV_BUILD_ID]: identity.buildId };
+    if (identity.branch)
+        env[ENV_GIT_BRANCH] = identity.branch;
+    if (identity.commit)
+        env[ENV_GIT_COMMIT] = identity.commit;
+    if (identity.scenario)
+        env[ENV_TEST_SCENARIO] = identity.scenario;
+    return env;
+}
+/**
+ * Validate a seconds-valued option. Returns the parsed number, or an error
+ * message describing why it is invalid (the caller adds the --flag prefix and
+ * decides how to surface it). A non-string value (unset, or the boolean parseArgs
+ * yields for a value-less flag) falls back to `fallback`. With `allowZero` the
+ * value may be 0 (used by --command-timeout, where 0 disables the bound);
+ * otherwise it must be strictly positive (as --ingest-timeout / --poll-interval
+ * require).
+ */
+export function validateSeconds(value, fallback, opts = {}) {
+    if (typeof value !== "string")
+        return { value: fallback };
+    const baseError = opts.allowZero
+        ? "must be a non-negative number of seconds (0 disables the bound)"
+        : "must be a positive number of seconds";
+    // Reject empty / whitespace explicitly: Number("") and Number(" ") are 0, which
+    // would silently DISABLE the bound under allowZero (a fail-closed footgun for a
+    // mistyped --command-timeout= value), so treat a blank value as invalid.
+    const trimmed = value.trim();
+    if (trimmed === "")
+        return { error: baseError };
+    const n = Number(trimmed);
+    const minOk = opts.allowZero ? n >= 0 : n > 0;
+    if (!Number.isFinite(n) || !minOk)
+        return { error: baseError };
+    // Guard against a value so large that timeoutMs overflows setTimeout's signed
+    // 32-bit delay, which Node clamps to 1ms -- an "effectively unbounded" input
+    // would then fire almost immediately and kill the run at once.
+    if (opts.max !== undefined && n > opts.max) {
+        return { error: `must be at most ${opts.max} seconds` };
+    }
+    return { value: n };
+}
+export function planTreeKill(platform, pid) {
+    // A missing, non-integer, or non-positive pid is UNSAFE to kill: on POSIX,
+    // process.kill(0, sig) signals the caller's OWN process group and kill(-1, sig)
+    // signals every process the user owns, either of which could take down this CLI
+    // or the CI runner itself. Refuse to act rather than risk it.
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) {
+        return { platform: "noop" };
+    }
+    if (platform === "win32") {
+        return { platform: "win32", command: "taskkill", args: ["/pid", String(pid), "/t", "/f"] };
+    }
+    // Negative pid targets the whole process group (see detached spawn in the command).
+    return { platform: "posix", groupPid: -pid };
+}
+/**
+ * The perf-bearing event count currently reported for a build_id, or 0 when the
+ * build is absent (or the row has no usable count). Normalizes the value with
+ * Number() so a JSON-quoted UInt64 string compares numerically, not
+ * lexicographically (otherwise "10" > "9" would be false). Used to snapshot the
+ * candidate's count before a run so the wait can require it to grow.
+ */
+export function buildEventCount(builds, buildId) {
+    if (!Array.isArray(builds))
+        return 0;
+    const row = builds.find((b) => b.build_id === buildId);
+    const count = Number(row?.event_count);
+    return Number.isFinite(count) ? count : 0;
+}
+/**
+ * True once the candidate build_id has produced MORE than `minEventCount`
+ * perf-bearing events. With the default 0 this means "present with any events".
+ * Passing the build's pre-run count makes the wait require fresh events from
+ * THIS run, so a CI re-run for the same build_id is not satisfied by old data.
+ */
+export function hasIngestedBuild(builds, buildId, minEventCount = 0) {
+    return buildEventCount(builds, buildId) > minEventCount;
+}
+/**
+ * Poll the builds list until the candidate build's perf data has landed, or the
+ * timeout elapses. Returns true if the build appeared, false on timeout. Always
+ * polls at least once (so timeoutMs=0 still makes a single attempt). A transient
+ * fetch error (ingest / ClickHouse lag) is swallowed and retried until the
+ * deadline rather than failing the whole run on a blip.
+ */
+export async function waitForIngest(deps) {
+    const deadline = deps.now() + deps.timeoutMs;
+    let attempt = 0;
+    while (true) {
+        attempt++;
+        deps.onPoll?.(attempt);
+        try {
+            const builds = await deps.fetchBuilds();
+            if (hasIngestedBuild(builds, deps.buildId, deps.minEventCount ?? 0))
+                return true;
+        }
+        catch {
+            // Transient ingest / aggregation lag -- keep polling until the deadline.
+        }
+        // Read the clock once so the deadline check and the sleep window are
+        // consistent (a second now() call could advance past the deadline and yield
+        // a negative remaining); never sleep past the deadline.
+        const remaining = deadline - deps.now();
+        if (remaining <= 0)
+            return false;
+        await deps.sleep(Math.min(deps.intervalMs, remaining));
+    }
+}
+//# sourceMappingURL=run-profile-test-lib.js.map