@groundfloorcloud/cli 0.1.10 → 0.1.12

package/README.md

@@ -1,7 +1,7 @@
 # `@groundfloorcloud/cli` (`gf`)
 
 Sign in to Groundfloor, manage workspaces, and work with Coderunner,
-secrets, files, apps, and Dataplane from your terminal.
+secrets, feature flags, files, apps, and Dataplane from your terminal.
 
 `gf login` opens a browser, you sign in, and the session is cached and
 refreshed automatically.
@@ -226,6 +226,27 @@ gf apps ls
 gf apps get <id|slug>
 ```
 
+## Feature flags
+
+Per-environment toggles and config values. `-e` takes an environment id or name
+(`dev`, `staging`, `prod`); without it the workspace default (`dev`) is used.
+
+```bash
+gf flags ls -e prod
+gf flags set new-checkout true -e dev          # boolean (inferred)
+gf flags set max-items 25 -e dev               # number (inferred)
+gf flags set banner '{"text":"Hi"}' --type json -e dev
+gf flags get new-checkout -e prod
+gf flags compare dev prod
+gf flags promote dev prod --dry-run            # then without --dry-run
+gf flags rm new-checkout -e dev
+```
+
+Keys are lowercase letters, digits, `-`, `_` and `.`, starting with a letter.
+Apps read flags at runtime from `GET /v1/workspaces/{id}/flags/runtime`: Shell
+apps with the end-user token, Coderunners with `gf m2m token` (read-only). See
+https://docs.groundfloor.cloud/docs/configure/feature-flags.
+
 ## Commands
 
 | Command | Description |
@@ -247,6 +268,7 @@ gf apps get <id|slug>
 | `gf deploy` | Package code and deploy as a coderunner. |
 | `gf domains ls\|add\|rm\|verify -c <id\|slug>` | Custom domains for a service. |
 | `gf secrets ls\|get\|set\|rm` | Workspace secrets. |
+| `gf flags ls\|get\|set\|rm\|compare\|promote` | Feature flags per environment (`-e <id\|name>`). |
 | `gf files ls\|upload\|download\|rm` | Workspace files. |
 | `gf apps init --slug <slug>` | Download the official Shell starter-kit and stamp APP_ID. |
 | `gf apps ls\|get\|create\|publish` | Product apps (Shell publish / standalone wrap). |
@@ -287,7 +309,7 @@ sign-in fails with an invalid redirect URI:
 ## More
 
 - [Customer Portal](https://app.groundfloor.cloud)
-- [Developers](https://docs.groundfloor.cloud/docs/customer-portal/developers)
-- [Deploy with agents](https://docs.groundfloor.cloud/docs/customer-portal/agents)
-- [Coderunner](https://docs.groundfloor.cloud/docs/customer-portal/coderunner)
+- [Developers](https://docs.groundfloor.cloud/docs/developer-tools/cli)
+- [Deploy with agents](https://docs.groundfloor.cloud/docs/developer-tools/ai-agents)
+- [Coderunner](https://docs.groundfloor.cloud/docs/deploy)
 - [API authentication](https://docs.groundfloor.cloud/docs/api/authentication)

package/dist/index.js

@@ -850,6 +850,53 @@ function deleteSecret(apiUrl, workspaceId, key, environmentId) {
     })}`
   );
 }
+function listFlags(apiUrl, workspaceId, environmentId) {
+  return cpGet(
+    apiUrl,
+    `${wsPath(workspaceId, "/flags")}${queryString({ environment_id: environmentId })}`
+  );
+}
+function getFlag(apiUrl, workspaceId, key, environmentId) {
+  return cpGet(
+    apiUrl,
+    `${wsPath(workspaceId, `/flags/${encodeURIComponent(key)}`)}${queryString({
+      environment_id: environmentId
+    })}`
+  );
+}
+function putFlag(apiUrl, workspaceId, key, payload, environmentId) {
+  return cpPutJson(
+    apiUrl,
+    `${wsPath(workspaceId, `/flags/${encodeURIComponent(key)}`)}${queryString({
+      environment_id: environmentId
+    })}`,
+    payload
+  );
+}
+function deleteFlag(apiUrl, workspaceId, key, environmentId) {
+  return cpDelete(
+    apiUrl,
+    `${wsPath(workspaceId, `/flags/${encodeURIComponent(key)}`)}${queryString({
+      environment_id: environmentId
+    })}`
+  );
+}
+function compareFlags(apiUrl, workspaceId, sourceEnvironmentId, targetEnvironmentId) {
+  return cpGet(
+    apiUrl,
+    `${wsPath(workspaceId, "/flags/compare")}${queryString({
+      source_environment_id: sourceEnvironmentId,
+      target_environment_id: targetEnvironmentId
+    })}`
+  );
+}
+function promoteFlags(apiUrl, workspaceId, body) {
+  return cpPostJson(
+    apiUrl,
+    wsPath(workspaceId, "/flags/promote"),
+    body
+  );
+}
 function listFiles(apiUrl, workspaceId) {
   return cpGet(apiUrl, wsPath(workspaceId, "/files"));
 }
@@ -2395,6 +2442,200 @@ async function secretsRmCommand(key, opts) {
 `);
 }
 
+// src/commands/flags.ts
+var VALUE_TYPES = [
+  "boolean",
+  "string",
+  "number",
+  "json"
+];
+var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function matchEnvironment(environments2, idOrName) {
+  const wanted = idOrName.trim();
+  const byId = environments2.find((env) => env.id === wanted);
+  if (byId) return byId.id;
+  const byName = environments2.filter(
+    (env) => env.name.toLowerCase() === wanted.toLowerCase()
+  );
+  if (byName.length === 1) return byName[0].id;
+  const names2 = environments2.map((env) => env.name).join(", ") || "none";
+  throw new Error(
+    `Environment "${wanted}" not found in this workspace (have: ${names2}). Run \`gf environments ls\`.`
+  );
+}
+async function resolveEnvironment(apiUrl, workspaceId, idOrName) {
+  if (!idOrName) return void 0;
+  if (UUID_RE2.test(idOrName.trim())) return idOrName.trim();
+  const environments2 = await listWorkspaceEnvironments(apiUrl, workspaceId);
+  return matchEnvironment(environments2, idOrName);
+}
+function parseFlagValue(raw, type) {
+  if (type !== void 0 && !VALUE_TYPES.includes(type)) {
+    throw new Error(`--type must be one of: ${VALUE_TYPES.join(", ")}`);
+  }
+  const lower = raw.trim().toLowerCase();
+  const valueType = type ?? (lower === "true" || lower === "false" ? "boolean" : raw.trim() !== "" && Number.isFinite(Number(raw)) ? "number" : "string");
+  switch (valueType) {
+    case "boolean":
+      if (lower !== "true" && lower !== "false") {
+        throw new Error("boolean flags take true or false");
+      }
+      return { value: lower === "true", value_type: "boolean" };
+    case "number": {
+      const n = Number(raw);
+      if (raw.trim() === "" || !Number.isFinite(n)) {
+        throw new Error(`"${raw}" is not a number`);
+      }
+      return { value: n, value_type: "number" };
+    }
+    case "json":
+      try {
+        return { value: JSON.parse(raw), value_type: "json" };
+      } catch {
+        throw new Error("--type json needs a valid JSON value");
+      }
+    default:
+      return { value: raw, value_type: "string" };
+  }
+}
+function formatValue(value) {
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+async function flagsListCommand(opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  const env = await resolveEnvironment(
+    cfg.apiUrl,
+    cfg.workspaceId,
+    opts.environment
+  );
+  const data = await listFlags(cfg.apiUrl, cfg.workspaceId, env);
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+    return;
+  }
+  process.stderr.write(`environment ${data.environment_id}
+`);
+  if (data.flags.length === 0) {
+    process.stdout.write("No flags in this environment.\n");
+    return;
+  }
+  for (const flag of data.flags) {
+    process.stdout.write(
+      `${flag.key}	${flag.value_type}	${formatValue(flag.value)}
+`
+    );
+  }
+}
+async function flagsGetCommand(key, opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  const env = await resolveEnvironment(
+    cfg.apiUrl,
+    cfg.workspaceId,
+    opts.environment
+  );
+  const flag = await getFlag(cfg.apiUrl, cfg.workspaceId, key, env);
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(flag, null, 2)}
+`);
+    return;
+  }
+  process.stdout.write(`${formatValue(flag.value)}
+`);
+}
+async function flagsSetCommand(key, value, opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  const env = await resolveEnvironment(
+    cfg.apiUrl,
+    cfg.workspaceId,
+    opts.environment
+  );
+  const parsed = parseFlagValue(value, opts.type);
+  const saved = await putFlag(
+    cfg.apiUrl,
+    cfg.workspaceId,
+    key,
+    { ...parsed, description: opts.description },
+    env
+  );
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(saved, null, 2)}
+`);
+    return;
+  }
+  process.stdout.write(
+    `Set ${saved.key} = ${formatValue(saved.value)} (${saved.value_type}) in environment ${saved.environment_id}
+`
+  );
+}
+async function flagsRmCommand(key, opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  const env = await resolveEnvironment(
+    cfg.apiUrl,
+    cfg.workspaceId,
+    opts.environment
+  );
+  await deleteFlag(cfg.apiUrl, cfg.workspaceId, key, env);
+  process.stdout.write(`Deleted flag ${key}
+`);
+}
+async function flagsCompareCommand(source, target, opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  const [src, tgt] = await Promise.all([
+    resolveEnvironment(cfg.apiUrl, cfg.workspaceId, source),
+    resolveEnvironment(cfg.apiUrl, cfg.workspaceId, target)
+  ]);
+  const data = await compareFlags(cfg.apiUrl, cfg.workspaceId, src, tgt);
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+    return;
+  }
+  if (data.keys.length === 0) {
+    process.stdout.write("No flags in either environment.\n");
+    return;
+  }
+  for (const row of data.keys) {
+    process.stdout.write(
+      `${row.key}	${row.status}	${formatValue(row.source_value ?? null)} \u2192 ${formatValue(row.target_value ?? null)}
+`
+    );
+  }
+}
+async function flagsPromoteCommand(source, target, opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  const [src, tgt] = await Promise.all([
+    resolveEnvironment(cfg.apiUrl, cfg.workspaceId, source),
+    resolveEnvironment(cfg.apiUrl, cfg.workspaceId, target)
+  ]);
+  const keys = opts.keys?.split(",").map((k) => k.trim()).filter(Boolean);
+  const result = await promoteFlags(cfg.apiUrl, cfg.workspaceId, {
+    source_environment_id: src,
+    target_environment_id: tgt,
+    keys: keys && keys.length > 0 ? keys : void 0,
+    mode: opts.overwrite ? "overwrite" : "skip_existing",
+    dry_run: Boolean(opts.dryRun)
+  });
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
+  }
+  const prefix = result.dry_run ? "[dry run] " : "";
+  process.stdout.write(
+    `${prefix}copied: ${result.copied.join(", ") || "none"}
+${prefix}skipped (already set; use --overwrite): ${result.skipped.join(", ") || "none"}
+`
+  );
+  for (const failure of result.failed) {
+    process.stdout.write(`${prefix}failed: ${failure.key} \u2014 ${failure.error}
+`);
+  }
+  if (result.failed.length > 0) {
+    process.exitCode = 1;
+  }
+}
+
 // src/commands/files.ts
 import { promises as fs5 } from "fs";
 import path6 from "path";
@@ -3459,6 +3700,24 @@ secrets.command("set <key> [value]").description("Create or update a secret (pas
   (key, value, opts) => run(() => secretsSetCommand(key, value, opts))
 );
 secrets.command("rm <key>").alias("delete").description("Delete a secret").option("-w, --workspace <id>", "Workspace id override").option("-e, --environment <id>", "Environment id").action((key, opts) => run(() => secretsRmCommand(key, opts)));
+var flags = program.command("flags").description(
+  "Manage feature flags per environment (apps read them via GET \u2026/flags/runtime)"
+);
+var ENV_HELP = "Environment id or name (dev, staging, prod). Default: workspace default (dev)";
+flags.command("ls").alias("list").description("List flags and values in an environment").option("-w, --workspace <id>", "Workspace id override").option("-e, --environment <idOrName>", ENV_HELP).option("--json", "Output raw JSON").action((opts) => run(() => flagsListCommand(opts)));
+flags.command("get <key>").description("Print a flag value").option("-w, --workspace <id>", "Workspace id override").option("-e, --environment <idOrName>", ENV_HELP).option("--json", "Output raw JSON").action((key, opts) => run(() => flagsGetCommand(key, opts)));
+flags.command("set <key> <value>").description(
+  "Create or update a flag (type inferred: true/false \u2192 boolean, numeric \u2192 number, else string)"
+).option("-w, --workspace <id>", "Workspace id override").option("-e, --environment <idOrName>", ENV_HELP).option("-t, --type <type>", "boolean | string | number | json").option("--description <text>", "Optional description (max 255 chars)").option("--json", "Output raw JSON").action(
+  (key, value, opts) => run(() => flagsSetCommand(key, value, opts))
+);
+flags.command("rm <key>").alias("delete").description("Delete a flag from one environment").option("-w, --workspace <id>", "Workspace id override").option("-e, --environment <idOrName>", ENV_HELP).action((key, opts) => run(() => flagsRmCommand(key, opts)));
+flags.command("compare <source> <target>").alias("diff").description("Diff flags between two environments (ids or names)").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action(
+  (source, target, opts) => run(() => flagsCompareCommand(source, target, opts))
+);
+flags.command("promote <source> <target>").description("Copy flags from one environment to another").option("-w, --workspace <id>", "Workspace id override").option("-k, --keys <keys>", "Comma-separated keys (default: all)").option("--overwrite", "Replace values already set in the target").option("--dry-run", "Show what would change without writing").option("--json", "Output raw JSON").action(
+  (source, target, opts) => run(() => flagsPromoteCommand(source, target, opts))
+);
 var files = program.command("files").description("Manage workspace files");
 files.command("ls").alias("list").description("List files").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action((opts) => run(() => filesListCommand(opts)));
 files.command("upload <path>").description("Upload a local file").option("-w, --workspace <id>", "Workspace id override").option("-n, --name <name>", "Display name (default: basename)").action(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundfloorcloud/cli",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Groundfloor gf CLI — sign in, deploy coderunners, publish Shell apps, and manage secrets, files, and Dataplane.",
   "type": "module",
   "bin": {
@@ -18,7 +18,7 @@
     "url": "git+ssh://git@bitbucket.org/codementeam/groundfloor-client-portal.git",
     "directory": "packages/cli"
   },
-  "homepage": "https://docs.groundfloor.cloud/docs/customer-portal/developers",
+  "homepage": "https://docs.groundfloor.cloud/docs/developer-tools/cli",
   "keywords": [
     "groundfloor",
     "cli",