flaghoist 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Damilola Oluwafemi and the Flaghoist contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,13 +1,52 @@
 # flaghoist
 
-**Reserved.** This name belongs to the [Flaghoist](https://github.com/flaghoist/flaghoist)
-project — an open-source, OpenFeature-native feature-flag service you self-host in five minutes,
-for $0.
+Feature flags you run yourself. This is the command line tool for setting up a Flaghoist server and
+managing the flags on it.
 
-The real `flaghoist` CLI — scaffold, deploy, and manage your own flag service — publishes here
-soon. In the meantime:
+Your whole project is one `flaghoist.toml` file. The CLI turns that into a Cloudflare Worker, or
+hands you the code if you would rather own it.
 
-- **Repo:** https://github.com/flaghoist/flaghoist
-- **Packages:** the [`@flaghoist`](https://www.npmjs.com/org/flaghoist) scope
+```bash
+npm create flaghoist@latest team-flags
+cd team-flags
+npx flaghoist deploy
+```
 
-Apache-2.0.
+That gives you an OFREP read API, an admin API, and a dashboard at `/admin`, all from a single
+deploy. On Cloudflare KV, the first deploy also creates the KV namespace for you and writes its id
+into `wrangler.toml`.
+
+## Managing flags
+
+Point the CLI at your server with `--url` and `--token`, or set `FLAGS_URL` and
+`FLAGS_ADMIN_TOKEN`.
+
+```bash
+flaghoist flag list
+flaghoist flag create new-checkout --desc "The redesigned checkout"
+flaghoist flag toggle new-checkout --on
+flaghoist flag rollout new-checkout 25
+```
+
+Rollouts are sticky. A user who lands inside 25 percent stays inside it as you go to 50, so nobody
+flickers in and out between deploys.
+
+## Owning the code
+
+```bash
+npx flaghoist eject
+```
+
+Writes `src/index.ts`, `wrangler.toml` and `package.json` into your project. From there it is a
+normal Worker and the CLI steps out of the way.
+
+Flags are boolean only. There are no multivariate flags, experiments or scheduled rules, and there
+is no plan to imply otherwise.
+
+## Status
+
+Pre-alpha, built and maintained by one person. The API can still change without notice, and
+production use is not recommended yet. If you try it and something breaks, an issue is genuinely
+useful.
+
+Apache-2.0. Part of [Flaghoist](https://github.com/flaghoist/flaghoist).

package/dist/chunk-S4XXPMMW.js

@@ -0,0 +1,51 @@
+// src/config.ts
+import { parse } from "smol-toml";
+var DEFAULT_CONFIG = {
+  name: "team-flags",
+  storage: "cloudflare-kv",
+  auth: { admin: "bearer-token", read: "api-key" },
+  dashboard: true
+};
+var STORAGE_KINDS = [
+  "cloudflare-kv",
+  "redis",
+  "postgres",
+  "memory"
+];
+function parseConfig(text) {
+  const raw = parse(text);
+  const name = typeof raw.name === "string" && raw.name ? raw.name : DEFAULT_CONFIG.name;
+  const storage = STORAGE_KINDS.includes(raw.storage) ? raw.storage : DEFAULT_CONFIG.storage;
+  const authRaw = typeof raw.auth === "object" && raw.auth !== null ? raw.auth : {};
+  const admin = authRaw.admin === "oidc" ? "oidc" : "bearer-token";
+  const allowedOrigins = Array.isArray(raw.allowedOrigins) ? raw.allowedOrigins.filter((x) => typeof x === "string") : void 0;
+  const dashboard = raw.dashboard !== false;
+  return { name, storage, auth: { admin, read: "api-key" }, allowedOrigins, dashboard };
+}
+function serializeConfig(config) {
+  const lines = [
+    `name = ${JSON.stringify(config.name)}`,
+    `storage = ${JSON.stringify(config.storage)}`
+  ];
+  if (config.allowedOrigins && config.allowedOrigins.length > 0) {
+    lines.push(`allowedOrigins = ${JSON.stringify(config.allowedOrigins)}`);
+  }
+  if (!config.dashboard) {
+    lines.push("dashboard = false");
+  }
+  lines.push(
+    "",
+    "[auth]",
+    `admin = ${JSON.stringify(config.auth.admin)}`,
+    `read = ${JSON.stringify(config.auth.read)}`
+  );
+  return `${lines.join("\n")}
+`;
+}
+
+export {
+  DEFAULT_CONFIG,
+  STORAGE_KINDS,
+  parseConfig,
+  serializeConfig
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,431 @@
+#!/usr/bin/env node
+import {
+  DEFAULT_CONFIG,
+  STORAGE_KINDS,
+  parseConfig,
+  serializeConfig
+} from "./chunk-S4XXPMMW.js";
+
+// src/index.ts
+import { spawnSync } from "child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { parseArgs } from "util";
+
+// src/admin.ts
+function createAdminClient(options) {
+  const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
+  const api = `${options.url.replace(/\/+$/, "")}/api/v1`;
+  const headers = {
+    authorization: `Bearer ${options.token}`,
+    "content-type": "application/json"
+  };
+  const path = (key) => `${api}/flags/${encodeURIComponent(key)}`;
+  return {
+    async list() {
+      const res = await doFetch(`${api}/flags`, { headers });
+      if (!res.ok) throw new Error(`Failed to list flags (${res.status})`);
+      return (await res.json()).flags;
+    },
+    async get(key) {
+      const res = await doFetch(path(key), { headers });
+      if (res.status === 404) return null;
+      if (!res.ok) throw new Error(`Failed to read flag "${key}" (${res.status})`);
+      return await res.json();
+    },
+    async put(key, input) {
+      const res = await doFetch(path(key), { method: "PUT", headers, body: JSON.stringify(input) });
+      if (!res.ok)
+        throw new Error(`Failed to save flag "${key}" (${res.status}): ${await res.text()}`);
+      return await res.json();
+    },
+    async delete(key) {
+      const res = await doFetch(path(key), { method: "DELETE", headers });
+      if (!res.ok && res.status !== 404)
+        throw new Error(`Failed to delete flag "${key}" (${res.status})`);
+    }
+  };
+}
+function requireFlag(flag, key) {
+  if (!flag) throw new Error(`Flag "${key}" not found`);
+  return flag;
+}
+function createFlag(client, key, opts) {
+  return client.put(key, {
+    enabled: opts.enabled ?? false,
+    rollout: { percentage: opts.percentage ?? 0 },
+    rules: [],
+    description: opts.description ?? ""
+  });
+}
+async function toggleFlag(client, key, to) {
+  const flag = requireFlag(await client.get(key), key);
+  const enabled = to === "flip" ? !flag.enabled : to;
+  return client.put(key, {
+    enabled,
+    rollout: flag.rollout,
+    rules: flag.rules,
+    description: flag.description
+  });
+}
+async function setRollout(client, key, percentage) {
+  const flag = requireFlag(await client.get(key), key);
+  return client.put(key, {
+    enabled: flag.enabled,
+    rollout: { percentage },
+    rules: flag.rules,
+    description: flag.description
+  });
+}
+async function setRules(client, key, rules) {
+  const flag = requireFlag(await client.get(key), key);
+  return client.put(key, {
+    enabled: flag.enabled,
+    rollout: flag.rollout,
+    rules,
+    description: flag.description
+  });
+}
+
+// src/generate.ts
+function storageSnippet(storage) {
+  switch (storage) {
+    case "cloudflare-kv":
+      return {
+        imports: [`import { cloudflareKV } from '@flaghoist/adapter-cloudflare-kv'`],
+        expr: "cloudflareKV(env.FLAGS)",
+        pkg: "@flaghoist/adapter-cloudflare-kv"
+      };
+    case "redis":
+      return {
+        imports: [
+          `import { redisAdapter } from '@flaghoist/adapter-redis'`,
+          `import { Redis } from '@upstash/redis/cloudflare'`
+        ],
+        expr: "redisAdapter(Redis.fromEnv(env))",
+        pkg: "@flaghoist/adapter-redis",
+        extraDeps: { "@upstash/redis": "^1.34.0" }
+      };
+    case "postgres":
+      return {
+        imports: [
+          `import { postgresAdapter } from '@flaghoist/adapter-postgres'`,
+          `import { Pool } from 'pg'`
+        ],
+        expr: "postgresAdapter(new Pool({ connectionString: env.DATABASE_URL }))",
+        pkg: "@flaghoist/adapter-postgres",
+        extraDeps: { pg: "^8.13.0" }
+      };
+    case "memory":
+      return {
+        imports: [`import { memoryAdapter } from '@flaghoist/adapter-memory'`],
+        expr: "memoryAdapter()",
+        pkg: "@flaghoist/adapter-memory"
+      };
+  }
+}
+function adminExpr(admin) {
+  return admin === "oidc" ? "oidc({ issuer: env.OIDC_ISSUER, audience: env.OIDC_AUDIENCE, groupsClaim: 'cognito:groups', allowedGroups: (env.ADMIN_GROUPS ?? '').split(',') })" : "bearerToken(env.ADMIN_TOKEN)";
+}
+function generateWorkerEntry(config) {
+  const storage = storageSnippet(config.storage);
+  const serverImports = [
+    "apiKey",
+    "createFlagServer",
+    config.auth.admin === "oidc" ? "oidc" : "bearerToken"
+  ].sort();
+  const imports = [
+    ...storage.imports,
+    `import { ${serverImports.join(", ")} } from '@flaghoist/server'`,
+    // A subpath import, so a Worker built with `dashboard = false` never pulls the HTML in.
+    ...config.dashboard ? [`import { dashboardHtml } from '@flaghoist/server/dashboard'`] : []
+  ].join("\n");
+  const origins = config.allowedOrigins && config.allowedOrigins.length > 0 ? `
+  allowedOrigins: ${JSON.stringify(config.allowedOrigins)},` : "";
+  const dashboard = config.dashboard ? "\n  dashboard: dashboardHtml," : "";
+  return `${imports}
+
+export default createFlagServer((env) => ({
+  storage: ${storage.expr},
+  auth: {
+    admin: ${adminExpr(config.auth.admin)},
+    read: apiKey(env.READ_API_KEY),
+  },${origins}${dashboard}
+}))
+`;
+}
+var KV_NAMESPACE_PLACEHOLDER = "<your-kv-namespace-id>";
+function generateWranglerToml(config) {
+  const lines = [
+    `name = ${JSON.stringify(config.name)}`,
+    `main = "src/index.ts"`,
+    `compatibility_date = "2025-01-01"`
+  ];
+  if (config.storage === "cloudflare-kv") {
+    lines.push(
+      "",
+      "# Created for you by `flaghoist deploy`, or by: npx wrangler kv namespace create FLAGS",
+      "kv_namespaces = [",
+      `  { binding = "FLAGS", id = ${JSON.stringify(KV_NAMESPACE_PLACEHOLDER)} }`,
+      "]"
+    );
+  }
+  return `${lines.join("\n")}
+`;
+}
+function needsKvNamespace(toml) {
+  return toml.includes(KV_NAMESPACE_PLACEHOLDER);
+}
+function fillKvNamespaceId(toml, id) {
+  return toml.replace(/^# Created for you by `flaghoist deploy`.*\n/m, "").replaceAll(KV_NAMESPACE_PLACEHOLDER, id);
+}
+function parseKvNamespaceId(output) {
+  const patterns = [
+    /\bid\s*=\s*"([0-9a-f]{32})"/i,
+    /"id"\s*:\s*"([0-9a-f]{32})"/i,
+    /\b([0-9a-f]{32})\b/i
+  ];
+  for (const re of patterns) {
+    const match = re.exec(output);
+    if (match) return match[1];
+  }
+  return void 0;
+}
+function generatePackageJson(config) {
+  const storage = storageSnippet(config.storage);
+  const dependencies = {
+    "@flaghoist/server": "^0.1.0",
+    [storage.pkg]: "^0.1.0",
+    ...storage.extraDeps
+  };
+  const pkg = {
+    name: config.name,
+    version: "0.0.0",
+    private: true,
+    type: "module",
+    scripts: { dev: "wrangler dev", deploy: "wrangler deploy" },
+    dependencies,
+    devDependencies: { wrangler: "^4.0.0" }
+  };
+  return `${JSON.stringify(pkg, null, 2)}
+`;
+}
+
+// src/version.ts
+import { createRequire } from "module";
+var VERSION = createRequire(import.meta.url)("../package.json").version;
+
+// src/index.ts
+function writeFileSafe(path, content) {
+  mkdirSync(dirname(path) || ".", { recursive: true });
+  writeFileSync(path, content);
+}
+function loadConfig() {
+  if (!existsSync("flaghoist.toml")) {
+    throw new Error("No flaghoist.toml found in this directory. Run `flaghoist init` first.");
+  }
+  return parseConfig(readFileSync("flaghoist.toml", "utf8"));
+}
+function clientFrom(values) {
+  const url = values.url ?? process.env.FLAGS_URL;
+  const token = values.token ?? process.env.FLAGS_ADMIN_TOKEN;
+  if (!url) throw new Error("Missing server URL. Pass --url or set FLAGS_URL.");
+  if (!token) throw new Error("Missing admin token. Pass --token or set FLAGS_ADMIN_TOKEN.");
+  return createAdminClient({ url, token });
+}
+function flagState(flag) {
+  if (!flag.enabled) return "disabled";
+  const pct = flag.rollout.percentage;
+  return pct >= 100 ? "on" : pct <= 0 ? "off" : `${pct}%`;
+}
+function printFlag(flag) {
+  const rules = flag.rules && flag.rules.length > 0 ? ` \xB7 ${flag.rules.length} rule(s)` : "";
+  console.log(`${flag.key.padEnd(28)} ${flagState(flag).padEnd(10)}${rules}`);
+}
+async function runFlag(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    options: {
+      url: { type: "string" },
+      token: { type: "string" },
+      on: { type: "boolean" },
+      off: { type: "boolean" },
+      rollout: { type: "string" },
+      desc: { type: "string" },
+      file: { type: "string" }
+    }
+  });
+  const [sub, a, b] = positionals;
+  switch (sub) {
+    case "list": {
+      const flags = await clientFrom(values).list();
+      if (flags.length === 0) return console.log("No flags.");
+      for (const flag of flags.sort((x, y) => x.key.localeCompare(y.key))) printFlag(flag);
+      return;
+    }
+    case "get": {
+      if (!a) throw new Error("Usage: flaghoist flag get <key>");
+      const flag = await clientFrom(values).get(a);
+      if (!flag) {
+        console.error(`Flag "${a}" not found`);
+        process.exit(1);
+      }
+      return console.log(JSON.stringify(flag, null, 2));
+    }
+    case "create": {
+      if (!a)
+        throw new Error('Usage: flaghoist flag create <key> [--on] [--rollout N] [--desc "..."]');
+      const flag = await createFlag(clientFrom(values), a, {
+        enabled: values.on ?? false,
+        percentage: values.rollout != null ? Number(values.rollout) : 0,
+        description: values.desc
+      });
+      console.log(`Created "${a}"`);
+      return printFlag(flag);
+    }
+    case "toggle": {
+      if (!a) throw new Error("Usage: flaghoist flag toggle <key> [--on|--off]");
+      const to = values.on ? true : values.off ? false : "flip";
+      return printFlag(await toggleFlag(clientFrom(values), a, to));
+    }
+    case "rollout": {
+      if (!a || b == null) throw new Error("Usage: flaghoist flag rollout <key> <percentage>");
+      return printFlag(await setRollout(clientFrom(values), a, Number(b)));
+    }
+    case "delete": {
+      if (!a) throw new Error("Usage: flaghoist flag delete <key>");
+      await clientFrom(values).delete(a);
+      return console.log(`Deleted "${a}"`);
+    }
+    case "rules": {
+      if (a !== "set" || !b)
+        throw new Error("Usage: flaghoist flag rules set <key> --file rules.json");
+      if (!values.file) throw new Error("Missing --file <rules.json>");
+      const rules = JSON.parse(readFileSync(values.file, "utf8"));
+      if (!Array.isArray(rules)) throw new Error("Rules file must contain a JSON array");
+      const flag = await setRules(clientFrom(values), b, rules);
+      console.log(`Updated rules for "${b}"`);
+      return printFlag(flag);
+    }
+    default:
+      throw new Error(`Unknown flag command: ${sub ?? "(none)"}. Try "flaghoist flag list".`);
+  }
+}
+function runInit(args) {
+  const { values } = parseArgs({
+    args,
+    allowPositionals: true,
+    options: { name: { type: "string" }, storage: { type: "string" } }
+  });
+  if (existsSync("flaghoist.toml")) throw new Error("flaghoist.toml already exists.");
+  if (values.storage && !STORAGE_KINDS.includes(values.storage)) {
+    throw new Error(`Unknown storage "${values.storage}". One of: ${STORAGE_KINDS.join(", ")}.`);
+  }
+  const config = {
+    ...DEFAULT_CONFIG,
+    name: values.name ?? DEFAULT_CONFIG.name,
+    storage: values.storage ?? DEFAULT_CONFIG.storage
+  };
+  writeFileSync("flaghoist.toml", serializeConfig(config));
+  console.log("Created flaghoist.toml");
+  console.log("Next: `flaghoist deploy` to ship it, or `flaghoist eject` to own the code.");
+}
+function writeProject(config, dir) {
+  writeFileSafe(join(dir, "src/index.ts"), generateWorkerEntry(config));
+  writeFileSafe(join(dir, "wrangler.toml"), generateWranglerToml(config));
+  writeFileSafe(join(dir, "package.json"), generatePackageJson(config));
+}
+function runEject() {
+  const config = loadConfig();
+  if (existsSync("src/index.ts")) throw new Error("src/index.ts already exists \u2014 already ejected?");
+  writeProject(config, ".");
+  console.log("Ejected to a code project you own: src/index.ts, wrangler.toml, package.json");
+  if (config.storage === "cloudflare-kv") {
+    console.log("Create your KV namespace and paste the id into wrangler.toml:");
+    console.log("  npx wrangler kv namespace create FLAGS");
+  }
+  console.log("Edit src/index.ts freely, then: npm install && npx wrangler deploy");
+}
+function ensureKvNamespace(config) {
+  if (config.storage !== "cloudflare-kv") return;
+  const toml = readFileSync("wrangler.toml", "utf8");
+  if (!needsKvNamespace(toml)) return;
+  console.log("Creating the FLAGS KV namespace...");
+  const created = spawnSync("npx", ["wrangler", "kv", "namespace", "create", "FLAGS"], {
+    stdio: ["inherit", "pipe", "inherit"],
+    encoding: "utf8"
+  });
+  const output = created.stdout ?? "";
+  if (output) process.stdout.write(output);
+  if (created.status !== 0) {
+    throw new Error(
+      "Could not create the KV namespace. Run `npx wrangler kv namespace create FLAGS` yourself, then paste the id into wrangler.toml."
+    );
+  }
+  const id = parseKvNamespaceId(output);
+  if (!id) {
+    throw new Error(
+      "Created the namespace but could not read its id from wrangler output. Paste the id above into wrangler.toml, then run `flaghoist deploy` again."
+    );
+  }
+  writeFileSync("wrangler.toml", fillKvNamespaceId(toml, id));
+  console.log(`Bound FLAGS to namespace ${id} in wrangler.toml`);
+}
+function runDeploy() {
+  const config = loadConfig();
+  if (!existsSync("src/index.ts")) writeProject(config, ".");
+  ensureKvNamespace(config);
+  console.log("Deploying with wrangler...");
+  const result = spawnSync("npx", ["wrangler", "deploy"], { stdio: "inherit" });
+  process.exit(result.status ?? 0);
+}
+function printHelp() {
+  console.log(`flaghoist ${VERSION} \u2014 hoist your own feature flags
+
+Usage: flaghoist <command>
+
+Scaffolding
+  init [--name N] [--storage cloudflare-kv|redis|postgres|memory]
+  eject                    Generate a code project you own
+  deploy                   Deploy to Cloudflare via wrangler
+
+Flag management (needs --url/--token or FLAGS_URL/FLAGS_ADMIN_TOKEN)
+  flag list
+  flag get <key>
+  flag create <key> [--on] [--rollout N] [--desc "..."]
+  flag toggle <key> [--on|--off]
+  flag rollout <key> <percentage>
+  flag rules set <key> --file rules.json
+  flag delete <key>`);
+}
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  switch (command) {
+    case "flag":
+      return runFlag(rest);
+    case "init":
+      return runInit(rest);
+    case "eject":
+      return runEject();
+    case "deploy":
+      return runDeploy();
+    case "-v":
+    case "--version":
+      return console.log(VERSION);
+    case void 0:
+    case "help":
+    case "-h":
+    case "--help":
+      return printHelp();
+    default:
+      console.error(`Unknown command: ${command}
+`);
+      printHelp();
+      process.exit(1);
+  }
+}
+main().then(() => process.exit(0)).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/dist/lib.d.ts

@@ -0,0 +1,22 @@
+type StorageKind = 'cloudflare-kv' | 'redis' | 'postgres' | 'memory';
+type AdminAuthKind = 'bearer-token' | 'oidc';
+interface FlaghoistConfig {
+    name: string;
+    storage: StorageKind;
+    auth: {
+        admin: AdminAuthKind;
+        read: 'api-key';
+    };
+    allowedOrigins?: string[];
+    /** Serve the admin dashboard at `/admin`. On by default. */
+    dashboard: boolean;
+}
+declare const DEFAULT_CONFIG: FlaghoistConfig;
+/** Every storage backend selectable by name in `flaghoist.toml`. */
+declare const STORAGE_KINDS: readonly StorageKind[];
+/** Parse a `flaghoist.toml` into a validated config, falling back to defaults for unknown values. */
+declare function parseConfig(text: string): FlaghoistConfig;
+/** Render a config back to `flaghoist.toml` text. */
+declare function serializeConfig(config: FlaghoistConfig): string;
+
+export { type AdminAuthKind, DEFAULT_CONFIG, type FlaghoistConfig, STORAGE_KINDS, type StorageKind, parseConfig, serializeConfig };

package/dist/lib.js

@@ -0,0 +1,12 @@
+import {
+  DEFAULT_CONFIG,
+  STORAGE_KINDS,
+  parseConfig,
+  serializeConfig
+} from "./chunk-S4XXPMMW.js";
+export {
+  DEFAULT_CONFIG,
+  STORAGE_KINDS,
+  parseConfig,
+  serializeConfig
+};

package/package.json

@@ -1,25 +1,60 @@
 {
   "name": "flaghoist",
-  "version": "0.0.1",
-  "description": "Reserved for the Flaghoist CLI — hoist your own feature flags. Coming soon.",
+  "version": "0.1.1",
+  "description": "Scaffold, deploy, and manage your Flaghoist feature-flag service from the terminal.",
   "license": "Apache-2.0",
-  "author": "Damilola Oluwafemi",
-  "homepage": "https://github.com/flaghoist/flaghoist",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/flaghoist/flaghoist.git"
+  "type": "module",
+  "bin": {
+    "flaghoist": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/lib.d.ts",
+        "default": "./dist/lib.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "smol-toml": "^1.7.1"
+  },
+  "devDependencies": {
+    "@flaghoist/adapter-memory": "0.1.1",
+    "@flaghoist/core": "0.1.1",
+    "@flaghoist/server": "0.1.1"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "keywords": [
     "feature-flags",
-    "feature-flag",
+    "feature-toggles",
     "openfeature",
     "ofrep",
-    "self-hosted"
+    "cloudflare-workers",
+    "self-hosted",
+    "cli"
   ],
-  "bin": {
-    "flaghoist": "bin.js"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flaghoist/flaghoist.git",
+    "directory": "packages/cli"
   },
-  "files": [
-    "bin.js"
-  ]
-}
+  "homepage": "https://github.com/flaghoist/flaghoist#readme",
+  "bugs": {
+    "url": "https://github.com/flaghoist/flaghoist/issues"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/lib.ts --format esm --dts --clean",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "check:package": "publint --strict && attw --pack . --profile esm-only"
+  }
+}

package/bin.js

@@ -1,5 +0,0 @@
-#!/usr/bin/env node
-console.log('Flaghoist — the open-source, OpenFeature-native feature-flag service you self-host.')
-console.log('')
-console.log('The CLI is on its way. Follow along:')
-console.log('  https://github.com/flaghoist/flaghoist')