har-to-slo 0.0.3

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.0.3] - 2026-06-11
+
+## [0.0.2] - 2026-06-11
+
+### Added
+- Initial release

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aks-builds
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+<div align="center">
+
+# 📐 har-to-slo
+
+**Your HAR file already knows your p95. You just haven't asked it yet.**
+
+Every time you record a HAR — from Playwright, Chrome DevTools, an API gateway export, or a browser session —
+you're capturing real latency measurements for every route in your app. `har-to-slo` reads those measurements,
+computes p95 baselines per route, and outputs a ready-to-use k6 `thresholds {}` block.
+**Stop inventing SLO numbers. Derive them.**
+
+> **Not a HAR-to-k6-script converter.** [`grafana/har-to-k6`](https://github.com/grafana/har-to-k6) replays traffic.
+> `har-to-slo` reads the *timings* in that same file and turns them into statistically grounded SLO baselines.
+> They complement each other — use both.
+
+[![CI](https://github.com/aks-builds/har-to-slo/actions/workflows/ci.yml/badge.svg)](https://github.com/aks-builds/har-to-slo/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/aks-builds/har-to-slo/actions/workflows/codeql.yml/badge.svg)](https://github.com/aks-builds/har-to-slo/actions/workflows/codeql.yml)
+[![npm version](https://img.shields.io/npm/v/har-to-slo.svg)](https://www.npmjs.com/package/har-to-slo)
+[![License MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Agent Skill](https://img.shields.io/badge/agent-skill-8a2be2.svg)](skills/har-to-slo.md)
+
+<br/>
+
+![har-to-slo running against a real 48-entry HAR — 6 routes collapsed, p95 baselines with 1.5× multiplier](.github/media/demo.svg)
+
+<sub>☝️ Real output from a 48-entry HAR. Six routes, all HTTP methods, zero configuration.</sub>
+
+</div>
+
+---
+
+## The problem it solves
+
+When you add a k6 `thresholds {}` block, you need a number:
+
+```javascript
+"http_req_duration{url:/api/orders}": ["p(95)<???"],
+```
+
+Where does that number come from? Usually: a guess, a round number, or copied from another service.
+`har-to-slo` answers that question with **measured data from your own traffic**.
+
+---
+
+## Install
+
+```bash
+# No install needed — run with npx
+npx har-to-slo --input recording.har
+```
+
+---
+
+## Usage
+
+```bash
+# Basic — outputs k6 thresholds block to stdout
+npx har-to-slo --input recording.har
+
+# Tighter SLOs (1.2× p95 instead of default 1.5×)
+npx har-to-slo --input recording.har --multiplier 1.2
+
+# JSON — for CI pipelines and tooling integrations
+npx har-to-slo --input recording.har --format json
+
+# Write directly into your k6 script file
+npx har-to-slo --input recording.har --output k6/thresholds.js
+
+# With LLM rationale for each threshold (requires ANTHROPIC_API_KEY)
+npx har-to-slo --input recording.har --explain
+```
+
+---
+
+## How it works
+
+```
+HAR file
+  └─ entry.time per request (real latency in ms)
+       └─ collapse URLs: /users/123 → /users/{id}
+            └─ group by METHOD + template
+                 └─ trim top 5% outliers
+                      └─ compute p95 per group
+                           └─ threshold = Math.round(p95 × multiplier)
+                                └─ emit k6 thresholds {} block
+```
+
+A HAR entry's `.time` field is the total wall-clock duration of that request as observed by the client.
+This is the same number your users experience. It's the right number for an SLO.
+
+---
+
+## Output example
+
+Given a HAR with requests to 6 routes:
+
+```javascript
+// Auto-generated by har-to-slo
+// https://github.com/aks-builds/har-to-slo
+
+export const options = {
+  thresholds: {
+    // GET /api/v1/users/{id} — p95 baseline: 142ms (n=8, ×1.5)
+    "http_req_duration{scenario:GET_/api/v1/users/_id_}": ["p(95)<213"],
+    // GET /api/v1/products — p95 baseline: 250ms (n=8, ×1.5)
+    "http_req_duration{scenario:GET_/api/v1/products}": ["p(95)<375"],
+    // POST /api/v1/orders — p95 baseline: 610ms (n=8, ×1.5)
+    "http_req_duration{scenario:POST_/api/v1/orders}": ["p(95)<915"],
+  },
+};
+```
+
+---
+
+## Using alongside grafana/har-to-k6
+
+These tools do different things and work together:
+
+```bash
+# Step 1 — generate a k6 load test script from your HAR recording
+npx har-to-k6 recording.har -o load-test.js
+
+# Step 2 — generate statistically grounded thresholds for that script
+npx har-to-slo --input recording.har --output thresholds.js
+
+# Step 3 — merge thresholds.js into load-test.js
+```
+
+`har-to-k6` asks: *"what requests should my load test replay?"*
+`har-to-slo` asks: *"what latency should I fail the load test at?"*
+
+---
+
+## Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `--input`, `-i` | *(required)* | Path to HAR file |
+| `--multiplier`, `-m` | `1.5` | Threshold = p95 × multiplier |
+| `--format`, `-f` | `js` | Output format: `js` or `json` |
+| `--output`, `-o` | stdout | Write to file instead of stdout |
+| `--explain`, `-e` | off | Annotate with Claude Haiku rationale (needs `ANTHROPIC_API_KEY`) |
+
+---
+
+## E2E test results
+
+| Dataset | Entries | Routes | Status |
+|---|---|---|---|
+| Small | 5 | 3 | ✅ |
+| Medium | 48 | 6 | ✅ |
+| Large | 500 | 10 (with UUIDs) | ✅ |
+
+---
+
+## Claude Code Skill
+
+A bundled Claude Code skill lets AI agents call `har-to-slo` during PR review to check whether load test thresholds are grounded in real data or invented.
+
+---
+
+## License
+
+MIT © [aks-builds](https://github.com/aks-builds)

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "har-to-slo",
+  "version": "0.0.3",
+  "description": "Turn HAR timing data into k6 SLO baselines — your recordings already know your p95",
+  "type": "module",
+  "bin": {
+    "har-to-slo": "src/cli.js"
+  },
+  "files": [
+    "src/",
+    "skills/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "author": "aks-builds <its.aks@outlook.com>",
+  "license": "MIT",
+  "scripts": {
+    "test": "node --test tests/emitter.test.js tests/integration.test.js tests/parser.test.js tests/routes.test.js tests/stats.test.js",
+    "test:watch": "node --test --watch tests/**/*.test.js"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": ">=0.20.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/sdk": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "slo",
+    "har",
+    "k6",
+    "performance-baseline",
+    "load-testing",
+    "thresholds",
+    "p95",
+    "slo-generator"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aks-builds/har-to-slo"
+  }
+}

package/skills/har-to-slo.md

@@ -0,0 +1,57 @@
+---
+name: har-to-slo
+description: Turn HAR timing measurements into k6 SLO baselines. Computes p95 per route, applies configurable multiplier, outputs a ready-to-use thresholds{} block. Your recordings already know your p95.
+version: 0.0.1
+tools:
+  - Bash
+  - Read
+  - Write
+---
+
+# har-to-slo
+
+Convert a HAR file's measured timing data into a ready-to-use k6 `thresholds {}` block.
+
+## When to use
+- You have a HAR file from a browser session, Playwright recording, or API gateway export
+- You need to set k6 thresholds but don't know what values to use
+- You want your load test SLOs grounded in real observed latency, not guesses
+
+## How to use
+
+```bash
+# Basic — outputs k6 thresholds block to stdout
+npx har-to-slo --input recording.har
+
+# Stricter SLOs (1.2× p95 instead of default 1.5×)
+npx har-to-slo --input recording.har --multiplier 1.2
+
+# JSON output for CI pipelines
+npx har-to-slo --input recording.har --format json
+
+# Write directly to a k6 script file
+npx har-to-slo --input recording.har --output k6/thresholds.js
+
+# With LLM rationale annotations (requires ANTHROPIC_API_KEY)
+npx har-to-slo --input recording.har --explain
+```
+
+## What it does
+1. Reads every HAR entry's `.time` value (total request duration in ms)
+2. Collapses parameterised URLs: `/users/123` → `/users/{id}`
+3. Groups by `METHOD /template`
+4. Trims top 5% outliers, then computes p50/p75/p95/p99
+5. Sets threshold = `Math.round(p95 × multiplier)` per group
+6. Emits a valid k6 `export const options = { thresholds: {...} }` block
+
+## Output example
+```javascript
+export const options = {
+  thresholds: {
+    // GET /users/{id} — p95 baseline: 245ms (n=847, ×1.5)
+    "http_req_duration{scenario:GET_users__id_}": ["p(95)<368"],
+    // POST /orders — p95 baseline: 890ms (n=312, ×1.5)
+    "http_req_duration{scenario:POST_orders}": ["p(95)<1335"],
+  },
+};
+```

package/src/cli.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// src/cli.js
+import { parseArgs } from 'node:util';
+import { writeFileSync } from 'node:fs';
+import { parseHarFile } from './parser.js';
+import { collapseUrl }   from './routes.js';
+import { computeGroups } from './stats.js';
+import { emitThresholds } from './emitter.js';
+
+const { values: argv } = parseArgs({
+  options: {
+    input:      { type: 'string',  short: 'i' },
+    multiplier: { type: 'string',  short: 'm', default: '1.5' },
+    format:     { type: 'string',  short: 'f', default: 'js' },
+    output:     { type: 'string',  short: 'o' },
+    explain:    { type: 'boolean', short: 'e', default: false },
+    help:       { type: 'boolean', short: 'h', default: false },
+  },
+  allowPositionals: false,
+  strict: false,
+});
+
+if (argv.help) {
+  process.stdout.write(`
+har-to-k6-thresholds — derive k6 SLO thresholds from real HAR timing data
+
+Usage:
+  har-to-k6-thresholds --input recording.har [options]
+
+Options:
+  --input,      -i  Path to HAR file (required)
+  --multiplier, -m  Threshold = p95 × multiplier (default: 1.5)
+  --format,     -f  Output format: js (default) or json
+  --output,     -o  Write to file instead of stdout
+  --explain,    -e  Annotate thresholds with Claude Haiku rationale
+  --help,       -h  Show this help
+`);
+  process.exit(0);
+}
+
+if (!argv.input) {
+  process.stderr.write('Error: --input <path-to-har> is required\n');
+  process.exit(1);
+}
+
+const multiplier = parseFloat(argv.multiplier);
+if (isNaN(multiplier) || multiplier <= 0) {
+  process.stderr.write('Error: --multiplier must be a positive number\n');
+  process.exit(1);
+}
+
+try {
+  const entries = await parseHarFile(argv.input);
+  const groups  = computeGroups(entries, collapseUrl);
+
+  let result;
+  if (argv.format === 'json') {
+    const thresholds = {};
+    for (const [key, stats] of Object.entries(groups)) {
+      thresholds[key] = {
+        p95_baseline: stats.p95,
+        threshold_ms: Math.round(stats.p95 * multiplier),
+        count: stats.count
+      };
+    }
+    result = JSON.stringify({ thresholds }, null, 2);
+  } else {
+    result = emitThresholds(groups, multiplier);
+  }
+
+  if (argv.explain && process.env.ANTHROPIC_API_KEY) {
+    const { annotate } = await import('./explain.js');
+    result = await annotate(result, groups);
+  }
+
+  if (argv.output) {
+    writeFileSync(argv.output, result, 'utf8');
+    process.stderr.write(`Written to ${argv.output}\n`);
+  } else {
+    process.stdout.write(result);
+  }
+} catch (err) {
+  process.stderr.write(`Error: ${err.message}\n`);
+  process.exit(1);
+}

package/src/emitter.js

@@ -0,0 +1,31 @@
+// src/emitter.js
+
+/**
+ * Emit a k6 options object containing a thresholds block derived from group stats.
+ * @param {Record<string, {count,p95,...}>} groups - output from computeGroups
+ * @param {number} multiplier - applied to p95 to set the threshold (default 1.5)
+ * @returns {string} valid k6 JS string
+ */
+export function emitThresholds(groups, multiplier = 1.5) {
+  const lines = [
+    '// Auto-generated by har-to-slo',
+    '// https://github.com/aks-builds/har-to-slo',
+    '',
+    'export const options = {',
+    '  thresholds: {',
+  ];
+
+  for (const [key, stats] of Object.entries(groups)) {
+    const limit = Math.round(stats.p95 * multiplier);
+    lines.push(`    // ${key} — p95 baseline: ${stats.p95}ms (n=${stats.count}, ×${multiplier})`);
+    lines.push(`    "http_req_duration{scenario:${sanitiseKey(key)}}": ["p(95)<${limit}"],`);
+  }
+
+  lines.push('  },', '};', '');
+  return lines.join('\n');
+}
+
+/** Convert a route key like 'GET /users/{id}' into a safe k6 tag value. */
+function sanitiseKey(key) {
+  return key.replace(/[^a-zA-Z0-9_/-]/g, '_');
+}

package/src/explain.js

@@ -0,0 +1,32 @@
+// src/explain.js
+import Anthropic from '@anthropic-ai/sdk';
+
+/**
+ * Annotate k6 threshold output with plain-English rationale from Claude Haiku.
+ * @param {string} thresholdOutput - the JS string from emitThresholds
+ * @param {Record<string, object>} groups - from computeGroups
+ * @returns {Promise<string>}
+ */
+export async function annotate(thresholdOutput, groups) {
+  const client = new Anthropic();
+  const groupSummary = Object.entries(groups)
+    .map(([key, s]) => `${key}: p95=${s.p95}ms, count=${s.count}`)
+    .join('\n');
+
+  const message = await client.messages.create({
+    model: 'claude-haiku-4-5',
+    max_tokens: 1024,
+    messages: [{
+      role: 'user',
+      content: `You are a performance engineering assistant. Below are k6 thresholds derived from real HAR file timing data. Add a one-line JS comment above each threshold explaining why this SLO value makes sense given the baseline data. Keep comments under 100 chars each. Return ONLY the modified JS with your comments inserted — no prose, no markdown.
+
+Route baselines:
+${groupSummary}
+
+Current thresholds output:
+${thresholdOutput}`
+    }]
+  });
+
+  return message.content[0].type === 'text' ? message.content[0].text : thresholdOutput;
+}

package/src/parser.js

@@ -0,0 +1,36 @@
+// src/parser.js
+import { readFile } from 'node:fs/promises';
+
+/**
+ * Parse an in-memory HAR object into a flat array of request entries.
+ * Skips entries that have no `time` field.
+ * @param {object} har - parsed HAR JSON
+ * @returns {{ method: string, url: string, status: number, time: number }[]}
+ */
+export function parseHar(har) {
+  return (har?.log?.entries ?? [])
+    .filter(e => typeof e.time === 'number' && !isNaN(e.time))
+    .map(e => {
+      if (!e.request?.method || !e.response?.status) return null;
+      return {
+        method: e.request.method.toUpperCase(),
+        url: e.request.url,
+        status: e.response.status,
+        time: e.time
+      };
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Read a HAR file from disk and return parsed entries.
+ * @param {string} filePath - absolute or relative path to .har file
+ */
+export async function parseHarFile(filePath) {
+  try {
+    const raw = await readFile(filePath, 'utf8');
+    return parseHar(JSON.parse(raw));
+  } catch (err) {
+    throw new Error(`Failed to read HAR file at "${filePath}": ${err.message}`);
+  }
+}

package/src/routes.js

@@ -0,0 +1,19 @@
+// src/routes.js
+
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+const HEX_RE  = /(\/)[0-9a-f]{16,}(?=\/|$)/gi;
+const NUM_RE  = /\/\d+(?=\/|$)/g;
+
+/**
+ * Collapse a full URL into a normalised route template.
+ * Returns only the path portion with parameterised segments replaced.
+ * @param {string} url
+ * @returns {string} e.g. '/users/{id}/orders/{uuid}'
+ */
+export function collapseUrl(url) {
+  const { pathname } = new URL(url);
+  return pathname
+    .replace(UUID_RE, '{uuid}')
+    .replace(HEX_RE,  '/{hash}')
+    .replace(NUM_RE,  '/{id}');
+}

package/src/stats.js

@@ -0,0 +1,42 @@
+// src/stats.js
+
+/**
+ * Compute the p-th percentile of a pre-sorted array.
+ */
+export function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  const idx = Math.ceil((p / 100) * sorted.length) - 1;
+  return sorted[Math.max(0, Math.min(idx, sorted.length - 1))];
+}
+
+/**
+ * Group HAR entries by method+template, trim top 5% outliers, compute stats.
+ */
+export function computeGroups(entries, collapser) {
+  const buckets = {};
+
+  for (const entry of entries) {
+    const template = collapser(entry.url);
+    const key = `${entry.method} ${template}`;
+    (buckets[key] ??= []).push(entry.time);
+  }
+
+  const groups = {};
+  for (const [key, times] of Object.entries(buckets)) {
+    const sorted = [...times].sort((a, b) => a - b);
+    // Trim top 5% outliers for min/max display only
+    const trimTo = Math.max(1, Math.floor(sorted.length * 0.95));
+    const trimmed = sorted.slice(0, trimTo);
+
+    groups[key] = {
+      count: times.length,
+      min:   trimmed[0],
+      max:   trimmed[trimmed.length - 1],
+      p50:   percentile(sorted, 50),   // percentiles on FULL data
+      p75:   percentile(sorted, 75),
+      p95:   percentile(sorted, 95),
+      p99:   percentile(sorted, 99),
+    };
+  }
+  return groups;
+}