@supersdk/supercli 0.5.10 → 0.5.12-staging.123
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/api/cdnClient.js +63 -21
- package/dist/api/cdnClient.js.map +1 -1
- package/dist/api/cdnDomainClient.js +80 -0
- package/dist/api/cdnDomainClient.js.map +1 -0
- package/dist/api/dbClient.js.map +1 -1
- package/dist/api/experimentClient.js +178 -0
- package/dist/api/experimentClient.js.map +1 -0
- package/dist/cli.js +2 -0
- package/dist/cli.js.map +1 -1
- package/dist/commands/cdn.js +198 -0
- package/dist/commands/cdn.js.map +1 -0
- package/dist/commands/cdnDomain.js +203 -0
- package/dist/commands/cdnDomain.js.map +1 -0
- package/dist/commands/db.js +31 -4
- package/dist/commands/db.js.map +1 -1
- package/dist/commands/delivery.js +3 -81
- package/dist/commands/delivery.js.map +1 -1
- package/dist/commands/experiment.js +1360 -0
- package/dist/commands/experiment.js.map +1 -0
- package/dist/output/envelope.js.map +1 -1
- package/dist/output/resultPrinter.js +2 -2
- package/dist/output/resultPrinter.js.map +1 -1
- package/dist/template/android/supersdk-default.config.json +1 -1
- package/dist/template/web/src/js/supersdk.js +2 -2
- package/dist/template/web/src/js/supersdk.provenance.json +3 -3
- package/package.json +1 -1
|
@@ -0,0 +1,1360 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
+
}) : function(o, v) {
|
|
16
|
+
o["default"] = v;
|
|
17
|
+
});
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
35
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.defaultExperimentDeps = exports.EXPERIMENT_LIST_MAX_PAGES = void 0;
|
|
37
|
+
exports.validExperimentKey = validExperimentKey;
|
|
38
|
+
exports.percentToBasisPoints = percentToBasisPoints;
|
|
39
|
+
exports.parseExpectedVersion = parseExpectedVersion;
|
|
40
|
+
exports.parseVariants = parseVariants;
|
|
41
|
+
exports.readJsonSource = readJsonSource;
|
|
42
|
+
exports.parsePayloads = parsePayloads;
|
|
43
|
+
exports.experimentFailure = experimentFailure;
|
|
44
|
+
exports.runExperimentList = runExperimentList;
|
|
45
|
+
exports.runExperimentGet = runExperimentGet;
|
|
46
|
+
exports.buildCreateBody = buildCreateBody;
|
|
47
|
+
exports.runExperimentCreate = runExperimentCreate;
|
|
48
|
+
exports.runExperimentUpdate = runExperimentUpdate;
|
|
49
|
+
exports.runExperimentTraffic = runExperimentTraffic;
|
|
50
|
+
exports.runExperimentAction = runExperimentAction;
|
|
51
|
+
exports.runExperimentHistory = runExperimentHistory;
|
|
52
|
+
exports.runExperimentOverridesGet = runExperimentOverridesGet;
|
|
53
|
+
exports.parseOverrideDevices = parseOverrideDevices;
|
|
54
|
+
exports.runExperimentOverridesSet = runExperimentOverridesSet;
|
|
55
|
+
exports.runExperimentMetricsList = runExperimentMetricsList;
|
|
56
|
+
exports.buildMetricInput = buildMetricInput;
|
|
57
|
+
exports.runExperimentMetricsAdd = runExperimentMetricsAdd;
|
|
58
|
+
exports.runExperimentMetricsRemove = runExperimentMetricsRemove;
|
|
59
|
+
exports.runExperimentResults = runExperimentResults;
|
|
60
|
+
exports.runExperimentLookup = runExperimentLookup;
|
|
61
|
+
exports.runExperimentVids = runExperimentVids;
|
|
62
|
+
exports.runExperimentLayersList = runExperimentLayersList;
|
|
63
|
+
exports.runExperimentLayersCreate = runExperimentLayersCreate;
|
|
64
|
+
exports.runExperimentLayersUpdate = runExperimentLayersUpdate;
|
|
65
|
+
exports.runExperimentLayersDelete = runExperimentLayersDelete;
|
|
66
|
+
exports.runExperimentNamespacesList = runExperimentNamespacesList;
|
|
67
|
+
exports.runExperimentNamespacesCreate = runExperimentNamespacesCreate;
|
|
68
|
+
exports.runExperimentNamespacesUpdate = runExperimentNamespacesUpdate;
|
|
69
|
+
exports.runExperimentNamespacesDelete = runExperimentNamespacesDelete;
|
|
70
|
+
exports.emitExperimentOutcome = emitExperimentOutcome;
|
|
71
|
+
exports.registerExperimentCommand = registerExperimentCommand;
|
|
72
|
+
const fs = __importStar(require("node:fs"));
|
|
73
|
+
const experimentClient_1 = require("../api/experimentClient");
|
|
74
|
+
const tokenAuth_1 = require("../auth/tokenAuth");
|
|
75
|
+
const environments_1 = require("../config/environments");
|
|
76
|
+
const resultPrinter_1 = require("../output/resultPrinter");
|
|
77
|
+
const accountStore_1 = require("../store/accountStore");
|
|
78
|
+
const credentialStore_1 = require("../store/credentialStore");
|
|
79
|
+
const prompt_1 = require("../util/prompt");
|
|
80
|
+
const projectContext_1 = require("../workspace/projectContext");
|
|
81
|
+
exports.EXPERIMENT_LIST_MAX_PAGES = 50;
|
|
82
|
+
const ENV_NAME_PATTERN = /^[a-z0-9]{1,10}$/;
|
|
83
|
+
const PERCENT_PATTERN = /^\d{1,3}(?:\.\d{1,2})?$/;
|
|
84
|
+
const METRIC_KINDS = ['conversion', 'count', 'sum', 'avg', 'pct', 'retention'];
|
|
85
|
+
const METRIC_ROLES = ['metric', 'guardrail'];
|
|
86
|
+
const METRIC_DIRECTIONS = ['up', 'down'];
|
|
87
|
+
function isOutcome(value) {
|
|
88
|
+
return value !== null && typeof value === 'object' && 'ok' in value && typeof value.ok === 'boolean';
|
|
89
|
+
}
|
|
90
|
+
function usage(message) {
|
|
91
|
+
return { ok: false, kind: 'usage_error', message };
|
|
92
|
+
}
|
|
93
|
+
function asRecord(value) {
|
|
94
|
+
return value !== null && typeof value === 'object' && !Array.isArray(value)
|
|
95
|
+
? value
|
|
96
|
+
: undefined;
|
|
97
|
+
}
|
|
98
|
+
function storedToken(account) {
|
|
99
|
+
return (0, credentialStore_1.backendForAccount)(account.backend, {
|
|
100
|
+
passphraseProvider: account.backend === 'encrypted-file'
|
|
101
|
+
? () => (0, prompt_1.promptHiddenSync)(`Encryption passphrase for ${account.email ?? account.accountKey}: `)
|
|
102
|
+
: undefined,
|
|
103
|
+
}).get(account.accountKey)?.token ?? null;
|
|
104
|
+
}
|
|
105
|
+
exports.defaultExperimentDeps = {
|
|
106
|
+
getCurrentAccount: accountStore_1.getCurrentAccount,
|
|
107
|
+
getStoredToken: storedToken,
|
|
108
|
+
markNeedsLogin: accountStore_1.markAccountNeedsLogin,
|
|
109
|
+
createClient: (apiOrigin) => new experimentClient_1.ExperimentClient(apiOrigin),
|
|
110
|
+
readFile: (file) => fs.readFileSync(file),
|
|
111
|
+
};
|
|
112
|
+
function resolveAuth(deps) {
|
|
113
|
+
const envToken = (0, tokenAuth_1.resolveEnvToken)();
|
|
114
|
+
if (envToken)
|
|
115
|
+
return { token: envToken, apiOrigin: (0, environments_1.resolveApiOrigin)().apiOrigin, source: 'env' };
|
|
116
|
+
const account = deps.getCurrentAccount();
|
|
117
|
+
if (!account) {
|
|
118
|
+
return { ok: false, kind: 'needs_login', message: 'no account is logged in — run `supercli login` first or set SUPERCLI_TOKEN' };
|
|
119
|
+
}
|
|
120
|
+
let token;
|
|
121
|
+
try {
|
|
122
|
+
token = deps.getStoredToken(account);
|
|
123
|
+
}
|
|
124
|
+
catch {
|
|
125
|
+
return { ok: false, kind: 'needs_login', message: 'cannot access the local credential — run `supercli login` again or set SUPERCLI_TOKEN' };
|
|
126
|
+
}
|
|
127
|
+
if (!token) {
|
|
128
|
+
deps.markNeedsLogin(account.accountKey);
|
|
129
|
+
return { ok: false, kind: 'needs_login', message: 'no valid credential found locally — run `supercli login` again or set SUPERCLI_TOKEN' };
|
|
130
|
+
}
|
|
131
|
+
return { token, apiOrigin: account.apiOrigin, source: 'stored', accountKey: account.accountKey };
|
|
132
|
+
}
|
|
133
|
+
function resolveProject(opts) {
|
|
134
|
+
const context = (0, projectContext_1.resolveWorkspaceContext)(process.cwd(), opts.config);
|
|
135
|
+
if (isOutcome(context))
|
|
136
|
+
return context;
|
|
137
|
+
if (!context.spid)
|
|
138
|
+
return usage('SPID is read from super.json');
|
|
139
|
+
return { configPath: context.configPath, spid: context.spid };
|
|
140
|
+
}
|
|
141
|
+
function resolveEnvScope(opts) {
|
|
142
|
+
const env = opts.env?.trim();
|
|
143
|
+
if (!env || !ENV_NAME_PATTERN.test(env)) {
|
|
144
|
+
return usage('--env is required and must be 1-10 lowercase letters or digits');
|
|
145
|
+
}
|
|
146
|
+
const project = resolveProject(opts);
|
|
147
|
+
if (isOutcome(project))
|
|
148
|
+
return project;
|
|
149
|
+
return { ...project, env };
|
|
150
|
+
}
|
|
151
|
+
// ── local validation ─────────────────────────────────────────────────────────────────────
|
|
152
|
+
function validExperimentKey(raw, label = 'experiment key') {
|
|
153
|
+
const key = raw?.trim() ?? '';
|
|
154
|
+
if (!experimentClient_1.EXPERIMENT_KEY_PATTERN.test(key)) {
|
|
155
|
+
return usage(`${label} must match ^[a-z][a-z0-9_]{1,39}$`);
|
|
156
|
+
}
|
|
157
|
+
if (label === 'experiment key' && experimentClient_1.EXPERIMENT_RESERVED_KEYS.includes(key)) {
|
|
158
|
+
return usage(`${key} is a reserved experiment key`);
|
|
159
|
+
}
|
|
160
|
+
return key;
|
|
161
|
+
}
|
|
162
|
+
/** Percent (0..100, up to two decimals) → basis points (0..10000). */
|
|
163
|
+
function percentToBasisPoints(raw, flag, opts = {}) {
|
|
164
|
+
const value = raw?.trim() ?? '';
|
|
165
|
+
const min = opts.min ?? 0;
|
|
166
|
+
const message = `${flag} must be a percentage ${min > 0 ? 'above 0' : 'from 0'} to 100 with at most two decimals`;
|
|
167
|
+
if (!PERCENT_PATTERN.test(value))
|
|
168
|
+
return usage(message);
|
|
169
|
+
const bp = Math.round(Number(value) * 100);
|
|
170
|
+
if (!Number.isInteger(bp) || bp < min || bp > experimentClient_1.EXPERIMENT_BUCKETS)
|
|
171
|
+
return usage(message);
|
|
172
|
+
return bp;
|
|
173
|
+
}
|
|
174
|
+
function parseExpectedVersion(raw) {
|
|
175
|
+
const value = raw?.trim() ?? '';
|
|
176
|
+
if (!/^\d{1,10}$/.test(value)) {
|
|
177
|
+
return usage('--expected-version is required and must be a positive integer (the `version` from `experiment get`)');
|
|
178
|
+
}
|
|
179
|
+
const parsed = Number(value);
|
|
180
|
+
if (parsed < 1 || parsed > 2_147_483_647) {
|
|
181
|
+
return usage('--expected-version must be a positive integer (the `version` from `experiment get`)');
|
|
182
|
+
}
|
|
183
|
+
return parsed;
|
|
184
|
+
}
|
|
185
|
+
function parseBoundedInt(raw, flag, min, max) {
|
|
186
|
+
if (raw === undefined)
|
|
187
|
+
return undefined;
|
|
188
|
+
const value = raw.trim();
|
|
189
|
+
const parsed = Number(value);
|
|
190
|
+
if (!/^\d{1,6}$/.test(value) || parsed < min || parsed > max) {
|
|
191
|
+
return usage(`${flag} must be an integer from ${min} to ${max}`);
|
|
192
|
+
}
|
|
193
|
+
return parsed;
|
|
194
|
+
}
|
|
195
|
+
/** `key:weight[:name]` × 2..10, weights in percent summing to exactly 100. */
|
|
196
|
+
function parseVariants(raw) {
|
|
197
|
+
const items = raw ?? [];
|
|
198
|
+
if (items.length < experimentClient_1.EXPERIMENT_VARIANTS_MIN || items.length > experimentClient_1.EXPERIMENT_VARIANTS_MAX) {
|
|
199
|
+
return usage(`--variant must be given ${experimentClient_1.EXPERIMENT_VARIANTS_MIN} to ${experimentClient_1.EXPERIMENT_VARIANTS_MAX} times (key:weight[:name])`);
|
|
200
|
+
}
|
|
201
|
+
const variants = [];
|
|
202
|
+
let sum = 0;
|
|
203
|
+
for (const item of items) {
|
|
204
|
+
const first = item.indexOf(':');
|
|
205
|
+
if (first <= 0)
|
|
206
|
+
return usage(`--variant ${JSON.stringify(item)} must be key:weight[:name]`);
|
|
207
|
+
const key = item.slice(0, first).trim();
|
|
208
|
+
const rest = item.slice(first + 1);
|
|
209
|
+
const second = rest.indexOf(':');
|
|
210
|
+
const weightRaw = second < 0 ? rest : rest.slice(0, second);
|
|
211
|
+
const name = second < 0 ? undefined : rest.slice(second + 1).trim();
|
|
212
|
+
if (!experimentClient_1.EXPERIMENT_VARIANT_KEY_PATTERN.test(key)) {
|
|
213
|
+
return usage(`variant key ${JSON.stringify(key)} must match ^[a-z][a-z0-9_]{0,19}$`);
|
|
214
|
+
}
|
|
215
|
+
if (variants.some((variant) => variant.key === key))
|
|
216
|
+
return usage(`duplicate variant key: ${key}`);
|
|
217
|
+
const weight = percentToBasisPoints(weightRaw, `variant ${key} weight`, { min: 1 });
|
|
218
|
+
if (isOutcome(weight))
|
|
219
|
+
return weight;
|
|
220
|
+
sum += weight;
|
|
221
|
+
variants.push({ key, weight_bp: weight, ...(name ? { name } : {}) });
|
|
222
|
+
}
|
|
223
|
+
if (sum !== experimentClient_1.EXPERIMENT_BUCKETS) {
|
|
224
|
+
return usage(`variant weights must sum to 100 (got ${sum / 100})`);
|
|
225
|
+
}
|
|
226
|
+
return variants;
|
|
227
|
+
}
|
|
228
|
+
/** Inline JSON or `@path` to a UTF-8 JSON file. */
|
|
229
|
+
function readJsonSource(raw, flag, deps) {
|
|
230
|
+
let text = raw;
|
|
231
|
+
if (raw.startsWith('@')) {
|
|
232
|
+
try {
|
|
233
|
+
text = new TextDecoder('utf-8', { fatal: true }).decode(deps.readFile(raw.slice(1)));
|
|
234
|
+
}
|
|
235
|
+
catch {
|
|
236
|
+
return usage(`${flag}: could not read a UTF-8 file at ${raw.slice(1)}`);
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
try {
|
|
240
|
+
return { value: JSON.parse(text) };
|
|
241
|
+
}
|
|
242
|
+
catch {
|
|
243
|
+
return usage(`${flag} must be valid JSON (inline or @file)`);
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
/** `--payload <variantKey>=<json | @file>` (repeatable); payloads must be JSON objects. */
|
|
247
|
+
function parsePayloads(raw, deps) {
|
|
248
|
+
const payloads = new Map();
|
|
249
|
+
for (const item of raw ?? []) {
|
|
250
|
+
const eq = item.indexOf('=');
|
|
251
|
+
if (eq <= 0)
|
|
252
|
+
return usage('--payload must be <variantKey>=<json> or <variantKey>=@file.json');
|
|
253
|
+
const key = item.slice(0, eq).trim();
|
|
254
|
+
if (!experimentClient_1.EXPERIMENT_VARIANT_KEY_PATTERN.test(key)) {
|
|
255
|
+
return usage(`--payload variant key ${JSON.stringify(key)} must match ^[a-z][a-z0-9_]{0,19}$`);
|
|
256
|
+
}
|
|
257
|
+
if (payloads.has(key))
|
|
258
|
+
return usage(`duplicate --payload for variant ${key}`);
|
|
259
|
+
const parsed = readJsonSource(item.slice(eq + 1), `--payload ${key}`, deps);
|
|
260
|
+
if (isOutcome(parsed))
|
|
261
|
+
return parsed;
|
|
262
|
+
if (!asRecord(parsed.value))
|
|
263
|
+
return usage(`--payload ${key} must be a JSON object`);
|
|
264
|
+
payloads.set(key, parsed.value);
|
|
265
|
+
}
|
|
266
|
+
return payloads;
|
|
267
|
+
}
|
|
268
|
+
function applyPayloads(variants, payloads) {
|
|
269
|
+
for (const key of payloads.keys()) {
|
|
270
|
+
if (!variants.some((variant) => variant.key === key))
|
|
271
|
+
return usage(`--payload names unknown variant ${key}`);
|
|
272
|
+
}
|
|
273
|
+
return variants.map((variant) => (payloads.has(variant.key) ? { ...variant, payload: payloads.get(variant.key) } : variant));
|
|
274
|
+
}
|
|
275
|
+
function parseAudience(raw, deps) {
|
|
276
|
+
if (raw === undefined)
|
|
277
|
+
return undefined;
|
|
278
|
+
const parsed = readJsonSource(raw, '--audience', deps);
|
|
279
|
+
if (isOutcome(parsed))
|
|
280
|
+
return parsed;
|
|
281
|
+
if (!Array.isArray(parsed.value))
|
|
282
|
+
return usage('--audience must be a JSON array of {attr, op, value} conditions');
|
|
283
|
+
return parsed.value;
|
|
284
|
+
}
|
|
285
|
+
// ── failures ─────────────────────────────────────────────────────────────────────────────
|
|
286
|
+
function failureResult(code, extra) {
|
|
287
|
+
const record = asRecord(extra);
|
|
288
|
+
if (!record || Object.keys(record).length === 0)
|
|
289
|
+
return undefined;
|
|
290
|
+
const result = { code, extra: record };
|
|
291
|
+
if (code === 'EXP_VERSION_CONFLICT' && typeof record.version === 'number')
|
|
292
|
+
result.current_version = record.version;
|
|
293
|
+
return result;
|
|
294
|
+
}
|
|
295
|
+
function experimentFailure(outcome, action, key) {
|
|
296
|
+
switch (outcome.kind) {
|
|
297
|
+
case 'business_error': {
|
|
298
|
+
const extra = failureResult(outcome.code, outcome.extra);
|
|
299
|
+
let message = `experiment ${action} rejected (${outcome.code}): ${outcome.message}`;
|
|
300
|
+
if (outcome.code === 'EXP_VERSION_CONFLICT') {
|
|
301
|
+
const current = typeof asRecord(outcome.extra)?.version === 'number' ? asRecord(outcome.extra)?.version : undefined;
|
|
302
|
+
message = current === undefined
|
|
303
|
+
? `experiment ${action} rejected (EXP_VERSION_CONFLICT): the experiment changed; re-read it with \`supercli experiment get${key ? ` ${key}` : ''}\``
|
|
304
|
+
: `experiment ${action} rejected (EXP_VERSION_CONFLICT): current version is ${String(current)}; re-read it with \`supercli experiment get${key ? ` ${key}` : ''}\` and retry with --expected-version ${String(current)}`;
|
|
305
|
+
}
|
|
306
|
+
const capacity = asRecord(outcome.extra);
|
|
307
|
+
if (outcome.code === 'EXP_LIMIT_EXCEEDED' && typeof capacity?.available_bp === 'number') {
|
|
308
|
+
// S3: available_bp = the most traffic this experiment can reach right now
|
|
309
|
+
// (held + free in the layer; for reopen continue = reclaimable width).
|
|
310
|
+
message += ` (layer ${str(capacity.layer_key)}: at most ${pct(capacity.available_bp)} available, ${pct(capacity.requested_bp)} requested)`;
|
|
311
|
+
}
|
|
312
|
+
const base = { ok: false, kind: 'business_error', publicCode: outcome.code, message };
|
|
313
|
+
return extra ? { ...base, result: extra } : base;
|
|
314
|
+
}
|
|
315
|
+
case 'auth_invalid':
|
|
316
|
+
return { ok: false, kind: 'auth_invalid', message: 'experiment authentication failed — run `supercli login` again or replace SUPERCLI_TOKEN' };
|
|
317
|
+
case 'forbidden':
|
|
318
|
+
return {
|
|
319
|
+
ok: false,
|
|
320
|
+
kind: 'forbidden',
|
|
321
|
+
message: `experiment ${action} is forbidden for this project — reads need org membership, writes need an admin credential in the owning organization`,
|
|
322
|
+
};
|
|
323
|
+
case 'rate_limited':
|
|
324
|
+
return { ok: false, kind: 'rate_limited', message: 'experiment request was rate limited — retry later' };
|
|
325
|
+
case 'infra_error':
|
|
326
|
+
return { ok: false, kind: 'infra_error', message: `experiment service is unavailable or returned an invalid response (${outcome.message}) — retry later` };
|
|
327
|
+
case 'success':
|
|
328
|
+
return { ok: false, kind: 'infra_error', message: 'unexpected experiment client outcome' };
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
function handleFailure(outcome, auth, deps, action, key) {
|
|
332
|
+
if (outcome.kind === 'auth_invalid' && auth.source === 'stored' && auth.accountKey)
|
|
333
|
+
deps.markNeedsLogin(auth.accountKey);
|
|
334
|
+
return experimentFailure(outcome, action, key);
|
|
335
|
+
}
|
|
336
|
+
// ── human rendering ──────────────────────────────────────────────────────────────────────
|
|
337
|
+
function pct(bp) {
|
|
338
|
+
return typeof bp === 'number' ? `${Number((bp / 100).toFixed(2))}%` : '-';
|
|
339
|
+
}
|
|
340
|
+
function str(value) {
|
|
341
|
+
return value === undefined || value === null ? '-' : String(value);
|
|
342
|
+
}
|
|
343
|
+
function experimentSummary(data) {
|
|
344
|
+
const exp = asRecord(data);
|
|
345
|
+
if (!exp)
|
|
346
|
+
return JSON.stringify(data, null, 2);
|
|
347
|
+
const layer = asRecord(exp.layer);
|
|
348
|
+
const lines = [
|
|
349
|
+
`${str(exp.key)} ${str(exp.name)}`,
|
|
350
|
+
` status ${str(exp.status)} · version ${str(exp.version)} · run ${str(exp.run)} · type ${str(exp.type)}`,
|
|
351
|
+
` traffic ${pct(exp.traffic_bp)} · namespace ${str(exp.namespace)} · layer ${str(layer?.key)}${layer?.shared === true ? ' (shared)' : ''}${typeof layer?.free_bp === 'number' ? ` · layer free ${pct(layer.free_bp)}` : ''}`,
|
|
352
|
+
];
|
|
353
|
+
if (exp.expires_at !== undefined)
|
|
354
|
+
lines.push(` expires ${str(exp.expires_at)} · days left ${str(exp.days_left)}`);
|
|
355
|
+
if (Array.isArray(exp.variants)) {
|
|
356
|
+
for (const raw of exp.variants) {
|
|
357
|
+
const variant = asRecord(raw);
|
|
358
|
+
if (variant)
|
|
359
|
+
lines.push(` - ${str(variant.key)} ${pct(variant.weight_bp)} vid=${str(variant.vid)} ${str(variant.name)}`);
|
|
360
|
+
}
|
|
361
|
+
}
|
|
362
|
+
return lines.join('\n');
|
|
363
|
+
}
|
|
364
|
+
function withScope(scope, payload) {
|
|
365
|
+
return (0, projectContext_1.withConfigIdentity)(scope, scope.env === undefined ? payload : { ...payload, env: scope.env });
|
|
366
|
+
}
|
|
367
|
+
function ok(result, humanMessage) {
|
|
368
|
+
return { ok: true, result, humanMessage };
|
|
369
|
+
}
|
|
370
|
+
function begin(deps, requestId) {
|
|
371
|
+
const auth = resolveAuth(deps);
|
|
372
|
+
if (isOutcome(auth))
|
|
373
|
+
return auth;
|
|
374
|
+
return { auth, client: deps.createClient(auth.apiOrigin), token: { token: auth.token, ...(requestId ? { requestId } : {}) } };
|
|
375
|
+
}
|
|
376
|
+
/**
|
|
377
|
+
* Fetch every page: stop on an empty page, once `total` rows are collected, or at the page
|
|
378
|
+
* cap (then `truncated: true`). Never trusts `total` alone.
|
|
379
|
+
*/
|
|
380
|
+
async function collectPages(fetchPage) {
|
|
381
|
+
const items = [];
|
|
382
|
+
let first;
|
|
383
|
+
let total = 0;
|
|
384
|
+
for (let page = 1; page <= exports.EXPERIMENT_LIST_MAX_PAGES; page++) {
|
|
385
|
+
const outcome = await fetchPage(page);
|
|
386
|
+
if (outcome.kind !== 'success')
|
|
387
|
+
return { kind: 'error', outcome };
|
|
388
|
+
const data = asRecord(outcome.data);
|
|
389
|
+
if (!data || !Array.isArray(data.list) || typeof data.total !== 'number') {
|
|
390
|
+
return { kind: 'error', outcome: { kind: 'infra_error', message: 'paged response is missing list/total' } };
|
|
391
|
+
}
|
|
392
|
+
if (!first)
|
|
393
|
+
first = outcome.data;
|
|
394
|
+
total = data.total;
|
|
395
|
+
if (data.list.length === 0)
|
|
396
|
+
return { kind: 'ok', items, first, total, truncated: false };
|
|
397
|
+
items.push(...data.list);
|
|
398
|
+
if (items.length >= total)
|
|
399
|
+
return { kind: 'ok', items, first, total, truncated: false };
|
|
400
|
+
}
|
|
401
|
+
return { kind: 'ok', items, first, total, truncated: true };
|
|
402
|
+
}
|
|
403
|
+
async function runExperimentList(opts, deps = exports.defaultExperimentDeps) {
|
|
404
|
+
const scope = resolveEnvScope(opts);
|
|
405
|
+
if (isOutcome(scope))
|
|
406
|
+
return scope;
|
|
407
|
+
const ctx = begin(deps);
|
|
408
|
+
if (isOutcome(ctx))
|
|
409
|
+
return ctx;
|
|
410
|
+
const collected = await collectPages((page) => ctx.client.list(ctx.token, scope, {
|
|
411
|
+
status: opts.status?.trim() || undefined,
|
|
412
|
+
namespace: opts.namespace?.trim() || undefined,
|
|
413
|
+
q: opts.q?.trim() || undefined,
|
|
414
|
+
page,
|
|
415
|
+
page_size: experimentClient_1.EXPERIMENT_PAGE_SIZE_MAX,
|
|
416
|
+
}));
|
|
417
|
+
if (collected.kind === 'error')
|
|
418
|
+
return handleFailure(collected.outcome, ctx.auth, deps, 'list');
|
|
419
|
+
const result = {
|
|
420
|
+
experiments: collected.items,
|
|
421
|
+
total: collected.total,
|
|
422
|
+
...(collected.first && 'expiring_soon_count' in collected.first ? { expiring_soon_count: collected.first.expiring_soon_count } : {}),
|
|
423
|
+
...(collected.truncated ? { truncated: true } : {}),
|
|
424
|
+
};
|
|
425
|
+
const lines = collected.items.map((raw) => {
|
|
426
|
+
const exp = asRecord(raw) ?? {};
|
|
427
|
+
return `${str(exp.key)}\t${str(exp.status)}\tv${str(exp.version)}\t${pct(exp.traffic_bp)}\t${str(exp.namespace)}\t${str(exp.name)}`;
|
|
428
|
+
});
|
|
429
|
+
lines.unshift(`${collected.items.length} of ${collected.total} experiment(s) in ${scope.env}`);
|
|
430
|
+
if (collected.truncated)
|
|
431
|
+
lines.push(`truncated after ${exports.EXPERIMENT_LIST_MAX_PAGES} pages; narrow with --status / --namespace / --q`);
|
|
432
|
+
return ok(withScope(scope, result), lines.join('\n'));
|
|
433
|
+
}
|
|
434
|
+
async function runExperimentGet(keyRaw, opts, deps = exports.defaultExperimentDeps) {
|
|
435
|
+
const key = validExperimentKey(keyRaw);
|
|
436
|
+
if (isOutcome(key))
|
|
437
|
+
return key;
|
|
438
|
+
const scope = resolveEnvScope(opts);
|
|
439
|
+
if (isOutcome(scope))
|
|
440
|
+
return scope;
|
|
441
|
+
const ctx = begin(deps);
|
|
442
|
+
if (isOutcome(ctx))
|
|
443
|
+
return ctx;
|
|
444
|
+
const outcome = await ctx.client.get(ctx.token, scope, key);
|
|
445
|
+
if (outcome.kind !== 'success')
|
|
446
|
+
return handleFailure(outcome, ctx.auth, deps, 'get', key);
|
|
447
|
+
return ok(withScope(scope, { experiment: outcome.data }), experimentSummary(outcome.data));
|
|
448
|
+
}
|
|
449
|
+
function buildCreateBody(key, opts, deps) {
|
|
450
|
+
const name = opts.name?.trim();
|
|
451
|
+
if (!name)
|
|
452
|
+
return usage('--name is required and must not be empty');
|
|
453
|
+
const traffic = percentToBasisPoints(opts.traffic, '--traffic');
|
|
454
|
+
if (isOutcome(traffic))
|
|
455
|
+
return traffic;
|
|
456
|
+
const parsed = parseVariants(opts.variant);
|
|
457
|
+
if (isOutcome(parsed))
|
|
458
|
+
return parsed;
|
|
459
|
+
const payloads = parsePayloads(opts.payload, deps);
|
|
460
|
+
if (isOutcome(payloads))
|
|
461
|
+
return payloads;
|
|
462
|
+
const variants = applyPayloads(parsed, payloads);
|
|
463
|
+
if (isOutcome(variants))
|
|
464
|
+
return variants;
|
|
465
|
+
const type = opts.type?.trim();
|
|
466
|
+
if (type !== undefined && type !== 'client' && type !== 'server')
|
|
467
|
+
return usage('--type must be client or server');
|
|
468
|
+
const namespace = opts.namespace?.trim();
|
|
469
|
+
if (namespace !== undefined && !experimentClient_1.EXPERIMENT_NAMESPACE_PATTERN.test(namespace)) {
|
|
470
|
+
return usage('--namespace must match ^[a-z][a-z0-9_]{1,31}$');
|
|
471
|
+
}
|
|
472
|
+
const layer = opts.layer?.trim();
|
|
473
|
+
if (layer !== undefined) {
|
|
474
|
+
const valid = validLayerKey(layer, '--layer');
|
|
475
|
+
if (isOutcome(valid))
|
|
476
|
+
return valid;
|
|
477
|
+
}
|
|
478
|
+
const days = parseBoundedInt(opts.days, '--days', 1, 180);
|
|
479
|
+
if (isOutcome(days))
|
|
480
|
+
return days;
|
|
481
|
+
const audience = parseAudience(opts.audience, deps);
|
|
482
|
+
if (isOutcome(audience))
|
|
483
|
+
return audience;
|
|
484
|
+
return {
|
|
485
|
+
key,
|
|
486
|
+
name,
|
|
487
|
+
traffic_bp: traffic,
|
|
488
|
+
variants,
|
|
489
|
+
...(namespace ? { namespace } : {}),
|
|
490
|
+
...(type ? { type } : {}),
|
|
491
|
+
...(layer ? { layer_key: layer } : {}),
|
|
492
|
+
...(days === undefined ? {} : { validity_days: days }),
|
|
493
|
+
...(audience === undefined ? {} : { audience }),
|
|
494
|
+
};
|
|
495
|
+
}
|
|
496
|
+
async function runExperimentCreate(keyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
497
|
+
const key = validExperimentKey(keyRaw);
|
|
498
|
+
if (isOutcome(key))
|
|
499
|
+
return key;
|
|
500
|
+
const body = buildCreateBody(key, opts, deps);
|
|
501
|
+
if (isOutcome(body))
|
|
502
|
+
return body;
|
|
503
|
+
const scope = resolveEnvScope(opts);
|
|
504
|
+
if (isOutcome(scope))
|
|
505
|
+
return scope;
|
|
506
|
+
const ctx = begin(deps, requestId);
|
|
507
|
+
if (isOutcome(ctx))
|
|
508
|
+
return ctx;
|
|
509
|
+
const outcome = await ctx.client.create(ctx.token, scope, body);
|
|
510
|
+
if (outcome.kind !== 'success')
|
|
511
|
+
return handleFailure(outcome, ctx.auth, deps, 'create', key);
|
|
512
|
+
return ok(withScope(scope, { experiment: outcome.data }), `created draft\n${experimentSummary(outcome.data)}`);
|
|
513
|
+
}
|
|
514
|
+
function currentVariants(detail) {
|
|
515
|
+
const variants = asRecord(detail)?.variants;
|
|
516
|
+
if (!Array.isArray(variants))
|
|
517
|
+
return undefined;
|
|
518
|
+
const out = [];
|
|
519
|
+
for (const raw of variants) {
|
|
520
|
+
const variant = asRecord(raw);
|
|
521
|
+
if (!variant || typeof variant.key !== 'string' || typeof variant.weight_bp !== 'number')
|
|
522
|
+
return undefined;
|
|
523
|
+
out.push({
|
|
524
|
+
key: variant.key,
|
|
525
|
+
weight_bp: variant.weight_bp,
|
|
526
|
+
...(typeof variant.name === 'string' ? { name: variant.name } : {}),
|
|
527
|
+
payload: variant.payload ?? {},
|
|
528
|
+
});
|
|
529
|
+
}
|
|
530
|
+
return out;
|
|
531
|
+
}
|
|
532
|
+
async function runExperimentUpdate(keyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
533
|
+
const key = validExperimentKey(keyRaw);
|
|
534
|
+
if (isOutcome(key))
|
|
535
|
+
return key;
|
|
536
|
+
const version = parseExpectedVersion(opts.expectedVersion);
|
|
537
|
+
if (isOutcome(version))
|
|
538
|
+
return version;
|
|
539
|
+
const body = { expected_version: version };
|
|
540
|
+
if (opts.name !== undefined) {
|
|
541
|
+
const name = opts.name.trim();
|
|
542
|
+
if (!name)
|
|
543
|
+
return usage('--name must not be empty');
|
|
544
|
+
body.name = name;
|
|
545
|
+
}
|
|
546
|
+
if (opts.traffic !== undefined) {
|
|
547
|
+
const traffic = percentToBasisPoints(opts.traffic, '--traffic');
|
|
548
|
+
if (isOutcome(traffic))
|
|
549
|
+
return traffic;
|
|
550
|
+
body.traffic_bp = traffic;
|
|
551
|
+
}
|
|
552
|
+
const days = parseBoundedInt(opts.days, '--days', 1, 180);
|
|
553
|
+
if (isOutcome(days))
|
|
554
|
+
return days;
|
|
555
|
+
if (days !== undefined)
|
|
556
|
+
body.validity_days = days;
|
|
557
|
+
const audience = parseAudience(opts.audience, deps);
|
|
558
|
+
if (isOutcome(audience))
|
|
559
|
+
return audience;
|
|
560
|
+
if (audience !== undefined)
|
|
561
|
+
body.audience = audience;
|
|
562
|
+
if (opts.layer !== undefined && opts.dedicatedLayer === true) {
|
|
563
|
+
return usage('choose either --layer <key> or --dedicated-layer, not both');
|
|
564
|
+
}
|
|
565
|
+
if (opts.layer !== undefined) {
|
|
566
|
+
const layer = validLayerKey(opts.layer, '--layer');
|
|
567
|
+
if (isOutcome(layer))
|
|
568
|
+
return layer;
|
|
569
|
+
body.layer_key = layer;
|
|
570
|
+
}
|
|
571
|
+
else if (opts.dedicatedLayer === true) {
|
|
572
|
+
body.layer_key = null;
|
|
573
|
+
}
|
|
574
|
+
if (opts.namespace !== undefined) {
|
|
575
|
+
const namespace = opts.namespace.trim();
|
|
576
|
+
if (!experimentClient_1.EXPERIMENT_NAMESPACE_PATTERN.test(namespace))
|
|
577
|
+
return usage('--namespace must match ^[a-z][a-z0-9_]{1,31}$');
|
|
578
|
+
body.namespace = namespace;
|
|
579
|
+
}
|
|
580
|
+
const payloads = parsePayloads(opts.payload, deps);
|
|
581
|
+
if (isOutcome(payloads))
|
|
582
|
+
return payloads;
|
|
583
|
+
let variants;
|
|
584
|
+
if ((opts.variant ?? []).length > 0) {
|
|
585
|
+
const parsed = parseVariants(opts.variant);
|
|
586
|
+
if (isOutcome(parsed))
|
|
587
|
+
return parsed;
|
|
588
|
+
variants = parsed;
|
|
589
|
+
}
|
|
590
|
+
if (Object.keys(body).length === 1 && !variants && payloads.size === 0) {
|
|
591
|
+
return usage('nothing to update — pass at least one of --name, --traffic, --variant, --payload, --days, --audience, --layer, --dedicated-layer, --namespace');
|
|
592
|
+
}
|
|
593
|
+
const scope = resolveEnvScope(opts);
|
|
594
|
+
if (isOutcome(scope))
|
|
595
|
+
return scope;
|
|
596
|
+
const ctx = begin(deps, requestId);
|
|
597
|
+
if (isOutcome(ctx))
|
|
598
|
+
return ctx;
|
|
599
|
+
if (!variants && payloads.size > 0) {
|
|
600
|
+
// Payload-only edit: the server takes the full variant list (set, order, names and
|
|
601
|
+
// weights unchanged while running), so start from the current detail.
|
|
602
|
+
const detail = await ctx.client.get({ token: ctx.auth.token }, scope, key);
|
|
603
|
+
if (detail.kind !== 'success')
|
|
604
|
+
return handleFailure(detail, ctx.auth, deps, 'update', key);
|
|
605
|
+
variants = currentVariants(detail.data);
|
|
606
|
+
if (!variants)
|
|
607
|
+
return { ok: false, kind: 'infra_error', message: 'experiment detail returned no usable variants' };
|
|
608
|
+
}
|
|
609
|
+
if (variants) {
|
|
610
|
+
const merged = applyPayloads(variants, payloads);
|
|
611
|
+
if (isOutcome(merged))
|
|
612
|
+
return merged;
|
|
613
|
+
body.variants = merged;
|
|
614
|
+
}
|
|
615
|
+
const outcome = await ctx.client.patch(ctx.token, scope, key, body);
|
|
616
|
+
if (outcome.kind !== 'success')
|
|
617
|
+
return handleFailure(outcome, ctx.auth, deps, 'update', key);
|
|
618
|
+
return ok(withScope(scope, { experiment: outcome.data }), `updated\n${experimentSummary(outcome.data)}`);
|
|
619
|
+
}
|
|
620
|
+
async function runExperimentTraffic(keyRaw, percent, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
621
|
+
const traffic = percentToBasisPoints(percent, 'traffic percent');
|
|
622
|
+
if (isOutcome(traffic))
|
|
623
|
+
return traffic;
|
|
624
|
+
const key = validExperimentKey(keyRaw);
|
|
625
|
+
if (isOutcome(key))
|
|
626
|
+
return key;
|
|
627
|
+
const version = parseExpectedVersion(opts.expectedVersion);
|
|
628
|
+
if (isOutcome(version))
|
|
629
|
+
return version;
|
|
630
|
+
const scope = resolveEnvScope(opts);
|
|
631
|
+
if (isOutcome(scope))
|
|
632
|
+
return scope;
|
|
633
|
+
const ctx = begin(deps, requestId);
|
|
634
|
+
if (isOutcome(ctx))
|
|
635
|
+
return ctx;
|
|
636
|
+
const outcome = await ctx.client.patch(ctx.token, scope, key, { expected_version: version, traffic_bp: traffic });
|
|
637
|
+
if (outcome.kind !== 'success')
|
|
638
|
+
return handleFailure(outcome, ctx.auth, deps, 'traffic', key);
|
|
639
|
+
return ok(withScope(scope, { experiment: outcome.data }), `traffic set to ${pct(traffic)}\n${experimentSummary(outcome.data)}`);
|
|
640
|
+
}
|
|
641
|
+
function actionBody(action, opts, deps) {
|
|
642
|
+
switch (action) {
|
|
643
|
+
case 'extend': {
|
|
644
|
+
const days = parseBoundedInt(opts.days, '--days', 1, 60);
|
|
645
|
+
if (isOutcome(days))
|
|
646
|
+
return days;
|
|
647
|
+
if (days === undefined)
|
|
648
|
+
return usage('--days is required (1-60)');
|
|
649
|
+
return { days };
|
|
650
|
+
}
|
|
651
|
+
case 'rollout': {
|
|
652
|
+
const variant = typeof opts.variant === 'string' ? opts.variant.trim() : '';
|
|
653
|
+
if (!experimentClient_1.EXPERIMENT_VARIANT_KEY_PATTERN.test(variant))
|
|
654
|
+
return usage('--variant <variantKey> is required');
|
|
655
|
+
return { variant };
|
|
656
|
+
}
|
|
657
|
+
case 'reopen': {
|
|
658
|
+
const mode = opts.mode?.trim();
|
|
659
|
+
if (mode !== 'continue' && mode !== 'new-run')
|
|
660
|
+
return usage('--mode must be continue or new-run');
|
|
661
|
+
const body = { mode: mode === 'new-run' ? 'new_run' : 'continue' };
|
|
662
|
+
if (opts.traffic !== undefined) {
|
|
663
|
+
const traffic = percentToBasisPoints(opts.traffic, '--traffic');
|
|
664
|
+
if (isOutcome(traffic))
|
|
665
|
+
return traffic;
|
|
666
|
+
body.traffic_bp = traffic;
|
|
667
|
+
}
|
|
668
|
+
const list = Array.isArray(opts.variant) ? opts.variant : [];
|
|
669
|
+
const payloads = parsePayloads(opts.payload, deps);
|
|
670
|
+
if (isOutcome(payloads))
|
|
671
|
+
return payloads;
|
|
672
|
+
if (list.length > 0) {
|
|
673
|
+
const variants = parseVariants(list);
|
|
674
|
+
if (isOutcome(variants))
|
|
675
|
+
return variants;
|
|
676
|
+
const merged = applyPayloads(variants, payloads);
|
|
677
|
+
if (isOutcome(merged))
|
|
678
|
+
return merged;
|
|
679
|
+
body.variants = merged;
|
|
680
|
+
}
|
|
681
|
+
else if (payloads.size > 0) {
|
|
682
|
+
return usage('--payload on reopen needs --variant (a new run defines its full variant set)');
|
|
683
|
+
}
|
|
684
|
+
return body;
|
|
685
|
+
}
|
|
686
|
+
default:
|
|
687
|
+
return {};
|
|
688
|
+
}
|
|
689
|
+
}
|
|
690
|
+
const ACTION_VERB = {
|
|
691
|
+
start: 'started',
|
|
692
|
+
pause: 'paused',
|
|
693
|
+
resume: 'resumed',
|
|
694
|
+
end: 'ended',
|
|
695
|
+
extend: 'extended',
|
|
696
|
+
rollout: 'rolled out',
|
|
697
|
+
'emergency-stop': 'emergency-stopped',
|
|
698
|
+
reopen: 'reopened',
|
|
699
|
+
archive: 'archived',
|
|
700
|
+
};
|
|
701
|
+
async function runExperimentAction(action, keyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
702
|
+
if (action === 'emergency-stop' && opts.emergency !== true) {
|
|
703
|
+
return usage('`experiment stop` requires --emergency (stops serving every variant immediately); use `experiment pause` to pause or `experiment end` to finish normally');
|
|
704
|
+
}
|
|
705
|
+
const key = validExperimentKey(keyRaw);
|
|
706
|
+
if (isOutcome(key))
|
|
707
|
+
return key;
|
|
708
|
+
const version = parseExpectedVersion(opts.expectedVersion);
|
|
709
|
+
if (isOutcome(version))
|
|
710
|
+
return version;
|
|
711
|
+
const extra = actionBody(action, opts, deps);
|
|
712
|
+
if (isOutcome(extra))
|
|
713
|
+
return extra;
|
|
714
|
+
const scope = resolveEnvScope(opts);
|
|
715
|
+
if (isOutcome(scope))
|
|
716
|
+
return scope;
|
|
717
|
+
const ctx = begin(deps, requestId);
|
|
718
|
+
if (isOutcome(ctx))
|
|
719
|
+
return ctx;
|
|
720
|
+
const outcome = await ctx.client.action(ctx.token, scope, key, action, { expected_version: version, ...extra });
|
|
721
|
+
const label = action === 'emergency-stop' ? 'stop' : action;
|
|
722
|
+
if (outcome.kind !== 'success')
|
|
723
|
+
return handleFailure(outcome, ctx.auth, deps, label, key);
|
|
724
|
+
return ok(withScope(scope, { experiment: outcome.data }), `${ACTION_VERB[action]}\n${experimentSummary(outcome.data)}`);
|
|
725
|
+
}
|
|
726
|
+
async function runExperimentHistory(keyRaw, opts, deps = exports.defaultExperimentDeps) {
|
|
727
|
+
const key = validExperimentKey(keyRaw);
|
|
728
|
+
if (isOutcome(key))
|
|
729
|
+
return key;
|
|
730
|
+
const scope = resolveEnvScope(opts);
|
|
731
|
+
if (isOutcome(scope))
|
|
732
|
+
return scope;
|
|
733
|
+
const ctx = begin(deps);
|
|
734
|
+
if (isOutcome(ctx))
|
|
735
|
+
return ctx;
|
|
736
|
+
const collected = await collectPages((page) => ctx.client.history(ctx.token, scope, key, page, experimentClient_1.EXPERIMENT_PAGE_SIZE_MAX));
|
|
737
|
+
if (collected.kind === 'error')
|
|
738
|
+
return handleFailure(collected.outcome, ctx.auth, deps, 'history', key);
|
|
739
|
+
const lines = collected.items.map((raw) => {
|
|
740
|
+
const entry = asRecord(raw) ?? {};
|
|
741
|
+
const actor = asRecord(entry.actor);
|
|
742
|
+
return `${str(entry.created_at)}\tv${str(entry.version)}\t${str(entry.action)}\t${str(entry.channel)}\t${str(actor?.email ?? actor?.user_id)}`;
|
|
743
|
+
});
|
|
744
|
+
if (collected.truncated)
|
|
745
|
+
lines.push(`truncated after ${exports.EXPERIMENT_LIST_MAX_PAGES} pages`);
|
|
746
|
+
return ok(withScope(scope, { key, history: collected.items, total: collected.total, ...(collected.truncated ? { truncated: true } : {}) }), lines.join('\n') || 'no history');
|
|
747
|
+
}
|
|
748
|
+
// ── overrides ────────────────────────────────────────────────────────────────────────────
|
|
749
|
+
async function runExperimentOverridesGet(keyRaw, opts, deps = exports.defaultExperimentDeps) {
|
|
750
|
+
const key = validExperimentKey(keyRaw);
|
|
751
|
+
if (isOutcome(key))
|
|
752
|
+
return key;
|
|
753
|
+
const scope = resolveEnvScope(opts);
|
|
754
|
+
if (isOutcome(scope))
|
|
755
|
+
return scope;
|
|
756
|
+
const ctx = begin(deps);
|
|
757
|
+
if (isOutcome(ctx))
|
|
758
|
+
return ctx;
|
|
759
|
+
const outcome = await ctx.client.getOverrides(ctx.token, scope, key);
|
|
760
|
+
if (outcome.kind !== 'success')
|
|
761
|
+
return handleFailure(outcome, ctx.auth, deps, 'overrides get', key);
|
|
762
|
+
const data = asRecord(outcome.data);
|
|
763
|
+
const rows = Array.isArray(data?.overrides) ? data.overrides : [];
|
|
764
|
+
const lines = [`version ${str(data?.version)} · ${rows.length} override(s)`];
|
|
765
|
+
for (const raw of rows) {
|
|
766
|
+
const row = asRecord(raw) ?? {};
|
|
767
|
+
lines.push(` ${str(row.device_id)} → ${str(row.variant_key)}`);
|
|
768
|
+
}
|
|
769
|
+
return ok(withScope(scope, { key, overrides: outcome.data }), lines.join('\n'));
|
|
770
|
+
}
|
|
771
|
+
function parseOverrideDevices(raw) {
|
|
772
|
+
const out = [];
|
|
773
|
+
for (const item of raw ?? []) {
|
|
774
|
+
// Variant keys never contain `=`; device ids might — split at the LAST `=`.
|
|
775
|
+
const eq = item.lastIndexOf('=');
|
|
776
|
+
if (eq <= 0)
|
|
777
|
+
return usage('--device must be <deviceId>=<variantKey>');
|
|
778
|
+
const deviceId = item.slice(0, eq).trim();
|
|
779
|
+
const variantKey = item.slice(eq + 1).trim();
|
|
780
|
+
if (!deviceId)
|
|
781
|
+
return usage('--device needs a non-empty device id');
|
|
782
|
+
if (!experimentClient_1.EXPERIMENT_VARIANT_KEY_PATTERN.test(variantKey)) {
|
|
783
|
+
return usage(`--device ${JSON.stringify(item)}: variant key must match ^[a-z][a-z0-9_]{0,19}$`);
|
|
784
|
+
}
|
|
785
|
+
if (out.some((row) => row.device_id === deviceId))
|
|
786
|
+
return usage(`duplicate --device ${deviceId}`);
|
|
787
|
+
out.push({ device_id: deviceId, variant_key: variantKey });
|
|
788
|
+
}
|
|
789
|
+
return out;
|
|
790
|
+
}
|
|
791
|
+
async function runExperimentOverridesSet(keyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
792
|
+
const key = validExperimentKey(keyRaw);
|
|
793
|
+
if (isOutcome(key))
|
|
794
|
+
return key;
|
|
795
|
+
const version = parseExpectedVersion(opts.expectedVersion);
|
|
796
|
+
if (isOutcome(version))
|
|
797
|
+
return version;
|
|
798
|
+
const devices = parseOverrideDevices(opts.device);
|
|
799
|
+
if (isOutcome(devices))
|
|
800
|
+
return devices;
|
|
801
|
+
if (opts.clear === true && devices.length > 0)
|
|
802
|
+
return usage('choose either --device … or --clear, not both');
|
|
803
|
+
if (opts.clear !== true && devices.length === 0) {
|
|
804
|
+
return usage('pass --device <deviceId>=<variantKey> (repeatable; replaces the whole list) or --clear');
|
|
805
|
+
}
|
|
806
|
+
const scope = resolveEnvScope(opts);
|
|
807
|
+
if (isOutcome(scope))
|
|
808
|
+
return scope;
|
|
809
|
+
const ctx = begin(deps, requestId);
|
|
810
|
+
if (isOutcome(ctx))
|
|
811
|
+
return ctx;
|
|
812
|
+
const outcome = await ctx.client.putOverrides(ctx.token, scope, key, { expected_version: version, overrides: devices });
|
|
813
|
+
if (outcome.kind !== 'success')
|
|
814
|
+
return handleFailure(outcome, ctx.auth, deps, 'overrides set', key);
|
|
815
|
+
const data = asRecord(outcome.data);
|
|
816
|
+
const count = Array.isArray(data?.overrides) ? data.overrides.length : devices.length;
|
|
817
|
+
return ok(withScope(scope, { key, overrides: outcome.data }), `overrides replaced: ${count} device(s) · version ${str(data?.version)}`);
|
|
818
|
+
}
|
|
819
|
+
// ── metrics ──────────────────────────────────────────────────────────────────────────────
|
|
820
|
+
async function runExperimentMetricsList(keyRaw, opts, deps = exports.defaultExperimentDeps) {
|
|
821
|
+
const key = validExperimentKey(keyRaw);
|
|
822
|
+
if (isOutcome(key))
|
|
823
|
+
return key;
|
|
824
|
+
const scope = resolveEnvScope(opts);
|
|
825
|
+
if (isOutcome(scope))
|
|
826
|
+
return scope;
|
|
827
|
+
const ctx = begin(deps);
|
|
828
|
+
if (isOutcome(ctx))
|
|
829
|
+
return ctx;
|
|
830
|
+
const outcome = await ctx.client.listMetrics(ctx.token, scope, key);
|
|
831
|
+
if (outcome.kind !== 'success')
|
|
832
|
+
return handleFailure(outcome, ctx.auth, deps, 'metrics list', key);
|
|
833
|
+
return ok(withScope(scope, { key, metrics: asRecord(outcome.data)?.metrics ?? outcome.data }), metricsSummary(outcome.data));
|
|
834
|
+
}
|
|
835
|
+
function metricsSummary(data) {
|
|
836
|
+
const metrics = asRecord(data)?.metrics;
|
|
837
|
+
if (!Array.isArray(metrics))
|
|
838
|
+
return JSON.stringify(data, null, 2);
|
|
839
|
+
if (metrics.length === 0)
|
|
840
|
+
return 'no metrics';
|
|
841
|
+
return metrics.map((raw) => {
|
|
842
|
+
const metric = asRecord(raw) ?? {};
|
|
843
|
+
const core = metric.is_core === true ? ' core' : '';
|
|
844
|
+
const tolerance = typeof metric.tolerance_pct === 'number' ? ` tolerance ${metric.tolerance_pct}%` : '';
|
|
845
|
+
return `${str(metric.metric_key)}\t${str(metric.role)}${core}\t${str(metric.kind)}\t${str(metric.event_name)}\t${str(metric.direction)}${tolerance}`;
|
|
846
|
+
}).join('\n');
|
|
847
|
+
}
|
|
848
|
+
function pickEnum(raw, allowed, flag) {
|
|
849
|
+
if (raw === undefined)
|
|
850
|
+
return undefined;
|
|
851
|
+
const value = raw.trim();
|
|
852
|
+
if (!allowed.includes(value))
|
|
853
|
+
return usage(`${flag} must be one of ${allowed.join(', ')}`);
|
|
854
|
+
return value;
|
|
855
|
+
}
|
|
856
|
+
function buildMetricInput(opts, deps) {
|
|
857
|
+
const kind = pickEnum(opts.kind, METRIC_KINDS, '--kind');
|
|
858
|
+
if (isOutcome(kind))
|
|
859
|
+
return kind;
|
|
860
|
+
if (!kind)
|
|
861
|
+
return usage(`--kind is required (${METRIC_KINDS.join(', ')})`);
|
|
862
|
+
const event = opts.event?.trim();
|
|
863
|
+
if (!event)
|
|
864
|
+
return usage('--event is required');
|
|
865
|
+
const role = pickEnum(opts.role, METRIC_ROLES, '--role');
|
|
866
|
+
if (isOutcome(role))
|
|
867
|
+
return role;
|
|
868
|
+
const direction = pickEnum(opts.direction, METRIC_DIRECTIONS, '--direction');
|
|
869
|
+
if (isOutcome(direction))
|
|
870
|
+
return direction;
|
|
871
|
+
const metric = { kind, event_name: event };
|
|
872
|
+
if (opts.metricKey !== undefined) {
|
|
873
|
+
const metricKey = validExperimentKey(opts.metricKey, '--metric-key');
|
|
874
|
+
if (isOutcome(metricKey))
|
|
875
|
+
return metricKey;
|
|
876
|
+
metric.metric_key = metricKey;
|
|
877
|
+
}
|
|
878
|
+
if (role)
|
|
879
|
+
metric.role = role;
|
|
880
|
+
if (opts.core === true)
|
|
881
|
+
metric.is_core = true;
|
|
882
|
+
if (direction)
|
|
883
|
+
metric.direction = direction;
|
|
884
|
+
if (opts.tolerance !== undefined) {
|
|
885
|
+
const tolerance = Number(opts.tolerance.trim());
|
|
886
|
+
if (!/^\d+(?:\.\d+)?$/.test(opts.tolerance.trim()) || !Number.isFinite(tolerance)) {
|
|
887
|
+
return usage('--tolerance must be a non-negative percentage, e.g. 5 or 2.5');
|
|
888
|
+
}
|
|
889
|
+
metric.tolerance_pct = tolerance;
|
|
890
|
+
}
|
|
891
|
+
const window = parseBoundedInt(opts.windowDays, '--window-days', 1, 60);
|
|
892
|
+
if (isOutcome(window))
|
|
893
|
+
return window;
|
|
894
|
+
if (window !== undefined)
|
|
895
|
+
metric.window_days = window;
|
|
896
|
+
const retentionDay = parseBoundedInt(opts.retentionDay, '--retention-day', 1, 30);
|
|
897
|
+
if (isOutcome(retentionDay))
|
|
898
|
+
return retentionDay;
|
|
899
|
+
if (retentionDay !== undefined)
|
|
900
|
+
metric.retention_day = retentionDay;
|
|
901
|
+
if (kind === 'retention' && retentionDay === undefined)
|
|
902
|
+
return usage('--retention-day is required for --kind retention (1-30)');
|
|
903
|
+
const percentile = parseBoundedInt(opts.percentile, '--percentile', 1, 99);
|
|
904
|
+
if (isOutcome(percentile))
|
|
905
|
+
return percentile;
|
|
906
|
+
if (percentile !== undefined)
|
|
907
|
+
metric.percentile = percentile;
|
|
908
|
+
if (opts.property !== undefined) {
|
|
909
|
+
const name = opts.property.trim();
|
|
910
|
+
const valueType = opts.propertyType?.trim() ?? 'float';
|
|
911
|
+
if (!name)
|
|
912
|
+
return usage('--property must name a numeric event property');
|
|
913
|
+
if (valueType !== 'int' && valueType !== 'float')
|
|
914
|
+
return usage('--property-type must be int or float');
|
|
915
|
+
metric.property = { name, value_type: valueType };
|
|
916
|
+
}
|
|
917
|
+
if ((kind === 'sum' || kind === 'avg' || kind === 'pct') && metric.property === undefined) {
|
|
918
|
+
return usage(`--property is required for --kind ${kind}`);
|
|
919
|
+
}
|
|
920
|
+
if (opts.filters !== undefined) {
|
|
921
|
+
const filters = readJsonSource(opts.filters, '--filters', deps);
|
|
922
|
+
if (isOutcome(filters))
|
|
923
|
+
return filters;
|
|
924
|
+
if (!Array.isArray(filters.value))
|
|
925
|
+
return usage('--filters must be a JSON array of {name, value_type, operator, values}');
|
|
926
|
+
metric.filters = filters.value;
|
|
927
|
+
}
|
|
928
|
+
return metric;
|
|
929
|
+
}
|
|
930
|
+
async function runExperimentMetricsAdd(keyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
931
|
+
const key = validExperimentKey(keyRaw);
|
|
932
|
+
if (isOutcome(key))
|
|
933
|
+
return key;
|
|
934
|
+
const metric = buildMetricInput(opts, deps);
|
|
935
|
+
if (isOutcome(metric))
|
|
936
|
+
return metric;
|
|
937
|
+
const scope = resolveEnvScope(opts);
|
|
938
|
+
if (isOutcome(scope))
|
|
939
|
+
return scope;
|
|
940
|
+
const ctx = begin(deps, requestId);
|
|
941
|
+
if (isOutcome(ctx))
|
|
942
|
+
return ctx;
|
|
943
|
+
const outcome = await ctx.client.addMetrics(ctx.token, scope, key, { metrics: [metric] });
|
|
944
|
+
if (outcome.kind !== 'success')
|
|
945
|
+
return handleFailure(outcome, ctx.auth, deps, 'metrics add', key);
|
|
946
|
+
return ok(withScope(scope, { key, metrics: asRecord(outcome.data)?.metrics ?? outcome.data }), metricsSummary(outcome.data));
|
|
947
|
+
}
|
|
948
|
+
async function runExperimentMetricsRemove(keyRaw, metricKeyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
949
|
+
const key = validExperimentKey(keyRaw);
|
|
950
|
+
if (isOutcome(key))
|
|
951
|
+
return key;
|
|
952
|
+
const metricKey = metricKeyRaw?.trim() ?? '';
|
|
953
|
+
if (!experimentClient_1.EXPERIMENT_METRIC_KEY_PATTERN.test(metricKey))
|
|
954
|
+
return usage('metric key must match ^[a-z][a-z0-9_]{1,39}$');
|
|
955
|
+
const scope = resolveEnvScope(opts);
|
|
956
|
+
if (isOutcome(scope))
|
|
957
|
+
return scope;
|
|
958
|
+
const ctx = begin(deps, requestId);
|
|
959
|
+
if (isOutcome(ctx))
|
|
960
|
+
return ctx;
|
|
961
|
+
const outcome = await ctx.client.removeMetric(ctx.token, scope, key, metricKey);
|
|
962
|
+
if (outcome.kind !== 'success')
|
|
963
|
+
return handleFailure(outcome, ctx.auth, deps, 'metrics remove', key);
|
|
964
|
+
return ok(withScope(scope, { key, removed: metricKey, metrics: asRecord(outcome.data)?.metrics ?? outcome.data }), `removed ${metricKey}\n${metricsSummary(outcome.data)}`);
|
|
965
|
+
}
|
|
966
|
+
async function runExperimentResults(keyRaw, opts, deps = exports.defaultExperimentDeps) {
|
|
967
|
+
const key = validExperimentKey(keyRaw);
|
|
968
|
+
if (isOutcome(key))
|
|
969
|
+
return key;
|
|
970
|
+
const scope = resolveEnvScope(opts);
|
|
971
|
+
if (isOutcome(scope))
|
|
972
|
+
return scope;
|
|
973
|
+
const ctx = begin(deps);
|
|
974
|
+
if (isOutcome(ctx))
|
|
975
|
+
return ctx;
|
|
976
|
+
const query = {
|
|
977
|
+
...(opts.timeZone?.trim() ? { time_zone: opts.timeZone.trim() } : {}),
|
|
978
|
+
...(opts.refresh === true ? { refresh: '1' } : {}),
|
|
979
|
+
};
|
|
980
|
+
const outcome = await ctx.client.results(ctx.token, scope, key, query);
|
|
981
|
+
if (outcome.kind !== 'success')
|
|
982
|
+
return handleFailure(outcome, ctx.auth, deps, 'results', key);
|
|
983
|
+
return ok(withScope(scope, { key, results: outcome.data }), JSON.stringify(outcome.data, null, 2));
|
|
984
|
+
}
|
|
985
|
+
async function runExperimentLookup(opts, deps = exports.defaultExperimentDeps) {
|
|
986
|
+
const device = opts.device?.trim();
|
|
987
|
+
const user = opts.user?.trim();
|
|
988
|
+
if ((device ? 1 : 0) + (user ? 1 : 0) !== 1)
|
|
989
|
+
return usage('pass exactly one of --device <id> or --user <id>');
|
|
990
|
+
const query = device ? { device_id: device } : { user_id: user };
|
|
991
|
+
for (const raw of opts.attr ?? []) {
|
|
992
|
+
const eq = raw.indexOf('=');
|
|
993
|
+
const name = eq > 0 ? raw.slice(0, eq).trim() : '';
|
|
994
|
+
if (!/^[A-Za-z0-9_]+$/.test(name))
|
|
995
|
+
return usage('--attr must be <name>=<value> with a name of letters, digits or underscores');
|
|
996
|
+
query[`attr.${name}`] = raw.slice(eq + 1);
|
|
997
|
+
}
|
|
998
|
+
const scope = resolveEnvScope(opts);
|
|
999
|
+
if (isOutcome(scope))
|
|
1000
|
+
return scope;
|
|
1001
|
+
const ctx = begin(deps);
|
|
1002
|
+
if (isOutcome(ctx))
|
|
1003
|
+
return ctx;
|
|
1004
|
+
const outcome = await ctx.client.lookup(ctx.token, scope, query);
|
|
1005
|
+
if (outcome.kind !== 'success')
|
|
1006
|
+
return handleFailure(outcome, ctx.auth, deps, 'lookup');
|
|
1007
|
+
return ok(withScope(scope, { lookup: outcome.data }), JSON.stringify(outcome.data, null, 2));
|
|
1008
|
+
}
|
|
1009
|
+
async function runExperimentVids(opts, deps = exports.defaultExperimentDeps) {
|
|
1010
|
+
const scope = resolveEnvScope(opts);
|
|
1011
|
+
if (isOutcome(scope))
|
|
1012
|
+
return scope;
|
|
1013
|
+
const ctx = begin(deps);
|
|
1014
|
+
if (isOutcome(ctx))
|
|
1015
|
+
return ctx;
|
|
1016
|
+
const outcome = await ctx.client.vids(ctx.token, scope);
|
|
1017
|
+
if (outcome.kind !== 'success')
|
|
1018
|
+
return handleFailure(outcome, ctx.auth, deps, 'vids');
|
|
1019
|
+
const rows = Array.isArray(outcome.data) ? outcome.data : [];
|
|
1020
|
+
const lines = rows.map((raw) => {
|
|
1021
|
+
const row = asRecord(raw) ?? {};
|
|
1022
|
+
return `${str(row.vid)}\t${str(row.key)}\trun ${str(row.run)}\t${str(row.variant)}\t${str(row.type)}`;
|
|
1023
|
+
});
|
|
1024
|
+
return ok(withScope(scope, { vids: outcome.data }), lines.join('\n') || 'no experiment variants');
|
|
1025
|
+
}
|
|
1026
|
+
// ── layers (S3 · layers.rs) ──────────────────────────────────────────────────────────────
|
|
1027
|
+
function validLayerKey(raw, label = 'layer key') {
|
|
1028
|
+
const key = raw?.trim() ?? '';
|
|
1029
|
+
if (!experimentClient_1.EXPERIMENT_LAYER_KEY_PATTERN.test(key))
|
|
1030
|
+
return usage(`${label} must match ^[a-z][a-z0-9_]{1,31}$`);
|
|
1031
|
+
if (key.startsWith('l_'))
|
|
1032
|
+
return usage(`${label}: keys starting with l_ are reserved for dedicated layers`);
|
|
1033
|
+
return key;
|
|
1034
|
+
}
|
|
1035
|
+
function validDescription(raw, required) {
|
|
1036
|
+
if (raw === undefined)
|
|
1037
|
+
return required ? usage('--description is required') : undefined;
|
|
1038
|
+
const description = raw.trim();
|
|
1039
|
+
if ([...description].length > experimentClient_1.EXPERIMENT_DESCRIPTION_MAX_CHARS) {
|
|
1040
|
+
return usage(`--description must be at most ${experimentClient_1.EXPERIMENT_DESCRIPTION_MAX_CHARS} characters`);
|
|
1041
|
+
}
|
|
1042
|
+
return description;
|
|
1043
|
+
}
|
|
1044
|
+
function layerLine(raw) {
|
|
1045
|
+
const layer = asRecord(raw) ?? {};
|
|
1046
|
+
const experiments = Array.isArray(layer.experiments) ? layer.experiments.length : undefined;
|
|
1047
|
+
return `${str(layer.key)}\tused ${pct(layer.used_bp)}\tfree ${pct(layer.free_bp)}\t${str(experiments)} experiment(s)\t${str(layer.description)}`;
|
|
1048
|
+
}
|
|
1049
|
+
async function runExperimentLayersList(opts, deps = exports.defaultExperimentDeps) {
|
|
1050
|
+
const scope = resolveEnvScope(opts);
|
|
1051
|
+
if (isOutcome(scope))
|
|
1052
|
+
return scope;
|
|
1053
|
+
const ctx = begin(deps);
|
|
1054
|
+
if (isOutcome(ctx))
|
|
1055
|
+
return ctx;
|
|
1056
|
+
const outcome = await ctx.client.listLayers(ctx.token, scope);
|
|
1057
|
+
if (outcome.kind !== 'success')
|
|
1058
|
+
return handleFailure(outcome, ctx.auth, deps, 'layers list');
|
|
1059
|
+
const rows = Array.isArray(outcome.data) ? outcome.data : asRecord(outcome.data)?.list ?? [];
|
|
1060
|
+
const lines = rows.map(layerLine);
|
|
1061
|
+
return ok(withScope(scope, { layers: outcome.data }), lines.join('\n') || 'no shared layers');
|
|
1062
|
+
}
|
|
1063
|
+
async function runExperimentLayersCreate(keyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
1064
|
+
const key = validLayerKey(keyRaw);
|
|
1065
|
+
if (isOutcome(key))
|
|
1066
|
+
return key;
|
|
1067
|
+
const description = validDescription(opts.description, false);
|
|
1068
|
+
if (isOutcome(description))
|
|
1069
|
+
return description;
|
|
1070
|
+
const scope = resolveEnvScope(opts);
|
|
1071
|
+
if (isOutcome(scope))
|
|
1072
|
+
return scope;
|
|
1073
|
+
const ctx = begin(deps, requestId);
|
|
1074
|
+
if (isOutcome(ctx))
|
|
1075
|
+
return ctx;
|
|
1076
|
+
const outcome = await ctx.client.createLayer(ctx.token, scope, { key, ...(description ? { description } : {}) });
|
|
1077
|
+
if (outcome.kind !== 'success')
|
|
1078
|
+
return handleFailure(outcome, ctx.auth, deps, 'layers create');
|
|
1079
|
+
return ok(withScope(scope, { layer: outcome.data }), `created shared layer\n${layerLine(outcome.data)}`);
|
|
1080
|
+
}
|
|
1081
|
+
async function runExperimentLayersUpdate(keyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
1082
|
+
const key = validLayerKey(keyRaw);
|
|
1083
|
+
if (isOutcome(key))
|
|
1084
|
+
return key;
|
|
1085
|
+
const description = validDescription(opts.description, true);
|
|
1086
|
+
if (isOutcome(description))
|
|
1087
|
+
return description;
|
|
1088
|
+
const scope = resolveEnvScope(opts);
|
|
1089
|
+
if (isOutcome(scope))
|
|
1090
|
+
return scope;
|
|
1091
|
+
const ctx = begin(deps, requestId);
|
|
1092
|
+
if (isOutcome(ctx))
|
|
1093
|
+
return ctx;
|
|
1094
|
+
const outcome = await ctx.client.updateLayer(ctx.token, scope, key, { description: description ?? '' });
|
|
1095
|
+
if (outcome.kind !== 'success')
|
|
1096
|
+
return handleFailure(outcome, ctx.auth, deps, 'layers update');
|
|
1097
|
+
return ok(withScope(scope, { layer: outcome.data }), `updated shared layer\n${layerLine(outcome.data)}`);
|
|
1098
|
+
}
|
|
1099
|
+
async function runExperimentLayersDelete(keyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
1100
|
+
const key = validLayerKey(keyRaw);
|
|
1101
|
+
if (isOutcome(key))
|
|
1102
|
+
return key;
|
|
1103
|
+
const scope = resolveEnvScope(opts);
|
|
1104
|
+
if (isOutcome(scope))
|
|
1105
|
+
return scope;
|
|
1106
|
+
const ctx = begin(deps, requestId);
|
|
1107
|
+
if (isOutcome(ctx))
|
|
1108
|
+
return ctx;
|
|
1109
|
+
const outcome = await ctx.client.deleteLayer(ctx.token, scope, key);
|
|
1110
|
+
if (outcome.kind !== 'success')
|
|
1111
|
+
return handleFailure(outcome, ctx.auth, deps, 'layers delete');
|
|
1112
|
+
// S3: DELETE returns the remaining layers array; passed through as `layers`.
|
|
1113
|
+
return ok(withScope(scope, { deleted: true, key, layers: outcome.data }), `deleted shared layer ${key}`);
|
|
1114
|
+
}
|
|
1115
|
+
// ── namespaces (S3 · namespaces.rs · project level) ──────────────────────────────────────
|
|
1116
|
+
function namespaceLine(raw) {
|
|
1117
|
+
const ns = asRecord(raw) ?? {};
|
|
1118
|
+
const byEnv = asRecord(ns.active_by_env);
|
|
1119
|
+
const envs = byEnv && Object.keys(byEnv).length > 0
|
|
1120
|
+
? ` (${Object.entries(byEnv).map(([env, n]) => `${env} ${String(n)}`).join(', ')})`
|
|
1121
|
+
: '';
|
|
1122
|
+
return `${str(ns.name)}\tactive ${str(ns.active)}${envs}\t${str(ns.experiment_count)} experiment(s)\t${str(ns.description)}`;
|
|
1123
|
+
}
|
|
1124
|
+
function validNamespace(raw) {
|
|
1125
|
+
const name = raw?.trim() ?? '';
|
|
1126
|
+
if (!experimentClient_1.EXPERIMENT_NAMESPACE_PATTERN.test(name))
|
|
1127
|
+
return usage('namespace must match ^[a-z][a-z0-9_]{1,31}$');
|
|
1128
|
+
return name;
|
|
1129
|
+
}
|
|
1130
|
+
async function runExperimentNamespacesList(opts, deps = exports.defaultExperimentDeps) {
|
|
1131
|
+
const project = resolveProject(opts);
|
|
1132
|
+
if (isOutcome(project))
|
|
1133
|
+
return project;
|
|
1134
|
+
const ctx = begin(deps);
|
|
1135
|
+
if (isOutcome(ctx))
|
|
1136
|
+
return ctx;
|
|
1137
|
+
const outcome = await ctx.client.listNamespaces(ctx.token, project);
|
|
1138
|
+
if (outcome.kind !== 'success')
|
|
1139
|
+
return handleFailure(outcome, ctx.auth, deps, 'namespaces list');
|
|
1140
|
+
const rows = Array.isArray(outcome.data) ? outcome.data : asRecord(outcome.data)?.list ?? [];
|
|
1141
|
+
const lines = rows.map(namespaceLine);
|
|
1142
|
+
return ok(withScope(project, { namespaces: outcome.data }), lines.join('\n') || 'no namespaces');
|
|
1143
|
+
}
|
|
1144
|
+
async function runExperimentNamespacesCreate(nameRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
1145
|
+
const name = validNamespace(nameRaw);
|
|
1146
|
+
if (isOutcome(name))
|
|
1147
|
+
return name;
|
|
1148
|
+
const description = validDescription(opts.description, false);
|
|
1149
|
+
if (isOutcome(description))
|
|
1150
|
+
return description;
|
|
1151
|
+
const project = resolveProject(opts);
|
|
1152
|
+
if (isOutcome(project))
|
|
1153
|
+
return project;
|
|
1154
|
+
const ctx = begin(deps, requestId);
|
|
1155
|
+
if (isOutcome(ctx))
|
|
1156
|
+
return ctx;
|
|
1157
|
+
const outcome = await ctx.client.createNamespace(ctx.token, project, { name, ...(description ? { description } : {}) });
|
|
1158
|
+
if (outcome.kind !== 'success')
|
|
1159
|
+
return handleFailure(outcome, ctx.auth, deps, 'namespaces create');
|
|
1160
|
+
return ok(withScope(project, { namespace: outcome.data }), `created namespace\n${namespaceLine(outcome.data)}`);
|
|
1161
|
+
}
|
|
1162
|
+
async function runExperimentNamespacesUpdate(nameRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
1163
|
+
const name = validNamespace(nameRaw);
|
|
1164
|
+
if (isOutcome(name))
|
|
1165
|
+
return name;
|
|
1166
|
+
const description = validDescription(opts.description, true);
|
|
1167
|
+
if (isOutcome(description))
|
|
1168
|
+
return description;
|
|
1169
|
+
const project = resolveProject(opts);
|
|
1170
|
+
if (isOutcome(project))
|
|
1171
|
+
return project;
|
|
1172
|
+
const ctx = begin(deps, requestId);
|
|
1173
|
+
if (isOutcome(ctx))
|
|
1174
|
+
return ctx;
|
|
1175
|
+
const outcome = await ctx.client.updateNamespace(ctx.token, project, name, { description: description ?? '' });
|
|
1176
|
+
if (outcome.kind !== 'success')
|
|
1177
|
+
return handleFailure(outcome, ctx.auth, deps, 'namespaces update');
|
|
1178
|
+
return ok(withScope(project, { namespace: outcome.data }), `updated namespace\n${namespaceLine(outcome.data)}`);
|
|
1179
|
+
}
|
|
1180
|
+
async function runExperimentNamespacesDelete(nameRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
1181
|
+
const name = validNamespace(nameRaw);
|
|
1182
|
+
if (isOutcome(name))
|
|
1183
|
+
return name;
|
|
1184
|
+
if (name === 'default')
|
|
1185
|
+
return usage('the default namespace cannot be deleted');
|
|
1186
|
+
const project = resolveProject(opts);
|
|
1187
|
+
if (isOutcome(project))
|
|
1188
|
+
return project;
|
|
1189
|
+
const ctx = begin(deps, requestId);
|
|
1190
|
+
if (isOutcome(ctx))
|
|
1191
|
+
return ctx;
|
|
1192
|
+
const outcome = await ctx.client.deleteNamespace(ctx.token, project, name);
|
|
1193
|
+
if (outcome.kind !== 'success')
|
|
1194
|
+
return handleFailure(outcome, ctx.auth, deps, 'namespaces delete');
|
|
1195
|
+
// S3: DELETE returns the remaining namespaces array; passed through as `namespaces`.
|
|
1196
|
+
return ok(withScope(project, { deleted: true, name, namespaces: outcome.data }), `deleted namespace ${name}`);
|
|
1197
|
+
}
|
|
1198
|
+
// ── registration ─────────────────────────────────────────────────────────────────────────
|
|
1199
|
+
function outputModeOf(cmd) {
|
|
1200
|
+
return cmd.optsWithGlobals?.()?.output === 'json' ? 'json' : 'human';
|
|
1201
|
+
}
|
|
1202
|
+
function collect(value, previous) {
|
|
1203
|
+
return previous.concat(value);
|
|
1204
|
+
}
|
|
1205
|
+
function emitExperimentOutcome(printer, outcome) {
|
|
1206
|
+
if (!outcome.ok && 'result' in outcome) {
|
|
1207
|
+
printer.failure(outcome.kind, outcome.message, { publicCode: outcome.publicCode, result: outcome.result });
|
|
1208
|
+
return;
|
|
1209
|
+
}
|
|
1210
|
+
printer.emit(outcome);
|
|
1211
|
+
}
|
|
1212
|
+
function act(run) {
|
|
1213
|
+
return async (...args) => {
|
|
1214
|
+
const cmd = args[args.length - 1];
|
|
1215
|
+
const printer = new resultPrinter_1.ResultPrinter(outputModeOf(cmd));
|
|
1216
|
+
emitExperimentOutcome(printer, await run(printer, ...args.slice(0, -1)));
|
|
1217
|
+
};
|
|
1218
|
+
}
|
|
1219
|
+
function envLeaf(parent, spec, description) {
|
|
1220
|
+
return parent.command(spec)
|
|
1221
|
+
.description(description)
|
|
1222
|
+
.option('--config <path>', 'explicit super.json path')
|
|
1223
|
+
.requiredOption('--env <env>', 'project environment');
|
|
1224
|
+
}
|
|
1225
|
+
function writeLeaf(parent, spec, description) {
|
|
1226
|
+
return envLeaf(parent, spec, description)
|
|
1227
|
+
.requiredOption('--expected-version <n>', 'the experiment `version` you last read (optimistic concurrency)');
|
|
1228
|
+
}
|
|
1229
|
+
function registerExperimentCommand(program, deps = exports.defaultExperimentDeps) {
|
|
1230
|
+
const experiment = program
|
|
1231
|
+
.command('experiment')
|
|
1232
|
+
.description('Manage A/B experiments in one project environment (lifecycle, overrides, metrics, results).');
|
|
1233
|
+
envLeaf(experiment, 'list', 'List experiments in the environment (all pages).')
|
|
1234
|
+
.option('--status <status>', 'filter: draft | running | paused | completed | rolled_out | archived')
|
|
1235
|
+
.option('--namespace <name>', 'filter by namespace')
|
|
1236
|
+
.option('--q <text>', 'keyword filter on key / name')
|
|
1237
|
+
.action(act((_p, opts) => runExperimentList(opts, deps)));
|
|
1238
|
+
envLeaf(experiment, 'get <key>', 'Show one experiment (variants, traffic, status, version).')
|
|
1239
|
+
.action(act((_p, key, opts) => runExperimentGet(key, opts, deps)));
|
|
1240
|
+
envLeaf(experiment, 'create <key>', 'Create a draft experiment. Percentages are converted to basis points.')
|
|
1241
|
+
.requiredOption('--name <name>', 'display name')
|
|
1242
|
+
.requiredOption('--traffic <percent>', 'share of devices entering the experiment, 0-100')
|
|
1243
|
+
.option('--variant <key:weight[:name]>', 'one variant; weights are percentages summing to 100 (repeat 2-10 times)', collect, [])
|
|
1244
|
+
.option('--payload <variantKey=json|@file>', 'JSON object payload for one variant (repeatable)', collect, [])
|
|
1245
|
+
.option('--namespace <name>', 'namespace (default: default)')
|
|
1246
|
+
.option('--type <type>', 'client (default) or server')
|
|
1247
|
+
.option('--layer <key>', 'shared layer key for mutually exclusive experiments (default: a dedicated layer)')
|
|
1248
|
+
.option('--days <n>', 'validity in days, 1-180 (default 60)')
|
|
1249
|
+
.option('--audience <json|@file>', 'JSON array of audience conditions {attr, op, value}')
|
|
1250
|
+
.action(act((printer, key, opts) => runExperimentCreate(key, opts, printer.requestId, deps)));
|
|
1251
|
+
writeLeaf(experiment, 'update <key>', 'Edit a draft, or the fields a running/paused experiment allows (name, traffic, payloads, audience).')
|
|
1252
|
+
.option('--name <name>', 'new display name')
|
|
1253
|
+
.option('--traffic <percent>', 'new traffic percentage, 0-100')
|
|
1254
|
+
.option('--variant <key:weight[:name]>', 'replace the variant set (draft only; repeat 2-10 times)', collect, [])
|
|
1255
|
+
.option('--payload <variantKey=json|@file>', 'replace one variant payload (repeatable)', collect, [])
|
|
1256
|
+
.option('--days <n>', 'validity in days, 1-180 (draft only; use extend afterwards)')
|
|
1257
|
+
.option('--audience <json|@file>', 'replace audience conditions (JSON array)')
|
|
1258
|
+
.option('--layer <key>', 'move the draft to a shared layer (draft only)')
|
|
1259
|
+
.option('--dedicated-layer', 'move the draft back to its own dedicated layer (draft only)')
|
|
1260
|
+
.option('--namespace <name>', 'move the draft to another registered namespace (draft only)')
|
|
1261
|
+
.action(act((printer, key, opts) => runExperimentUpdate(key, opts, printer.requestId, deps)));
|
|
1262
|
+
for (const [name, description] of [
|
|
1263
|
+
['start', 'Start a draft experiment.'],
|
|
1264
|
+
['pause', 'Pause a running experiment (devices fall back to the default).'],
|
|
1265
|
+
['resume', 'Resume a paused experiment.'],
|
|
1266
|
+
['end', 'End an experiment normally (releases its traffic).'],
|
|
1267
|
+
['archive', 'Archive a completed or rolled-out experiment.'],
|
|
1268
|
+
]) {
|
|
1269
|
+
writeLeaf(experiment, `${name} <key>`, description)
|
|
1270
|
+
.action(act((printer, key, opts) => runExperimentAction(name, key, opts, printer.requestId, deps)));
|
|
1271
|
+
}
|
|
1272
|
+
writeLeaf(experiment, 'traffic <key> <percent>', 'Change the traffic percentage (0-100).')
|
|
1273
|
+
.action(act((printer, key, percent, opts) => runExperimentTraffic(key, percent, opts, printer.requestId, deps)));
|
|
1274
|
+
writeLeaf(experiment, 'extend <key>', 'Extend the validity of a running or paused experiment.')
|
|
1275
|
+
.requiredOption('--days <n>', 'days to add, 1-60')
|
|
1276
|
+
.action(act((printer, key, opts) => runExperimentAction('extend', key, opts, printer.requestId, deps)));
|
|
1277
|
+
writeLeaf(experiment, 'rollout <key>', 'End the experiment and serve one variant to everyone (client experiments).')
|
|
1278
|
+
.requiredOption('--variant <variantKey>', 'the winning variant')
|
|
1279
|
+
.action(act((printer, key, opts) => runExperimentAction('rollout', key, opts, printer.requestId, deps)));
|
|
1280
|
+
writeLeaf(experiment, 'stop <key>', 'Emergency stop: every device stops getting any variant immediately. Requires --emergency.')
|
|
1281
|
+
.option('--emergency', 'confirm the emergency stop')
|
|
1282
|
+
.action(act((printer, key, opts) => runExperimentAction('emergency-stop', key, opts, printer.requestId, deps)));
|
|
1283
|
+
writeLeaf(experiment, 'reopen <key>', 'Reopen a completed experiment: continue the same run or start a new run.')
|
|
1284
|
+
.requiredOption('--mode <mode>', 'continue | new-run')
|
|
1285
|
+
.option('--traffic <percent>', 'traffic percentage for the reopened run')
|
|
1286
|
+
.option('--variant <key:weight[:name]>', 'new variant set (new-run only; repeat 2-10 times)', collect, [])
|
|
1287
|
+
.option('--payload <variantKey=json|@file>', 'variant payload for the new run (repeatable)', collect, [])
|
|
1288
|
+
.action(act((printer, key, opts) => runExperimentAction('reopen', key, opts, printer.requestId, deps)));
|
|
1289
|
+
envLeaf(experiment, 'history <key>', 'Show the audit history of one experiment (all pages).')
|
|
1290
|
+
.action(act((_p, key, opts) => runExperimentHistory(key, opts, deps)));
|
|
1291
|
+
const overrides = experiment.command('overrides').description('Forced device → variant assignments.');
|
|
1292
|
+
envLeaf(overrides, 'get <key>', 'Show the forced device list.')
|
|
1293
|
+
.action(act((_p, key, opts) => runExperimentOverridesGet(key, opts, deps)));
|
|
1294
|
+
writeLeaf(overrides, 'set <key>', 'Replace the whole forced device list (or --clear it).')
|
|
1295
|
+
.option('--device <deviceId=variantKey>', 'one forced device (repeatable)', collect, [])
|
|
1296
|
+
.option('--clear', 'remove every forced device')
|
|
1297
|
+
.action(act((printer, key, opts) => runExperimentOverridesSet(key, opts, printer.requestId, deps)));
|
|
1298
|
+
const metrics = experiment.command('metrics').description('Experiment metrics and guardrails.');
|
|
1299
|
+
envLeaf(metrics, 'list <key>', 'List metrics and guardrails.')
|
|
1300
|
+
.action(act((_p, key, opts) => runExperimentMetricsList(key, opts, deps)));
|
|
1301
|
+
envLeaf(metrics, 'add <key>', 'Add one metric or guardrail (does not change the experiment version).')
|
|
1302
|
+
.requiredOption('--kind <kind>', 'conversion | count | sum | avg | pct | retention')
|
|
1303
|
+
.requiredOption('--event <name>', 'event name')
|
|
1304
|
+
.option('--metric-key <key>', 'metric key (derived from kind + event when omitted)')
|
|
1305
|
+
.option('--role <role>', 'metric (default) | guardrail')
|
|
1306
|
+
.option('--core', 'mark as the core metric')
|
|
1307
|
+
.option('--direction <dir>', 'up | down: which direction is better')
|
|
1308
|
+
.option('--tolerance <percent>', 'guardrail tolerance in percent')
|
|
1309
|
+
.option('--window-days <n>', 'observation window after exposure, 1-60 (default 7)')
|
|
1310
|
+
.option('--retention-day <n>', 'retention day N for --kind retention, 1-30')
|
|
1311
|
+
.option('--property <name>', 'numeric property for sum / avg / pct')
|
|
1312
|
+
.option('--property-type <type>', 'int | float (default float)')
|
|
1313
|
+
.option('--percentile <n>', 'percentile for --kind pct, 1-99')
|
|
1314
|
+
.option('--filters <json|@file>', 'JSON array of event filters {name, value_type, operator, values}')
|
|
1315
|
+
.action(act((printer, key, opts) => runExperimentMetricsAdd(key, opts, printer.requestId, deps)));
|
|
1316
|
+
envLeaf(metrics, 'remove <key> <metricKey>', 'Remove one metric or guardrail.')
|
|
1317
|
+
.action(act((printer, key, metricKey, opts) => runExperimentMetricsRemove(key, metricKey, opts, printer.requestId, deps)));
|
|
1318
|
+
envLeaf(experiment, 'results <key>', 'Show experiment results (may recompute on the server; waits up to 150 s).')
|
|
1319
|
+
.option('--refresh', 'ask the server to recompute (throttled to once a minute)')
|
|
1320
|
+
.option('--time-zone <iana>', 'IANA time zone, only used the first time results are computed')
|
|
1321
|
+
.action(act((_p, key, opts) => runExperimentResults(key, opts, deps)));
|
|
1322
|
+
envLeaf(experiment, 'lookup', 'Show which variants one device (or a user\'s devices) gets and why.')
|
|
1323
|
+
.option('--device <id>', 'device id')
|
|
1324
|
+
.option('--user <id>', 'user id (resolved to the devices it used)')
|
|
1325
|
+
.option('--attr <name=value>', 'override one custom attribute for the evaluation (repeatable)', collect, [])
|
|
1326
|
+
.action(act((_p, opts) => runExperimentLookup(opts, deps)));
|
|
1327
|
+
envLeaf(experiment, 'vids', 'Export the variant id (vid) table of the environment\'s experiments.')
|
|
1328
|
+
.action(act((_p, opts) => runExperimentVids(opts, deps)));
|
|
1329
|
+
const layers = experiment.command('layers').description('Shared layers for mutually exclusive experiments.');
|
|
1330
|
+
envLeaf(layers, 'list', 'List shared layers and their bucket usage.')
|
|
1331
|
+
.action(act((_p, opts) => runExperimentLayersList(opts, deps)));
|
|
1332
|
+
envLeaf(layers, 'create <key>', 'Create a shared layer.')
|
|
1333
|
+
.option('--description <text>', 'layer description (at most 200 characters)')
|
|
1334
|
+
.action(act((printer, key, opts) => runExperimentLayersCreate(key, opts, printer.requestId, deps)));
|
|
1335
|
+
envLeaf(layers, 'update <key>', 'Change the description of a shared layer.')
|
|
1336
|
+
.requiredOption('--description <text>', 'new description (at most 200 characters; empty string clears it)')
|
|
1337
|
+
.action(act((printer, key, opts) => runExperimentLayersUpdate(key, opts, printer.requestId, deps)));
|
|
1338
|
+
envLeaf(layers, 'delete <key>', 'Delete a shared layer that no experiment uses.')
|
|
1339
|
+
.action(act((printer, key, opts) => runExperimentLayersDelete(key, opts, printer.requestId, deps)));
|
|
1340
|
+
const namespaces = experiment.command('namespaces').description('Project-level experiment namespaces (shared by every environment).');
|
|
1341
|
+
namespaces.command('list')
|
|
1342
|
+
.description('List namespaces.')
|
|
1343
|
+
.option('--config <path>', 'explicit super.json path')
|
|
1344
|
+
.action(act((_p, opts) => runExperimentNamespacesList(opts, deps)));
|
|
1345
|
+
namespaces.command('create <name>')
|
|
1346
|
+
.description('Create a namespace.')
|
|
1347
|
+
.option('--config <path>', 'explicit super.json path')
|
|
1348
|
+
.option('--description <text>', 'namespace description (at most 200 characters)')
|
|
1349
|
+
.action(act((printer, name, opts) => runExperimentNamespacesCreate(name, opts, printer.requestId, deps)));
|
|
1350
|
+
namespaces.command('update <name>')
|
|
1351
|
+
.description('Change the description of a namespace (default included).')
|
|
1352
|
+
.option('--config <path>', 'explicit super.json path')
|
|
1353
|
+
.requiredOption('--description <text>', 'new description (at most 200 characters; empty string clears it)')
|
|
1354
|
+
.action(act((printer, name, opts) => runExperimentNamespacesUpdate(name, opts, printer.requestId, deps)));
|
|
1355
|
+
namespaces.command('delete <name>')
|
|
1356
|
+
.description('Delete a namespace no unarchived experiment uses.')
|
|
1357
|
+
.option('--config <path>', 'explicit super.json path')
|
|
1358
|
+
.action(act((printer, name, opts) => runExperimentNamespacesDelete(name, opts, printer.requestId, deps)));
|
|
1359
|
+
}
|
|
1360
|
+
//# sourceMappingURL=experiment.js.map
|