@variantlab/cli 0.1.0

package/dist/variantlab.js

@@ -0,0 +1,664 @@
+#!/usr/bin/env node
+import { access, mkdir, writeFile, readFile } from 'fs/promises';
+import { resolve, dirname } from 'path';
+import { watch } from 'fs';
+import { validateConfig, ConfigValidationError, explain, createEngine } from '@variantlab/core';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/utils/printer.ts
+function supportsColor() {
+  if (typeof process === "undefined") return false;
+  if (process.env.NO_COLOR !== void 0) return false;
+  if (process.env.FORCE_COLOR !== void 0) return true;
+  if (process.stdout && "isTTY" in process.stdout) return !!process.stdout.isTTY;
+  return false;
+}
+function wrap(code, text) {
+  return useColor ? `${code}${text}${RESET}` : text;
+}
+function success(msg) {
+  console.log(`${color.green("\u2713")} ${msg}`);
+}
+function info(msg) {
+  console.log(`${color.blue("\u2139")} ${msg}`);
+}
+function error(msg) {
+  console.error(`${color.red("\u2717")} ${msg}`);
+}
+function verbose(msg, isVerbose) {
+  if (isVerbose) console.log(`${color.dim(`  ${msg}`)}`);
+}
+var ESC, RESET, codes, useColor, color;
+var init_printer = __esm({
+  "src/utils/printer.ts"() {
+    ESC = "\x1B[";
+    RESET = `${ESC}0m`;
+    codes = {
+      red: `${ESC}31m`,
+      green: `${ESC}32m`,
+      yellow: `${ESC}33m`,
+      blue: `${ESC}34m`,
+      magenta: `${ESC}35m`,
+      cyan: `${ESC}36m`,
+      gray: `${ESC}90m`,
+      bold: `${ESC}1m`,
+      dim: `${ESC}2m`
+    };
+    useColor = supportsColor();
+    color = {
+      red: (t) => wrap(codes.red, t),
+      green: (t) => wrap(codes.green, t),
+      yellow: (t) => wrap(codes.yellow, t),
+      blue: (t) => wrap(codes.blue, t),
+      magenta: (t) => wrap(codes.magenta, t),
+      cyan: (t) => wrap(codes.cyan, t),
+      gray: (t) => wrap(codes.gray, t),
+      bold: (t) => wrap(codes.bold, t),
+      dim: (t) => wrap(codes.dim, t)
+    };
+  }
+});
+async function readTextFile(path) {
+  return readFile(path, "utf-8");
+}
+async function writeTextFile(path, content) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content, "utf-8");
+}
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var init_file = __esm({
+  "src/utils/file.ts"() {
+  }
+});
+
+// src/commands/init.ts
+var init_exports = {};
+__export(init_exports, {
+  init: () => init
+});
+async function init(options = {}) {
+  const configPath = resolve("experiments.json");
+  if (!options.force && await fileExists(configPath)) {
+    error("experiments.json already exists. Use --force to overwrite.");
+    return 1;
+  }
+  try {
+    await writeTextFile(configPath, STARTER_CONFIG);
+    success("Created experiments.json");
+  } catch (err) {
+    error(`Failed to write experiments.json: ${err.message}`);
+    return 3;
+  }
+  const pkgPath = resolve("package.json");
+  if (await fileExists(pkgPath)) {
+    try {
+      const raw = await readTextFile(pkgPath);
+      const pkg = JSON.parse(raw);
+      const scripts = pkg.scripts ?? {};
+      if (!scripts["variantlab:generate"]) {
+        scripts["variantlab:generate"] = "variantlab generate";
+        pkg.scripts = scripts;
+        await writeTextFile(pkgPath, `${JSON.stringify(pkg, null, 2)}
+`);
+        success('Added "variantlab:generate" script to package.json');
+      }
+    } catch {
+      verbose("Could not update package.json (non-fatal)", true);
+    }
+  }
+  console.log("");
+  info("Next steps:");
+  console.log("  1. Edit experiments.json to define your experiments");
+  console.log("  2. Run: variantlab generate");
+  console.log("  3. Import the generated types in your app");
+  console.log("");
+  return 0;
+}
+var STARTER_CONFIG;
+var init_init = __esm({
+  "src/commands/init.ts"() {
+    init_file();
+    init_printer();
+    STARTER_CONFIG = `{
+  "$schema": "https://variantlab.dev/schemas/experiments.schema.json",
+  "version": 1,
+  "experiments": [
+    {
+      "id": "welcome-message",
+      "name": "Welcome message copy",
+      "type": "value",
+      "default": "hello",
+      "variants": [
+        { "id": "hello", "label": "Hello", "value": "Hello, welcome!" },
+        { "id": "hey", "label": "Hey", "value": "Hey there, glad you're here!" }
+      ]
+    },
+    {
+      "id": "hero-layout",
+      "name": "Hero section layout",
+      "type": "render",
+      "default": "centered",
+      "variants": [
+        { "id": "centered", "label": "Centered" },
+        { "id": "split", "label": "Split view" }
+      ]
+    }
+  ]
+}
+`;
+  }
+});
+
+// src/commands/generate.ts
+var generate_exports = {};
+__export(generate_exports, {
+  generate: () => generate
+});
+async function generate(options = {}) {
+  const configPath = resolve(options.config ?? "experiments.json");
+  const outPath = resolve(options.out ?? "src/variantlab.generated.ts");
+  const code = await runGenerate(configPath, outPath, options.verbose ?? false);
+  if (code !== 0) return code;
+  if (options.watch) {
+    info(`Watching ${configPath} for changes...`);
+    let debounce = null;
+    watch(configPath, () => {
+      if (debounce) clearTimeout(debounce);
+      debounce = setTimeout(async () => {
+        info("Config changed, regenerating...");
+        await runGenerate(configPath, outPath, options.verbose ?? false);
+      }, 100);
+    });
+    await new Promise(() => {
+    });
+  }
+  return 0;
+}
+async function runGenerate(configPath, outPath, isVerbose) {
+  if (!await fileExists(configPath)) {
+    error(`Config not found: ${configPath}`);
+    return 1;
+  }
+  let raw;
+  try {
+    raw = await readTextFile(configPath);
+  } catch (err) {
+    error(`Failed to read config: ${err.message}`);
+    return 3;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    error(`Invalid JSON: ${err.message}`);
+    return 2;
+  }
+  let config;
+  try {
+    config = validateConfig(parsed);
+  } catch (err) {
+    error(`Validation failed: ${err.message}`);
+    return 2;
+  }
+  verbose(`Loaded ${config.experiments.length} experiment(s)`, isVerbose);
+  const output = emitTypeScript(config);
+  try {
+    await writeTextFile(outPath, output);
+  } catch (err) {
+    error(`Failed to write output: ${err.message}`);
+    return 3;
+  }
+  success(`Generated ${outPath}`);
+  return 0;
+}
+function emitTypeScript(config) {
+  const lines = [
+    "// AUTO-GENERATED by @variantlab/cli",
+    `// Generated at ${(/* @__PURE__ */ new Date()).toISOString()}`,
+    "// DO NOT EDIT BY HAND",
+    "// Regenerate with: variantlab generate",
+    "",
+    "export interface VariantLabExperiments {"
+  ];
+  for (const exp of config.experiments) {
+    if (exp.name) {
+      lines.push(`  /** ${escapeComment(exp.name)} */`);
+    }
+    lines.push(`  "${exp.id}": {`);
+    lines.push(`    type: "${exp.type ?? "render"}";`);
+    lines.push(`    variants: ${variantUnion(exp)};`);
+    lines.push(`    default: "${exp.default}";`);
+    if (exp.type === "value") {
+      lines.push(`    value: ${valueUnion(exp)};`);
+    }
+    lines.push("  };");
+  }
+  lines.push("}");
+  lines.push("");
+  lines.push('declare module "@variantlab/core" {');
+  lines.push("  interface VariantLabRegistry extends VariantLabExperiments {}");
+  lines.push("}");
+  lines.push("");
+  lines.push("export type ExperimentId = keyof VariantLabExperiments;");
+  lines.push("");
+  lines.push("export type VariantId<T extends ExperimentId> =");
+  lines.push('  VariantLabExperiments[T]["variants"];');
+  lines.push("");
+  lines.push("export type VariantValueType<T extends ExperimentId> =");
+  lines.push("  VariantLabExperiments[T] extends { value: infer V } ? V : never;");
+  lines.push("");
+  return lines.join("\n");
+}
+function variantUnion(exp) {
+  return exp.variants.map((v) => `"${escapeStr(v.id)}"`).join(" | ");
+}
+function valueUnion(exp) {
+  const values = exp.variants.map((v) => v.value).filter((v) => v !== void 0);
+  if (values.length === 0) return "never";
+  return values.map((v) => {
+    if (typeof v === "string") return `"${escapeStr(v)}"`;
+    if (typeof v === "number" || typeof v === "boolean") return String(v);
+    return "unknown";
+  }).join(" | ");
+}
+function escapeStr(s) {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function escapeComment(s) {
+  return s.replace(/\*\//g, "* /");
+}
+var init_generate = __esm({
+  "src/commands/generate.ts"() {
+    init_file();
+    init_printer();
+  }
+});
+
+// src/commands/validate.ts
+var validate_exports = {};
+__export(validate_exports, {
+  validate: () => validate
+});
+async function validate(configPathArg, options = {}) {
+  const configPath = resolve(configPathArg ?? "experiments.json");
+  if (!await fileExists(configPath)) {
+    error(`Config not found: ${configPath}`);
+    return 1;
+  }
+  let raw;
+  try {
+    raw = await readTextFile(configPath);
+  } catch (err) {
+    error(`Failed to read config: ${err.message}`);
+    return 3;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    error(`Invalid JSON in ${configPath}`);
+    error(err.message);
+    return 2;
+  }
+  try {
+    const config = validateConfig(parsed);
+    success(`Valid config: ${config.experiments.length} experiment(s)`);
+    if (options.verbose) {
+      for (const exp of config.experiments) {
+        console.log(
+          `  ${color.cyan(exp.id)} \u2014 ${exp.variants.length} variants, assignment: ${exp.assignment ?? "default"}, status: ${exp.status ?? "active"}`
+        );
+      }
+    }
+    return 0;
+  } catch (err) {
+    if (err instanceof ConfigValidationError) {
+      error(`Validation failed with ${err.issues.length} issue(s):`);
+      console.log("");
+      for (const issue of err.issues) {
+        console.log(`  ${color.red(issue.code)} at ${color.yellow(issue.path)}`);
+        console.log(`    ${issue.message}`);
+      }
+      console.log("");
+      return 2;
+    }
+    error(`Unexpected error: ${err.message}`);
+    return 2;
+  }
+}
+var init_validate = __esm({
+  "src/commands/validate.ts"() {
+    init_file();
+    init_printer();
+    init_printer();
+  }
+});
+
+// src/commands/eval.ts
+var eval_exports = {};
+__export(eval_exports, {
+  evalCommand: () => evalCommand
+});
+async function evalCommand(configPathArg, options = {}) {
+  const configPath = resolve(configPathArg ?? "experiments.json");
+  if (!options.experiment) {
+    error("Missing required flag: --experiment <id>");
+    return 4;
+  }
+  if (!await fileExists(configPath)) {
+    error(`Config not found: ${configPath}`);
+    return 1;
+  }
+  let config;
+  try {
+    const raw = await readTextFile(configPath);
+    const parsed = JSON.parse(raw);
+    config = validateConfig(parsed);
+  } catch (err) {
+    if (err instanceof ConfigValidationError) {
+      error(`Invalid config: ${err.issues.length} issue(s)`);
+      return 2;
+    }
+    error(`Failed to load config: ${err.message}`);
+    return err instanceof SyntaxError ? 2 : 3;
+  }
+  let context = {};
+  if (options.contextFile) {
+    try {
+      const raw = await readTextFile(resolve(options.contextFile));
+      context = JSON.parse(raw);
+    } catch (err) {
+      error(`Failed to load context file: ${err.message}`);
+      return 3;
+    }
+  } else if (options.context) {
+    try {
+      context = JSON.parse(options.context);
+    } catch (err) {
+      error(`Invalid context JSON: ${err.message}`);
+      return 4;
+    }
+  }
+  const experiment = config.experiments.find((e) => e.id === options.experiment);
+  if (!experiment) {
+    error(`Experiment not found: ${options.experiment}`);
+    const ids = config.experiments.map((e) => e.id);
+    if (ids.length > 0) {
+      info(`Available experiments: ${ids.join(", ")}`);
+    }
+    return 4;
+  }
+  console.log(color.bold(`Experiment: ${experiment.id}`));
+  console.log(`  Name: ${experiment.name}`);
+  console.log(`  Type: ${experiment.type ?? "render"}`);
+  console.log(`  Assignment: ${experiment.assignment ?? "default"}`);
+  console.log(`  Default: ${experiment.default}`);
+  console.log(`  Variants: ${experiment.variants.map((v) => v.id).join(", ")}`);
+  console.log("");
+  console.log(color.bold("Context:"));
+  if (Object.keys(context).length === 0) {
+    console.log("  (empty)");
+  } else {
+    for (const [key, val] of Object.entries(context)) {
+      console.log(`  ${key}: ${JSON.stringify(val)}`);
+    }
+  }
+  console.log("");
+  console.log(color.bold("Targeting trace:"));
+  const result = explain(experiment, context);
+  if (result.steps.length === 0) {
+    console.log("  (no targeting rules)");
+  } else {
+    for (const step of result.steps) {
+      const icon = step.matched ? color.green("PASS") : color.red("FAIL");
+      const detail = step.detail ? ` \u2014 ${step.detail}` : "";
+      console.log(`  ${icon} ${step.field}${detail}`);
+    }
+  }
+  console.log("");
+  const engine = createEngine(config, { context });
+  const variantId = engine.getVariant(experiment.id);
+  const variant = experiment.variants.find((v) => v.id === variantId);
+  console.log(color.bold("Result:"));
+  console.log(`  Targeted: ${result.matched ? color.green("yes") : color.red("no")}`);
+  console.log(`  Variant: ${color.cyan(variantId)}`);
+  if (variant?.value !== void 0) {
+    console.log(`  Value: ${JSON.stringify(variant.value)}`);
+  }
+  if (!result.matched && result.reason) {
+    console.log(`  Reason: failed on ${color.yellow(result.reason)}`);
+  }
+  console.log("");
+  engine.dispose();
+  return 0;
+}
+var init_eval = __esm({
+  "src/commands/eval.ts"() {
+    init_file();
+    init_printer();
+    init_printer();
+  }
+});
+
+// src/utils/arg-parser.ts
+function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+  let command;
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith("--")) {
+      const eqIdx = arg.indexOf("=");
+      if (eqIdx !== -1) {
+        const key = camelCase(arg.slice(2, eqIdx));
+        flags[key] = arg.slice(eqIdx + 1);
+      } else {
+        const raw = arg.slice(2);
+        if (raw.startsWith("no-")) {
+          flags[camelCase(raw.slice(3))] = false;
+        } else {
+          const key = camelCase(raw);
+          const next = argv[i + 1];
+          if (next !== void 0 && !next.startsWith("-")) {
+            flags[key] = next;
+            i++;
+          } else {
+            flags[key] = true;
+          }
+        }
+      }
+    } else if (arg.startsWith("-") && arg.length === 2) {
+      const key = arg[1];
+      const next = argv[i + 1];
+      if (next !== void 0 && !next.startsWith("-")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else if (command === void 0 && !arg.startsWith("-")) {
+      command = arg;
+    } else {
+      positionals.push(arg);
+    }
+    i++;
+  }
+  return { flags, positionals, command };
+}
+function camelCase(s) {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+// src/bin/variantlab.ts
+init_printer();
+var VERSION = "0.0.0";
+var USAGE = `
+Usage: variantlab <command> [options]
+
+Commands:
+  init                    Scaffold experiments.json in the current directory
+  generate                Generate TypeScript from experiments.json
+  validate [path]         Validate an experiments.json config file
+  eval [path]             Evaluate an experiment against a context
+
+Options:
+  --help                  Show this help message
+  --version               Show version
+  --verbose               Enable verbose output
+
+Run "variantlab <command> --help" for command-specific help.
+`.trim();
+var INIT_HELP = `
+Usage: variantlab init [options]
+
+Scaffold a starter experiments.json in the current directory.
+
+Options:
+  --force     Overwrite existing experiments.json
+  --verbose   Enable verbose output
+  --help      Show this help message
+`.trim();
+var GENERATE_HELP = `
+Usage: variantlab generate [options]
+
+Generate TypeScript types from experiments.json.
+
+Options:
+  --config <path>   Path to experiments.json (default: ./experiments.json)
+  --out <path>      Output path (default: ./src/variantlab.generated.ts)
+  --watch           Watch for config changes and regenerate
+  --verbose         Enable verbose output
+  --help            Show this help message
+`.trim();
+var VALIDATE_HELP = `
+Usage: variantlab validate [path] [options]
+
+Validate an experiments.json config file.
+
+Arguments:
+  path        Path to config file (default: ./experiments.json)
+
+Options:
+  --verbose   Show experiment details on success
+  --help      Show this help message
+`.trim();
+var EVAL_HELP = `
+Usage: variantlab eval [path] [options]
+
+Evaluate an experiment against a context and show targeting trace.
+
+Arguments:
+  path                    Path to config file (default: ./experiments.json)
+
+Options:
+  --experiment <id>       Experiment ID to evaluate (required)
+  --context '<json>'      Inline JSON context
+  --context-file <path>   Path to a JSON context file
+  --verbose               Enable verbose output
+  --help                  Show this help message
+`.trim();
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.flags.version) {
+    console.log(VERSION);
+    process.exit(0);
+  }
+  if (!args.command || args.flags.help) {
+    if (!args.command) {
+      console.log(USAGE);
+      process.exit(args.flags.help ? 0 : 4);
+    }
+  }
+  const isVerbose = args.flags.verbose === true;
+  switch (args.command) {
+    case "init": {
+      if (args.flags.help) {
+        console.log(INIT_HELP);
+        process.exit(0);
+      }
+      const { init: init2 } = await Promise.resolve().then(() => (init_init(), init_exports));
+      const code = await init2({
+        force: args.flags.force === true,
+        verbose: isVerbose
+      });
+      process.exit(code);
+      break;
+    }
+    case "generate": {
+      if (args.flags.help) {
+        console.log(GENERATE_HELP);
+        process.exit(0);
+      }
+      const { generate: generate2 } = await Promise.resolve().then(() => (init_generate(), generate_exports));
+      const code = await generate2({
+        config: typeof args.flags.config === "string" ? args.flags.config : void 0,
+        out: typeof args.flags.out === "string" ? args.flags.out : void 0,
+        watch: args.flags.watch === true,
+        verbose: isVerbose
+      });
+      process.exit(code);
+      break;
+    }
+    case "validate": {
+      if (args.flags.help) {
+        console.log(VALIDATE_HELP);
+        process.exit(0);
+      }
+      const { validate: validate2 } = await Promise.resolve().then(() => (init_validate(), validate_exports));
+      const configPath = args.positionals[0];
+      const code = await validate2(typeof configPath === "string" ? configPath : void 0, {
+        verbose: isVerbose
+      });
+      process.exit(code);
+      break;
+    }
+    case "eval": {
+      if (args.flags.help) {
+        console.log(EVAL_HELP);
+        process.exit(0);
+      }
+      const { evalCommand: evalCommand2 } = await Promise.resolve().then(() => (init_eval(), eval_exports));
+      const configPath = args.positionals[0];
+      const code = await evalCommand2(typeof configPath === "string" ? configPath : void 0, {
+        experiment: typeof args.flags.experiment === "string" ? args.flags.experiment : void 0,
+        context: typeof args.flags.context === "string" ? args.flags.context : void 0,
+        contextFile: typeof args.flags.contextFile === "string" ? args.flags.contextFile : void 0,
+        verbose: isVerbose
+      });
+      process.exit(code);
+      break;
+    }
+    default:
+      error(`Unknown command: ${args.command}`);
+      console.log("");
+      console.log(USAGE);
+      process.exit(4);
+  }
+}
+main().catch((err) => {
+  error(err.message);
+  process.exit(1);
+});
+//# sourceMappingURL=variantlab.js.map
+//# sourceMappingURL=variantlab.js.map