@nanoflags/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @nanoflags/cli
 
-Command line for NanoFlags: export a project, evaluate flags locally, run scenario checks in CI,
+Command line for NanoFlags: export a project, create flags, evaluate flags locally, run scenario checks in CI,
 publish, upload flag code references, and remove resolved flags from code.
 
 ```sh
@@ -19,7 +19,7 @@ workflow (`.github/workflows/release.yml`, tag `cli-v<version>`).
 
 | | |
 | --- | --- |
-| `NANOFLAGS_KEY` / `--key` | A **CI key** (`nf_ci_…`: export, scenarios, code references) or an **admin key** (`nf_adm_…`: all of that, plus publish). SDK keys are refused by these endpoints. Prefer the environment variable — arguments are visible in process lists and shell history. |
+| `NANOFLAGS_KEY` / `--key` | A **CI key** (`nf_ci_…`: export, scenarios, code references) or an **admin key** (`nf_adm_…`: all of that, plus `flags create` and publish). SDK keys are refused by these endpoints. Prefer the environment variable — arguments are visible in process lists and shell history. |
 | `NANOFLAGS_BASE_URL` / `--base-url` | Edge URL. Default `https://edge.nanoflags.io`. Must be `https` (plain `http` only for `localhost`). |
 | `NANOFLAGS_SDK_KEY` / `--sdk-key` | Optional, only for `eval --source published`: a server SDK key; reads `/v1/bundle` instead of `/v1/ci/published`. |
 
@@ -50,6 +50,31 @@ The saved file can be passed to other commands with `--export <file>` to work of
 Table of the project's flags: key, type, purpose, lifetime (permanent/temporary), client exposure, and
 on/off in the draft of the key's environment.
 
+### `nanoflags flags create <key> --type boolean|string|number|json [--default <json>] [--description <text>] [--name <text>] [--json]`
+
+`POST /v1/admin/flags` — creates a flag in the key's project. **Admin key only** (a CI key is refused
+before any request). Nothing is published: every environment's **draft** starts with the default value,
+and the flag reaches SDKs only with the next publish.
+
+```sh
+nanoflags flags create new-checkout --description "New checkout flow"            # boolean, default false
+nanoflags flags create theme --type string --default blue --name "Theme"         # bare word = string
+nanoflags flags create search-limit --type number --default 25
+nanoflags flags create ranker --type json --default '{"model":"v2","weights":[1,2]}'
+```
+
+- `--type` defaults to `boolean`; `--default` defaults to `false` for boolean flags and is required otherwise.
+- `--default` is JSON and must match the type. For string flags a value that is not JSON is taken as the
+  string itself (`--default blue` = `--default '"blue"'`).
+- The key follows the dashboard rules: lowercase letters, digits, `-` and `_`, starting with a letter or digit, at most 63.
+- `--name` defaults to the key. Purpose, owner, review date and client exposure are set in the dashboard.
+- The creation is recorded in the project's activity log with the key's name.
+
+| Refusal (exit 1) | Meaning |
+| --- | --- |
+| `CONFLICT` | A flag with this key already exists in the project. |
+| `INVALID_VALUE` | The default does not match the flag type. |
+
 ### `nanoflags eval <flag> [--context <json>] [--source draft|published] [--fallback <json>] [--environment <key>] [--json]`
 
 Evaluates one flag **locally** with the NanoFlags engine — the same code the SDKs and the edge run —

package/dist/bin.js

@@ -258,6 +258,10 @@ var Api = class {
   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);
   }
@@ -276,7 +280,7 @@ function explain(e, key2, what) {
 }
 
 // src/main.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 var HELP = `nanoflags ${VERSION} \u2014 NanoFlags command line
 
 Usage: nanoflags <command> [options]
@@ -284,6 +288,8 @@ 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]
@@ -318,6 +324,10 @@ var OPTIONS = {
   "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" },
@@ -413,6 +423,66 @@ async function cmdFlagsList(r) {
 `);
   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;
@@ -731,6 +801,7 @@ Run \`nanoflags --help\` for usage.
   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));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nanoflags/cli",
-  "version": "0.1.0",
-  "description": "NanoFlags command line: export, local evaluation, CI scenario checks, publishing, code references and flag cleanup.",
+  "version": "0.2.0",
+  "description": "NanoFlags command line: export, flag creation, local evaluation, CI scenario checks, publishing, code references and flag cleanup.",
   "keywords": [
     "nanoflags",
     "feature-flags",