splithub 0.1.8 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/dist/chunk-3DUWIEHB.js +561 -0
  2. package/dist/chunk-3DUWIEHB.js.map +1 -0
  3. package/dist/chunk-3VACHXWE.js +319 -0
  4. package/dist/chunk-3VACHXWE.js.map +1 -0
  5. package/dist/chunk-3VY5CP3E.js +383 -0
  6. package/dist/chunk-3VY5CP3E.js.map +1 -0
  7. package/dist/chunk-74NI7BED.js +58 -0
  8. package/dist/chunk-74NI7BED.js.map +1 -0
  9. package/dist/chunk-A2RCSPG6.js +184 -0
  10. package/dist/chunk-A2RCSPG6.js.map +1 -0
  11. package/dist/chunk-AJO3C4BS.js +97 -0
  12. package/dist/chunk-AJO3C4BS.js.map +1 -0
  13. package/dist/chunk-C5S7RPYM.js +54 -0
  14. package/dist/chunk-C5S7RPYM.js.map +1 -0
  15. package/dist/chunk-EUF75FUC.js +160 -0
  16. package/dist/chunk-EUF75FUC.js.map +1 -0
  17. package/dist/chunk-EYYLDI5J.js +195 -0
  18. package/dist/chunk-EYYLDI5J.js.map +1 -0
  19. package/dist/chunk-GVARYUL3.js +28 -0
  20. package/dist/chunk-GVARYUL3.js.map +1 -0
  21. package/dist/chunk-HSH4ZI2V.js +72 -0
  22. package/dist/chunk-HSH4ZI2V.js.map +1 -0
  23. package/dist/chunk-PLXDG4B5.js +134 -0
  24. package/dist/chunk-PLXDG4B5.js.map +1 -0
  25. package/dist/chunk-PWSRKABE.js +113 -0
  26. package/dist/chunk-PWSRKABE.js.map +1 -0
  27. package/dist/chunk-QOXGIB3R.js +393 -0
  28. package/dist/chunk-QOXGIB3R.js.map +1 -0
  29. package/dist/chunk-UUTLLC54.js +158 -0
  30. package/dist/chunk-UUTLLC54.js.map +1 -0
  31. package/dist/chunk-V3DLUVOE.js +112 -0
  32. package/dist/chunk-V3DLUVOE.js.map +1 -0
  33. package/dist/chunk-YSXW2HN6.js +104 -0
  34. package/dist/chunk-YSXW2HN6.js.map +1 -0
  35. package/dist/ci-ZQZ6RBUJ.js +16 -0
  36. package/dist/ci-ZQZ6RBUJ.js.map +1 -0
  37. package/dist/create-K75OY6XK.js +18 -0
  38. package/dist/create-K75OY6XK.js.map +1 -0
  39. package/dist/dev-WQWFEA6I.js +11 -0
  40. package/dist/dev-WQWFEA6I.js.map +1 -0
  41. package/dist/doctor-MFYBZUKO.js +13 -0
  42. package/dist/doctor-MFYBZUKO.js.map +1 -0
  43. package/dist/holdout-PECSNGAD.js +44 -0
  44. package/dist/holdout-PECSNGAD.js.map +1 -0
  45. package/dist/index.js +84 -2238
  46. package/dist/index.js.map +1 -1
  47. package/dist/init-QAAM2GQ7.js +15 -0
  48. package/dist/init-QAAM2GQ7.js.map +1 -0
  49. package/dist/lifecycle-56HM7ITG.js +12 -0
  50. package/dist/lifecycle-56HM7ITG.js.map +1 -0
  51. package/dist/login-TTWSQ7XS.js +18 -0
  52. package/dist/login-TTWSQ7XS.js.map +1 -0
  53. package/dist/menu-UQX3K5QR.js +162 -0
  54. package/dist/menu-UQX3K5QR.js.map +1 -0
  55. package/dist/plan-BSFSMKTU.js +135 -0
  56. package/dist/plan-BSFSMKTU.js.map +1 -0
  57. package/dist/push-YVS25VVD.js +16 -0
  58. package/dist/push-YVS25VVD.js.map +1 -0
  59. package/dist/refs-ZDNH6NRK.js +44 -0
  60. package/dist/refs-ZDNH6NRK.js.map +1 -0
  61. package/dist/remove-KFQUK367.js +54 -0
  62. package/dist/remove-KFQUK367.js.map +1 -0
  63. package/dist/report-TF2BLJMC.js +64 -0
  64. package/dist/report-TF2BLJMC.js.map +1 -0
  65. package/dist/results-TLV5KJWO.js +17 -0
  66. package/dist/results-TLV5KJWO.js.map +1 -0
  67. package/dist/review-EIZDOGDC.js +34 -0
  68. package/dist/review-EIZDOGDC.js.map +1 -0
  69. package/dist/ship-4YX2WCBP.js +450 -0
  70. package/dist/ship-4YX2WCBP.js.map +1 -0
  71. package/dist/skills-HWQT3DTJ.js +13 -0
  72. package/dist/skills-HWQT3DTJ.js.map +1 -0
  73. package/dist/status-CWI7ZCYJ.js +11 -0
  74. package/dist/status-CWI7ZCYJ.js.map +1 -0
  75. package/package.json +22 -5
package/dist/index.js CHANGED
@@ -1,2216 +1,13 @@
1
1
  #!/usr/bin/env node
2
+ import {
3
+ c,
4
+ errorJson,
5
+ fail
6
+ } from "./chunk-V3DLUVOE.js";
2
7
 
3
8
  // src/index.ts
9
+ import { createRequire } from "module";
4
10
  import { parseArgs } from "util";
5
-
6
- // src/commands/create.ts
7
- import * as p from "@clack/prompts";
8
- import { mvtVariants } from "@splithub/core";
9
- import { existsSync as existsSync2, mkdirSync, writeFileSync as writeFileSync2 } from "fs";
10
- import { join as join2, relative } from "path";
11
-
12
- // src/config-file.ts
13
- import { isSplitHubConfig } from "@splithub/core";
14
- import { readFileSync, writeFileSync } from "fs";
15
- import { pathToFileURL } from "url";
16
- async function loadConfig(file) {
17
- const { createJiti } = await import("jiti");
18
- const jiti = createJiti(pathToFileURL(file).href, { fsCache: false, moduleCache: false });
19
- const mod = await jiti.import(file, { default: true });
20
- if (!isSplitHubConfig(mod)) {
21
- throw new Error(`${file} must \`export default defineConfig({...})\` from @splithub/core.`);
22
- }
23
- return mod;
24
- }
25
- function keyPattern(key) {
26
- const esc = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
27
- return new RegExp(`(^|\\n)([ \\t]*)(['"]?)${esc}\\3[ \\t]*:[ \\t]*\\{`);
28
- }
29
- function findObjectEnd(source, open) {
30
- let depth = 0;
31
- let inStr = null;
32
- let inLineComment = false;
33
- for (let i = open; i < source.length; i++) {
34
- const ch = source[i];
35
- if (inLineComment) {
36
- if (ch === "\n") inLineComment = false;
37
- continue;
38
- }
39
- if (inStr) {
40
- if (ch === "\\") i++;
41
- else if (ch === inStr) inStr = null;
42
- continue;
43
- }
44
- if (ch === "/" && source[i + 1] === "/") {
45
- inLineComment = true;
46
- continue;
47
- }
48
- if (ch === "'" || ch === '"' || ch === "`") inStr = ch;
49
- else if (ch === "{") depth++;
50
- else if (ch === "}") {
51
- depth--;
52
- if (depth === 0) return i;
53
- }
54
- }
55
- return null;
56
- }
57
- function findExperimentBlock(source, key) {
58
- const expIdx = source.search(/experiments\s*:\s*\{/);
59
- if (expIdx < 0) return null;
60
- const m = keyPattern(key).exec(source.slice(expIdx));
61
- if (!m) return null;
62
- const open = expIdx + m.index + m[0].length - 1;
63
- const close = findObjectEnd(source, open);
64
- return close === null ? null : [open, close];
65
- }
66
- function hasExperiment(source, key) {
67
- return findExperimentBlock(source, key) !== null;
68
- }
69
- function q(s) {
70
- return `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
71
- }
72
- function k(s) {
73
- return /^[a-z_$][\w$]*$/i.test(s) ? s : q(s);
74
- }
75
- function renderExperiment(e, indent = " ") {
76
- const i2 = indent + " ";
77
- const i3 = i2 + " ";
78
- const lines = [`${k(e.key)}: {`];
79
- lines.push(`${i2}kind: ${q(e.kind)},`);
80
- lines.push(`${i2}status: ${q(e.status)},`);
81
- if (e.match) lines.push(`${i2}match: ${q(e.match)},`);
82
- if (e.kind === "mvt") {
83
- lines.push(`${i2}factors: {`);
84
- for (const [factor, levels] of Object.entries(e.factors ?? {})) {
85
- lines.push(`${i3}${k(factor)}: { ${Object.entries(levels).map(([l, v]) => `${k(l)}: ${q(v)}`).join(", ")} },`);
86
- }
87
- lines.push(`${i2}},`);
88
- } else if (e.kind === "component") {
89
- lines.push(`${i2}variants: { ${e.variants.map((v) => `${k(v.key)}: ${v.weight}`).join(", ")} },`);
90
- } else {
91
- lines.push(`${i2}variants: {`);
92
- for (const v of e.variants) {
93
- const extra = e.kind === "value" ? `value: ${q(v.value ?? "")}` : `to: ${q(v.to ?? "/")}`;
94
- lines.push(`${i3}${k(v.key)}: { weight: ${v.weight}, ${extra} },`);
95
- }
96
- lines.push(`${i2}},`);
97
- }
98
- if (e.goal) lines.push(`${i2}goal: ${q(e.goal)},`);
99
- if (e.traffic !== void 0 && e.traffic !== 1) lines.push(`${i2}traffic: ${e.traffic},`);
100
- if (e.maxExposures) lines.push(`${i2}maxExposures: ${e.maxExposures},`);
101
- if (e.schedule && (e.schedule.startAt || e.schedule.endAt)) lines.push(`${i2}schedule: { ${[e.schedule.startAt ? `startAt: ${q(e.schedule.startAt)}` : null, e.schedule.endAt ? `endAt: ${q(e.schedule.endAt)}` : null].filter(Boolean).join(", ")} },`);
102
- if (e.description) lines.push(`${i2}description: ${q(e.description)},`);
103
- if (e.flow) {
104
- const json = JSON.stringify(e.flow, null, 2).split("\n");
105
- lines.push(`${i2}// targeting graph from the dashboard; edit it there or by hand
106
- ${i2}flow: ${json.map((l, n) => n === 0 ? l : i2 + l).join("\n")},`);
107
- }
108
- lines.push(`${indent}}`);
109
- return lines.join("\n");
110
- }
111
- function insertExperiment(source, e) {
112
- const m = /experiments\s*:\s*\{/.exec(source);
113
- if (!m) throw new Error("could not find `experiments: {` in the config file.");
114
- const open = m.index + m[0].length - 1;
115
- const close = findObjectEnd(source, open);
116
- if (close === null) throw new Error("unbalanced braces after `experiments: {`.");
117
- const lineStart = source.lastIndexOf("\n", close) + 1;
118
- const closeIndent = /^[ \t]*/.exec(source.slice(lineStart, close))?.[0] ?? " ";
119
- const indent = closeIndent + " ";
120
- const before = source.slice(open + 1, lineStart).replace(/\/\/[^\n]*/g, "").trimEnd();
121
- const needsComma = before.length > 0 && !before.endsWith(",");
122
- const block = `${indent}${renderExperiment(e, indent)},
123
- `;
124
- const head = source.slice(0, lineStart);
125
- return `${needsComma ? addTrailingComma(head) : head}${block}${source.slice(lineStart)}`;
126
- }
127
- function addTrailingComma(head) {
128
- const lines = head.split("\n");
129
- for (let i = lines.length - 1; i >= 0; i--) {
130
- const line = lines[i];
131
- const trimmed = line.trim();
132
- if (trimmed === "" || trimmed.startsWith("//")) continue;
133
- const commentAt = line.indexOf("//");
134
- const code = commentAt >= 0 ? line.slice(0, commentAt) : line;
135
- const rest = commentAt >= 0 ? line.slice(commentAt) : "";
136
- const codeTrimmed = code.trimEnd();
137
- lines[i] = `${codeTrimmed},${code.slice(codeTrimmed.length)}${rest}`;
138
- break;
139
- }
140
- return lines.join("\n");
141
- }
142
- function setExperimentStatus(source, key, status2) {
143
- const block = findExperimentBlock(source, key);
144
- if (!block) throw new Error(`experiment "${key}" not found in the config file.`);
145
- const [open, close] = block;
146
- const body = source.slice(open, close + 1);
147
- const re = /(status\s*:\s*)(['"])[a-z]+\2/;
148
- if (!re.test(body)) throw new Error(`experiment "${key}" has no \`status\` field.`);
149
- const updated = body.replace(re, `$1$2${status2}$2`);
150
- return source.slice(0, open) + updated + source.slice(close + 1);
151
- }
152
- function readSource(file) {
153
- return readFileSync(file, "utf8");
154
- }
155
- function writeSource(file, source) {
156
- writeFileSync(file, source, "utf8");
157
- }
158
-
159
- // src/project.ts
160
- import { existsSync, readFileSync as readFileSync2, readdirSync, statSync } from "fs";
161
- import { join, resolve } from "path";
162
- var CONFIG_NAMES = ["splithub.config.ts", "splithub.config.mts", "splithub.config.js", "splithub.config.mjs"];
163
- function findConfigFile(root) {
164
- for (const name of CONFIG_NAMES) {
165
- const p4 = join(root, name);
166
- if (existsSync(p4)) return p4;
167
- }
168
- return null;
169
- }
170
- function detectProject(cwd = process.cwd()) {
171
- const root = resolve(cwd);
172
- let name = "my-app";
173
- let deps = {};
174
- try {
175
- const pkg = JSON.parse(readFileSync2(join(root, "package.json"), "utf8"));
176
- name = pkg.name ?? name;
177
- deps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
178
- } catch {
179
- }
180
- const has = (file) => existsSync(join(root, file));
181
- const framework = deps.next || has("next.config.js") || has("next.config.mjs") || has("next.config.ts") ? "next" : deps.vite || has("vite.config.ts") || has("vite.config.js") || has("vite.config.mjs") ? "vite" : "unknown";
182
- const packageManager = has("pnpm-lock.yaml") ? "pnpm" : has("yarn.lock") ? "yarn" : has("bun.lockb") || has("bun.lock") ? "bun" : "npm";
183
- const appDir = has("src/app") ? "src/app" : has("app") ? "app" : null;
184
- return {
185
- root,
186
- name: name.replace(/^@[^/]+\//, ""),
187
- framework,
188
- packageManager,
189
- appDir,
190
- hasSrc: has("src"),
191
- configFile: findConfigFile(root),
192
- typescript: has("tsconfig.json")
193
- };
194
- }
195
- function installCommand(pm, packages, dev2 = false) {
196
- const flag = dev2 ? pm === "npm" ? " -D" : " -D" : "";
197
- switch (pm) {
198
- case "pnpm":
199
- return `pnpm add${flag} ${packages.join(" ")}`;
200
- case "yarn":
201
- return `yarn add${flag} ${packages.join(" ")}`;
202
- case "bun":
203
- return `bun add${dev2 ? " -d" : ""} ${packages.join(" ")}`;
204
- default:
205
- return `npm install${flag} ${packages.join(" ")}`;
206
- }
207
- }
208
- var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".next", "dist", "build", ".git", "coverage", "out", ".turbo"]);
209
- var CODE_EXT = /\.(tsx?|jsx?|mjs|cjs|mts|cts)$/;
210
- function listSourceFiles(root, maxFiles = 5e3) {
211
- const out = [];
212
- const walk = (dir, depth) => {
213
- if (out.length >= maxFiles || depth > 8) return;
214
- let entries;
215
- try {
216
- entries = readdirSync(dir);
217
- } catch {
218
- return;
219
- }
220
- for (const entry of entries) {
221
- if (SKIP_DIRS.has(entry)) continue;
222
- const full = join(dir, entry);
223
- let st;
224
- try {
225
- st = statSync(full);
226
- } catch {
227
- continue;
228
- }
229
- if (st.isDirectory()) walk(full, depth + 1);
230
- else if (CODE_EXT.test(entry)) out.push(full);
231
- }
232
- };
233
- walk(root, 0);
234
- return out;
235
- }
236
- function grepFiles(files, needle) {
237
- const hits = [];
238
- for (const f of files) {
239
- try {
240
- if (readFileSync2(f, "utf8").includes(needle)) hits.push(f);
241
- } catch {
242
- }
243
- }
244
- return hits;
245
- }
246
-
247
- // src/skills-self-hosted.ts
248
- var SKILL_SELF_HOSTED = `---
249
- name: splithub-self-hosted
250
- description: Keep SplitHub events in your own database (self mode): which tables, how to write a Store for Postgres, MySQL, Prisma, Drizzle, Supabase or anything else, where the ingest route lives, how the CLI reads results from it, and how to get cloud data into your own database for reports. Use when the user wants data in their infra or asks about tables, schema or reporting.
251
- ---
252
-
253
- # SplitHub with your own database
254
-
255
- Two ways to own the data:
256
-
257
- 1. **Self mode** \u2014 the app hosts the ingest route and the store; nothing leaves your infra.
258
- \`splithub.config.ts\`: \`storage: { mode: 'self', endpoint: '/api/splithub' }\`.
259
- 2. **Cloud + export** \u2014 events go to SplitHub Cloud; you pull summaries into your warehouse for reports.
260
-
261
- ## Self mode: the pieces
262
-
263
- - Route: \`app/api/splithub/[[...path]]/route.ts\` (Next.js) or any fetch-style handler from
264
- \`createSplitHubHandler({ config, store, adminToken })\` in \`@splithub/node\`. It accepts
265
- \`POST /events\` from the SDK and answers \`GET /status\`, \`GET /results/<id>\` for the CLI
266
- (\`npx splithub status\` talks to the local dev server, or \`--url https://your.app/api/splithub\`).
267
- - Store: an object with three methods (below). Ready-made: \`@splithub/adapter-sqlite\`
268
- (Node 22.13+, \`node:sqlite\`, zero setup) and \`@splithub/adapter-d1\` (Cloudflare D1).
269
- \`npx splithub init --mode self --db postgres|mysql|custom\` writes \`splithub/store.ts\` with a
270
- working Postgres (pg) or MySQL (mysql2) store, or a documented stub for anything else.
271
- - Admin token: set \`SPLITHUB_ADMIN_TOKEN\` in the app and \`--token\` / \`SPLITHUB_ADMIN_TOKEN\` for
272
- the CLI, so results are not public.
273
-
274
- ## The events table
275
-
276
- One table, one row per event. Column names are yours; the templates use these:
277
-
278
- | column | type | meaning |
279
- |---|---|---|
280
- | id | text, primary key | client-generated, unique; dedupe on it (retries resend batches) |
281
- | type | text | \`exposure\` or \`goal\` |
282
- | experiment, variant | text | for exposures |
283
- | goal | text | for goals |
284
- | visitor_id, session_id | text | \`sh_vid\` cookie / session |
285
- | ts | bigint | client time, unix ms |
286
- | url | text | page |
287
- | props | json | goal payload, e.g. \`{ "revenue": 49 }\` |
288
- | received_at | bigint | server time, unix ms |
289
- | host, country, device, browser | text | request metadata (fill from headers if you want breakdowns) |
290
-
291
- Indexes: \`(type, experiment, visitor_id, ts)\` and \`(type, goal, visitor_id, ts)\`.
292
-
293
- ## The Store interface (\`@splithub/node\`)
294
-
295
- \`\`\`ts
296
- interface Store {
297
- insertEvents(events: StoredEvent[]): Promise<number>; // skip existing ids, return inserted count
298
- variantCounts(experiment: string, goal: string): Promise<VariantCounts[]>; // per variant: exposures, conversions, revenue
299
- summaries(): Promise<ExperimentSummary[]>; // per experiment: exposures, visitors, first/last ts
300
- close?(): Promise<void> | void;
301
- }
302
- \`\`\`
303
-
304
- Attribution rule \u2014 keep it exactly, so self-hosted results equal the cloud's:
305
- **a visitor converts for a variant when they sent the goal at or after their first exposure to
306
- that variant; exposures and conversions count unique visitors.** The SQL in the generated
307
- \`splithub/store.ts\` implements it (CTE \`first_exposure\`, then goals joined with \`ts >= first_ts\`).
308
-
309
- Prisma / Drizzle: map the table in your schema and write the three methods with the ORM, or run the
310
- one raw query for \`variantCounts\`. Supabase: the same SQL as a Postgres function called through
311
- \`rpc\`. Mongo: \`$group\` by variant and visitor with \`$min ts\`, then \`$lookup\` goals.
312
-
313
- ## Reports from the cloud into your database
314
-
315
- - CSV: dashboard \u2192 experiment \u2192 Export (summary, daily timeline, raw events up to 50k rows).
316
- - Webhook channel for alerts and the digest: POST JSON to your endpoint when something happens.
317
- - Scheduled pull: a cron in your app calls \`GET /v1/status\` and \`GET /v1/results/<id>\` with the
318
- API key (\`sk_\u2026\`) and stores the verdicts. Raw events live 30\u201390 days in the cloud (plan dependent),
319
- aggregates a year: pull summaries, not raw rows, for long-term reporting.
320
- - Need every raw event forever in your infra? Use self mode; one store per project.
321
-
322
- ## Do not
323
-
324
- - Put database credentials in \`splithub.config.ts\` (it ships to the browser). They belong in the route's env.
325
- - Compute winners from raw rates in SQL; use \`npx splithub results\` (or \`@splithub/stats\`) for the verdict.
326
- `;
327
-
328
- // src/skills-ship.ts
329
- var SKILL_SHIP = `---
330
- name: splithub-ship
331
- description: Ship the winner of an A/B test and remove the test from the code: keep only the winning value, component or page, delete the losing variants, finish the experiment and clean splithub.config.ts. Use when a test has a verdict and the user says ship it, roll out the winner, remove the test, or clean up; and whenever a test shows status finished and the user agreed on which variant to keep.
332
- ---
333
-
334
- # Shipping the winner
335
-
336
- Goal: the app behaves exactly as the winning variant did, with no experiment left in the code or in the config.
337
-
338
- ## Before touching code
339
-
340
- 1. Read the verdict: \`npx splithub results <id> --json\`. Act on \`verdict.status\`:
341
- - \`winner_found\`: ship \`verdict.winner\`.
342
- - \`no_significant_difference\` with enough sample: keep the control, or the simpler variant if the user agrees.
343
- - \`insufficient_sample\`: do not ship. Say roughly how many more visitors are needed (\`sample.neededPerVariant\`).
344
- - \`srm_detected\`: do not ship. The split is broken; fix the setup first.
345
- 2. Finish the experiment first so new visitors stop entering: \`npx splithub finish <id>\`. Results stay readable afterwards.
346
-
347
- ## Per kind
348
-
349
- - **value** (\`useValue('<id>')\`, \`sh.value('<id>')\`, \`getValue\`): replace every call with the winning literal (text, number, JSON).
350
- Remove imports that become unused.
351
- - **component** (\`<Experiment id="<id>">\` with \`<Variant>\` children, or a \`useVariant('<id>')\` switch): keep the winning branch
352
- inline where the wrapper was, delete the other branches and the wrapper. Delete components, files and styles only the losing
353
- variants used.
354
- - **redirect** (the winner is a URL): if a new page won, make it the real page: serve the winning content at the original path
355
- (move the route, or add a permanent redirect from the old path), delete the losing page, update internal links and the sitemap.
356
- If the control won, delete the new page and its route. Remove the experiment's \`match\`.
357
- - **drop-in script sites** (no SDK): nothing to change in code; remove the test from the config or the dashboard.
358
-
359
- ## Config and cloud
360
-
361
- 3. Remove the experiment from \`experiments\` in \`splithub.config.ts\`. Keep the goal if another test uses it. Cloud mode:
362
- \`npx splithub push\`. Tests created in the dashboard ("cloud" badge): finished is enough, or delete them there.
363
- 4. Keep \`track('<goal>')\` calls when the goal is still in use; remove them only if nothing else measures that goal.
364
-
365
- ## Verify and report
366
-
367
- 5. \`npx splithub doctor\`, then the project's typecheck and tests. Grep for the experiment id: nothing should reference it.
368
- 6. Report what changed (files, the winning content) and the verdict in one line with its numbers.
369
- 7. Never reuse the experiment id for a new test: the history belongs to the old one.
370
- `;
371
-
372
- // src/skills.ts
373
- var SKILL_SPLITHUB = `---
374
- name: splithub
375
- description: Add, change, run or read A/B experiments in an app that uses SplitHub (@splithub/react, splithub.config.ts, the splithub CLI, SplitHub Cloud). Use when the user asks to A/B test a component, headline, image, price, CTA or page, asks which variant is winning, or wants to start, pause or finish a test.
376
- ---
377
-
378
- # SplitHub for coding agents
379
-
380
- Three pieces: \`splithub.config.ts\` (the experiments; source of truth when it exists),
381
- \`@splithub/react\` (renders variants), the \`splithub\` CLI (creates, pushes, reads results).
382
- Events go to the app's own database (self mode) or to SplitHub Cloud (cloud mode).
383
-
384
- ## Where things live
385
-
386
- - Config: \`splithub.config.ts\` in the project root. Experiments and goals. Ships to the browser: never put secrets in it.
387
- - Credentials: \`npx splithub login\` (or \`init --mode cloud\`) prints a link; the human approves it in the browser; the CLI
388
- stores a project API key for this folder. Never ask the user to paste keys. CI uses \`SPLITHUB_API_KEY\`.
389
- - The public key (\`pk_\`) ends up in \`storage.key\` of the config from any of: \`login\` (saved credentials), the first
390
- \`push\`, \`init --key\`, or \`SPLITHUB_API_KEY\` in the environment (init asks the cloud). Missing key = events go nowhere.
391
- - Cloud: \`npx splithub push\` uploads the config; \`npx splithub pull\` writes dashboard-created experiments into the file.
392
- - Results: \`npx splithub status --json\`, \`npx splithub results <id> --json\`.
393
- - Everything interactive: \`npx splithub\` (menu). Everything scriptable: subcommands + \`--json\`.
394
-
395
- ## Pick the kind
396
-
397
- | kind | use it when | create | read in code |
398
- |---|---|---|---|
399
- | \`value\` | only data changes: text, number, image URL, price, JSON. The default choice: no new components. | \`--variants control,bold --value control="Old text" --value bold="New text"\` | \`const text = useValue<string>('<id>')\`; server components: \`getValue\` from \`@splithub/next\`; no SDK: \`sh.value('<id>')\` |
400
- | \`component\` | structure changes: a layout, a section, a flow, a different component per variant | \`--variants control,bold\` (the CLI scaffolds \`splithub/<id>/<Variant>.tsx\` stubs) | \`<Experiment id="<id>"><Variant name="control">\u2026</Variant><Variant name="bold">\u2026</Variant></Experiment>\`, or \`useVariant('<id>')\` in a switch |
401
- | \`redirect\` | a whole page changes: another URL per variant | \`--match / --to control=/ --to v2=/home-v2\` | nothing: \`@splithub/next\` middleware or the drop-in script \`<script src="https://go.splithub.io/sh.js" data-key="pk_\u2026">\` sends visitors there |
402
- | \`mvt\` | several things change at once (headline \xD7 button \xD7 image) and the user wants to know which of them matters; every combination is tested and each factor is read on its own | \`--factor headline=old:"Old text",new:"New text" --factor button=blue:#2563eb,green:#16a34a\` (no \`--variants\`; first level = control; at most 4 factors \xD7 4 levels, 16 combinations) | \`const { headline, button } = useValue<{ headline: string; button: string }>('<id>')\` |
403
-
404
- mvt needs more visitors than an A/B test: every combination must reach the minimum on its own (the results show the
405
- combinations and, below them, each factor summed over its combinations). With little traffic, test one thing with \`value\`.
406
-
407
- ## Create an experiment
408
-
409
- 1. \`npx splithub create --kind <value|component|redirect|mvt> --id <key> \u2026 --goal <goal> --yes --json\` (see the table).
410
- 2. Goal: pick an existing key or add one to \`goals\`:
411
- \`{ type: 'event' }\` + \`track('<goal>')\` where the conversion happens; \`{ type: 'pageview', path: '/thanks' }\`;
412
- \`{ type: 'click', selector: '#buy' }\` (tracked automatically by the SDK and the script).
413
- 3. Wire it in code. \`create\` writes \`status: 'running'\`: the test goes live for every visitor, first page view
414
- included, as soon as this code is deployed. Use \`--status draft\` only when the user asks to hold it.
415
- 4. Cloud mode: \`npx splithub push\` after any config change.
416
- 5. Hand-off, always: end your reply by saying the test is **running in the config** and goes live when the user deploys
417
- this code; nothing is recorded before that, and local development never sends events to the cloud. Tell them how to
418
- check it locally (\`?sh_force=<id>:<variant>\`) and that Pause in the dashboard or \`npx splithub pause <id>\` holds it.
419
- For a draft (only if asked): say visitors do not see it and nothing is recorded until \`npx splithub start <id>\`.
420
-
421
- A draft is invisible to visitors. To check one before starting: \`runDraftsInDev: true\` at the top level of the config
422
- serves drafts like running tests in development only (\`NODE_ENV=development\`: \`next dev\`, \`vite\`);
423
- \`?sh_force=<id>:<variant>\` shows one variant on any page, draft or not, without recording an exposure;
424
- \`?sh_debug=1\` (or \`npx splithub dev\`) logs every decision and opens a panel to switch variants.
425
- In development the SDK explains drafts, paused tests and held-back events in one line each. Vite apps: add \`splithub()\`
426
- from \`@splithub/core/vite\` to the plugins in vite.config so these lines and a summary of every experiment appear in the
427
- terminal that runs \`vite\`; Next.js server code prints them in its terminal anyway.
428
-
429
- Keys: lowercase a-z 0-9 - _, max 64 chars. First variant = control. Weights are relative (50/50, 1/1, 90/10).
430
- Targeting (country, device, UTM, cookie, time) is a \`flow\` graph on the experiment, edited in the dashboard; \`pull\` brings it into the file.
431
-
432
- ## Read results
433
-
434
- \`verdict.status\` \u2208 no_data | insufficient_sample | srm_detected | winner_found | no_significant_difference.
435
- Report \`verdict.message\` verbatim and the numbers behind it (visitors per variant, lift, p-value, CI).
436
- Never declare a winner from raw rates. \`srm_detected\` means the split is broken: fix the setup before anything else.
437
-
438
- ## Finish, and what to do when a test is finished
439
-
440
- \`npx splithub finish <id>\` stops the test (live within a minute in cloud mode). A finished test keeps its numbers for as long
441
- as it stays in the config; the code still contains every variant until someone removes it.
442
-
443
- Whenever you see a test with \`status: finished\` (in \`status\`, \`results\`, the MCP tools, or right after you finished it):
444
- 1. Read \`npx splithub results <id> --json\` and tell the user the verdict in one line with its numbers.
445
- 2. Ask two questions, do not assume: **which variant to keep** (recommend \`verdict.winner\`; with no significant
446
- difference, the control or the simpler one) and **whether to remove the test from the code now**.
447
- 3. On yes, follow the \`splithub-ship\` skill: keep only the chosen variant's content, delete the other variants' code and
448
- files, remove the entry from \`splithub.config.ts\`, \`push\` in cloud mode, run \`doctor\` and the project's checks.
449
- 4. On no, leave everything: a finished test costs nothing and the user may come back to it.
450
-
451
- A \`paused\` test is not over: say so and ask whether to resume (\`start\`) or finish it.
452
-
453
- ## Do not
454
-
455
- - Nest an \`<Experiment>\` inside a \`<Variant>\` of the same id; call hooks conditionally.
456
- - Change \`seed\`, weights or variants of a running experiment (reshuffles visitors). Create a new experiment instead.
457
- - Edit in the dashboard what the config file owns: file experiments are read-only there (pause/finish still work).
458
- - Run more than 2-3 experiments on one page of a low-traffic site.
459
- - Put secrets, API keys or database credentials in the config or in the browser. \`pk_\` is public, \`sk_\` is not.
460
- `;
461
- var SKILL_AB_TESTING = `---
462
- name: ab-testing
463
- description: How to design, run and read an A/B test correctly: hypothesis, control, primary metric, sample size, significance, SRM, peeking, when to stop. Use before creating an experiment or when interpreting results, with any tool.
464
- ---
465
-
466
- # A/B testing, the parts that matter
467
-
468
- An A/B test splits visitors at random into variants and compares one metric. It answers one question:
469
- "does this change move this metric?" Everything below exists to keep that answer honest.
470
-
471
- ## Before creating a test
472
-
473
- 1. **One hypothesis, one primary metric.** "A shorter signup form raises signup completion." The metric is a goal
474
- (event, page visit or click) that happens after the exposure. Pick it before looking at data.
475
- 2. **Control first.** The first variant is what exists today. Change one thing per variant; several unrelated changes
476
- in one variant cannot be attributed.
477
- 3. **Traffic reality.** Rough rule: to detect a relative lift L on a baseline rate p you need about
478
- \`16 \xB7 p(1-p) / (p\xB7L)\xB2\` visitors per variant (95% confidence, 80% power).
479
- Examples: baseline 5%, lift 20% \u2192 ~7,600 per variant; baseline 2%, lift 10% \u2192 ~78,000 per variant.
480
- If the site cannot reach that in 2-4 weeks, test a bigger change or a higher-traffic page.
481
- 4. **Few tests per page.** Interactions between simultaneous tests on the same page muddy both.
482
-
483
- ## While it runs
484
-
485
- - **Do not peek and stop early.** Checking daily and stopping at the first "significant" moment inflates false
486
- positives several times. Decide the sample or the duration up front; run whole weeks (weekday/weekend cycles).
487
- - **SRM (sample ratio mismatch).** If the split is 50/50 and you see 60/40, the assignment or the tracking is broken
488
- (bots, caching, redirect loops, a variant that errors). Fix first; results from an SRM run are meaningless.
489
- - **Keep variants frozen.** Changing copy, weights or targeting mid-run reshuffles who saw what. Start a new test.
490
- - **Watch the guardrails.** A variant that wins the primary metric but breaks revenue, errors or latency is not a win.
491
-
492
- ## Reading results
493
-
494
- - Significance (p < 0.05 after correction for several variants) says the difference is unlikely to be noise;
495
- the confidence interval says how big it plausibly is. A "winner" with a CI that touches 0 is a weak win.
496
- - "No significant difference" with a sample smaller than needed means **keep running**, not "no effect".
497
- With enough sample it means the change does not matter: ship whichever is cheaper or cleaner.
498
- - Relative lift is on the baseline rate: 5% \u2192 6% is +20% relative, +1 point absolute. Report both.
499
- - Attribution: conversions count only after the visitor's first exposure, per unique visitor.
500
- - Segments (country, device) are for hypotheses, not verdicts: slicing after the fact finds noise.
501
-
502
- ## When to stop
503
-
504
- - Winner found with the planned sample \u2192 ship it, finish the test, remove the losing code.
505
- - Planned sample reached, no difference \u2192 ship the simpler variant, finish.
506
- - SRM or broken tracking \u2192 stop, fix, restart as a new test.
507
- - The business moved on \u2192 finish; do not leave tests running forever (they cost events and split traffic).
508
-
509
- ## Vocabulary
510
-
511
- exposure = a visitor saw a variant \xB7 conversion = the goal happened after exposure \xB7 lift = relative change in rate \xB7
512
- p-value = chance of seeing this difference by luck \xB7 CI = range the true difference likely lies in \xB7
513
- SRM = the split differs from the configured weights \xB7 guardrail = a metric that must not get worse.
514
- `;
515
- var SKILL_SPLITHUB_API = `---
516
- name: splithub-api
517
- description: Use the SplitHub Cloud HTTP API directly: public key event ingest, API-key endpoints for config, status, results and overrides, hosted experiments. Use when writing a server, a script, a non-JS client, or when the CLI is not available.
518
- ---
519
-
520
- # SplitHub Cloud API
521
-
522
- Base URL: \`https://go.splithub.io\`. JSON in, JSON out (no envelope under \`/v1/*\`). Two credentials:
523
-
524
- - **Public key \`pk_\u2026\`**: identifies the project to browsers and SDKs. Safe to ship. Can only send events and read
525
- the public overrides JSON.
526
- - **API key \`sk_\u2026\`**: project-scoped secret for servers, CI and the CLI (\`npx splithub login\` mints one through a
527
- browser approval; or Settings \u2192 API keys in the dashboard). Never in client code.
528
-
529
- ## Send events (public key)
530
-
531
- \`\`\`http
532
- POST /v1/events
533
- Authorization: Bearer pk_live_\u2026
534
- Content-Type: application/json
535
-
536
- { "project": "my-app", "sdk": "custom/1.0", "events": [
537
- { "id": "e_01h\u2026", "type": "exposure", "exp": "hero-cta", "var": "bold", "vid": "v_abc", "sid": "s_1", "ts": 1760000000000, "url": "/" },
538
- { "id": "g_01h\u2026", "type": "goal", "goal": "signup", "vid": "v_abc", "sid": "s_1", "ts": 1760000010000, "props": { "revenue": 49 } }
539
- ] }
540
- \`\`\`
541
-
542
- - \`id\`: unique per event (8-64 chars, [a-z0-9_-]); duplicates are ignored. \`vid\`: stable visitor id (cookie \`sh_vid\`).
543
- - Reply \`202 { ok, received, inserted, dropped }\`. A project with nothing running or no config yet answers
544
- \`202 { ok, inserted: 0, idle: 'no_running' | 'no_config' }\`: nothing stored, not an error. \`429\` with \`code\` \u2208
545
- quota_exceeded | deleted: back off for \`Retry-After\` seconds; nothing was stored. \`403 origin_not_allowed\` when the project restricts domains.
546
- - Exposures for experiments that are not running are dropped and not billed. Goals are never billed.
547
-
548
- ## Live config for clients (public key)
549
-
550
- \`GET /v1/overrides/<pk>.json\` \u2192 \`{ version, experiments: { <id>: { status?, traffic?, weights?, values? } }, added: [ \u2026hosted experiments\u2026 ], goals: [...], ctx: { country, region, city } }\`.
551
- Poll it at most once a minute; the SDK caches it in localStorage. \`ctx\` is the visitor's geo for targeting.
552
-
553
- ## Project endpoints (API key)
554
-
555
- \`\`\`http
556
- GET /v1/status every experiment: status, visitors, days, verdict headline
557
- GET /v1/results/<experiment> full verdict: sample, comparisons (lift, p-value, CI, P(beat)), srm, winner
558
- GET /v1/config the config stored in the cloud (file + dashboard experiments)
559
- PUT /v1/config { config } push a normalized config (what defineConfig returns); answers cloudOnly experiments to adopt
560
- GET /v1/overrides live overrides
561
- PUT /v1/overrides/<experiment> { status | traffic | weights | values } pause / resume / reweight without a deploy
562
- DELETE /v1/overrides/<experiment>
563
- \`\`\`
564
-
565
- \`Authorization: Bearer sk_live_\u2026\` on each. Status values: draft | running | paused | finished.
566
-
567
- ## Dashboard-scope endpoints (session, same shapes the dashboard uses)
568
-
569
- Under \`/v1/projects/<projectId>/\u2026\` with a user session: \`experiments\` (hosted experiments CRUD incl. \`flow\` targeting),
570
- \`goals\`, \`timeline\`, \`breakdown\`, \`realtime\`, \`events\`, \`export\`, \`notes\`, \`domains\`, \`links\`, \`alerts\`, \`billing\`, \`ai\`.
571
- Scripts should prefer the API-key endpoints above; the session ones exist for the UI.
572
-
573
- ## Drop-in script (no SDK)
574
-
575
- \`<script src="https://go.splithub.io/sh.js" data-key="pk_live_\u2026"></script>\` in \`<head>\`: redirect experiments, page-visit and
576
- click goals from the cloud config, \`window.splithub.track('goal')\` for custom events,
577
- \`<meta name="splithub-experiment" content="<id>">\` on a tested page for an instant decision.
578
-
579
- ## Errors
580
-
581
- \`400\` validation (message in \`error\`), \`401\` bad key, \`403\` forbidden, \`404\` unknown experiment/project, \`409\` state
582
- (e.g. \`config_not_pushed\`, \`file_owned\`), \`429\` gate or rate limit. Bodies: \`{ error, code? }\`.
583
- `;
584
- var SKILL_SPLITHUB_MCP = `---
585
- name: splithub-mcp
586
- description: Use or set up the SplitHub MCP server (@splithub/mcp) so an agent can create experiments, read verdicts, start/pause/finish tests and push config through tools instead of shelling out. Use when the user asks to connect SplitHub to Claude Code, Cursor, Codex or another MCP client.
587
- ---
588
-
589
- # SplitHub MCP server
590
-
591
- \`@splithub/mcp\` is a stdio MCP server that wraps the \`splithub\` CLI for the current project folder.
592
- Same credentials and config file as the CLI; nothing extra to configure.
593
-
594
- ## Register it
595
-
596
- Claude Code (project scope, committed in \`.mcp.json\`):
597
-
598
- \`\`\`json
599
- { "mcpServers": { "splithub": { "command": "npx", "args": ["-y", "@splithub/mcp"] } } }
600
- \`\`\`
601
-
602
- or \`claude mcp add splithub -- npx -y @splithub/mcp\`. Cursor: the same object in \`.cursor/mcp.json\`.
603
- Codex / other clients: command \`npx\`, args \`-y @splithub/mcp\`. \`npx splithub skills --mcp\` writes both files.
604
- Env: \`SPLITHUB_PROJECT_DIR\` (defaults to the MCP client's working directory), \`SPLITHUB_API\` (staging or self-hosted cloud), \`SPLITHUB_API_KEY\` (CI).
605
-
606
- ## Tools
607
-
608
- | tool | does | notes |
609
- |---|---|---|
610
- | \`splithub_status\` | all experiments with verdict headline | start here |
611
- | \`splithub_results\` | full verdict for one experiment | report \`verdict.message\` verbatim |
612
- | \`splithub_review\` | stored AI reviews (Pro): at start, on verdict changes, on finish, on demand | quote them as the analyst's opinion, the verdict stays the source of truth |
613
- | \`splithub_create_experiment\` | adds an experiment to splithub.config.ts | kind value / component / redirect / mvt, id, variants (or factors for mvt), goal, values/to; starts as draft |
614
- | \`splithub_set_status\` | start / pause / finish | applies live in cloud mode; after \`finished\`, ask which variant to keep and whether to clean the code (splithub-ship skill) |
615
- | \`splithub_push\` / \`splithub_pull\` | sync the config with the cloud | pull adopts dashboard-created experiments |
616
- | \`splithub_doctor\` | checks the installation | run after wiring code |
617
- | \`splithub_login\` | returns a sign-in link; the human approves it in the browser | show the link, then call \`splithub_whoami\` |
618
- | \`splithub_whoami\` | connected project and keys | |
619
-
620
- ## Working rules
621
-
622
- - Create (running by default) \u2192 wire in code \u2192 \`doctor\` \u2192 \`push\` (cloud mode) \u2192 tell the user it goes live when they
623
- deploy this code and that \`set_status paused\` or Pause in the dashboard holds it.
624
- - Results: never call a winner from raw rates; quote the verdict. \`srm_detected\` = fix the setup first.
625
- - Running experiments are frozen: no weight / variant / seed edits; create a new one.
626
- - If a tool answers that the folder is not connected, call \`splithub_login\`, show the link to the user, wait for them, then retry.
627
- - A \`finished\` experiment in \`splithub_status\` or \`splithub_results\` means the test is over but its code is still there: report
628
- the verdict, ask which variant to keep and whether to remove the test from the code, then follow the \`splithub-ship\` skill.
629
- `;
630
- var SKILLS = [
631
- { dir: "splithub", body: SKILL_SPLITHUB },
632
- { dir: "ab-testing", body: SKILL_AB_TESTING },
633
- { dir: "splithub-api", body: SKILL_SPLITHUB_API },
634
- { dir: "splithub-mcp", body: SKILL_SPLITHUB_MCP },
635
- { dir: "splithub-self-hosted", body: SKILL_SELF_HOSTED },
636
- { dir: "splithub-ship", body: SKILL_SHIP }
637
- ];
638
- var MCP_SERVER_ENTRY = { command: "npx", args: ["-y", "@splithub/mcp"] };
639
-
640
- // src/templates.ts
641
- function configTemplate(project, mode, key) {
642
- const storage = mode === "self" ? `{ mode: 'self', endpoint: '/api/splithub' }` : `{ mode: 'cloud', key: ${key ? `'${key}'` : "process.env.NEXT_PUBLIC_SPLITHUB_KEY ?? ''"} }`;
643
- return `import { defineConfig } from '@splithub/core';
644
-
645
- // SplitHub experiments. This file is the source of truth: the SDK, the CLI
646
- // and the dashboard all read it. Keys: lowercase a-z 0-9 - _. First variant = control.
647
- export default defineConfig({
648
- project: '${project}',
649
- storage: ${storage},
650
- // Drafts behave like running tests while you develop (next dev, vite); production ignores them.
651
- runDraftsInDev: true,
652
-
653
- goals: {
654
- // call track('signup') where the conversion happens
655
- signup: { type: 'event' },
656
- },
657
-
658
- experiments: {
659
- // run \`npx splithub create\` or add entries here:
660
- //
661
- // 'hero-title': {
662
- // kind: 'value',
663
- // status: 'running',
664
- // variants: {
665
- // control: { weight: 50, value: 'Ship faster' },
666
- // direct: { weight: 50, value: 'Know which version wins' },
667
- // },
668
- // goal: 'signup',
669
- // },
670
- },
671
- });
672
- `;
673
- }
674
- function nextMiddlewareTemplate(configImport) {
675
- return `import { splithubMiddleware } from '@splithub/next';
676
- import splithub from '${configImport}';
677
-
678
- // Sets the visitor cookie, forwards it to Server Components and serves
679
- // redirect experiments with an invisible rewrite.
680
- export default splithubMiddleware(splithub);
681
-
682
- export const config = {
683
- matcher: ['/((?!_next|api|.*\\\\..*).*)'],
684
- };
685
- `;
686
- }
687
- function nextRouteTemplate(configImport, store = { imports: "import { sqliteStore } from '@splithub/adapter-sqlite';", factory: "sqliteStore({ file: process.env.SPLITHUB_DB ?? './splithub.db' })" }) {
688
- return `import { createSplitHubHandler } from '@splithub/node';
689
- ${store.imports}
690
- import config from '${configImport}';
691
-
692
- // Self-hosted ingest + results: events stay in your database. The CLI reads
693
- // status / results from this route; set SPLITHUB_ADMIN_TOKEN to protect it.
694
- const handler = createSplitHubHandler({
695
- config,
696
- store: ${store.factory},
697
- adminToken: process.env.SPLITHUB_ADMIN_TOKEN,
698
- });
699
-
700
- export const POST = handler;
701
- export const GET = handler;
702
- export const runtime = 'nodejs';
703
- `;
704
- }
705
- function componentVariantTemplate(name, experiment, variant) {
706
- return `// Variant "${variant}" of experiment "${experiment}". Edit freely.
707
- export function ${name}() {
708
- return (
709
- <section>
710
- <h2>${experiment} \xB7 ${variant}</h2>
711
- </section>
712
- );
713
- }
714
- `;
715
- }
716
- var AGENTS_SECTION = `
717
- ## A/B testing (SplitHub)
718
-
719
- This project uses SplitHub (\`@splithub/react\`). Experiments are declared in
720
- \`splithub.config.ts\` and rendered with \`<Experiment id>\` / \`useVariant(id)\` /
721
- \`useValue(id)\`. Conversions: \`useTrack()\` then \`track('<goal>')\`.
722
-
723
- - Not connected yet? \`npx splithub init --mode cloud\` (or \`npx splithub login\`) prints a link: show it to the user, they sign in and approve, the CLI gets the keys. Never ask the user to paste keys.
724
- - New experiment: \`npx splithub create --kind value|component|redirect|mvt --id <key> --variants control,<other> --goal <goal> --yes\`
725
- then wire it in code (value \u2192 \`useValue\`, component \u2192 \`<Experiment>\` with one \`<Variant>\` per key, redirect \u2192 nothing,
726
- mvt \u2192 \`--factor name=level:value,\u2026\` and \`const { a, b } = useValue(id)\`).
727
- - Results: \`npx splithub results <id> --json\`; report \`verdict.message\` verbatim, never call a winner from raw rates.
728
- - Lifecycle: \`npx splithub start|pause|finish <id>\`. Check setup: \`npx splithub doctor\`.
729
- - A \`finished\` test still has all its variants in the code: report the verdict, ask which variant to keep and whether to
730
- remove the test from the code, then follow .claude/skills/splithub-ship/SKILL.md. Never delete test code unasked.
731
- - \`create\` writes \`status: 'running'\`: the test goes live when the code is deployed. Always tell the user that, and that
732
- \`npx splithub pause <id>\` or Pause in the dashboard holds it. Never change \`seed\` of a running experiment.
733
- - Config ships to the browser: no secrets in it. Full rules: .claude/skills/splithub/SKILL.md
734
- `;
735
- var CURSOR_RULE = `---
736
- description: SplitHub A/B testing conventions
737
- globs: ["splithub.config.ts", "splithub/**", "**/*.tsx"]
738
- alwaysApply: false
739
- ---
740
- ${SKILL_SPLITHUB.replace(/^---[\s\S]*?---\n/, "")}`;
741
-
742
- // src/ui.ts
743
- var enabled = process.stdout.isTTY && !process.env.NO_COLOR;
744
- var wrap = (open, close) => (s) => enabled ? `\x1B[${open}m${s}\x1B[${close}m` : s;
745
- var c = {
746
- bold: wrap(1, 22),
747
- dim: wrap(2, 22),
748
- red: wrap(31, 39),
749
- green: wrap(32, 39),
750
- yellow: wrap(33, 39),
751
- blue: wrap(34, 39),
752
- magenta: wrap(35, 39),
753
- cyan: wrap(36, 39)
754
- };
755
- function table(headers, rows) {
756
- const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => strip(r[i] ?? "").length)));
757
- const line = (cells) => cells.map((cell, i) => cell + " ".repeat(widths[i] - strip(cell).length)).join(" ");
758
- return [c.dim(line(headers)), ...rows.map(line)].join("\n");
759
- }
760
- function strip(s) {
761
- return s.replace(/\u001b\[\d+m/g, "");
762
- }
763
- function pct(x, signed = false) {
764
- if (x === null || x === void 0 || !Number.isFinite(x)) return "\u2013";
765
- const v = (x * 100).toFixed(1);
766
- return signed && x >= 0 ? `+${v}%` : `${v}%`;
767
- }
768
- function statusColor(status2) {
769
- switch (status2) {
770
- case "running":
771
- return c.green(status2);
772
- case "paused":
773
- return c.yellow(status2);
774
- case "finished":
775
- return c.blue(status2);
776
- default:
777
- return c.dim(status2);
778
- }
779
- }
780
- function verdictIcon(status2) {
781
- switch (status2) {
782
- case "winner_found":
783
- return "\u2605";
784
- case "srm_detected":
785
- return "!";
786
- case "insufficient_sample":
787
- return "\u2026";
788
- case "no_significant_difference":
789
- return "=";
790
- default:
791
- return "\xB7";
792
- }
793
- }
794
- function bar(value, max, width = 20, paint = c.green) {
795
- const n = max > 0 ? Math.max(0, Math.min(width, Math.round(value / max * width))) : 0;
796
- return paint("\u2588".repeat(n)) + c.dim("\u2591".repeat(width - n));
797
- }
798
- function verdictColor(status2, text3) {
799
- switch (status2) {
800
- case "winner_found":
801
- return c.green(text3);
802
- case "srm_detected":
803
- return c.red(text3);
804
- case "insufficient_sample":
805
- return c.yellow(text3);
806
- case "no_significant_difference":
807
- return c.cyan(text3);
808
- default:
809
- return c.dim(text3);
810
- }
811
- }
812
-
813
- // src/commands/create.ts
814
- var KEY = /^[a-z0-9][a-z0-9_-]{0,63}$/;
815
- function str(v) {
816
- return typeof v === "string" && v.length > 0 ? v : void 0;
817
- }
818
- function list(v) {
819
- if (Array.isArray(v)) return v.map(String);
820
- if (typeof v === "string") return [v];
821
- return [];
822
- }
823
- function parsePairs(items) {
824
- const out = {};
825
- for (const item of items) {
826
- const i = item.indexOf("=");
827
- if (i > 0) out[item.slice(0, i).trim()] = item.slice(i + 1);
828
- }
829
- return out;
830
- }
831
- function pascal(s) {
832
- return s.replace(/(^|[-_])([a-z0-9])/g, (_, __, ch) => ch.toUpperCase());
833
- }
834
- async function ask(promise) {
835
- const v = await promise;
836
- if (p.isCancel(v)) {
837
- p.cancel("Cancelled.");
838
- process.exit(0);
839
- }
840
- return v;
841
- }
842
- async function create(flags) {
843
- const json = Boolean(flags.json);
844
- const yes = Boolean(flags.yes);
845
- const project = detectProject();
846
- if (!project.configFile) throw new Error("splithub.config.ts not found. Run `npx splithub init` first.");
847
- const config = await loadConfig(project.configFile);
848
- const source = readSource(project.configFile);
849
- const interactive = !yes && !json;
850
- if (interactive) p.intro(c.bold("splithub create"));
851
- let kind = str(flags.kind);
852
- if (!kind) {
853
- if (!interactive) throw new Error("--kind value|component|redirect|mvt is required with --yes");
854
- kind = await ask(
855
- p.select({
856
- message: "What changes between variants?",
857
- options: [
858
- { value: "value", label: "Text, image URL, number", hint: "no new components" },
859
- { value: "component", label: "Layout / structure", hint: "one component per variant" },
860
- { value: "redirect", label: "A whole page", hint: "needs @splithub/next middleware" },
861
- { value: "mvt", label: "Several things at once", hint: "multivariate: every combination, each factor read on its own" }
862
- ]
863
- })
864
- );
865
- }
866
- let id = str(flags.id);
867
- if (!id) {
868
- if (!interactive) throw new Error("--id is required with --yes");
869
- id = await ask(
870
- p.text({
871
- message: "Experiment id",
872
- placeholder: "hero-title",
873
- validate: (v) => !KEY.test(v) ? "lowercase a-z 0-9 - _ only" : hasExperiment(source, v) ? "already exists" : void 0
874
- })
875
- );
876
- }
877
- if (!KEY.test(id)) throw new Error(`invalid id "${id}" (lowercase a-z 0-9 - _, max 64)`);
878
- if (hasExperiment(source, id)) throw new Error(`experiment "${id}" already exists`);
879
- const factors = {};
880
- if (kind === "mvt") {
881
- for (const raw of list(flags.factor)) {
882
- const eq = raw.indexOf("=");
883
- if (eq <= 0) throw new Error(`--factor expects name=level:value,level:value, got "${raw}"`);
884
- const name = raw.slice(0, eq).trim();
885
- const levels = {};
886
- for (const part of raw.slice(eq + 1).split(",")) {
887
- const colon = part.indexOf(":");
888
- const level = (colon >= 0 ? part.slice(0, colon) : part).trim();
889
- if (!level) continue;
890
- levels[level] = colon >= 0 ? part.slice(colon + 1).trim() : level;
891
- }
892
- factors[name] = levels;
893
- }
894
- while (interactive && Object.keys(factors).length === 0) {
895
- const name = await ask(p.text({ message: "Factor name (what changes), e.g. headline", validate: (v) => !KEY.test(v) ? "lowercase a-z 0-9 - _ only" : void 0 }));
896
- const levelsRaw = await ask(p.text({ message: `Levels of "${name}" as key:value, comma separated (first = control)`, placeholder: "old:Old headline, new:New headline" }));
897
- const levels = {};
898
- for (const part of levelsRaw.split(",")) {
899
- const colon = part.indexOf(":");
900
- const level = (colon >= 0 ? part.slice(0, colon) : part).trim();
901
- if (level) levels[level] = colon >= 0 ? part.slice(colon + 1).trim() : level;
902
- }
903
- factors[name] = levels;
904
- while (await ask(p.confirm({ message: "Add another factor?", initialValue: false }))) {
905
- const more = await ask(p.text({ message: "Factor name", validate: (v) => !KEY.test(v) ? "lowercase a-z 0-9 - _ only" : void 0 }));
906
- const moreRaw = await ask(p.text({ message: `Levels of "${more}" as key:value, comma separated`, placeholder: "blue:#2563eb, green:#16a34a" }));
907
- const moreLevels = {};
908
- for (const part of moreRaw.split(",")) {
909
- const colon = part.indexOf(":");
910
- const level = (colon >= 0 ? part.slice(0, colon) : part).trim();
911
- if (level) moreLevels[level] = colon >= 0 ? part.slice(colon + 1).trim() : level;
912
- }
913
- factors[more] = moreLevels;
914
- }
915
- }
916
- if (Object.keys(factors).length === 0) throw new Error("--factor name=level:value,level:value is required for mvt experiments (repeat it per factor)");
917
- }
918
- const mvt = kind === "mvt" ? mvtVariants(id, factors) : null;
919
- let variantKeys = mvt ? mvt.variants.map((v) => v.key) : str(flags.variants)?.split(",").map((s) => s.trim()).filter(Boolean);
920
- if (!variantKeys || variantKeys.length < 2) {
921
- if (!interactive) variantKeys = ["control", "b"];
922
- else {
923
- const v = await ask(p.text({ message: "Variant keys, comma separated (first = control)", initialValue: "control, b" }));
924
- variantKeys = v.split(",").map((s) => s.trim()).filter(Boolean);
925
- }
926
- }
927
- for (const k2 of variantKeys) if (!KEY.test(k2)) throw new Error(`invalid variant key "${k2}"`);
928
- if (variantKeys.length < 2) throw new Error("need at least 2 variants");
929
- const weightsRaw = str(flags.weights)?.split(",").map(Number);
930
- const weights = weightsRaw && weightsRaw.length === variantKeys.length && weightsRaw.every((w) => Number.isFinite(w) && w >= 0) ? weightsRaw : variantKeys.map(() => 1);
931
- const values = parsePairs(list(flags.value));
932
- const tos = parsePairs(list(flags.to));
933
- if (kind === "value" && interactive) {
934
- for (const k2 of variantKeys) {
935
- if (values[k2] === void 0) values[k2] = await ask(p.text({ message: `Value for "${k2}"`, placeholder: k2 === variantKeys[0] ? "current text" : "new text" }));
936
- }
937
- }
938
- let match = str(flags.match);
939
- if (kind === "redirect") {
940
- if (!match) {
941
- if (!interactive) throw new Error("--match /path is required for redirect experiments");
942
- match = await ask(p.text({ message: "Path to run the redirect test on", initialValue: "/" }));
943
- }
944
- for (const k2 of variantKeys) {
945
- if (tos[k2] === void 0) {
946
- if (!interactive) tos[k2] = k2 === variantKeys[0] ? match : `${match.replace(/\/$/, "")}/${k2}`;
947
- else tos[k2] = await ask(p.text({ message: `URL for "${k2}"`, initialValue: k2 === variantKeys[0] ? match : "" }));
948
- }
949
- }
950
- }
951
- let goal = str(flags.goal);
952
- const goals = config.goals.map((g) => g.key);
953
- if (!goal) {
954
- if (!interactive) goal = goals[0];
955
- else if (goals.length > 0) {
956
- goal = await ask(
957
- p.select({
958
- message: "Goal (conversion) to optimise",
959
- options: [...goals.map((g) => ({ value: g, label: g })), { value: "", label: "none yet (add later)" }]
960
- })
961
- );
962
- if (!goal) goal = void 0;
963
- }
964
- }
965
- if (goal && !goals.includes(goal)) throw new Error(`goal "${goal}" is not declared in splithub.config.ts goals: ${goals.join(", ") || "none"}`);
966
- const status2 = str(flags.status) ?? "running";
967
- const description = str(flags.description);
968
- const experiment = {
969
- key: id,
970
- kind,
971
- status: status2,
972
- goal,
973
- match,
974
- description,
975
- variants: mvt ? mvt.variants.map((v) => ({ key: v.key, weight: v.weight })) : variantKeys.map((k2, i) => ({ key: k2, weight: weights[i], value: values[k2], to: tos[k2] })),
976
- ...mvt ? { factors } : {},
977
- // limits: --traffic 50 (percent), --max-visitors 10000, --start / --end ISO dates
978
- traffic: typeof flags.traffic === "string" && flags.traffic !== "" ? Math.min(1, Math.max(0, Number(flags.traffic) / 100)) : void 0,
979
- maxExposures: typeof flags["max-visitors"] === "string" && Number(flags["max-visitors"]) > 0 ? Math.floor(Number(flags["max-visitors"])) : void 0,
980
- schedule: typeof flags.start === "string" || typeof flags.end === "string" ? { startAt: typeof flags.start === "string" ? flags.start : null, endAt: typeof flags.end === "string" ? flags.end : null } : void 0
981
- };
982
- writeSource(project.configFile, insertExperiment(source, experiment));
983
- const files = [];
984
- const componentNames = {};
985
- if (kind === "component") {
986
- const dir = join2(project.root, project.hasSrc ? "src/splithub" : "splithub", id);
987
- mkdirSync(dir, { recursive: true });
988
- for (const k2 of variantKeys) {
989
- const name = `${pascal(id)}${pascal(k2)}`;
990
- componentNames[k2] = name;
991
- const file = join2(dir, `${pascal(k2)}.tsx`);
992
- if (!existsSync2(file)) {
993
- writeFileSync2(file, componentVariantTemplate(name, id, k2), "utf8");
994
- files.push(relative(project.root, file));
995
- }
996
- }
997
- }
998
- const snippet = kind === "mvt" ? `const { ${Object.keys(factors).join(", ")} } = useValue<{ ${Object.keys(factors).map((f) => `${f}: string`).join("; ")} }>('${id}');` : kind === "value" ? `const value = useValue<string>('${id}');` : kind === "component" ? `<Experiment id="${id}">
999
- ${variantKeys.map((k2) => ` <Variant name="${k2}"><${componentNames[k2]} /></Variant>`).join("\n")}
1000
- </Experiment>` : `// handled by @splithub/next middleware on ${match}; no code needed`;
1001
- const result = { experiment: id, kind, status: status2, variants: experiment.variants, goal: goal ?? null, configFile: relative(project.root, project.configFile), files, snippet };
1002
- if (json) {
1003
- const cloudMode = /mode\s*:\s*['"]cloud['"]/.test(readSource(project.configFile));
1004
- const handoff = status2 === "draft" ? `${id} is a draft: visitors do not see it and nothing is recorded until it is started. Tell the user and ask whether to start it now (npx splithub start ${id}).` : `${id} is running in the config: it goes live for visitors when this code is deployed${cloudMode ? " and pushed; local development never sends events to the cloud" : ""}. Tell the user, and that npx splithub pause ${id} or Pause in the dashboard holds it.`;
1005
- const nextStep = cloudMode ? `npx splithub push # the cloud does not know about ${id} until you push` : status2 === "draft" ? `npx splithub start ${id}` : "deploy the app";
1006
- console.log(JSON.stringify({ ...result, nextStep, handoff }, null, 2));
1007
- return;
1008
- }
1009
- p.note(snippet, kind === "redirect" ? "Nothing to wire" : "Wire it in your code");
1010
- if (files.length) p.note(files.join("\n"), "Scaffolded");
1011
- const cloud = /mode\s*:\s*['"]cloud['"]/.test(readSource(project.configFile));
1012
- if (cloud) p.log.warn(`Cloud mode: the cloud does not know about it until you run ${c.cyan("npx splithub push")}.`);
1013
- if (status2 === "draft") p.log.warn(`${c.bold(id)} is a draft: visitors do not see it and nothing is recorded until you start it.`);
1014
- if (status2 === "running") p.log.info(`${c.bold(id)} goes live when you deploy this code. Check it first with ${c.cyan(`?sh_force=${id}:<variant>`)}; ${c.cyan(`npx splithub pause ${id}`)} holds it.`);
1015
- if (status2 === "draft") p.log.info(`See it before you start it: ${c.cyan("runDraftsInDev: true")} in the config serves drafts in development, ${c.cyan(`?sh_force=${id}:<variant>`)} shows one variant anywhere.`);
1016
- p.outro(`Added ${c.bold(id)} (${status2}) to ${relative(project.root, project.configFile)}. ${status2 === "running" ? "" : `Start it with ${c.cyan(`npx splithub start ${id}`)}. `}${cloud ? `Then ${c.cyan("npx splithub push")}.` : ""}`);
1017
- }
1018
-
1019
- // src/commands/dev.ts
1020
- import { spawn } from "child_process";
1021
-
1022
- // src/api.ts
1023
- import { readFileSync as readFileSync4 } from "fs";
1024
-
1025
- // src/credentials.ts
1026
- import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
1027
- import { homedir } from "os";
1028
- import { join as join3, resolve as resolve2 } from "path";
1029
- function credentialsFile() {
1030
- const base = process.env.XDG_CONFIG_HOME || (process.platform === "win32" ? process.env.APPDATA || join3(homedir(), "AppData", "Roaming") : join3(homedir(), ".config"));
1031
- return join3(base, "splithub", "credentials.json");
1032
- }
1033
- function read() {
1034
- const file = credentialsFile();
1035
- if (!existsSync3(file)) return {};
1036
- try {
1037
- return JSON.parse(readFileSync3(file, "utf8"));
1038
- } catch {
1039
- return {};
1040
- }
1041
- }
1042
- function loadCredential(api, root = process.cwd()) {
1043
- return read()[api]?.[resolve2(root)] ?? null;
1044
- }
1045
- function saveCredential(api, root, cred) {
1046
- const file = credentialsFile();
1047
- const store = read();
1048
- store[api] = { ...store[api] ?? {}, [resolve2(root)]: cred };
1049
- mkdirSync2(join3(file, ".."), { recursive: true });
1050
- writeFileSync3(file, JSON.stringify(store, null, 2) + "\n", { mode: 384 });
1051
- return file;
1052
- }
1053
- function listCredentials(api) {
1054
- const store = read();
1055
- const out = [];
1056
- for (const [a, dirs] of Object.entries(store)) {
1057
- if (api && a !== api) continue;
1058
- for (const [root, cred] of Object.entries(dirs)) out.push({ api: a, root, cred });
1059
- }
1060
- return out.sort((x, y) => y.cred.savedAt.localeCompare(x.cred.savedAt));
1061
- }
1062
- function removeCredential(api, root = process.cwd()) {
1063
- const store = read();
1064
- const key = resolve2(root);
1065
- if (!store[api]?.[key]) return false;
1066
- delete store[api][key];
1067
- writeFileSync3(credentialsFile(), JSON.stringify(store, null, 2) + "\n", { mode: 384 });
1068
- return true;
1069
- }
1070
-
1071
- // src/api.ts
1072
- var CLOUD_API = "https://go.splithub.io/v1";
1073
- function storageFromConfig(project) {
1074
- const fallback = { mode: "self", endpoint: "/api/splithub" };
1075
- if (!project?.configFile) return fallback;
1076
- try {
1077
- const src = readFileSync4(project.configFile, "utf8");
1078
- const mode = /mode\s*:\s*['"](cloud|self)['"]/.exec(src)?.[1];
1079
- const endpoint = /endpoint\s*:\s*['"]([^'"]+)['"]/.exec(src)?.[1];
1080
- return { mode: mode ?? "self", endpoint: endpoint ?? "/api/splithub" };
1081
- } catch {
1082
- return fallback;
1083
- }
1084
- }
1085
- function cloudTarget(flags) {
1086
- const url = typeof flags.api === "string" && flags.api || process.env.SPLITHUB_API || CLOUD_API;
1087
- const base = url.replace(/\/+$/, "");
1088
- const token = typeof flags.token === "string" && flags.token || process.env.SPLITHUB_API_KEY || loadCredential(base)?.apiKey || void 0;
1089
- return { url: base, token };
1090
- }
1091
- function resolveTarget(flags, project) {
1092
- const explicit = typeof flags.url === "string" && flags.url || process.env.SPLITHUB_URL;
1093
- const storage = storageFromConfig(project);
1094
- if (!explicit && storage.mode === "cloud") return cloudTarget(flags);
1095
- const port = project?.framework === "next" ? 3e3 : 5173;
1096
- const url = explicit || `http://localhost:${port}${storage.endpoint}`;
1097
- const token = typeof flags.token === "string" && flags.token || process.env.SPLITHUB_ADMIN_TOKEN || void 0;
1098
- return { url: url.replace(/\/+$/, ""), token };
1099
- }
1100
- function apiErrorMessage(status2, body, fallback) {
1101
- const error = body?.error;
1102
- const text3 = typeof error === "string" ? error : typeof error?.message === "string" ? error.message : fallback;
1103
- return status2 === 401 ? `${text3} This folder is not signed in: run npx splithub login (or set SPLITHUB_API_KEY).` : text3;
1104
- }
1105
- async function get(target, path) {
1106
- const headers = {};
1107
- if (target.token) headers.authorization = `Bearer ${target.token}`;
1108
- let res;
1109
- try {
1110
- res = await fetch(`${target.url}${path}`, { headers });
1111
- } catch (error) {
1112
- throw new Error(`cannot reach ${target.url}: ${error instanceof Error ? error.message : String(error)}. Is your app running? Set --url or SPLITHUB_URL.`);
1113
- }
1114
- if (!res.ok) {
1115
- const body = await res.json().catch(() => ({}));
1116
- throw new Error(apiErrorMessage(res.status, body, `${target.url}${path} responded ${res.status}`));
1117
- }
1118
- return await res.json();
1119
- }
1120
- var fetchStatus = (t) => get(t, "/status");
1121
- var fetchResults = (t, key) => get(t, `/results/${encodeURIComponent(key)}`);
1122
-
1123
- // src/commands/dev.ts
1124
- function openBrowser(url) {
1125
- const [cmd, args] = process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
1126
- try {
1127
- spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
1128
- } catch {
1129
- }
1130
- }
1131
- async function dev(flags) {
1132
- const project = detectProject();
1133
- const port = project?.framework === "next" ? 3e3 : 5173;
1134
- const page = typeof flags.url === "string" && flags.url || `http://localhost:${port}/`;
1135
- const u = new URL(page);
1136
- u.searchParams.set("sh_debug", flags.hold ? "hold" : "1");
1137
- const link = u.toString();
1138
- console.log(`${c.bold("SplitHub dev mode")}
1139
- `);
1140
- console.log(` ${c.cyan(link)}
1141
- `);
1142
- console.log(c.dim(" In the browser: the console shows every assignment (variant + reason), exposure and goal; the panel"));
1143
- console.log(c.dim(" in the corner forces variants, starts a new visitor and can hold redirects. Add ?sh_debug=0 to stop.\n"));
1144
- if (!flags["no-open"]) openBrowser(link);
1145
- const target = resolveTarget(flags, project);
1146
- console.log(c.dim(` Watching ${target.url} every 5 s. Ctrl+C to stop.
1147
- `));
1148
- const seen = /* @__PURE__ */ new Map();
1149
- let first = true;
1150
- const poll = async () => {
1151
- let data;
1152
- try {
1153
- data = await fetchStatus(target);
1154
- } catch (e) {
1155
- if (first) console.log(c.yellow(` results endpoint not reachable yet (${e instanceof Error ? e.message : String(e)}); is the dev server running?`));
1156
- first = false;
1157
- return;
1158
- }
1159
- const now = (/* @__PURE__ */ new Date()).toLocaleTimeString();
1160
- for (const e of data.experiments) {
1161
- const prev = seen.get(e.experiment);
1162
- if (!prev) console.log(` ${c.dim(now)} ${c.bold(e.experiment)} ${c.dim(e.status)} \xB7 ${e.visitors} visitors${e.headline ? ` \xB7 ${e.headline}` : ""}`);
1163
- else if (prev.visitors !== e.visitors || prev.headline !== (e.headline ?? null)) console.log(` ${c.dim(now)} ${c.bold(e.experiment)} ${c.green(`+${e.visitors - prev.visitors}`)} \u2192 ${e.visitors} visitors${e.headline ? ` \xB7 ${e.headline}` : ""}`);
1164
- seen.set(e.experiment, { visitors: e.visitors, headline: e.headline ?? null });
1165
- }
1166
- first = false;
1167
- };
1168
- await poll();
1169
- await new Promise((resolve3) => {
1170
- const t = setInterval(() => void poll(), 5e3);
1171
- process.on("SIGINT", () => {
1172
- clearInterval(t);
1173
- resolve3();
1174
- });
1175
- });
1176
- }
1177
-
1178
- // src/commands/doctor.ts
1179
- import { existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
1180
- import { join as join4, relative as relative2 } from "path";
1181
- async function doctor(flags) {
1182
- const checks = [];
1183
- const add = (level, message) => checks.push({ level, message });
1184
- const project = detectProject();
1185
- add("ok", `project "${project.name}" \xB7 ${project.framework} \xB7 ${project.packageManager}`);
1186
- if (!project.configFile) {
1187
- add("error", "splithub.config.ts not found. Run `npx splithub init`.");
1188
- return report(checks, flags);
1189
- }
1190
- add("ok", `config: ${relative2(project.root, project.configFile)}`);
1191
- let config;
1192
- try {
1193
- config = await loadConfig(project.configFile);
1194
- add("ok", `config loads \xB7 ${config.experiments.length} experiment(s) \xB7 storage ${config.storage.mode}`);
1195
- } catch (error) {
1196
- add("error", `config does not load: ${error instanceof Error ? error.message : String(error)}`);
1197
- return report(checks, flags);
1198
- }
1199
- const files = listSourceFiles(project.root);
1200
- const providerHits = grepFiles(files, "SplitHubProvider").concat(grepFiles(files, "SplitHubNextProvider"));
1201
- if (providerHits.length === 0) add("error", "no <SplitHubProvider> found in source. Wrap your app once.");
1202
- else add("ok", `provider in ${relative2(project.root, providerHits[0])}`);
1203
- if (project.framework === "next") {
1204
- const mw = ["middleware.ts", "src/middleware.ts", "middleware.js", "src/middleware.js"].map((f) => join4(project.root, f)).find((f) => existsSync4(f));
1205
- const hasRedirects = config.experiments.some((e) => e.kind === "redirect");
1206
- if (!mw) add(hasRedirects ? "error" : "warn", "no middleware.ts: visitor cookie is not set on the server (SSR may flicker)" + (hasRedirects ? "; redirect experiments will not run" : ""));
1207
- else if (!readFileSync5(mw, "utf8").includes("splithubMiddleware")) add("warn", `${relative2(project.root, mw)} does not call splithubMiddleware()`);
1208
- else add("ok", `middleware: ${relative2(project.root, mw)}`);
1209
- if (config.storage.mode === "self" && project.appDir) {
1210
- const catchAll = join4(project.root, project.appDir, "api/splithub/[[...path]]/route.ts");
1211
- const plain = join4(project.root, project.appDir, "api/splithub/route.ts");
1212
- if (existsSync4(catchAll)) add("ok", `ingest route: ${relative2(project.root, catchAll)}`);
1213
- else if (existsSync4(plain)) add("error", `${relative2(project.root, plain)} only serves POST /api/splithub; move it to api/splithub/[[...path]]/route.ts so /status and /results work`);
1214
- else add("error", `self mode but ${relative2(project.root, catchAll)} is missing (ingest endpoint)`);
1215
- }
1216
- }
1217
- for (const exp of config.experiments) {
1218
- const label2 = `${exp.key} (${exp.kind}, ${exp.status})`;
1219
- if (!exp.goal) add(exp.status === "running" ? "error" : "warn", `${label2}: no goal; the verdict cannot be computed`);
1220
- if (exp.kind !== "redirect") {
1221
- const used = grepFiles(files.filter((f) => !f.endsWith("splithub.config.ts")), `'${exp.key}'`).length + grepFiles(files, `"${exp.key}"`).length;
1222
- if (used === 0) add(exp.status === "running" ? "error" : "warn", `${label2}: not referenced in code (useValue/useVariant/<Experiment id>)`);
1223
- }
1224
- if (exp.status === "running" && exp.variants.every((v) => v.weight === 0)) add("error", `${label2}: all weights are 0`);
1225
- }
1226
- for (const goal of config.goals) {
1227
- if (goal.type === "event" && grepFiles(files, `'${goal.key}'`).length + grepFiles(files, `"${goal.key}"`).length === 0) {
1228
- add("warn", `goal "${goal.key}": track('${goal.key}') is never called`);
1229
- }
1230
- }
1231
- const target = resolveTarget(flags, project);
1232
- try {
1233
- const ctrl = new AbortController();
1234
- const t = setTimeout(() => ctrl.abort(), 2500);
1235
- const res = await fetch(`${target.url}/health`, { signal: ctrl.signal });
1236
- clearTimeout(t);
1237
- add(res.ok ? "ok" : "warn", `endpoint ${target.url}/health \u2192 ${res.status}`);
1238
- } catch {
1239
- add("warn", `endpoint ${target.url} not reachable (is the dev server running?)`);
1240
- }
1241
- return report(checks, flags);
1242
- }
1243
- function report(checks, flags) {
1244
- const errors = checks.filter((x) => x.level === "error").length;
1245
- if (flags.json) {
1246
- console.log(JSON.stringify({ ok: errors === 0, checks }, null, 2));
1247
- } else {
1248
- for (const x of checks) {
1249
- const icon = x.level === "ok" ? c.green("\u2714") : x.level === "warn" ? c.yellow("!") : c.red("\u2716");
1250
- console.log(`${icon} ${x.message}`);
1251
- }
1252
- console.log();
1253
- console.log(errors === 0 ? c.green("All good.") : c.red(`${errors} problem(s) to fix.`));
1254
- }
1255
- if (errors > 0) process.exitCode = 1;
1256
- }
1257
-
1258
- // src/commands/init.ts
1259
- import * as p2 from "@clack/prompts";
1260
- import { execSync } from "child_process";
1261
- import { existsSync as existsSync6, mkdirSync as mkdirSync4, writeFileSync as writeFileSync5 } from "fs";
1262
- import { dirname as dirname2, join as join6, relative as relative4 } from "path";
1263
-
1264
- // src/commands/login.ts
1265
- import { hostname } from "os";
1266
- import { basename } from "path";
1267
- var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
1268
- async function deviceLogin(options) {
1269
- const { api } = options;
1270
- const root = options.root ?? process.cwd();
1271
- const label2 = `cli \xB7 ${basename(root)} @ ${hostname()}`.slice(0, 80);
1272
- const startRes = await fetch(`${api}/auth/device`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ label: label2 }) });
1273
- if (!startRes.ok) throw new Error(`${api}/auth/device responded ${startRes.status}`);
1274
- const start = await startRes.json();
1275
- if (options.project) start.verifyUrl += `${start.verifyUrl.includes("?") ? "&" : "?"}project=${encodeURIComponent(options.project)}`;
1276
- if (options.onCode) options.onCode(start);
1277
- else if (options.json) console.log(JSON.stringify({ step: "approve", userCode: start.userCode, verifyUrl: start.verifyUrl, expiresIn: start.expiresIn }));
1278
- else {
1279
- console.log(`
1280
- ${c.bold("Open this link to connect:")} ${c.cyan(start.verifyUrl)}`);
1281
- console.log(`${c.dim("Code")} ${c.green(start.userCode)} ${c.dim(`(expires in ${Math.round(start.expiresIn / 60)} min)`)}`);
1282
- console.log(c.dim("Sign in, pick or create the project, approve. Waiting\u2026"));
1283
- }
1284
- const deadline = Date.now() + start.expiresIn * 1e3;
1285
- while (Date.now() < deadline) {
1286
- await sleep(Math.max(2, start.interval) * 1e3);
1287
- const res = await fetch(`${api}/auth/device/${start.deviceCode}`);
1288
- if (!res.ok) throw new Error(`${api}/auth/device responded ${res.status}`);
1289
- const poll = await res.json();
1290
- if (poll.status === "pending") continue;
1291
- if (poll.status === "denied") throw new Error("login was denied in the dashboard");
1292
- if (poll.status === "expired") throw new Error("the code expired. Run `splithub login` again.");
1293
- if (poll.status === "consumed" || !poll.apiKey) throw new Error("the key for this code was already collected. Run `splithub login` again.");
1294
- const cred = { apiKey: poll.apiKey, projectId: poll.projectId ?? null, projectName: poll.projectName ?? null, publicKey: poll.publicKey ?? null, savedAt: (/* @__PURE__ */ new Date()).toISOString() };
1295
- saveCredential(api, root, cred);
1296
- return cred;
1297
- }
1298
- throw new Error("the code expired. Run `splithub login` again.");
1299
- }
1300
- async function login(flags) {
1301
- const api = cloudTarget({ api: flags.api }).url;
1302
- const root = process.cwd();
1303
- const existing = loadCredential(api, root);
1304
- if (existing && !flags.yes) {
1305
- const msg = `already logged in for ${c.cyan(existing.projectName ?? existing.projectId ?? "a project")} (${credentialsFile()}). Use --yes to replace.`;
1306
- if (flags.json) console.log(JSON.stringify({ ok: true, alreadyLoggedIn: true, projectId: existing.projectId, projectName: existing.projectName, publicKey: existing.publicKey ?? null }));
1307
- else console.log(msg);
1308
- return;
1309
- }
1310
- const cred = await deviceLogin({ api, root, json: Boolean(flags.json), ...typeof flags.project === "string" ? { project: flags.project } : {} });
1311
- if (flags.json) console.log(JSON.stringify({ ok: true, projectId: cred.projectId, projectName: cred.projectName, publicKey: cred.publicKey, credentials: credentialsFile() }));
1312
- else {
1313
- console.log(`${c.green("\u2714")} logged in to ${c.cyan(cred.projectName ?? cred.projectId ?? "project")}`);
1314
- console.log(c.dim(`key saved for ${root} in ${credentialsFile()}`));
1315
- console.log(c.dim("next: npx splithub push"));
1316
- }
1317
- }
1318
- async function logout(flags) {
1319
- const api = cloudTarget({ api: flags.api }).url;
1320
- const removed = removeCredential(api, process.cwd());
1321
- if (flags.json) console.log(JSON.stringify({ ok: true, removed }));
1322
- else console.log(removed ? `${c.green("\u2714")} removed the saved key for this directory` : c.dim("nothing saved for this directory"));
1323
- }
1324
- async function whoami(flags) {
1325
- const target = cloudTarget(flags);
1326
- if (!target.token) throw new Error("not logged in. Run `splithub login` or set SPLITHUB_API_KEY.");
1327
- const res = await fetch(`${target.url}/status`, { headers: { authorization: `Bearer ${target.token}` } });
1328
- const data = await res.json().catch(() => ({}));
1329
- if (!res.ok) throw new Error(apiErrorMessage(res.status, data, `${target.url}/status responded ${res.status}`));
1330
- const saved = loadCredential(target.url);
1331
- if (flags.json) console.log(JSON.stringify({ ok: true, api: target.url, project: data.project, projectId: saved?.projectId ?? null, publicKey: saved?.publicKey ?? null }));
1332
- else console.log(`${c.bold("api")} ${target.url}
1333
- ${c.bold("project")} ${c.cyan(data.project ?? "?")}
1334
- ${c.bold("public key")} ${saved?.publicKey ?? c.dim("unknown (log in again to fetch it)")}
1335
- ${c.bold("api key")} ${target.token.slice(0, 11)}\u2026`);
1336
- }
1337
- async function projects(flags) {
1338
- const api = cloudTarget({ api: flags.api }).url;
1339
- const here = process.cwd();
1340
- const rows = listCredentials(api).map((r) => ({ root: r.root, current: r.root === here, projectId: r.cred.projectId, projectName: r.cred.projectName, publicKey: r.cred.publicKey ?? null, savedAt: r.cred.savedAt }));
1341
- if (flags.json) {
1342
- console.log(JSON.stringify({ api, credentials: credentialsFile(), projects: rows }, null, 2));
1343
- return;
1344
- }
1345
- if (rows.length === 0) {
1346
- console.log(c.dim("no directory on this machine is connected yet. Run `splithub login` in your app."));
1347
- return;
1348
- }
1349
- for (const r of rows) console.log(`${r.current ? c.green("\u25B8") : " "} ${c.cyan(r.projectName ?? r.projectId ?? "?")} ${c.dim(`\xB7 ${r.root}`)}`);
1350
- console.log(c.dim("\nswitch: run `splithub login --yes --project <name>` in that directory \xB7 disconnect: `splithub logout`"));
1351
- }
1352
-
1353
- // src/templates-store.ts
1354
- var DB_KINDS = ["sqlite", "postgres", "mysql", "custom"];
1355
- var PG_STORE = `import type { ExperimentSummary, Store, StoredEvent } from '@splithub/node';
1356
- import type { VariantCounts } from '@splithub/stats';
1357
- import { Pool } from 'pg';
1358
-
1359
- // SplitHub events in your Postgres. Run once (or add to your migrations):
1360
- export const SCHEMA_SQL = \`
1361
- CREATE TABLE IF NOT EXISTS splithub_events (
1362
- id text PRIMARY KEY,
1363
- type text NOT NULL, -- exposure | goal
1364
- experiment text,
1365
- variant text,
1366
- goal text,
1367
- visitor_id text NOT NULL,
1368
- session_id text NOT NULL,
1369
- ts bigint NOT NULL, -- client clock, unix ms
1370
- url text,
1371
- props jsonb,
1372
- received_at bigint NOT NULL, -- server clock, unix ms
1373
- host text,
1374
- country text,
1375
- device text,
1376
- browser text
1377
- );
1378
- CREATE INDEX IF NOT EXISTS splithub_events_exp ON splithub_events (type, experiment, visitor_id, ts);
1379
- CREATE INDEX IF NOT EXISTS splithub_events_goal ON splithub_events (type, goal, visitor_id, ts);
1380
- \`;
1381
-
1382
- export function pgStore(pool: Pool = new Pool({ connectionString: process.env.DATABASE_URL })): Store {
1383
- return {
1384
- async insertEvents(events: StoredEvent[]) {
1385
- if (events.length === 0) return 0;
1386
- const cols = 15;
1387
- const values: unknown[] = [];
1388
- const rows = events.map((e, i) => {
1389
- values.push(e.id, e.type, e.experiment, e.variant, e.goal, e.visitorId, e.sessionId, e.ts, e.url, e.props ? JSON.stringify(e.props) : null, e.receivedAt, e.host ?? null, e.country ?? null, e.device ?? null, e.browser ?? null);
1390
- return '(' + Array.from({ length: cols }, (_, j) => '$' + (i * cols + j + 1)).join(', ') + ')';
1391
- });
1392
- const r = await pool.query(
1393
- 'INSERT INTO splithub_events (id, type, experiment, variant, goal, visitor_id, session_id, ts, url, props, received_at, host, country, device, browser) VALUES ' + rows.join(', ') + ' ON CONFLICT (id) DO NOTHING',
1394
- values
1395
- );
1396
- return r.rowCount ?? 0;
1397
- },
1398
- async variantCounts(experiment: string, goal: string): Promise<VariantCounts[]> {
1399
- const r = await pool.query(
1400
- \`WITH fv AS (
1401
- SELECT visitor_id, MIN(ts) AS first_ts FROM splithub_events
1402
- WHERE type = 'exposure' AND experiment = $1 GROUP BY visitor_id),
1403
- first_exposure AS (
1404
- SELECT MIN(e.variant) AS variant, fv.visitor_id, fv.first_ts
1405
- FROM fv JOIN splithub_events e
1406
- ON e.type = 'exposure' AND e.experiment = $1 AND e.visitor_id = fv.visitor_id AND e.ts = fv.first_ts
1407
- GROUP BY fv.visitor_id, fv.first_ts),
1408
- converted AS (
1409
- SELECT fe.variant, fe.visitor_id, SUM(COALESCE((g.props->>'revenue')::numeric, 0)) AS revenue
1410
- FROM first_exposure fe JOIN splithub_events g
1411
- ON g.type = 'goal' AND g.goal = $2 AND g.visitor_id = fe.visitor_id AND g.ts >= fe.first_ts
1412
- GROUP BY fe.variant, fe.visitor_id)
1413
- SELECT fe.variant, COUNT(*)::int AS exposures,
1414
- (SELECT COUNT(*)::int FROM converted c WHERE c.variant = fe.variant) AS conversions,
1415
- (SELECT COALESCE(SUM(revenue), 0)::float FROM converted c WHERE c.variant = fe.variant) AS revenue
1416
- FROM first_exposure fe GROUP BY fe.variant\`,
1417
- [experiment, goal]
1418
- );
1419
- return r.rows.map((x) => ({ variant: String(x.variant), exposures: Number(x.exposures), conversions: Number(x.conversions), revenue: Number(x.revenue) }));
1420
- },
1421
- async summaries(): Promise<ExperimentSummary[]> {
1422
- const r = await pool.query(
1423
- \`SELECT experiment, COUNT(*)::int AS exposures, COUNT(DISTINCT visitor_id)::int AS visitors, MIN(ts)::bigint AS first_ts, MAX(ts)::bigint AS last_ts
1424
- FROM splithub_events WHERE type = 'exposure' GROUP BY experiment\`
1425
- );
1426
- return r.rows.map((x) => ({ experiment: String(x.experiment), exposures: Number(x.exposures), visitors: Number(x.visitors), firstExposureAt: x.first_ts == null ? null : Number(x.first_ts), lastExposureAt: x.last_ts == null ? null : Number(x.last_ts) }));
1427
- },
1428
- close: () => pool.end(),
1429
- };
1430
- }
1431
- `;
1432
- var MYSQL_STORE = `import type { ExperimentSummary, Store, StoredEvent } from '@splithub/node';
1433
- import type { VariantCounts } from '@splithub/stats';
1434
- import mysql, { type Pool } from 'mysql2/promise';
1435
-
1436
- // SplitHub events in your MySQL / MariaDB / PlanetScale. Run once (or add to your migrations):
1437
- export const SCHEMA_SQL = \`
1438
- CREATE TABLE IF NOT EXISTS splithub_events (
1439
- id VARCHAR(64) PRIMARY KEY,
1440
- type VARCHAR(16) NOT NULL,
1441
- experiment VARCHAR(64) NULL,
1442
- variant VARCHAR(64) NULL,
1443
- goal VARCHAR(64) NULL,
1444
- visitor_id VARCHAR(64) NOT NULL,
1445
- session_id VARCHAR(64) NOT NULL,
1446
- ts BIGINT NOT NULL,
1447
- url VARCHAR(512) NULL,
1448
- props JSON NULL,
1449
- received_at BIGINT NOT NULL,
1450
- host VARCHAR(255) NULL,
1451
- country VARCHAR(8) NULL,
1452
- device VARCHAR(16) NULL,
1453
- browser VARCHAR(32) NULL,
1454
- INDEX splithub_events_exp (type, experiment, visitor_id, ts),
1455
- INDEX splithub_events_goal (type, goal, visitor_id, ts)
1456
- );
1457
- \`;
1458
-
1459
- export function mysqlStore(pool: Pool = mysql.createPool(process.env.DATABASE_URL ?? '')): Store {
1460
- return {
1461
- async insertEvents(events: StoredEvent[]) {
1462
- if (events.length === 0) return 0;
1463
- const values = events.map((e) => [e.id, e.type, e.experiment, e.variant, e.goal, e.visitorId, e.sessionId, e.ts, e.url, e.props ? JSON.stringify(e.props) : null, e.receivedAt, e.host ?? null, e.country ?? null, e.device ?? null, e.browser ?? null]);
1464
- const [r] = await pool.query(
1465
- 'INSERT IGNORE INTO splithub_events (id, type, experiment, variant, goal, visitor_id, session_id, ts, url, props, received_at, host, country, device, browser) VALUES ?',
1466
- [values]
1467
- );
1468
- return (r as { affectedRows: number }).affectedRows;
1469
- },
1470
- async variantCounts(experiment: string, goal: string): Promise<VariantCounts[]> {
1471
- const [rows] = await pool.query(
1472
- // Derived tables only (no CTEs, no window functions) so this runs on MySQL 5.7.
1473
- \`SELECT v.variant, COUNT(*) AS exposures, SUM(v.converted) AS conversions, COALESCE(SUM(v.revenue), 0) AS revenue
1474
- FROM (
1475
- SELECT fe.variant, fe.visitor_id,
1476
- CASE WHEN COUNT(g.id) > 0 THEN 1 ELSE 0 END AS converted,
1477
- SUM(COALESCE(JSON_EXTRACT(g.props, '$.revenue'), 0)) AS revenue
1478
- FROM (
1479
- SELECT MIN(e.variant) AS variant, fv.visitor_id, fv.first_ts
1480
- FROM (SELECT visitor_id, MIN(ts) AS first_ts FROM splithub_events WHERE type = 'exposure' AND experiment = ? GROUP BY visitor_id) fv
1481
- JOIN splithub_events e ON e.type = 'exposure' AND e.experiment = ? AND e.visitor_id = fv.visitor_id AND e.ts = fv.first_ts
1482
- GROUP BY fv.visitor_id, fv.first_ts) fe
1483
- LEFT JOIN splithub_events g ON g.type = 'goal' AND g.goal = ? AND g.visitor_id = fe.visitor_id AND g.ts >= fe.first_ts
1484
- GROUP BY fe.variant, fe.visitor_id) v
1485
- GROUP BY v.variant\`,
1486
- [experiment, experiment, goal]
1487
- );
1488
- return (rows as Array<Record<string, unknown>>).map((x) => ({ variant: String(x.variant), exposures: Number(x.exposures), conversions: Number(x.conversions), revenue: Number(x.revenue) }));
1489
- },
1490
- async summaries(): Promise<ExperimentSummary[]> {
1491
- const [rows] = await pool.query(
1492
- \`SELECT experiment, COUNT(*) AS exposures, COUNT(DISTINCT visitor_id) AS visitors, MIN(ts) AS first_ts, MAX(ts) AS last_ts
1493
- FROM splithub_events WHERE type = 'exposure' GROUP BY experiment\`
1494
- );
1495
- return (rows as Array<Record<string, unknown>>).map((x) => ({ experiment: String(x.experiment), exposures: Number(x.exposures), visitors: Number(x.visitors), firstExposureAt: x.first_ts == null ? null : Number(x.first_ts), lastExposureAt: x.last_ts == null ? null : Number(x.last_ts) }));
1496
- },
1497
- close: () => pool.end(),
1498
- };
1499
- }
1500
- `;
1501
- var CUSTOM_STORE = `import type { ExperimentSummary, Store, StoredEvent } from '@splithub/node';
1502
- import type { VariantCounts } from '@splithub/stats';
1503
-
1504
- /**
1505
- * Your own store (Prisma, Drizzle, Supabase, Mongo, anything). Three methods.
1506
- * Attribution rule (keep it, so results match the dashboard):
1507
- * a visitor counts once per experiment, in the variant of their earliest
1508
- * exposure (same ts: smallest variant key), and converts when they sent the
1509
- * goal at or after that exposure; count unique visitors, not events.
1510
- * Columns worth keeping: id (unique, dedupe on it), type, experiment, variant,
1511
- * goal, visitor_id, session_id, ts, url, props (json), received_at, host,
1512
- * country, device, browser.
1513
- */
1514
- export function customStore(): Store {
1515
- return {
1516
- async insertEvents(events: StoredEvent[]): Promise<number> {
1517
- // Insert, skipping ids that already exist. Return how many were inserted.
1518
- throw new Error('implement insertEvents ' + events.length);
1519
- },
1520
- async variantCounts(experiment: string, goal: string): Promise<VariantCounts[]> {
1521
- // For each variant: exposures = visitors whose earliest exposure in this experiment was to it;
1522
- // conversions = those visitors with a goal event (goal === goal) at ts >= that earliest exposure;
1523
- // revenue = sum of props.revenue over those goal events.
1524
- throw new Error('implement variantCounts ' + experiment + ' ' + goal);
1525
- },
1526
- async summaries(): Promise<ExperimentSummary[]> {
1527
- // Per experiment: exposures, unique visitors, first and last exposure ts (unix ms).
1528
- throw new Error('implement summaries');
1529
- },
1530
- };
1531
- }
1532
- `;
1533
- function storeTemplate(db) {
1534
- return db === "postgres" ? PG_STORE : db === "mysql" ? MYSQL_STORE : db === "custom" ? CUSTOM_STORE : null;
1535
- }
1536
- function storeUsage(db, storeImport) {
1537
- switch (db) {
1538
- case "postgres":
1539
- return { imports: `import { pgStore } from '${storeImport}';`, factory: "pgStore()" };
1540
- case "mysql":
1541
- return { imports: `import { mysqlStore } from '${storeImport}';`, factory: "mysqlStore()" };
1542
- case "custom":
1543
- return { imports: `import { customStore } from '${storeImport}';`, factory: "customStore()" };
1544
- default:
1545
- return { imports: `import { sqliteStore } from '@splithub/adapter-sqlite';`, factory: `sqliteStore({ file: process.env.SPLITHUB_DB ?? './splithub.db' })` };
1546
- }
1547
- }
1548
- function runtimePackages(db) {
1549
- return db === "postgres" ? ["pg"] : db === "mysql" ? ["mysql2"] : db === "sqlite" ? ["@splithub/adapter-sqlite"] : [];
1550
- }
1551
-
1552
- // src/commands/skills.ts
1553
- import { existsSync as existsSync5, mkdirSync as mkdirSync3, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
1554
- import { dirname, join as join5, relative as relative3 } from "path";
1555
- function writeFile(file, content, force, out) {
1556
- if (existsSync5(file) && !force) {
1557
- const current = readFileSync6(file, "utf8");
1558
- if (current === content) {
1559
- out.skipped.push(file);
1560
- return;
1561
- }
1562
- if (!/SplitHub|splithub/.test(current)) {
1563
- out.skipped.push(file);
1564
- return;
1565
- }
1566
- }
1567
- mkdirSync3(dirname(file), { recursive: true });
1568
- writeFileSync4(file, content, "utf8");
1569
- out.written.push(file);
1570
- }
1571
- function registerMcp(file, out) {
1572
- let json = {};
1573
- if (existsSync5(file)) {
1574
- try {
1575
- json = JSON.parse(readFileSync6(file, "utf8"));
1576
- } catch {
1577
- out.skipped.push(`${file} (not valid JSON, left untouched)`);
1578
- return;
1579
- }
1580
- }
1581
- const servers = json.mcpServers ?? {};
1582
- if (JSON.stringify(servers.splithub) === JSON.stringify(MCP_SERVER_ENTRY)) {
1583
- out.skipped.push(file);
1584
- return;
1585
- }
1586
- json.mcpServers = { ...servers, splithub: MCP_SERVER_ENTRY };
1587
- mkdirSync3(dirname(file), { recursive: true });
1588
- writeFileSync4(file, JSON.stringify(json, null, 2) + "\n", "utf8");
1589
- out.mcp.push(file);
1590
- }
1591
- function installSkills(root, options = {}) {
1592
- const out = { written: [], skipped: [], mcp: [] };
1593
- for (const s of SKILLS) writeFile(join5(root, ".claude", "skills", s.dir, "SKILL.md"), s.body, Boolean(options.force), out);
1594
- writeFile(join5(root, ".cursor", "rules", "splithub.mdc"), CURSOR_RULE, Boolean(options.force), out);
1595
- const agentsFile = ["AGENTS.md", "CLAUDE.md"].map((f) => join5(root, f)).find((f) => existsSync5(f)) ?? join5(root, "AGENTS.md");
1596
- if (!existsSync5(agentsFile)) {
1597
- writeFileSync4(agentsFile, `# ${detectProject(root).name}
1598
- ${AGENTS_SECTION}`, "utf8");
1599
- out.written.push(agentsFile);
1600
- } else if (!/SplitHub/.test(readFileSync6(agentsFile, "utf8"))) {
1601
- writeFileSync4(agentsFile, readFileSync6(agentsFile, "utf8") + `
1602
- ${AGENTS_SECTION}`, "utf8");
1603
- out.written.push(`${agentsFile} (section appended)`);
1604
- } else {
1605
- out.skipped.push(agentsFile);
1606
- }
1607
- if (options.mcp) {
1608
- registerMcp(join5(root, ".mcp.json"), out);
1609
- registerMcp(join5(root, ".cursor", "mcp.json"), out);
1610
- }
1611
- return out;
1612
- }
1613
- async function skills(flags) {
1614
- const project = detectProject();
1615
- const result = installSkills(project.root, { mcp: Boolean(flags.mcp), force: Boolean(flags.force) });
1616
- if (flags.json) {
1617
- console.log(JSON.stringify(result, null, 2));
1618
- return;
1619
- }
1620
- const rel = (f) => relative3(project.root, f) || f;
1621
- if (result.written.length) console.log(`${c.green("\u2714")} wrote
1622
- ${result.written.map(rel).join("\n ")}`);
1623
- if (result.mcp.length) console.log(`${c.green("\u2714")} MCP server registered in
1624
- ${result.mcp.map(rel).join("\n ")}`);
1625
- if (result.skipped.length) console.log(c.dim(`unchanged: ${result.skipped.map(rel).join(", ")}`));
1626
- if (!flags.mcp) console.log(c.dim(`add --mcp to register the SplitHub MCP server (Claude Code .mcp.json, Cursor .cursor/mcp.json; Codex and Copilot read AGENTS.md)`));
1627
- console.log(c.dim("skills: splithub (library + CLI), ab-testing (how to test well), splithub-api (HTTP API), splithub-mcp (MCP tools), splithub-self-hosted (your own database), splithub-ship (keep the winner, remove the test)"));
1628
- }
1629
-
1630
- // src/commands/init.ts
1631
- function str2(v) {
1632
- return typeof v === "string" ? v : void 0;
1633
- }
1634
- function writeIfMissing(file, content, created, skipped) {
1635
- if (existsSync6(file)) {
1636
- skipped.push(file);
1637
- return;
1638
- }
1639
- mkdirSync4(dirname2(file), { recursive: true });
1640
- writeFileSync5(file, content, "utf8");
1641
- created.push(file);
1642
- }
1643
- function importPath(fromFile, toFile) {
1644
- let rel = relative4(dirname2(fromFile), toFile).replace(/\\/g, "/").replace(/\.(ts|mts|js|mjs)$/, "");
1645
- if (!rel.startsWith(".")) rel = `./${rel}`;
1646
- return rel;
1647
- }
1648
- var VITE_PLUGIN_HINT = `// vite.config.ts
1649
- import { splithub } from '@splithub/core/vite';
1650
-
1651
- export default defineConfig({ plugins: [react(), splithub()] });`;
1652
- async function init(flags) {
1653
- const yes = Boolean(flags.yes);
1654
- const json = Boolean(flags.json);
1655
- const project = detectProject();
1656
- const created = [];
1657
- const skipped = [];
1658
- if (!json) p2.intro(c.bold("splithub init"));
1659
- let mode = str2(flags.mode);
1660
- if (!mode) {
1661
- if (yes) mode = "self";
1662
- else {
1663
- const picked = await p2.select({
1664
- message: "Where should events be stored?",
1665
- options: [
1666
- { value: "self", label: "My own database (self-hosted)", hint: "free forever, nothing leaves your infra" },
1667
- { value: "cloud", label: "SplitHub Cloud", hint: "hosted dashboard, no server code" }
1668
- ]
1669
- });
1670
- if (p2.isCancel(picked)) return cancel3();
1671
- mode = picked;
1672
- }
1673
- }
1674
- let db = DB_KINDS.includes(str2(flags.db) ?? "") ? str2(flags.db) : "sqlite";
1675
- if (mode === "self" && !flags.db && !yes) {
1676
- const picked = await p2.select({
1677
- message: "Where should events be stored?",
1678
- options: [
1679
- { value: "sqlite", label: "SQLite file (zero setup)", hint: "./splithub.db via node:sqlite" },
1680
- { value: "postgres", label: "Postgres", hint: "pg + DATABASE_URL, table splithub_events" },
1681
- { value: "mysql", label: "MySQL / MariaDB / PlanetScale", hint: "mysql2 + DATABASE_URL" },
1682
- { value: "custom", label: "My own store (Prisma, Drizzle, Supabase, Mongo\u2026)", hint: "a stub with the three methods to fill in" }
1683
- ]
1684
- });
1685
- if (p2.isCancel(picked)) return cancel3();
1686
- db = picked;
1687
- }
1688
- let key = str2(flags.key);
1689
- let connected = null;
1690
- if (mode === "cloud") {
1691
- const api = cloudTarget(flags).url;
1692
- const saved = loadCredential(api, project.root);
1693
- if (saved) {
1694
- key ??= saved.publicKey ?? void 0;
1695
- connected = { projectName: saved.projectName, projectId: saved.projectId };
1696
- } else if (!process.env.SPLITHUB_API_KEY && !flags["no-login"]) {
1697
- if (!json) p2.log.step("Connect to SplitHub Cloud");
1698
- try {
1699
- const cred = await deviceLogin({
1700
- api,
1701
- root: project.root,
1702
- json,
1703
- onCode: json ? (s) => console.log(JSON.stringify({ step: "approve", verifyUrl: s.verifyUrl, userCode: s.userCode, expiresIn: s.expiresIn, hint: "Show this link to the user and wait; init continues once approved." })) : (s) => p2.note(`${c.cyan(s.verifyUrl)}
1704
-
1705
- Code ${c.green(s.userCode)} \xB7 sign in, pick or create the project, approve.`, "Open this link")
1706
- });
1707
- key ??= cred.publicKey ?? void 0;
1708
- connected = { projectName: cred.projectName, projectId: cred.projectId };
1709
- if (!json) p2.log.success(`connected to ${c.cyan(cred.projectName ?? cred.projectId ?? "project")}`);
1710
- } catch (error) {
1711
- if (!json) p2.log.warn(`not connected: ${error instanceof Error ? error.message : String(error)}. Run ${c.cyan("npx splithub login")} later.`);
1712
- }
1713
- }
1714
- if (!key && process.env.SPLITHUB_API_KEY) {
1715
- try {
1716
- const res = await fetch(`${api}/config`, { headers: { authorization: `Bearer ${process.env.SPLITHUB_API_KEY}` } });
1717
- const body = await res.json().catch(() => ({}));
1718
- if (typeof body.publicKey === "string" && body.publicKey.startsWith("pk_")) {
1719
- key = body.publicKey;
1720
- connected ??= { projectName: null, projectId: null };
1721
- }
1722
- } catch {
1723
- }
1724
- }
1725
- if (!key && !yes) {
1726
- const k2 = await p2.text({ message: "Cloud public key (pk_...), leave empty to set later via NEXT_PUBLIC_SPLITHUB_KEY", placeholder: "pk_" });
1727
- if (p2.isCancel(k2)) return cancel3();
1728
- key = k2 || void 0;
1729
- }
1730
- }
1731
- const configFile = project.configFile ?? join6(project.root, "splithub.config.ts");
1732
- writeIfMissing(configFile, configTemplate(project.name, mode, key), created, skipped);
1733
- const storeBody = mode === "self" ? storeTemplate(db) : null;
1734
- const storeFile = storeBody ? join6(project.root, "splithub", "store.ts") : null;
1735
- if (storeFile && storeBody) writeIfMissing(storeFile, storeBody, created, skipped);
1736
- if (project.framework === "next") {
1737
- const mwFile = join6(project.root, project.hasSrc ? "src/middleware.ts" : "middleware.ts");
1738
- writeIfMissing(mwFile, nextMiddlewareTemplate(importPath(mwFile, configFile)), created, skipped);
1739
- if (mode === "self" && project.appDir) {
1740
- const routeFile = join6(project.root, project.appDir, "api/splithub/[[...path]]/route.ts");
1741
- writeIfMissing(routeFile, nextRouteTemplate(importPath(routeFile, configFile), storeUsage(db, storeFile ? importPath(routeFile, storeFile) : "")), created, skipped);
1742
- }
1743
- }
1744
- let mcp = !flags["no-mcp"];
1745
- if (!yes && !json && mcp) {
1746
- const want = await p2.confirm({ message: "Register the SplitHub MCP server for Claude Code / Cursor (.mcp.json, .cursor/mcp.json)?", initialValue: true });
1747
- if (p2.isCancel(want)) return cancel3();
1748
- mcp = want;
1749
- }
1750
- const skillsResult = installSkills(project.root, { mcp });
1751
- created.push(...skillsResult.written, ...skillsResult.mcp.map((f) => `${f} (MCP server)`));
1752
- skipped.push(...skillsResult.skipped);
1753
- const runtime = ["@splithub/react", "@splithub/core"];
1754
- if (project.framework === "next") runtime.push("@splithub/next");
1755
- if (mode === "self") runtime.push("@splithub/node", ...runtimePackages(db));
1756
- const installRuntime = installCommand(project.packageManager, runtime);
1757
- const installDev = installCommand(project.packageManager, ["splithub"], true);
1758
- let installed = false;
1759
- if (!flags["no-install"]) {
1760
- const go = yes ? true : await p2.confirm({ message: `Install packages now? (${installRuntime})` });
1761
- if (p2.isCancel(go)) return cancel3();
1762
- if (go) {
1763
- const s = json ? null : p2.spinner();
1764
- s?.start("Installing");
1765
- try {
1766
- execSync(installRuntime, { cwd: project.root, stdio: json ? "ignore" : "inherit" });
1767
- execSync(installDev, { cwd: project.root, stdio: json ? "ignore" : "inherit" });
1768
- installed = true;
1769
- s?.stop("Installed");
1770
- } catch (error) {
1771
- s?.stop("Install failed; run it manually");
1772
- if (!json) p2.log.error(error instanceof Error ? error.message : String(error));
1773
- }
1774
- }
1775
- }
1776
- const providerHint = project.framework === "next" ? `// ${project.appDir ?? "app"}/layout.tsx
1777
- import { SplitHubNextProvider } from '@splithub/next/client';
1778
- import { getSplitHub } from '@splithub/next/server';
1779
- import config from '${importPath(join6(project.root, project.appDir ?? "app", "layout.tsx"), configFile)}';
1780
-
1781
- export default async function RootLayout({ children }) {
1782
- const sh = await getSplitHub(config);
1783
- return <html><body><SplitHubNextProvider config={config} visitorId={sh.visitorId ?? undefined} remoteOverrides={sh.overrides}>{children}</SplitHubNextProvider></body></html>;
1784
- }` : `// main.tsx
1785
- import { SplitHubProvider } from '@splithub/react';
1786
- import config from './splithub.config';
1787
-
1788
- <SplitHubProvider config={config}><App /></SplitHubProvider>`;
1789
- const warning = mode === "cloud" && !key ? "No public key yet: storage.key falls back to process.env.NEXT_PUBLIC_SPLITHUB_KEY. It is written into the config by the first `npx splithub push`, by `npx splithub login` (saved with the credentials), or pass --key pk_\u2026 (dashboard \u2192 Setup); SPLITHUB_API_KEY in the environment also resolves it." : null;
1790
- const summary = { project: project.name, framework: project.framework, mode, db: mode === "self" ? db : null, connected, publicKey: key ?? null, warning, created, skipped, installed, installCommands: installed ? [] : [installRuntime, installDev], nextStep: providerHint, ...project.framework === "vite" ? { vitePlugin: VITE_PLUGIN_HINT } : {} };
1791
- if (json) {
1792
- console.log(JSON.stringify(summary, null, 2));
1793
- return;
1794
- }
1795
- if (warning) p2.log.warn(warning);
1796
- if (mode === "self" && db !== "sqlite") p2.note(db === "custom" ? "Fill in the three methods in splithub/store.ts (the comments say what each must return)." : `Set DATABASE_URL and run the SCHEMA_SQL from splithub/store.ts once (or add it to your migrations).`, `Database: ${db}`);
1797
- if (created.length) p2.note(created.map((f) => relative4(project.root, f) || f).join("\n"), "Created");
1798
- if (skipped.length) p2.note(skipped.map((f) => relative4(project.root, f)).join("\n"), "Already present, left untouched");
1799
- if (!installed) p2.note(`${installRuntime}
1800
- ${installDev}`, "Install");
1801
- p2.note(providerHint, "Wrap your app once");
1802
- if (project.framework === "vite") p2.note(VITE_PLUGIN_HINT, "Notes in your dev terminal");
1803
- p2.outro(`Next: ${c.cyan("npx splithub create")} to add your first experiment, ${c.cyan("npx splithub push")} to sync it, ${c.cyan("npx splithub doctor")} to verify.`);
1804
- }
1805
- function cancel3() {
1806
- p2.cancel("Cancelled.");
1807
- process.exit(0);
1808
- }
1809
-
1810
- // src/commands/lifecycle.ts
1811
- import { relative as relative5 } from "path";
1812
- var MAP = { start: "running", pause: "paused", finish: "finished" };
1813
- async function lifecycle(command, id, flags) {
1814
- const status2 = MAP[command];
1815
- if (!status2) throw new Error(`unknown command "${command}"`);
1816
- if (!id) throw new Error(`usage: splithub ${command} <experiment>`);
1817
- const project = detectProject();
1818
- if (!project.configFile) throw new Error("splithub.config.ts not found. Run `npx splithub init` first.");
1819
- const updated = setExperimentStatus(readSource(project.configFile), id, status2);
1820
- writeSource(project.configFile, updated);
1821
- const file = relative5(project.root, project.configFile);
1822
- let live = "skipped";
1823
- try {
1824
- const config = await loadConfig(project.configFile);
1825
- if (config.storage.mode === "cloud") {
1826
- const target = cloudTarget(flags);
1827
- if (!target.token) live = "no API key (set SPLITHUB_API_KEY to apply without a deploy)";
1828
- else {
1829
- const res = await fetch(`${target.url}/overrides/${encodeURIComponent(id)}`, {
1830
- method: "PUT",
1831
- headers: { authorization: `Bearer ${target.token}`, "content-type": "application/json" },
1832
- body: JSON.stringify({ status: status2 })
1833
- });
1834
- const body = await res.json().catch(() => ({}));
1835
- live = res.ok ? "applied" : `cloud refused: ${apiErrorMessage(res.status, body, String(res.status))}`;
1836
- }
1837
- }
1838
- } catch (error) {
1839
- live = `could not apply live: ${error instanceof Error ? error.message : String(error)}`;
1840
- }
1841
- const next = status2 === "finished" ? `Read the verdict (npx splithub results ${id}), decide which variant to keep, then remove the test from the code and the config: the splithub-ship skill walks an agent through it.` : null;
1842
- if (flags.json) console.log(JSON.stringify({ experiment: id, status: status2, configFile: file, live, ...next ? { next } : {} }));
1843
- else {
1844
- console.log(`${c.green("\u2714")} ${c.bold(id)} \u2192 ${status2} ${c.dim(`(${file})`)}`);
1845
- if (live === "applied") console.log(`${c.green("\u2714")} live in the cloud within 60s, no deploy needed (the config change ships with your next deploy)`);
1846
- else if (live !== "skipped") console.log(c.yellow(`! ${live}`));
1847
- if (next) console.log(c.dim(`Next: ${next}`));
1848
- }
1849
- }
1850
-
1851
- // src/commands/menu.ts
1852
- import * as p3 from "@clack/prompts";
1853
- import { readFileSync as readFileSync7 } from "fs";
1854
-
1855
- // src/commands/push.ts
1856
- import { relative as relative6 } from "path";
1857
- function factorsOf(e) {
1858
- const out = {};
1859
- for (const f of e.factors ?? []) {
1860
- out[f.key] = {};
1861
- for (const level of f.levels) {
1862
- const combo = e.variants.find((v) => v.levels?.[f.key] === level);
1863
- const value = combo?.value?.[f.key];
1864
- out[f.key][level] = typeof value === "string" ? value : value === void 0 ? level : JSON.stringify(value);
1865
- }
1866
- }
1867
- return out;
1868
- }
1869
- function adoptCloudExperiments(file, cloudOnly) {
1870
- if (!cloudOnly || cloudOnly.length === 0) return [];
1871
- let source = readSource(file);
1872
- const written = [];
1873
- for (const e of cloudOnly) {
1874
- if (hasExperiment(source, e.key)) continue;
1875
- const total = e.variants.reduce((s, v) => s + v.weight, 0) || 1;
1876
- source = insertExperiment(source, {
1877
- key: e.key,
1878
- kind: e.kind,
1879
- status: e.status,
1880
- goal: e.goal ?? void 0,
1881
- match: e.match ?? void 0,
1882
- description: e.description ?? void 0,
1883
- flow: e.flow ?? void 0,
1884
- traffic: e.traffic,
1885
- maxExposures: e.maxExposures ?? void 0,
1886
- schedule: e.schedule ?? void 0,
1887
- variants: e.variants.map((v) => ({ key: v.key, weight: Math.round(v.weight / total * 100), value: typeof v.value === "string" ? v.value : v.value === void 0 ? void 0 : JSON.stringify(v.value), to: v.to })),
1888
- ...e.kind === "mvt" && e.factors ? { factors: factorsOf(e) } : {}
1889
- });
1890
- written.push(e.key);
1891
- }
1892
- if (written.length) writeSource(file, source);
1893
- return written;
1894
- }
1895
- async function push(flags) {
1896
- const project = detectProject();
1897
- if (!project.configFile) throw new Error("splithub.config.ts not found. Run `npx splithub init` first.");
1898
- const config = await loadConfig(project.configFile);
1899
- if (config.storage.mode !== "cloud") {
1900
- throw new Error(`storage.mode is "${config.storage.mode}". Set storage: { mode: 'cloud' } in splithub.config.ts to use SplitHub Cloud.`);
1901
- }
1902
- const target = cloudTarget(flags);
1903
- if (!target.token) throw new Error("project API key required: run `npx splithub login`, or pass --token sk_... / SPLITHUB_API_KEY (dashboard \u2192 Settings \u2192 API keys).");
1904
- const res = await fetch(`${target.url}/config`, {
1905
- method: "PUT",
1906
- headers: { authorization: `Bearer ${target.token}`, "content-type": "application/json" },
1907
- body: JSON.stringify({ config })
1908
- });
1909
- const body = await res.json().catch(() => ({}));
1910
- if (!res.ok) throw new Error(apiErrorMessage(res.status, body, `${target.url}/config responded ${res.status}`));
1911
- let keyWritten = false;
1912
- if (body.publicKey && !config.storage.key) {
1913
- const source = readSource(project.configFile);
1914
- const updated = source.replace(/(mode\s*:\s*['"]cloud['"]\s*)(,?)(\s*\})/, (_m, a, _comma, b) => `${a}, key: '${body.publicKey}'${b}`);
1915
- if (updated !== source) {
1916
- writeSource(project.configFile, updated);
1917
- keyWritten = true;
1918
- }
1919
- }
1920
- const adopted = adoptCloudExperiments(project.configFile, body.cloudOnly);
1921
- const out = { ...body, configFile: relative6(project.root, project.configFile), keyWritten, adopted };
1922
- if (flags.json) {
1923
- console.log(JSON.stringify(out, null, 2));
1924
- return;
1925
- }
1926
- console.log(`${c.green("\u2714")} pushed ${c.bold(String(body.project))} v${body.version} \xB7 ${body.experiments} experiment(s) \u2192 ${target.url}`);
1927
- if (adopted.length) console.log(`${c.green("\u2714")} written into ${out.configFile} from the dashboard: ${adopted.join(", ")} (wire them in code if they are value/component experiments)`);
1928
- if (body.publicKey) {
1929
- console.log(keyWritten ? `${c.green("\u2714")} public key written to ${out.configFile}` : `${c.dim("public key:")} ${body.publicKey}`);
1930
- if (!keyWritten && !config.storage.key) console.log(c.yellow(`Add it to splithub.config.ts: storage: { mode: 'cloud', key: '${body.publicKey}' }`));
1931
- }
1932
- }
1933
- async function pull(flags) {
1934
- const target = cloudTarget(flags);
1935
- if (!target.token) throw new Error("project API key required: run `npx splithub login`, or pass --token sk_... / SPLITHUB_API_KEY");
1936
- const res = await fetch(`${target.url}/config`, { headers: { authorization: `Bearer ${target.token}` } });
1937
- const body = await res.json().catch(() => ({}));
1938
- if (!res.ok) throw new Error(apiErrorMessage(res.status, body, `${target.url}/config responded ${res.status}`));
1939
- const project = detectProject();
1940
- const dashboardOnes = (body.config?.experiments ?? []).filter((e) => e.origin === "dashboard");
1941
- const adopted = project.configFile ? adoptCloudExperiments(project.configFile, dashboardOnes) : [];
1942
- if (flags.json) {
1943
- console.log(JSON.stringify({ ...body, adopted }, null, 2));
1944
- return;
1945
- }
1946
- console.log(`${c.bold("cloud config")} v${body.version} ${c.dim(`pushed ${body.pushedAt}`)} \xB7 public key ${body.publicKey}`);
1947
- if (adopted.length) console.log(`${c.green("\u2714")} written into ${relative6(project.root, project.configFile ?? "")}: ${adopted.join(", ")}`);
1948
- else if (dashboardOnes.length) console.log(c.dim(`dashboard experiments already present locally: ${dashboardOnes.map((e) => e.key).join(", ")}`));
1949
- else console.log(c.dim("no dashboard-created experiments to pull"));
1950
- }
1951
-
1952
- // src/commands/results.ts
1953
- async function results(key, flags) {
1954
- if (!key) throw new Error("usage: splithub results <experiment>");
1955
- const target = resolveTarget(flags, detectProject());
1956
- const r = await fetchResults(target, key);
1957
- if (flags.json) {
1958
- console.log(JSON.stringify(r.status === "finished" ? { ...r, next: FINISHED_NEXT } : r, null, 2));
1959
- return;
1960
- }
1961
- const v = r.verdict;
1962
- console.log(`${c.bold(r.experiment)} ${c.dim(`\xB7 ${r.kind} \xB7 `)}${statusColor(r.status)} ${c.dim(`\xB7 goal: ${r.goal ?? "none"}`)}`);
1963
- if (r.description) console.log(c.dim(r.description));
1964
- console.log();
1965
- console.log(verdictColor(v.status, `${label(v.status)} ${v.message}`));
1966
- console.log();
1967
- const rates = /* @__PURE__ */ new Map();
1968
- for (const cnt of v.sample.variants) rates.set(cnt.variant, cnt.exposures > 0 ? cnt.conversions / cnt.exposures : 0);
1969
- console.log(
1970
- table(
1971
- ["VARIANT", "VISITORS", "CONV", "RATE", "LIFT", "P(BEAT)", "P-VALUE", "95% CI"],
1972
- v.sample.variants.map((cnt, i) => {
1973
- const cmp = v.comparisons.find((x) => x.variant === cnt.variant);
1974
- const name = i === 0 ? `${cnt.variant} ${c.dim("(control)")}` : cnt.variant;
1975
- const marked = v.winner === cnt.variant ? c.green(`\u2605 ${name}`) : name;
1976
- return [
1977
- marked,
1978
- String(cnt.exposures),
1979
- String(cnt.conversions),
1980
- pct(rates.get(cnt.variant)),
1981
- cmp ? pct(cmp.relativeLift, true) : "\u2013",
1982
- cmp ? pct(cmp.probabilityToBeat) : "\u2013",
1983
- cmp ? cmp.pValue.toFixed(4) : "\u2013",
1984
- cmp ? `${pct(cmp.ci.low, true)} \u2026 ${pct(cmp.ci.high, true)}` : "\u2013"
1985
- ];
1986
- })
1987
- )
1988
- );
1989
- const maxRate = Math.max(1e-4, ...v.sample.variants.map((cnt) => rates.get(cnt.variant) ?? 0));
1990
- const nameWidth = Math.max(...v.sample.variants.map((cnt) => cnt.variant.length));
1991
- console.log();
1992
- console.log(c.dim("RATE"));
1993
- for (const cnt of v.sample.variants) {
1994
- const cmp = v.comparisons.find((x) => x.variant === cnt.variant);
1995
- const paint = v.winner === cnt.variant ? c.green : cmp && (cmp.relativeLift ?? 0) < 0 ? c.red : c.cyan;
1996
- const lift = cmp ? (cmp.relativeLift ?? 0) >= 0 ? c.green(`\u25B2 ${pct(cmp.relativeLift, true)}`) : c.red(`\u25BC ${pct(cmp.relativeLift, true)}`) : c.dim("baseline");
1997
- console.log(`${cnt.variant.padEnd(nameWidth)} ${bar(rates.get(cnt.variant) ?? 0, maxRate, 24, paint)} ${pct(rates.get(cnt.variant)).padStart(6)} ${lift}`);
1998
- }
1999
- if (v.comparisons.length) {
2000
- console.log();
2001
- console.log(c.dim("CHANCE TO BEAT THE CONTROL"));
2002
- for (const cmp of v.comparisons) {
2003
- const paint = cmp.probabilityToBeat >= 0.95 ? c.green : cmp.probabilityToBeat <= 0.05 ? c.red : c.yellow;
2004
- console.log(`${cmp.variant.padEnd(nameWidth)} ${bar(cmp.probabilityToBeat, 1, 24, paint)} ${pct(cmp.probabilityToBeat).padStart(6)}`);
2005
- }
2006
- }
2007
- if (v.srm) {
2008
- console.log();
2009
- console.log(c.dim(`SRM check: chi\xB2=${v.srm.chiSquare.toFixed(2)} p=${v.srm.pValue.toExponential(2)} ${v.srm.detected ? c.red("DETECTED") : "ok"}`));
2010
- }
2011
- if (v.status === "insufficient_sample" && v.sample.neededPerVariant) {
2012
- console.log(c.dim(`Estimated ${v.sample.neededPerVariant} visitors per variant needed to confirm the current lift.`));
2013
- }
2014
- if (r.factors?.length) {
2015
- console.log();
2016
- console.log(c.bold("Each factor on its own") + c.dim(" (a level sums every combination that uses it, compared with the first level)"));
2017
- for (const f of r.factors) {
2018
- console.log(
2019
- table(
2020
- [f.key.toUpperCase(), "VISITORS", "CONV.", "RATE", "LIFT", "P-VALUE"],
2021
- f.levels.map((l) => [l.level + (f.best === l.level ? c.green(" \u2714") : ""), String(l.exposures), String(l.conversions), pct(l.rate), l.relativeLift === null ? "\u2013" : pct(l.relativeLift, true), l.pValue === null ? "\u2013" : l.pValue.toFixed(3)])
2022
- )
2023
- );
2024
- }
2025
- }
2026
- if (r.status === "finished") {
2027
- console.log();
2028
- console.log(c.dim(FINISHED_NEXT));
2029
- }
2030
- }
2031
- var FINISHED_NEXT = "This test is finished but its variants are still in the code. Decide which variant to keep, then remove the test from the code and the config (agents: the splithub-ship skill).";
2032
- function label(status2) {
2033
- const icon = verdictIcon(status2);
2034
- switch (status2) {
2035
- case "winner_found":
2036
- return `${icon} WINNER`;
2037
- case "srm_detected":
2038
- return `${icon} SRM`;
2039
- case "insufficient_sample":
2040
- return `${icon} TOO EARLY`;
2041
- case "no_significant_difference":
2042
- return `${icon} NO DIFFERENCE`;
2043
- default:
2044
- return `${icon} NO DATA`;
2045
- }
2046
- }
2047
-
2048
- // src/commands/status.ts
2049
- async function status(flags) {
2050
- const target = resolveTarget(flags, detectProject());
2051
- const data = await fetchStatus(target);
2052
- const finished = data.experiments.filter((e) => e.status === "finished").map((e) => e.experiment);
2053
- const next = finished.length ? `Finished but still in the code: ${finished.join(", ")}. Decide which variant to keep, then remove the test from the code and the config (agents: the splithub-ship skill).` : null;
2054
- if (flags.json) {
2055
- console.log(JSON.stringify(next ? { ...data, next } : data, null, 2));
2056
- return;
2057
- }
2058
- console.log(`${c.bold("SplitHub")} ${c.dim("\xB7")} project ${c.cyan(data.project)} ${c.dim(`\xB7 ${target.url}`)}
2059
- `);
2060
- if (data.experiments.length === 0) {
2061
- console.log(c.dim("No experiments in splithub.config.ts yet. Run `splithub create`."));
2062
- return;
2063
- }
2064
- const maxVisitors = Math.max(1, ...data.experiments.map((e) => e.visitors));
2065
- console.log(
2066
- table(
2067
- ["EXPERIMENT", "KIND", "STATUS", "VISITORS", "", "DAYS", "VERDICT"],
2068
- data.experiments.map((e) => [
2069
- c.bold(e.experiment),
2070
- e.kind,
2071
- statusColor(e.status),
2072
- String(e.visitors),
2073
- bar(e.visitors, maxVisitors, 12, e.status === "running" ? c.green : c.dim),
2074
- e.days ? String(e.days) : "\u2013",
2075
- verdictColor(e.verdict, `${verdictIcon(e.goal ? e.verdict : null)} ${e.headline ?? (e.goal ? "no data" : "no goal")}`)
2076
- ])
2077
- )
2078
- );
2079
- if (next) console.log(`
2080
- ${c.dim(next)}`);
2081
- }
2082
-
2083
- // src/commands/menu.ts
2084
- function state(flags) {
2085
- const project = detectProject();
2086
- const api = cloudTarget({ api: flags.api }).url;
2087
- const cred = loadCredential(api, project.root);
2088
- const mode = project.configFile ? /mode\s*:\s*['"]cloud['"]/.test(readSafe(project.configFile)) ? "cloud" : "self" : null;
2089
- return { project, cred, mode, connected: Boolean(cred || process.env.SPLITHUB_API_KEY) };
2090
- }
2091
- function readSafe(file) {
2092
- try {
2093
- return readFileSync7(file, "utf8");
2094
- } catch {
2095
- return "";
2096
- }
2097
- }
2098
- async function pickExperiment(flags, message) {
2099
- try {
2100
- const data = await fetchStatus(resolveTarget(flags, detectProject()));
2101
- if (data.experiments.length === 0) {
2102
- p3.log.warn("no experiments yet");
2103
- return null;
2104
- }
2105
- const picked = await p3.select({ message, options: data.experiments.map((e) => ({ value: e.experiment, label: e.experiment, hint: `${e.status} \xB7 ${e.visitors} visitors${e.headline ? ` \xB7 ${e.headline}` : ""}` })) });
2106
- if (p3.isCancel(picked)) return null;
2107
- return picked;
2108
- } catch (error) {
2109
- p3.log.error(error instanceof Error ? error.message : String(error));
2110
- return null;
2111
- }
2112
- }
2113
- async function menu(flags) {
2114
- p3.intro(c.bold("splithub"));
2115
- for (; ; ) {
2116
- const s = state(flags);
2117
- const where = s.project.configFile ? `${c.green("config")} ${s.mode === "cloud" ? "cloud mode" : "self-hosted"}` : c.yellow("no config yet");
2118
- const who = s.cred ? `${c.green("connected")} to ${c.cyan(s.cred.projectName ?? s.cred.projectId ?? "project")}` : s.mode === "cloud" ? c.yellow("not connected") : c.dim("local only");
2119
- p3.log.info(`${c.bold(s.project.name)} (${s.project.framework}) \xB7 ${where} \xB7 ${who}`);
2120
- const options = [];
2121
- if (!s.project.configFile) options.push({ value: "init", label: "Set up this app", hint: "config, framework files, agent docs, sign-in link" });
2122
- else {
2123
- if (s.mode === "cloud" && !s.connected) options.push({ value: "login", label: "Connect to SplitHub Cloud", hint: "opens a sign-in link" });
2124
- options.push({ value: "create", label: "Create an experiment", hint: "step by step" });
2125
- options.push({ value: "status", label: "Status of all experiments" });
2126
- options.push({ value: "results", label: "Results of one experiment", hint: "verdict, lift, confidence" });
2127
- options.push({ value: "start", label: "Start an experiment" }, { value: "pause", label: "Pause an experiment" }, { value: "finish", label: "Finish an experiment" });
2128
- if (s.mode === "cloud") options.push({ value: "push", label: "Push config to the cloud", hint: "after editing splithub.config.ts" }, { value: "pull", label: "Pull dashboard changes into the file" });
2129
- options.push({ value: "dev", label: "Test locally in the browser", hint: "debug panel: variants, reasons, events" });
2130
- options.push({ value: "doctor", label: "Check the installation" });
2131
- options.push({ value: "skills", label: "Install agent skills + MCP server", hint: "Claude Code, Cursor, Codex" });
2132
- if (s.cred) options.push({ value: "logout", label: "Disconnect this folder" });
2133
- }
2134
- options.push({ value: "exit", label: "Exit" });
2135
- const action = await p3.select({ message: "What do you want to do?", options });
2136
- if (p3.isCancel(action) || action === "exit") break;
2137
- try {
2138
- switch (action) {
2139
- case "init":
2140
- await init({ ...flags, mode: flags.mode ?? "cloud" });
2141
- break;
2142
- case "login":
2143
- await login({ ...flags, yes: true });
2144
- break;
2145
- case "create":
2146
- await create(flags);
2147
- break;
2148
- case "status":
2149
- await status(flags);
2150
- break;
2151
- case "results": {
2152
- const key = await pickExperiment(flags, "Which experiment?");
2153
- if (key) await results(key, flags);
2154
- break;
2155
- }
2156
- case "start":
2157
- case "pause":
2158
- case "finish": {
2159
- const key = await pickExperiment(flags, `Which experiment to ${action}?`);
2160
- if (key) await lifecycle(action, key, flags);
2161
- break;
2162
- }
2163
- case "push":
2164
- await push(flags);
2165
- break;
2166
- case "pull":
2167
- await pull(flags);
2168
- break;
2169
- case "logout":
2170
- await logout(flags);
2171
- break;
2172
- case "dev":
2173
- await dev(flags);
2174
- break;
2175
- case "doctor":
2176
- await doctor(flags);
2177
- break;
2178
- case "skills":
2179
- await skills({ ...flags, mcp: true });
2180
- break;
2181
- }
2182
- } catch (error) {
2183
- p3.log.error(error instanceof Error ? error.message : String(error));
2184
- }
2185
- console.log();
2186
- }
2187
- p3.outro(`Scripts and agents: ${c.cyan("splithub --help")} lists every command; add ${c.cyan("--json")} for machine output.`);
2188
- }
2189
-
2190
- // src/commands/review.ts
2191
- async function review(key, flags) {
2192
- const target = cloudTarget(flags);
2193
- if (!target.token) throw new Error("project API key required: run `npx splithub login`, or set SPLITHUB_API_KEY");
2194
- const res = await fetch(`${target.url}/reviews${key ? `/${encodeURIComponent(key)}` : ""}`, { headers: { authorization: `Bearer ${target.token}` } });
2195
- const data = await res.json().catch(() => ({}));
2196
- if (!res.ok) throw new Error(apiErrorMessage(res.status, data, `${target.url}/reviews responded ${res.status}`));
2197
- const reviews = data.reviews ?? [];
2198
- if (flags.json) {
2199
- console.log(JSON.stringify({ experiment: key ?? null, reviews }, null, 2));
2200
- return;
2201
- }
2202
- if (reviews.length === 0) {
2203
- console.log(c.dim(key ? `no reviews for ${key} yet (Pro writes one at the start, when the verdict changes while running, and on finish; or click "Review now" in the dashboard)` : "no reviews yet"));
2204
- return;
2205
- }
2206
- for (const r of reviews) {
2207
- console.log(`${c.bold(r.experiment ?? "project")} ${c.dim(`\xB7 ${r.kind}${r.trigger && r.trigger !== "manual" ? ` \xB7 ${r.trigger}` : ""} \xB7 ${new Date(r.createdAt).toLocaleString()}`)}`);
2208
- console.log(r.body.trim());
2209
- console.log();
2210
- }
2211
- }
2212
-
2213
- // src/index.ts
2214
11
  var HELP = `
2215
12
  ${c.bold("splithub")} \u2014 A/B testing for agent-built apps
2216
13
 
@@ -2221,31 +18,44 @@ Usage
2221
18
  splithub start|pause|finish <id>
2222
19
  splithub status all experiments with a verdict headline
2223
20
  splithub results <id> full verdict for one experiment
21
+ splithub plan visitors a test needs: --baseline 0.05 --mde 0.1 [--variants 2] [<id> for days at its traffic]
22
+ splithub refs <id> files and lines that use the experiment and its goal
23
+ splithub ship <id> --keep <v> finish, remove from the config and rewrite the code to the kept variant (--dry-run shows the diff)
24
+ splithub remove <id> remove an experiment from the config (archived in the cloud when connected)
25
+ splithub holdout set <percent> keep a share of visitors out of every test to measure the long-term impact (0-50; --goal); holdout off removes it
2224
26
  splithub review [<id>] AI reviews stored in the cloud (Pro: at start, on verdict changes, on finish, or on demand)
27
+ splithub report status and verdicts as Markdown (used by the GitHub workflow)
28
+ splithub ci init write .github/workflows/splithub.yml (checks on PRs, results comment on a schedule)
2225
29
  splithub dev [--url] [--hold] open the app with ?sh_debug=1 (console + panel: variants, reasons, events) and watch results
2226
30
  splithub doctor check the installation
2227
- splithub skills [--mcp] install / refresh agent skills (library, A/B testing, API, MCP, self-hosting, ship the winner); --mcp registers the MCP server
31
+ splithub skills [--mcp] install / refresh agent skills (library, A/B testing, API, MCP, self-hosting, ship the winner, full loop); --mcp registers the MCP server
2228
32
  splithub login [--project <name|id>] connect this directory to a SplitHub Cloud project (sign-in link, no secrets typed)
2229
- splithub projects every directory connected on this machine and its project; --json for agents
33
+ splithub projects every directory connected on this machine and its project
2230
34
  splithub whoami the project this directory is connected to
2231
35
  splithub logout disconnect this directory
2232
- splithub push upload splithub.config.ts to SplitHub Cloud
36
+ splithub push [--dry-run] upload splithub.config.ts to SplitHub Cloud (--dry-run: check and show what would change)
2233
37
  splithub pull show the config stored in the cloud
2234
38
 
2235
39
  create flags
2236
- --kind value|component|redirect --id <key> --variants control,b --weights 50,50
2237
- --goal <goal> --value k=text (repeatable) --match /path --to k=/url (repeatable)
2238
- --status draft|running --description "..." --traffic 50 (percent) --max-visitors 10000 --start/--end <ISO date> --yes
40
+ --kind value|component|redirect|mvt --id <key> --goal <goal> --status running|draft --description "..." --yes
41
+ value / component / redirect: --variants control,b --weights 50,50
42
+ value: --value control="Old text" --value b="New text" (repeatable)
43
+ redirect: --match /path --to control=/ --to b=/new (repeatable)
44
+ mvt: --factor headline=old:Old,new:New --factor button=blue:#2563eb,green:#16a34a (repeatable; first level = control)
45
+ limits: --traffic 50 (percent of visitors) --max-visitors 10000 --min-days 3 (days before a verdict, 0-30, default 1) --start / --end <ISO date>
46
+ metrics: --secondary pricing_view,signup --guardrail refunds:higher,errors (must not get worse; :higher when a rise is bad)
47
+ layers: --layer checkout:0-50 (tests in one layer never share a visitor; ranges must not overlap)
2239
48
 
2240
49
  init flags
2241
- --mode self|cloud --db sqlite|postgres|mysql|custom (self mode) --key pk_... --no-install --no-login --no-mcp --yes
50
+ --mode self|cloud --db sqlite|postgres|mysql|custom (self mode) --key pk_... --no-install --no-login --no-mcp --github-action --yes
2242
51
  (cloud mode without a saved login prints a link; approve it in the browser and init continues)
2243
52
 
2244
53
  Global
2245
54
  --url <url> results endpoint (default: $SPLITHUB_URL, the cloud API in cloud mode, else the local dev server)
2246
55
  --token <token> admin token (self: $SPLITHUB_ADMIN_TOKEN) or project API key (cloud: $SPLITHUB_API_KEY, else the key saved by "splithub login")
2247
56
  --api <url> cloud API base (default: https://go.splithub.io/v1 or $SPLITHUB_API)
2248
- --json machine-readable output (for agents)
57
+ --json one line of JSON (for agents); errors are { error, code, hint? } and exit 1
58
+ -v, --version
2249
59
  -h, --help
2250
60
  `;
2251
61
  async function main() {
@@ -2258,12 +68,15 @@ async function main() {
2258
68
  json: { type: "boolean", default: false },
2259
69
  yes: { type: "boolean", short: "y", default: false },
2260
70
  help: { type: "boolean", short: "h", default: false },
71
+ version: { type: "boolean", short: "v", default: false },
2261
72
  mode: { type: "string" },
2262
73
  db: { type: "string" },
2263
74
  key: { type: "string" },
2264
75
  "no-install": { type: "boolean", default: false },
2265
76
  "no-login": { type: "boolean", default: false },
2266
77
  "no-mcp": { type: "boolean", default: false },
78
+ "no-open": { type: "boolean", default: false },
79
+ hold: { type: "boolean", default: false },
2267
80
  mcp: { type: "boolean", default: false },
2268
81
  force: { type: "boolean", default: false },
2269
82
  kind: { type: "string" },
@@ -2279,61 +92,94 @@ async function main() {
2279
92
  description: { type: "string" },
2280
93
  traffic: { type: "string" },
2281
94
  "max-visitors": { type: "string" },
95
+ "min-days": { type: "string" },
2282
96
  start: { type: "string" },
2283
97
  end: { type: "string" },
2284
- project: { type: "string" }
98
+ project: { type: "string" },
99
+ keep: { type: "string" },
100
+ "dry-run": { type: "boolean", default: false },
101
+ baseline: { type: "string" },
102
+ mde: { type: "string" },
103
+ "github-action": { type: "boolean", default: false },
104
+ secondary: { type: "string", multiple: true },
105
+ guardrail: { type: "string", multiple: true },
106
+ layer: { type: "string" }
2285
107
  }
2286
108
  });
2287
- const [command, arg] = positionals;
109
+ const [command, arg, third] = positionals;
2288
110
  if (values.help) {
2289
111
  console.log(HELP.trimEnd());
2290
112
  return;
2291
113
  }
114
+ if (values.version) {
115
+ const { version } = createRequire(import.meta.url)("../package.json");
116
+ console.log(values.json ? JSON.stringify({ version }) : version);
117
+ return;
118
+ }
2292
119
  if (!command) {
2293
- if (process.stdin.isTTY && process.stdout.isTTY && !values.json) return menu(values);
120
+ if (process.stdin.isTTY && process.stdout.isTTY && !values.json) return (await import("./menu-UQX3K5QR.js")).menu(values);
2294
121
  console.log(HELP.trimEnd());
2295
122
  return;
2296
123
  }
2297
124
  switch (command) {
2298
125
  case "init":
2299
- return init(values);
126
+ return (await import("./init-QAAM2GQ7.js")).init(values);
2300
127
  case "create":
2301
- return create(values);
128
+ return (await import("./create-K75OY6XK.js")).create(values);
2302
129
  case "start":
2303
130
  case "pause":
2304
131
  case "finish":
2305
- return lifecycle(command, arg, values);
132
+ return (await import("./lifecycle-56HM7ITG.js")).lifecycle(command, arg, values);
2306
133
  case "status":
2307
- return status(values);
134
+ return (await import("./status-CWI7ZCYJ.js")).status(values);
2308
135
  case "results":
2309
- return results(arg, values);
136
+ return (await import("./results-TLV5KJWO.js")).results(arg, values);
137
+ case "plan":
138
+ return (await import("./plan-BSFSMKTU.js")).plan(arg, values);
139
+ case "refs":
140
+ return (await import("./refs-ZDNH6NRK.js")).refs(arg, values);
141
+ case "remove":
142
+ return (await import("./remove-KFQUK367.js")).remove(arg, values);
143
+ case "ship":
144
+ return (await import("./ship-4YX2WCBP.js")).ship(arg, values);
145
+ case "report":
146
+ return (await import("./report-TF2BLJMC.js")).report(values);
147
+ case "ci":
148
+ if (arg !== "init") fail("USAGE", `Unknown "ci ${arg ?? ""}".`, "Run npx splithub ci init.");
149
+ return (await import("./ci-ZQZ6RBUJ.js")).ciInit(values);
150
+ case "holdout":
151
+ return (await import("./holdout-PECSNGAD.js")).holdout(arg, third, values);
2310
152
  case "review":
2311
- return review(arg, values);
153
+ return (await import("./review-EIZDOGDC.js")).review(arg, values);
2312
154
  case "dev":
2313
- return dev(values);
155
+ return (await import("./dev-WQWFEA6I.js")).dev(values);
2314
156
  case "doctor":
2315
- return doctor(values);
157
+ return (await import("./doctor-MFYBZUKO.js")).doctor(values);
2316
158
  case "skills":
2317
- return skills(values);
159
+ return (await import("./skills-HWQT3DTJ.js")).skills(values);
2318
160
  case "push":
2319
- return push(values);
161
+ return (await import("./push-YVS25VVD.js")).push(values);
2320
162
  case "pull":
2321
- return pull(values);
163
+ return (await import("./push-YVS25VVD.js")).pull(values);
2322
164
  case "login":
2323
- return login(values);
165
+ return (await import("./login-TTWSQ7XS.js")).login(values);
2324
166
  case "logout":
2325
- return logout(values);
167
+ return (await import("./login-TTWSQ7XS.js")).logout(values);
2326
168
  case "whoami":
2327
- return whoami(values);
169
+ return (await import("./login-TTWSQ7XS.js")).whoami(values);
2328
170
  case "projects":
2329
- return projects(values);
171
+ return (await import("./login-TTWSQ7XS.js")).projects(values);
2330
172
  default:
2331
- throw new Error(`unknown command "${command}"
2332
- ${HELP}`);
173
+ fail("USAGE", `Unknown command "${command}".`, "Run npx splithub --help for the list.");
2333
174
  }
2334
175
  }
2335
176
  main().catch((error) => {
2336
- console.error(c.red(`error: ${error instanceof Error ? error.message : String(error)}`));
177
+ const body = errorJson(error);
178
+ if (process.argv.includes("--json")) console.log(JSON.stringify(body));
179
+ else {
180
+ console.error(c.red(`error: ${body.error}`));
181
+ if (body.hint) console.error(c.dim(body.hint));
182
+ }
2337
183
  process.exit(1);
2338
184
  });
2339
185
  //# sourceMappingURL=index.js.map