@nanoflags/cli 0.0.0-stage → 0.2.0

package/dist/bin.js

@@ -0,0 +1,839 @@
+#!/usr/bin/env node
+import {
+  CliError,
+  DEFAULT_MAX_FILE_BYTES,
+  EXIT,
+  clip,
+  show,
+  table,
+  unifiedDiff,
+  walk
+} from "./chunk-KGDBDK5S.js";
+
+// src/main.ts
+import { appendFileSync, existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+
+// ../engine/src/index.ts
+var encoder = new TextEncoder();
+function murmur3(input, seed = 0) {
+  const data = encoder.encode(input.normalize("NFC"));
+  const c1 = 3432918353;
+  const c2 = 461845907;
+  let h = seed >>> 0;
+  const blocks = data.length >> 2;
+  for (let i = 0; i < blocks; i++) {
+    const o = i * 4;
+    let k2 = data[o] | data[o + 1] << 8 | data[o + 2] << 16 | data[o + 3] << 24;
+    k2 = Math.imul(k2, c1);
+    k2 = k2 << 15 | k2 >>> 17;
+    k2 = Math.imul(k2, c2);
+    h ^= k2;
+    h = h << 13 | h >>> 19;
+    h = Math.imul(h, 5) + 3864292196 | 0;
+  }
+  let k = 0;
+  const tail = blocks * 4;
+  switch (data.length & 3) {
+    case 3:
+      k ^= data[tail + 2] << 16;
+    // falls through
+    case 2:
+      k ^= data[tail + 1] << 8;
+    // falls through
+    case 1:
+      k ^= data[tail];
+      k = Math.imul(k, c1);
+      k = k << 15 | k >>> 17;
+      k = Math.imul(k, c2);
+      h ^= k;
+  }
+  h ^= data.length;
+  h ^= h >>> 16;
+  h = Math.imul(h, 2246822507);
+  h ^= h >>> 13;
+  h = Math.imul(h, 3266489909);
+  h ^= h >>> 16;
+  return h >>> 0;
+}
+function bucketOf(seed, identity) {
+  return murmur3(`${seed}:${identity}`) % 1e4 / 100;
+}
+function own(obj, key2) {
+  return obj != null && Object.prototype.hasOwnProperty.call(obj, key2) ? obj[key2] : void 0;
+}
+function looseEq(a, b) {
+  if (a === void 0 || b === void 0) return false;
+  if (typeof a === "object" || typeof b === "object") return JSON.stringify(a) === JSON.stringify(b);
+  return a === b;
+}
+function num(v) {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string" && v.trim() !== "" && Number.isFinite(Number(v))) return Number(v);
+  return null;
+}
+function matchCondition(c, ctx, segments, depth = 0) {
+  if (c.op === "segment" || c.op === "not_segment") {
+    const seg = typeof c.value === "string" ? own(segments, c.value) : void 0;
+    const inSeg = seg !== void 0 && depth < 4 && matchAll(seg.match, seg.conditions, ctx, segments, depth + 1);
+    return c.op === "segment" ? inSeg : seg !== void 0 && !inSeg;
+  }
+  const actual = own(ctx, c.attribute);
+  switch (c.op) {
+    case "exists":
+      return actual !== void 0 && actual !== null;
+    case "not_exists":
+      return actual === void 0 || actual === null;
+    case "eq":
+      return looseEq(actual, c.value);
+    case "neq":
+      return actual !== void 0 && !looseEq(actual, c.value);
+    case "in":
+      return Array.isArray(c.value) && c.value.some((v) => looseEq(actual, v));
+    case "not_in":
+      return actual !== void 0 && Array.isArray(c.value) && !c.value.some((v) => looseEq(actual, v));
+    case "contains":
+      return typeof actual === "string" && typeof c.value === "string" && actual.includes(c.value);
+    case "starts_with":
+      return typeof actual === "string" && typeof c.value === "string" && actual.startsWith(c.value);
+    case "ends_with":
+      return typeof actual === "string" && typeof c.value === "string" && actual.endsWith(c.value);
+    case "gt":
+    case "gte":
+    case "lt":
+    case "lte": {
+      const a = num(actual);
+      const b = num(c.value);
+      if (a === null || b === null) return false;
+      return c.op === "gt" ? a > b : c.op === "gte" ? a >= b : c.op === "lt" ? a < b : a <= b;
+    }
+    default:
+      return false;
+  }
+}
+function matchAll(mode, conditions, ctx, segments, depth = 0) {
+  if (conditions.length === 0) return true;
+  return mode === "any" ? conditions.some((c) => matchCondition(c, ctx, segments, depth)) : conditions.every((c) => matchCondition(c, ctx, segments, depth));
+}
+function describeCondition(c) {
+  const v = Array.isArray(c.value) ? c.value.join(", ") : c.value === void 0 ? "" : String(c.value);
+  const words = {
+    eq: "=",
+    neq: "\u2260",
+    in: "in",
+    not_in: "not in",
+    contains: "contains",
+    starts_with: "starts with",
+    ends_with: "ends with",
+    gt: ">",
+    gte: "\u2265",
+    lt: "<",
+    lte: "\u2264",
+    exists: "exists",
+    not_exists: "does not exist",
+    segment: "in segment",
+    not_segment: "not in segment"
+  };
+  if (c.op === "segment" || c.op === "not_segment") return `${words[c.op]} ${v}`;
+  if (c.op === "exists" || c.op === "not_exists") return `${c.attribute} ${words[c.op]}`;
+  return `${c.attribute} ${words[c.op]} ${v}`;
+}
+function evaluate(bundle, flagKey, ctx, fallback) {
+  const revision = bundle?.revision ?? 0;
+  const trace = [];
+  try {
+    const flag = own(bundle?.flags, flagKey);
+    if (!bundle || !flag) {
+      trace.push({ kind: "result", title: `Returned ${fmt(fallback)}`, detail: bundle ? "Flag is not in this configuration. The application fallback applies." : "No configuration is loaded. The application fallback applies." });
+      return { flagKey, value: fallback, reason: "flag_not_found", revision, trace };
+    }
+    trace.push({ kind: "config", title: "Configuration loaded", detail: revision > 0 ? `r${revision}` : "draft" });
+    if (!flag.enabled) {
+      trace.push({ kind: "result", title: `Returned ${fmt(flag.off)}`, detail: "Flag is disabled in this environment." });
+      return { flagKey, value: flag.off, reason: "off", revision, trace };
+    }
+    for (let i = 0; i < flag.rules.length; i++) {
+      const rule = flag.rules[i];
+      const matched = matchAll(rule.match, rule.conditions, ctx, bundle.segments);
+      const label = `Rule ${String(i + 1).padStart(2, "0")}`;
+      const summary = rule.conditions.length ? rule.conditions.map(describeCondition).join(rule.match === "any" ? " OR " : " AND ") : "all contexts";
+      trace.push({ kind: "rule", title: matched ? `${label} matched` : `${label} did not match`, detail: summary, matched });
+      if (!matched) continue;
+      if (rule.serve.type === "fixed") {
+        trace.push({ kind: "result", title: `Returned ${fmt(rule.serve.value)}`, detail: `${label} serves a fixed value.` });
+        return { flagKey, value: rule.serve.value, reason: "rule_match", ruleIndex: i, ruleId: rule.id, revision, trace };
+      }
+      const attr = rule.serve.bucketBy ?? "key";
+      const identity = own(ctx, attr);
+      if (identity === void 0 || identity === null || identity === "") {
+        trace.push({ kind: "allocation", title: "Allocation skipped", detail: `Context has no "${attr}" to bucket by; treated as outside the allocation.`, matched: false });
+        trace.push({ kind: "result", title: `Returned ${fmt(rule.serve.otherwise)}`, detail: "Remaining eligible users." });
+        return { flagKey, value: rule.serve.otherwise, reason: "rule_match", ruleIndex: i, ruleId: rule.id, inRollout: false, revision, trace };
+      }
+      const bucket = bucketOf(rule.serve.seed ?? flagKey, String(identity));
+      const inRollout = bucket < rule.serve.percentage;
+      trace.push({ kind: "allocation", title: "Allocation evaluated", detail: `${rule.serve.percentage}% rollout \xB7 ${attr} ${inRollout ? "inside" : "outside"} allocation (bucket ${bucket.toFixed(2)})`, matched: inRollout });
+      const value = inRollout ? rule.serve.value : rule.serve.otherwise;
+      trace.push({ kind: "result", title: `Returned ${fmt(value)}`, detail: inRollout ? `Inside the ${rule.serve.percentage}% allocation.` : "Remaining eligible users." });
+      return { flagKey, value, reason: "rule_match", ruleIndex: i, ruleId: rule.id, inRollout, bucket, revision, trace };
+    }
+    trace.push({ kind: "result", title: `Returned ${fmt(flag.default)}`, detail: "No rule matched. The flag default applies." });
+    return { flagKey, value: flag.default, reason: "default", revision, trace };
+  } catch (e) {
+    const error = e instanceof Error ? e.message : String(e);
+    trace.push({ kind: "result", title: `Returned ${fmt(fallback)}`, detail: `Evaluation error: ${error}. The application fallback applies.` });
+    return { flagKey, value: fallback, reason: "error", revision, trace, error };
+  }
+}
+function fmt(v) {
+  return typeof v === "string" ? v : JSON.stringify(v);
+}
+
+// src/api.ts
+var DEFAULT_BASE_URL = "https://edge.nanoflags.io";
+var ApiError = class extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "ApiError";
+  }
+  status;
+  code;
+};
+function isExport(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const e = v;
+  return typeof e.project === "object" && e.project !== null && Array.isArray(e.flags) && e.flags.every((f) => typeof f === "object" && f !== null && typeof f.key === "string");
+}
+function keyKind(key2) {
+  return key2.startsWith("nf_adm_") ? "admin" : key2.startsWith("nf_ci_") ? "ci" : key2.startsWith("nf_srv_") ? "server" : key2.startsWith("nf_pub_") ? "client" : "unknown";
+}
+var Api = class {
+  constructor(o) {
+    this.o = o;
+  }
+  o;
+  async call(method, path2, body) {
+    let res;
+    try {
+      res = await this.o.fetch(`${this.o.baseUrl}${path2}`, {
+        method,
+        headers: { Authorization: `Bearer ${this.o.key}`, Accept: "application/json", "User-Agent": this.o.userAgent, ...body === void 0 ? {} : { "Content-Type": "application/json" } },
+        ...body === void 0 ? {} : { body: JSON.stringify(body) },
+        signal: AbortSignal.timeout(3e4)
+      });
+    } catch (e) {
+      throw new CliError(`Could not reach ${this.o.baseUrl}: ${e instanceof Error ? e.message : String(e)}`, EXIT.unavailable);
+    }
+    const text = await res.text();
+    let json = null;
+    try {
+      json = text === "" ? null : JSON.parse(text);
+    } catch {
+    }
+    if (res.ok) {
+      if (json === null) throw new CliError(`${method} ${path2} returned an empty or non-JSON response (HTTP ${res.status}).`, EXIT.unavailable);
+      return json;
+    }
+    const err = json?.error;
+    const code = typeof err === "object" && err !== null && typeof err.code === "string" ? err.code : typeof err === "string" ? err : `http_${res.status}`;
+    const message = typeof err === "object" && err !== null && typeof err.message === "string" ? err.message : `HTTP ${res.status}`;
+    throw new ApiError(message, res.status, code);
+  }
+  export() {
+    return this.call("GET", "/v1/admin/export");
+  }
+  bundle() {
+    return this.call("GET", "/v1/bundle");
+  }
+  /** The published revision of the key's environment (CI or admin key). */
+  published() {
+    return this.call("GET", "/v1/ci/published");
+  }
+  runScenarios(body) {
+    return this.call("POST", "/v1/ci/scenarios/run", body);
+  }
+  publish(body) {
+    return this.call("POST", "/v1/admin/publish", body);
+  }
+  /** Creates a flag in the key's project (admin key). Every environment's draft starts with `default`. */
+  createFlag(body) {
+    return this.call("POST", "/v1/admin/flags", body);
+  }
+  putCodeRefs(body) {
+    return this.call("PUT", "/v1/ci/code-refs", body);
+  }
+};
+function explain(e, key2, what) {
+  if (e instanceof CliError) return e;
+  if (e instanceof ApiError) {
+    const kind = keyKind(key2);
+    if (e.status === 401) return new CliError(`The key was rejected (unknown or revoked). Check NANOFLAGS_KEY.`, EXIT.usage);
+    if (e.status === 403) return new CliError(`This key may not ${what}${kind === "unknown" ? "" : ` (it is a ${kind} key)`}. ${e.message}`, EXIT.usage);
+    if (e.status === 404 && e.code === "not_found") return new CliError(`The edge at this base URL does not offer this endpoint (${e.message}). Check --base-url, or the edge is older than this CLI.`, EXIT.unavailable);
+    if (e.status >= 500) return new CliError(`NanoFlags could not ${what} right now (HTTP ${e.status}: ${e.message}).`, EXIT.unavailable);
+    return new CliError(`Could not ${what}: ${e.message} [${e.code}]`, EXIT.failed);
+  }
+  return new CliError(e instanceof Error ? e.message : String(e), EXIT.failed);
+}
+
+// src/main.ts
+var VERSION = "0.2.0";
+var HELP = `nanoflags ${VERSION} \u2014 NanoFlags command line
+
+Usage: nanoflags <command> [options]
+
+Commands
+  export [--out <file>]                         Download flags, segments and drafts as JSON
+  flags list [--json]                           List the project's flags
+  flags create <key> --type boolean|string|number|json [--default <json>] [--description <text>] [--name <text>] [--json]
+                                                Create a flag in the key's project (admin key); nothing is published
+  eval <flag> [--context <json>] [--source draft|published] [--fallback <json>] [--json]
+                                                Evaluate one flag locally and print value, reason and trace
+  scenarios run [--source draft|revision] [--commit <sha>] [--run-url <url>] [--json]
+                                                Run the saved scenarios; exit 1 when one fails
+  publish --expected-revision <n> [--note <text>]
+                                                Publish the draft of the key's environment (admin key)
+  refs scan [dir] --repo <owner/name> [--commit <sha>] [--dry-run] [--json]
+                                                Find flag references in source files and upload them
+  cleanup <flag> --value <json> [dir] [--write] Propose (or apply) the removal of a resolved flag from code
+
+Global options
+  --key <key>          CI or admin key. Default: $NANOFLAGS_KEY. Prefer the environment variable:
+                       command-line arguments are visible to other processes.
+  --sdk-key <key>      Optional server SDK key for \`eval --source published\` (reads /v1/bundle instead of
+                       /v1/ci/published with --key). Default: $NANOFLAGS_SDK_KEY
+  --base-url <url>     Default: $NANOFLAGS_BASE_URL or ${DEFAULT_BASE_URL}
+  --export <file>      Read a saved \`nanoflags export\` instead of calling the API (eval, flags list, refs scan, cleanup)
+  -h, --help           -v, --version
+
+Exit codes: 0 ok \xB7 1 a check failed (failing scenario, publish refused) \xB7 2 usage, configuration or key problem \xB7 3 NanoFlags unreachable
+`;
+var OPTIONS = {
+  key: { type: "string" },
+  "sdk-key": { type: "string" },
+  "base-url": { type: "string" },
+  out: { type: "string" },
+  context: { type: "string" },
+  source: { type: "string" },
+  fallback: { type: "string" },
+  environment: { type: "string" },
+  commit: { type: "string" },
+  "run-url": { type: "string" },
+  json: { type: "boolean" },
+  "expected-revision": { type: "string" },
+  type: { type: "string" },
+  default: { type: "string" },
+  description: { type: "string" },
+  name: { type: "string" },
+  note: { type: "string" },
+  repo: { type: "string" },
+  "dry-run": { type: "boolean" },
+  value: { type: "string" },
+  write: { type: "boolean" },
+  export: { type: "string" },
+  "max-file-size": { type: "string" },
+  help: { type: "boolean", short: "h" },
+  version: { type: "boolean", short: "v" }
+};
+function usage(message) {
+  return new CliError(`${message}
+Run \`nanoflags --help\` for usage.`, EXIT.usage);
+}
+function parseJson(text, what) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw usage(`${what} must be valid JSON, got: ${clip(text, 80)}`);
+  }
+}
+function baseUrl(r) {
+  const raw = (r.values["base-url"] || r.io.env.NANOFLAGS_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw usage(`--base-url is not a URL: ${raw}`);
+  }
+  const local = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && local)) throw usage(`--base-url must use https (http is only accepted for localhost): ${raw}`);
+  return raw;
+}
+function key(r) {
+  const k = (r.values.key ?? r.io.env.NANOFLAGS_KEY ?? "").trim();
+  if (k === "") throw usage("No key. Set NANOFLAGS_KEY (or pass --key) to a NanoFlags CI or admin key.");
+  return k;
+}
+function api(r) {
+  return new Api({ baseUrl: baseUrl(r), key: key(r), fetch: r.io.fetch, userAgent: `nanoflags-cli/${VERSION}` });
+}
+function path(r, p) {
+  return isAbsolute(p) ? p : resolve(r.io.cwd, p);
+}
+async function loadExport(r) {
+  const file = r.values.export;
+  if (file !== void 0) {
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync(path(r, file), "utf8"));
+    } catch (e) {
+      throw usage(`Could not read --export ${file}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!isExport(parsed)) throw usage(`--export ${file} is not a NanoFlags export.`);
+    return parsed;
+  }
+  const k = key(r);
+  try {
+    const data = await api(r).export();
+    if (!isExport(data)) throw new CliError("The export has an unexpected shape.", EXIT.unavailable);
+    return data;
+  } catch (e) {
+    throw explain(e, k, "read the project export");
+  }
+}
+async function cmdExport(r) {
+  const data = await loadExport(r);
+  const text = `${JSON.stringify(data, null, 2)}
+`;
+  if (r.values.out !== void 0) {
+    writeFileSync(path(r, r.values.out), text);
+    r.io.err(`Wrote ${r.values.out} (${data.flags.length} flags, ${data.segments?.length ?? 0} segments, ${Object.keys(data.drafts ?? {}).length} environments).
+`);
+  } else r.io.out(text);
+  return EXIT.ok;
+}
+async function cmdFlagsList(r) {
+  const data = await loadExport(r);
+  if (r.values.json) {
+    r.io.out(`${JSON.stringify(data.flags, null, 2)}
+`);
+    return EXIT.ok;
+  }
+  const draft = data.drafts?.[data.key_environment]?.flags ?? {};
+  const rows = data.flags.map((f) => {
+    const cfg = Object.prototype.hasOwnProperty.call(draft, f.key) ? draft[f.key] : void 0;
+    return [f.key, f.type, f.purpose ?? "", f.permanent ? "permanent" : "temporary", f.client_exposed ? "yes" : "no", f.archived ? "archived" : cfg === void 0 ? "-" : cfg.enabled ? "on" : "off"];
+  });
+  r.io.out(`${data.project.key} \xB7 ${data.flags.length} flags \xB7 state shown for ${data.key_environment} (draft)
+
+`);
+  r.io.out(`${table(["KEY", "TYPE", "PURPOSE", "LIFETIME", "CLIENT", "STATE"], rows)}
+`);
+  return EXIT.ok;
+}
+var FLAG_KEY = /^[a-z0-9][a-z0-9_-]{0,62}$/;
+var FLAG_TYPES = ["boolean", "string", "number", "json"];
+function parseDefault(type, raw) {
+  if (raw === void 0) {
+    if (type === "boolean") return false;
+    throw usage(`flags create needs --default for a ${type} flag: the value every environment's draft starts with (JSON, e.g. ${type === "string" ? `'"blue"'` : type === "number" ? "0" : "'{}'"}).`);
+  }
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    if (type !== "string") throw usage(`--default must be valid JSON for a ${type} flag, got: ${clip(raw, 80)}`);
+    value = raw;
+  }
+  const ok = type === "boolean" ? typeof value === "boolean" : type === "string" ? typeof value === "string" : type === "number" ? typeof value === "number" && Number.isFinite(value) : true;
+  if (!ok) throw usage(`--default must be a ${type} value for a ${type} flag, got: ${clip(raw, 80)}`);
+  return value;
+}
+var CREATE_HELP = {
+  CONFLICT: "Choose another key, or use the existing flag (`nanoflags flags list`).",
+  INVALID_VALUE: "The default does not match the flag type.",
+  INVALID: "Check the key, name and description."
+};
+async function cmdFlagsCreate(r) {
+  const flagKey = r.args[0];
+  if (!flagKey || r.args.length > 1) throw usage("Usage: nanoflags flags create <key> --type boolean|string|number|json [--default <json>] [--description <text>] [--name <text>]");
+  if (!FLAG_KEY.test(flagKey)) throw usage(`The flag key must start with a lowercase letter or digit and use only lowercase letters, digits, hyphens and underscores (max 63), got "${clip(flagKey, 80)}".`);
+  const type = r.values.type ?? "boolean";
+  if (!FLAG_TYPES.includes(type)) throw usage(`--type must be one of ${FLAG_TYPES.join(", ")}, got "${type}".`);
+  const value = parseDefault(type, r.values.default);
+  const description = r.values.description ?? "";
+  if (description.length > 2e3) throw usage("--description is limited to 2000 characters.");
+  const name = r.values.name;
+  if (name !== void 0 && (name.trim() === "" || name.length > 120)) throw usage("--name must be 1\u2013120 characters.");
+  const k = key(r);
+  const kind = keyKind(k);
+  if (kind !== "admin" && kind !== "unknown") throw usage(`flags create needs an admin key; this is a ${kind} key.`);
+  try {
+    const res = await api(r).createFlag({ key: flagKey, type, default: value, description, ...name !== void 0 ? { name: name.trim() } : {} });
+    if (r.values.json) r.io.out(`${JSON.stringify(res, null, 2)}
+`);
+    else {
+      r.io.out(`Created ${res.key} (${res.type}, default ${JSON.stringify(res.default ?? value)}).
+`);
+      r.io.out(`Every environment's draft now has it${Array.isArray(res.environments) && res.environments.length ? ` (${res.environments.join(", ")})` : ""}. Nothing was published.
+`);
+    }
+    return EXIT.ok;
+  } catch (e) {
+    const err = e;
+    const help = e instanceof ApiError && typeof err.code === "string" ? CREATE_HELP[err.code] : void 0;
+    if (help) {
+      r.io.err(`Flag not created: ${err.message ?? err.code} [${err.code}]
+${help}
+`);
+      return EXIT.failed;
+    }
+    throw explain(e, k, "create flags");
+  }
+}
+function isBundle(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const b = v;
+  return typeof b.flags === "object" && b.flags !== null && typeof b.segments === "object" && b.segments !== null;
+}
+async function cmdEval(r) {
+  const flag = r.args[0];
+  if (!flag || r.args.length > 1) throw usage(`Usage: nanoflags eval <flag> [--context '{"key":"u1"}'] [--source draft|published]`);
+  const source = r.values.source ?? "draft";
+  if (source !== "draft" && source !== "published") throw usage(`--source must be draft or published, got "${source}".`);
+  const ctx = r.values.context === void 0 ? {} : parseJson(r.values.context, "--context");
+  if (typeof ctx !== "object" || ctx === null || Array.isArray(ctx)) throw usage("--context must be a JSON object.");
+  const fallback = r.values.fallback === void 0 ? null : parseJson(r.values.fallback, "--fallback");
+  let bundle;
+  let label;
+  if (source === "draft") {
+    const data = await loadExport(r);
+    const env = r.values.environment ?? data.key_environment;
+    const draft = data.drafts?.[env];
+    if (!isBundle(draft)) throw usage(`The export has no draft for environment "${env}". Available: ${Object.keys(data.drafts ?? {}).join(", ") || "none"}.`);
+    bundle = { schema: 1, project: data.project.key, environment: env, revision: 0, flags: draft.flags, segments: draft.segments };
+    label = `draft of ${env}`;
+  } else {
+    if (r.values.environment !== void 0) throw usage("--environment only applies to --source draft: a key reads the published configuration of its own environment.");
+    const sdkKey = (r.values["sdk-key"] ?? r.io.env.NANOFLAGS_SDK_KEY ?? "").trim();
+    const main2 = (r.values.key ?? r.io.env.NANOFLAGS_KEY ?? "").trim();
+    const k = sdkKey !== "" ? sdkKey : keyKind(main2) === "server" || keyKind(main2) === "client" ? main2 : "";
+    if (k === "" && main2 === "") throw usage("--source published needs a key: NANOFLAGS_KEY (a CI or admin key of the environment) or NANOFLAGS_SDK_KEY (--sdk-key, a server SDK key).");
+    const useSdk = k !== "";
+    const used = useSdk ? k : main2;
+    try {
+      const client = new Api({ baseUrl: baseUrl(r), key: used, fetch: r.io.fetch, userAgent: `nanoflags-cli/${VERSION}` });
+      const res = useSdk ? await client.bundle() : await client.published();
+      if (!isBundle(res.bundle)) throw new CliError("The published bundle has an unexpected shape.", EXIT.unavailable);
+      bundle = res.bundle;
+      label = `published r${res.revision}`;
+    } catch (e) {
+      if (!useSdk && e instanceof ApiError && e.code === "INVALID_STATE") throw new CliError(`Nothing is published in this key's environment yet. ${e.message}`, EXIT.usage);
+      throw explain(e, used, "read the published configuration");
+    }
+  }
+  const result = evaluate(bundle, flag, ctx, fallback);
+  if (r.values.json) r.io.out(`${JSON.stringify({ source: label, ...result }, null, 2)}
+`);
+  else {
+    const rule = result.ruleId !== void 0 ? ` \xB7 rule ${result.ruleId} (#${(result.ruleIndex ?? 0) + 1})` : "";
+    const rollout = result.inRollout === void 0 ? "" : ` \xB7 ${result.inRollout ? "inside" : "outside"} rollout${result.bucket === void 0 ? "" : ` (bucket ${result.bucket.toFixed(2)})`}`;
+    r.io.out(`${flag} = ${JSON.stringify(result.value)}
+`);
+    r.io.out(`reason: ${result.reason}${rule}${rollout}
+`);
+    r.io.out(`source: ${label}
+`);
+    r.io.out(`trace:
+${result.trace.map((t) => `  ${t.kind.padEnd(10)} ${t.title} \u2014 ${t.detail}`).join("\n")}
+`);
+    if (result.reason === "flag_not_found") r.io.err(`Note: "${flag}" is not in this configuration; the value above is the fallback.
+`);
+  }
+  return EXIT.ok;
+}
+var cell = (s) => s.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+function scenariosMarkdown(run, meta) {
+  const lines = [
+    `### NanoFlags scenarios: ${run.failed === 0 ? "passed" : "FAILED"}`,
+    "",
+    `**${run.passed} passed, ${run.failed} failed** \xB7 source \`${run.source}\`${run.checksum ? ` \xB7 checksum \`${run.checksum}\`` : ""}${run.publishedRevision != null ? ` \xB7 published r${run.publishedRevision}` : ""}${meta.commit ? ` \xB7 commit \`${meta.commit.slice(0, 12)}\`` : ""}`,
+    ""
+  ];
+  if (run.results.length === 0) lines.push("No scenarios are included in CI for this project.");
+  else {
+    lines.push("| Result | Scenario | Flag | Expected | Actual | Reason |", "| --- | --- | --- | --- | --- | --- |");
+    for (const s of run.results) lines.push(`| ${s.passed ? "pass" : "**FAIL**"} | ${cell(s.name)} | \`${cell(s.flag)}\` | \`${cell(show(s.expected))}\` | \`${cell(show(s.actual))}\` | ${cell(s.reason ?? "")} |`);
+  }
+  return `${lines.join("\n")}
+
+`;
+}
+async function cmdScenariosRun(r) {
+  const source = r.values.source ?? "draft";
+  if (source !== "draft" && source !== "revision") throw usage(`--source must be draft or revision, got "${source}".`);
+  const commit = r.values.commit || r.io.env.GITHUB_SHA;
+  const runUrl = r.values["run-url"] || (r.io.env.GITHUB_SERVER_URL && r.io.env.GITHUB_REPOSITORY && r.io.env.GITHUB_RUN_ID ? `${r.io.env.GITHUB_SERVER_URL}/${r.io.env.GITHUB_REPOSITORY}/actions/runs/${r.io.env.GITHUB_RUN_ID}` : void 0);
+  const k = key(r);
+  let run;
+  try {
+    run = await api(r).runScenarios({ source, ...commit ? { commit } : {}, ...runUrl ? { runUrl } : {} });
+  } catch (e) {
+    throw explain(e, k, "run scenarios");
+  }
+  if (!run || !Array.isArray(run.results)) throw new CliError("The scenario run has an unexpected shape.", EXIT.unavailable);
+  const failed = Math.max(Number(run.failed) || 0, run.results.filter((s) => !s.passed).length);
+  const passed = run.results.filter((s) => s.passed).length;
+  const normalized = { ...run, passed, failed };
+  if (r.values.json) r.io.out(`${JSON.stringify(normalized, null, 2)}
+`);
+  else {
+    if (run.results.length === 0) r.io.out("No scenarios are included in CI for this project.\n");
+    else r.io.out(`${table(["RESULT", "SCENARIO", "FLAG", "EXPECTED", "ACTUAL", "REASON"], run.results.map((s) => [s.passed ? "pass" : "FAIL", clip(s.name, 48), s.flag, clip(show(s.expected), 32), clip(show(s.actual), 32), s.reason ?? ""]))}
+`);
+    r.io.out(`
+${passed} passed, ${failed} failed \xB7 source ${run.source}${run.checksum ? ` \xB7 checksum ${run.checksum}` : ""}${run.publishedRevision != null ? ` \xB7 published r${run.publishedRevision}` : ""}
+`);
+  }
+  const summary = r.io.env.GITHUB_STEP_SUMMARY;
+  if (summary) {
+    try {
+      appendFileSync(summary, scenariosMarkdown(normalized, { ...commit ? { commit } : {}, ...runUrl ? { runUrl } : {} }));
+    } catch (e) {
+      r.io.err(`Could not write the job summary: ${e instanceof Error ? e.message : String(e)}
+`);
+    }
+  }
+  if (failed > 0) {
+    r.io.err(`${failed} scenario${failed === 1 ? "" : "s"} failed.
+`);
+    return EXIT.failed;
+  }
+  return EXIT.ok;
+}
+var PUBLISH_HELP = {
+  DESTINATION_CHANGED: "Someone published in the meantime. Review the new revision, then run again with its number as --expected-revision.",
+  CHANGE_REQUIRED: "This environment only accepts reviewed changes. Publish it from the dashboard; an admin key cannot bypass review.",
+  SCENARIOS_REQUIRED: "Run `nanoflags scenarios run --source draft` and fix the failing scenarios (or the draft), then publish again.",
+  NO_CHANGES: "There is nothing to publish."
+};
+async function cmdPublish(r) {
+  const raw = r.values["expected-revision"];
+  if (raw === void 0 || !/^\d+$/.test(raw)) throw usage("publish needs --expected-revision <n>: the revision you believe is currently published (see `nanoflags export`). It prevents publishing over someone else's change.");
+  const k = key(r);
+  const kind = keyKind(k);
+  if (kind !== "admin" && kind !== "unknown") throw usage(`publish needs an admin key; this is a ${kind} key. ${kind === "ci" ? "CI keys can run scenarios and upload references, never publish." : ""}`.trim());
+  try {
+    const res = await api(r).publish({ expectedRevision: Number(raw), ...r.values.note ? { note: r.values.note } : {} });
+    if (r.values.json) r.io.out(`${JSON.stringify(res, null, 2)}
+`);
+    else r.io.out(`Published r${res.revision} (checksum ${res.checksum}).
+`);
+    return EXIT.ok;
+  } catch (e) {
+    const err = e;
+    const help = typeof err.code === "string" ? PUBLISH_HELP[err.code] : void 0;
+    if (help) {
+      r.io.err(`Publish refused: ${err.message ?? err.code} [${err.code}]
+${help}
+`);
+      return EXIT.failed;
+    }
+    throw explain(e, k, "publish");
+  }
+}
+function directory(r, arg) {
+  const dir = path(r, arg ?? ".");
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) throw usage(`Not a directory: ${arg ?? "."}`);
+  return dir;
+}
+function maxBytes(r) {
+  const raw = r.values["max-file-size"];
+  if (raw === void 0) return DEFAULT_MAX_FILE_BYTES;
+  if (!/^\d+$/.test(raw) || Number(raw) <= 0) throw usage("--max-file-size must be a positive number of bytes.");
+  return Number(raw);
+}
+var MAX_REFS = 5e3;
+async function cmdRefsScan(r) {
+  if (r.args.length > 1) throw usage("Usage: nanoflags refs scan [dir] --repo <owner/name> [--commit <sha>] [--dry-run]");
+  const dry = r.values["dry-run"] === true;
+  const repo = r.values.repo || r.io.env.GITHUB_REPOSITORY || void 0;
+  if (!dry && !repo) throw usage("refs scan needs --repo <owner/name> (or run with --dry-run).");
+  if (repo !== void 0 && !/^[\w.-]+\/[\w.-]+$/.test(repo)) throw usage(`--repo must look like owner/name, got "${repo}".`);
+  const commit = r.values.commit || r.io.env.GITHUB_SHA || null;
+  const dir = directory(r, r.args[0]);
+  const data = await loadExport(r);
+  const keys = new Set(data.flags.map((f) => f.key));
+  const { scanText } = await import("./refs-CYG6GHJL.js");
+  const { files, tooLarge } = walk(dir, maxBytes(r));
+  const refs = [];
+  for (const file of files) {
+    let text;
+    try {
+      text = readFileSync(join(dir, file), "utf8");
+    } catch {
+      continue;
+    }
+    refs.push(...scanText(file, text, keys));
+  }
+  for (const f of tooLarge) r.io.err(`Skipped ${f}: larger than the file size cap.
+`);
+  const truncated = refs.length > MAX_REFS;
+  const upload = truncated ? refs.slice(0, MAX_REFS) : refs;
+  if (truncated) r.io.err(`Found ${refs.length} references; only the first ${MAX_REFS} are uploaded.
+`);
+  const flagsSeen = new Set(refs.map((x) => x.flag));
+  if (r.values.json) r.io.out(`${JSON.stringify({ repo: repo ?? null, commit, files: files.length, refs: upload }, null, 2)}
+`);
+  else {
+    if (refs.length > 0) r.io.out(`${table(["FLAG", "LOCATION", "CODE"], refs.map((x) => [x.flag, `${x.path}:${x.line}`, clip(x.snippet, 80)]))}
+
+`);
+    r.io.out(`${refs.length} reference${refs.length === 1 ? "" : "s"} to ${flagsSeen.size} of ${keys.size} flags in ${files.length} files.
+`);
+  }
+  if (dry) {
+    r.io.err("Dry run: nothing was uploaded.\n");
+    return EXIT.ok;
+  }
+  const k = key(r);
+  try {
+    const res = await api(r).putCodeRefs({ repo, commit, refs: upload });
+    r.io.err(`Uploaded: ${res.stored} reference${res.stored === 1 ? "" : "s"} stored for ${repo}${commit ? ` at ${commit.slice(0, 12)}` : ""}. Earlier references for this repository were replaced.
+`);
+  } catch (e) {
+    throw explain(e, k, "upload code references");
+  }
+  return EXIT.ok;
+}
+function matchesType(type, v) {
+  if (type === "boolean") return typeof v === "boolean";
+  if (type === "string") return typeof v === "string";
+  if (type === "number") return typeof v === "number";
+  return true;
+}
+async function cmdCleanup(r) {
+  const flag = r.args[0];
+  if (!flag || r.args.length > 2) throw usage("Usage: nanoflags cleanup <flag> --value <json> [dir] [--write]");
+  if (r.values.value === void 0) throw usage(`cleanup needs --value <json>: the value the flag is permanently resolved to, e.g. --value true or --value '"v2"'.`);
+  const value = parseJson(r.values.value, "--value");
+  const dir = directory(r, r.args[1]);
+  const data = await loadExport(r);
+  const meta = data.flags.find((f) => f.key === flag);
+  if (!meta) throw usage(`Unknown flag "${flag}" in project ${data.project.key}.`);
+  if (meta.permanent) {
+    throw new CliError(`"${flag}" is marked permanent (${meta.purpose ?? "long-lived"}): it is meant to stay in code. Nothing was changed.
+If it really should go, clear "permanent" on the flag in the dashboard first.`, EXIT.usage);
+  }
+  if (!matchesType(meta.type, value)) throw usage(`"${flag}" is a ${meta.type} flag; --value ${r.values.value} is not a ${meta.type}.`);
+  const write = r.values.write === true;
+  const { cleanupText } = await import("./cleanup-QYR3DM6S.js");
+  const { files, tooLarge } = walk(dir, maxBytes(r));
+  const transformed = [];
+  const skipped = [];
+  const unreachable = [];
+  let changedFiles = 0;
+  for (const file of files) {
+    const full = join(dir, file);
+    let text;
+    try {
+      text = readFileSync(full, "utf8");
+    } catch {
+      continue;
+    }
+    if (!text.includes(flag)) continue;
+    const res = cleanupText(file, text, flag, value);
+    transformed.push(...res.transformed.map((s) => ({ ...s, path: file })));
+    unreachable.push(...res.unreachable.map((s) => ({ ...s, path: file })));
+    skipped.push(...res.skipped.map((s) => ({ ...s, path: file })));
+    if (res.output === text) continue;
+    changedFiles++;
+    if (write) writeFileSync(full, res.output);
+    else r.io.out(unifiedDiff(file, text, res.output));
+  }
+  for (const f of tooLarge) r.io.err(`Skipped ${f}: larger than the file size cap.
+`);
+  const e = r.io.err;
+  e(`
+${flag} \u2192 ${JSON.stringify(value)}
+`);
+  e(`${write ? "Rewrote" : "Would rewrite"} ${transformed.length} reference${transformed.length === 1 ? "" : "s"} in ${changedFiles} file${changedFiles === 1 ? "" : "s"}.
+`);
+  for (const s of transformed) e(`  ${s.path}:${s.line}  ${clip(s.snippet, 100)}
+`);
+  if (skipped.length > 0) {
+    e(`
+NOT transformed (${skipped.length}) \u2014 review these by hand:
+`);
+    for (const s of skipped) e(`  ${s.path}:${s.line}  ${clip(s.snippet, 100)}
+      ${s.reason}${s.removed ? " (it was inside code that this cleanup removes)" : ""}
+`);
+  }
+  if (unreachable.length > 0) {
+    e(`
+Now unreachable (${unreachable.length}) \u2014 code after a return/throw that the cleanup exposed; delete it if it is no longer needed (line numbers after the cleanup):
+`);
+    for (const s of unreachable) e(`  ${s.path}:${s.line}  ${clip(s.snippet, 100)}
+`);
+  }
+  if (transformed.length === 0 && skipped.length === 0) e("No references found. Only calls with the flag key as a string literal are recognised.\n");
+  e(
+    write ? "\nFiles were edited in place. Nothing was committed or pushed: review the changes (git diff), run your tests, then commit.\n" : "\nDry run: no file was changed. Re-run with --write to apply. This command never commits, pushes or opens pull requests.\n"
+  );
+  return EXIT.ok;
+}
+async function main(argv, io) {
+  let values;
+  let positionals;
+  try {
+    const parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
+    values = parsed.values;
+    positionals = parsed.positionals;
+  } catch (e) {
+    io.err(`${e instanceof Error ? e.message : String(e)}
+Run \`nanoflags --help\` for usage.
+`);
+    return EXIT.usage;
+  }
+  if (values.version) {
+    io.out(`${VERSION}
+`);
+    return EXIT.ok;
+  }
+  const [command, sub] = positionals;
+  if (values.help || command === void 0 || command === "help") {
+    io.out(HELP);
+    return command === void 0 && !values.help ? EXIT.usage : EXIT.ok;
+  }
+  const run = (skip) => ({ io, values, args: positionals.slice(skip) });
+  try {
+    if (command === "export") return await cmdExport(run(1));
+    if (command === "flags" && sub === "list") return await cmdFlagsList(run(2));
+    if (command === "flags" && sub === "create") return await cmdFlagsCreate(run(2));
+    if (command === "eval") return await cmdEval(run(1));
+    if (command === "scenarios" && sub === "run") return await cmdScenariosRun(run(2));
+    if (command === "publish") return await cmdPublish(run(1));
+    if (command === "refs" && sub === "scan") return await cmdRefsScan(run(2));
+    if (command === "cleanup") return await cmdCleanup(run(1));
+    throw usage(`Unknown command: ${positionals.slice(0, 2).join(" ")}`);
+  } catch (e) {
+    if (e instanceof CliError) {
+      io.err(`${e.message}
+`);
+      return e.exitCode;
+    }
+    io.err(`Unexpected error: ${e instanceof Error ? e.stack ?? e.message : String(e)}
+`);
+    return EXIT.failed;
+  }
+}
+
+// src/bin.ts
+main(process.argv.slice(2), {
+  env: process.env,
+  cwd: process.cwd(),
+  fetch: (input, init) => fetch(input, init),
+  out: (text) => void process.stdout.write(text),
+  err: (text) => void process.stderr.write(text)
+}).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (e) => {
+    process.stderr.write(`${e instanceof Error ? e.message : String(e)}
+`);
+    process.exitCode = 1;
+  }
+);