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