lumibase 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,192 @@
+                                 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.
+
+   Copyright 2024-present LumiBase 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

@@ -0,0 +1,101 @@
+# `lumibase`
+
+[LumiBase](https://lumibase.dev) in one package — the JS/TS client plus the `lumibase` CLI: generate TypeScript types from a live schema, check that your setup can reach the CMS, scaffold a project.
+
+```bash
+npm install lumibase
+```
+
+```ts
+import { createLumiClient, readItems } from 'lumibase';
+
+const client = createLumiClient({ url: 'https://api.mysite.lumibase.dev', token, siteId });
+const { data } = await client.request(readItems('articles', { limit: 10 }));
+```
+
+The library entry re-exports [`@lumibase/sdk`](https://www.npmjs.com/package/@lumibase/sdk) (REST + GraphQL + realtime, isomorphic ESM) — same client, one name to install. The CLI can also be run without installing:
+
+```bash
+npx lumibase --help
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `lumibase init [name]` | Scaffold a new project (runs `create-lumibase@<same version>` via `npx` / `pnpm dlx` / `yarn dlx` / `bunx`) |
+| `lumibase types` | Generate TypeScript types from a running CMS |
+| `lumibase doctor` | Report resolved configuration and probe connectivity |
+
+## Connection settings
+
+Resolved with precedence **flag > environment > `lumibase.config.json`**:
+
+| Setting | Flag | Environment | Config file |
+| --- | --- | --- | --- |
+| CMS base URL | `--url` | `LUMIBASE_URL` | `url` |
+| Site / tenant id | `--site` | `LUMIBASE_SITE_ID` | `siteId` |
+| Bearer token | `--token` | `LUMIBASE_TOKEN` | — |
+
+The token is deliberately **not** readable from the config file — that file is meant to be committed. A `token` key there is rejected with an error rather than silently ignored.
+
+```json
+{
+  "url": "https://api.mysite.lumibase.dev",
+  "siteId": "site_abc123",
+  "typegen": {
+    "out": "src/lumibase-types.d.ts",
+    "exclude": ["internal_logs"]
+  }
+}
+```
+
+The file is looked up from the working directory upward, so it works from any package inside a monorepo.
+
+## `lumibase types`
+
+Fetches the collection manifest from `GET /api/v1/typegen/schema` and writes TypeScript definitions.
+
+```bash
+lumibase types                                # -> lumibase-types.d.ts
+lumibase types --out src/lumibase-types.d.ts  # custom path (directories are created)
+lumibase types --include articles,authors     # subset of collections
+lumibase types --no-branded                   # plain string ids
+lumibase types --import-from @lumibase/sdk    # module the generated file imports from (default: lumibase)
+lumibase types --stdout                       # print instead of writing
+```
+
+The generated file imports its helper types from `lumibase` by default — the package you already have installed. Use `--import-from` (or `typegen.importFrom` in the config file) if your project depends on `@lumibase/sdk` directly.
+
+Output is **deterministic** — no timestamp, host, or site id in the header — so the file can be committed and verified in CI:
+
+```yaml
+- run: npx lumibase types --check
+```
+
+`--check` exits non-zero when the committed file is missing or stale, and never writes anything.
+
+## `lumibase doctor`
+
+```
+✔ node         v22.22.2
+✔ config       /path/to/lumibase.config.json
+✔ url          http://localhost:1989 (from lumibase.config.json)
+✔ siteId       site_abc123 (from lumibase.config.json)
+✔ token        tok_••••••••3f (from environment)
+✔ health       reachable — status: healthy
+✔ schema       12 collections readable
+```
+
+Exits non-zero if any check fails. Tokens are masked — a short prefix is kept so you can tell *which* token was picked up without the value reaching CI logs.
+
+## Requirements
+
+Node.js 22+.
+
+## Links
+
+- Documentation — <https://docs.lumibase.dev>
+- Issues — <https://github.com/khuepm/lumibase/issues>
+
+Apache-2.0

package/bin/lumibase.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Guard BEFORE loading the ESM graph so the message is a plain sentence rather
+// than a syntax/import error from a Node 22+ feature further down the tree.
+const major = Number(process.versions.node.split('.')[0]);
+if (!Number.isFinite(major) || major < 22) {
+  console.error(`lumibase requires Node.js 22+. Current: ${process.versions.node}`);
+  process.exit(1);
+}
+
+import('../dist/index.js').catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/index.js

@@ -0,0 +1,767 @@
+// src/index.ts
+import process5 from "process";
+import pc4 from "picocolors";
+
+// src/cli.ts
+import pc3 from "picocolors";
+
+// src/commands/doctor.ts
+import process2 from "process";
+import pc2 from "picocolors";
+
+// src/errors.ts
+var CliError = class extends Error {
+  constructor(message, hint, exitCode = 1) {
+    super(message);
+    this.hint = hint;
+    this.exitCode = exitCode;
+    this.name = "CliError";
+  }
+  hint;
+  exitCode;
+};
+
+// src/api.ts
+var DEFAULT_TIMEOUT_MS = 15e3;
+async function request(connection, path, query = {}, options = {}) {
+  const fetcher = options.fetcher ?? globalThis.fetch;
+  const target = new URL(path, `${connection.url}/`);
+  for (const [key, value] of Object.entries(query)) {
+    if (value) target.searchParams.set(key, value);
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  let response;
+  try {
+    response = await fetcher(target, {
+      headers: {
+        Authorization: `Bearer ${connection.token}`,
+        "X-Lumi-Site": connection.siteId,
+        Accept: "application/json"
+      },
+      signal: controller.signal
+    });
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new CliError(`Request to ${target.href} timed out.`);
+    }
+    throw new CliError(
+      `Could not reach ${target.href}: ${err instanceof Error ? err.message : String(err)}`,
+      "Is the CMS running, and is --url / LUMIBASE_URL pointing at it?"
+    );
+  } finally {
+    clearTimeout(timeout);
+  }
+  if (!response.ok) {
+    throw new CliError(describeHttpError(response.status, target.href), hintForStatus(response.status));
+  }
+  return response.json();
+}
+function describeHttpError(status, href) {
+  if (status === 401) return `Unauthorized (401) from ${href}.`;
+  if (status === 403) return `Forbidden (403) from ${href}.`;
+  if (status === 404) return `Not found (404) at ${href}.`;
+  return `Request to ${href} failed with HTTP ${status}.`;
+}
+function hintForStatus(status) {
+  if (status === 401) return "The token is missing, expired, or not valid for this site.";
+  if (status === 403) return "The token is valid but lacks permission to read the schema.";
+  if (status === 404) {
+    return "Check the base URL \u2014 it should point at the CMS root (e.g. http://localhost:1989), not at an endpoint.";
+  }
+  return void 0;
+}
+async function fetchTypegenManifest(connection, filters = {}, options = {}) {
+  const body = await request(
+    connection,
+    "api/v1/typegen/schema",
+    {
+      include: filters.include?.join(","),
+      exclude: filters.exclude?.join(",")
+    },
+    options
+  );
+  const manifest = body?.data;
+  if (typeof manifest !== "object" || manifest === null || !Array.isArray(manifest.collections)) {
+    throw new CliError(
+      "The schema endpoint returned an unexpected payload.",
+      "Make sure the CMS is a LumiBase instance and its version supports GET /api/v1/typegen/schema."
+    );
+  }
+  return manifest;
+}
+async function probeHealth(url, options = {}) {
+  const fetcher = options.fetcher ?? globalThis.fetch;
+  const target = new URL("health", `${url}/`);
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  try {
+    const response = await fetcher(target, { signal: controller.signal });
+    if (!response.ok) {
+      return { ok: false, detail: `HTTP ${response.status} from ${target.href}` };
+    }
+    const body = await response.json();
+    const status = typeof body.status === "string" ? body.status : void 0;
+    return {
+      ok: status !== "unhealthy",
+      status,
+      detail: status ? `reachable \u2014 status: ${status}` : `reachable at ${target.href}`
+    };
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      return { ok: false, detail: `timed out reaching ${target.href}` };
+    }
+    return {
+      ok: false,
+      detail: `unreachable: ${err instanceof Error ? err.message : String(err)}`
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// src/config.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import process from "process";
+
+// src/utils/args.ts
+function parseArgs(argv) {
+  const result = { _: [] };
+  const passthrough = [];
+  let afterDoubleDash = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg) continue;
+    if (afterDoubleDash) {
+      passthrough.push(arg);
+      continue;
+    }
+    if (arg === "--") {
+      afterDoubleDash = true;
+      continue;
+    }
+    if (arg === "-h") {
+      result["help"] = true;
+      continue;
+    }
+    if (arg === "-v") {
+      result["version"] = true;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      const raw = arg.slice(2);
+      if (raw.startsWith("no-")) {
+        result[raw] = true;
+        continue;
+      }
+      const eqIdx = raw.indexOf("=");
+      if (eqIdx !== -1) {
+        result[raw.slice(0, eqIdx)] = raw.slice(eqIdx + 1);
+        continue;
+      }
+      const next = argv[i + 1];
+      if (next && !next.startsWith("-")) {
+        result[raw] = next;
+        i++;
+      } else {
+        result[raw] = true;
+      }
+      continue;
+    }
+    result._.push(arg);
+  }
+  if (passthrough.length > 0) {
+    result._.push(...passthrough);
+  }
+  return result;
+}
+function argvAfterCommand(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg) continue;
+    if (arg.startsWith("-")) {
+      if (arg.startsWith("--") && !arg.includes("=") && !arg.startsWith("--no-")) {
+        const next = argv[i + 1];
+        if (next && !next.startsWith("-")) i++;
+      }
+      continue;
+    }
+    return argv.slice(i + 1);
+  }
+  return [];
+}
+function stringFlag(args, name) {
+  const value = args[name];
+  if (value === void 0) return void 0;
+  if (typeof value !== "string") {
+    throw new Error(`Flag --${name} needs a value (e.g. --${name}=<value>).`);
+  }
+  return value;
+}
+function boolFlag(args, name) {
+  return args[name] === true || args[name] === "true";
+}
+
+// src/config.ts
+var CONFIG_FILENAME = "lumibase.config.json";
+function findConfigFile(startDir) {
+  let dir = resolve(startDir);
+  for (; ; ) {
+    const candidate = join(dir, CONFIG_FILENAME);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+function readConfigFile(path) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (err) {
+    throw new CliError(
+      `Could not read ${path}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CliError(`${path} is not valid JSON.`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new CliError(`${path} must contain a JSON object.`);
+  }
+  const config = parsed;
+  if ("token" in config) {
+    throw new CliError(
+      `${CONFIG_FILENAME} must not contain a "token".`,
+      "Pass the token via the LUMIBASE_TOKEN environment variable or --token instead \u2014 this file is meant to be committed."
+    );
+  }
+  return {
+    url: typeof config["url"] === "string" ? config["url"] : void 0,
+    siteId: typeof config["siteId"] === "string" ? config["siteId"] : void 0,
+    typegen: readTypegenSection(config["typegen"])
+  };
+}
+function readTypegenSection(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const section = value;
+  return {
+    out: typeof section["out"] === "string" ? section["out"] : void 0,
+    include: stringArray(section["include"]),
+    exclude: stringArray(section["exclude"]),
+    branded: typeof section["branded"] === "boolean" ? section["branded"] : void 0,
+    importFrom: typeof section["importFrom"] === "string" ? section["importFrom"] : void 0
+  };
+}
+function stringArray(value) {
+  if (!Array.isArray(value)) return void 0;
+  const items = value.filter((entry) => typeof entry === "string");
+  return items.length > 0 ? items : void 0;
+}
+function resolveConfig(args, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const env = options.env ?? process.env;
+  const configPath = findConfigFile(cwd);
+  const file = configPath ? readConfigFile(configPath) : {};
+  const url = pick(stringFlag(args, "url"), env["LUMIBASE_URL"], file.url);
+  const siteId = pick(stringFlag(args, "site"), env["LUMIBASE_SITE_ID"], file.siteId);
+  const token = pick(stringFlag(args, "token"), env["LUMIBASE_TOKEN"], void 0);
+  return {
+    url: url.value ? stripTrailingSlash(url.value) : void 0,
+    siteId: siteId.value,
+    token: token.value,
+    sources: { url: url.source, siteId: siteId.source, token: token.source },
+    configPath,
+    typegen: file.typegen ?? {}
+  };
+}
+function pick(flag, envValue, fileValue) {
+  if (flag) return { value: flag, source: "flag" };
+  if (envValue) return { value: envValue, source: "env" };
+  if (fileValue) return { value: fileValue, source: "file" };
+  return { source: "missing" };
+}
+function stripTrailingSlash(url) {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+function requireConnection(config) {
+  const missing = [];
+  if (!config.url) missing.push("url (--url / LUMIBASE_URL)");
+  if (!config.siteId) missing.push("siteId (--site / LUMIBASE_SITE_ID)");
+  if (!config.token) missing.push("token (--token / LUMIBASE_TOKEN)");
+  if (missing.length > 0) {
+    throw new CliError(
+      `Missing connection settings: ${missing.join(", ")}.`,
+      `Set them in the environment, or put "url" and "siteId" in ${CONFIG_FILENAME}. Run \`lumibase doctor\` to see what was resolved.`
+    );
+  }
+}
+
+// src/utils/log.ts
+import pc from "picocolors";
+var log = {
+  plain(message = "") {
+    console.log(message);
+  },
+  info(message) {
+    console.log(`${pc.cyan("\u2022")} ${message}`);
+  },
+  success(message) {
+    console.log(`${pc.green("\u2714")} ${message}`);
+  },
+  warn(message) {
+    console.warn(`${pc.yellow("!")} ${message}`);
+  },
+  error(message) {
+    console.error(`${pc.red("\u2716")} ${message}`);
+  },
+  dim(message) {
+    console.log(pc.dim(message));
+  }
+};
+function maskSecret(secret) {
+  if (secret.length <= 8) return "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022";
+  return `${secret.slice(0, 4)}${"\u2022".repeat(8)}${secret.slice(-2)}`;
+}
+
+// src/commands/doctor.ts
+var MIN_NODE_MAJOR = 22;
+function describeSource(source) {
+  switch (source) {
+    case "flag":
+      return "from flag";
+    case "env":
+      return "from environment";
+    case "file":
+      return `from ${CONFIG_FILENAME}`;
+    case "missing":
+      return "not set";
+  }
+}
+function printCheck(check) {
+  const mark = check.status === "ok" ? pc2.green("\u2714") : check.status === "warn" ? pc2.yellow("!") : pc2.red("\u2716");
+  console.log(`${mark} ${check.label.padEnd(12)} ${pc2.dim(check.detail)}`);
+}
+async function doctorCommand(args, options = {}) {
+  const cwd = options.cwd ?? process2.cwd();
+  const config = resolveConfig(args, { cwd, env: options.env });
+  const checks = [];
+  const nodeVersion = options.nodeVersion ?? process2.versions.node;
+  const nodeMajor = Number(nodeVersion.split(".")[0]);
+  checks.push({
+    label: "node",
+    status: Number.isFinite(nodeMajor) && nodeMajor >= MIN_NODE_MAJOR ? "ok" : "fail",
+    detail: Number.isFinite(nodeMajor) && nodeMajor >= MIN_NODE_MAJOR ? `v${nodeVersion}` : `v${nodeVersion} \u2014 LumiBase needs Node ${MIN_NODE_MAJOR}+`
+  });
+  checks.push({
+    label: "config",
+    status: config.configPath ? "ok" : "warn",
+    detail: config.configPath ?? `no ${CONFIG_FILENAME} found \u2014 using flags and environment only`
+  });
+  checks.push({
+    label: "url",
+    status: config.url ? "ok" : "fail",
+    detail: config.url ? `${config.url} (${describeSource(config.sources.url)})` : "not set \u2014 pass --url or set LUMIBASE_URL"
+  });
+  checks.push({
+    label: "siteId",
+    status: config.siteId ? "ok" : "fail",
+    detail: config.siteId ? `${config.siteId} (${describeSource(config.sources.siteId)})` : "not set \u2014 pass --site or set LUMIBASE_SITE_ID"
+  });
+  checks.push({
+    label: "token",
+    status: config.token ? "ok" : "fail",
+    detail: config.token ? `${maskSecret(config.token)} (${describeSource(config.sources.token)})` : "not set \u2014 pass --token or set LUMIBASE_TOKEN"
+  });
+  if (config.url) {
+    const health = await probeHealth(config.url, options.request);
+    checks.push({
+      label: "health",
+      status: health.ok ? health.status === "degraded" ? "warn" : "ok" : "fail",
+      detail: health.detail
+    });
+  }
+  if (config.url && config.siteId && config.token) {
+    try {
+      const manifest = await fetchTypegenManifest(
+        { url: config.url, siteId: config.siteId, token: config.token },
+        {},
+        options.request
+      );
+      checks.push({
+        label: "schema",
+        status: "ok",
+        detail: `${manifest.collections.length} collections readable`
+      });
+    } catch (err) {
+      checks.push({
+        label: "schema",
+        status: "fail",
+        detail: err instanceof CliError ? err.message : String(err)
+      });
+    }
+  }
+  log.plain();
+  for (const check of checks) printCheck(check);
+  log.plain();
+  const failures = checks.filter((check) => check.status === "fail");
+  if (failures.length > 0) {
+    log.error(`${failures.length} check${failures.length === 1 ? "" : "s"} failed.`);
+    return 1;
+  }
+  log.success("Everything looks good.");
+  return 0;
+}
+
+// src/commands/init.ts
+import { spawnSync } from "child_process";
+import process3 from "process";
+
+// src/version.ts
+import { createRequire } from "module";
+function readVersion(requireFrom = createRequire(import.meta.url)) {
+  const manifest = requireFrom("../package.json");
+  return manifest.version ?? "0.0.0";
+}
+
+// src/commands/init.ts
+function resolveScaffoldCommand(version, userAgent = process3.env["npm_config_user_agent"] ?? "") {
+  const pkg = `create-lumibase@${version}`;
+  const [name = "", ver = ""] = userAgent.split(" ")[0]?.split("/") ?? [];
+  const major = Number(ver.split(".")[0]);
+  switch (name) {
+    case "pnpm":
+      return { command: "pnpm", args: ["dlx", pkg] };
+    case "yarn":
+      if (major >= 2) return { command: "yarn", args: ["dlx", pkg] };
+      return { command: "npx", args: ["--yes", pkg] };
+    case "bun":
+      return { command: "bunx", args: [pkg] };
+    default:
+      return { command: "npx", args: ["--yes", pkg] };
+  }
+}
+function initCommand(argv, options = {}) {
+  const scaffold = resolveScaffoldCommand(
+    options.version ?? readVersion(),
+    options.userAgent
+  );
+  const run2 = options.run ?? ((command, args) => {
+    const result = spawnSync(command, args, {
+      stdio: "inherit",
+      // npx/pnpm/yarn/bunx are `.cmd` shims on Windows; a shell resolves them.
+      shell: process3.platform === "win32"
+    });
+    if (result.error) {
+      throw new CliError(
+        `Failed to run the scaffolder: ${result.error.message}`,
+        "Run `npm create lumibase@latest` directly."
+      );
+    }
+    return result.status ?? 1;
+  });
+  return run2(scaffold.command, [...scaffold.args, ...argv]);
+}
+
+// src/commands/types.ts
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { dirname as dirname2, relative, resolve as resolve2 } from "path";
+import process4 from "process";
+
+// ../sdk/src/typegen/index.ts
+var DEFAULT_IMPORT_SOURCE = "@lumibase/sdk";
+function generateTypes(manifest, options = {}) {
+  const { format = "single", branded = true, importSource = DEFAULT_IMPORT_SOURCE } = options;
+  if (format === "single") {
+    return generateSingleFile(manifest, branded, importSource);
+  }
+  return generatePerCollection(manifest, branded, importSource);
+}
+function generateSingleFile(manifest, branded, importSource) {
+  const imports = [
+    `import type { ID, Locale } from '${importSource}';`,
+    branded ? `import type { Brand } from '${importSource}';` : ""
+  ].filter(Boolean).join("\n");
+  const collectionInterfaces = manifest.collections.map((coll) => {
+    const base = generateCollectionInterface(coll, branded);
+    const expanded = generateExpandedType(coll);
+    return [base, expanded].filter(Boolean).join("\n\n");
+  }).join("\n\n");
+  const collectionsMap = `export interface LumibaseCollections {
+${manifest.collections.map((c) => `  ${c.name}: ${capitalize(c.name)};`).join("\n")}
+}`;
+  const schemaType = "export type LumibaseSchema = LumibaseCollections;";
+  return `${imports}
+
+${collectionInterfaces}
+
+${collectionsMap}
+
+${schemaType}`;
+}
+function generatePerCollection(manifest, branded, importSource) {
+  return generateSingleFile(manifest, branded, importSource);
+}
+function generateCollectionInterface(coll, branded) {
+  const fields = coll.fields.map((f) => {
+    const tsType = mapFieldTypeToTs(f, coll, branded);
+    const optional = f.required ? "" : "?";
+    const readonly = f.readonly || f.generated ? "readonly " : "";
+    return `  ${readonly}${f.name}${optional}: ${tsType};`;
+  }).join("\n");
+  return `export interface ${capitalize(coll.name)} {
+${fields}
+}`;
+}
+function generateExpandedType(coll) {
+  const relations = coll.relations ?? [];
+  if (relations.length === 0) {
+    return `export type ${capitalize(coll.name)}Expanded = ${capitalize(coll.name)};`;
+  }
+  const omittedKeys = relations.map((relation) => quoteProperty(relation.field)).join(" | ");
+  const fields = relations.map((relation) => `  ${relation.field}?: ${expandedRelationType(relation)};`).join("\n");
+  return `export type ${capitalize(coll.name)}Expanded = Omit<${capitalize(coll.name)}, ${omittedKeys}> & {
+${fields}
+};`;
+}
+function expandedRelationType(relation) {
+  if (relation.kind === "m2o") {
+    return `${capitalize(relation.target)} | ${capitalize(relation.target)}Expanded | null`;
+  }
+  if (relation.kind === "o2m" || relation.kind === "m2m") {
+    return `Array<${capitalize(relation.target)} | ${capitalize(relation.target)}Expanded>`;
+  }
+  return `Array<{ collection: string; item: unknown }>`;
+}
+function mapFieldTypeToTs(field, coll, branded) {
+  if (field.kind === "m2o") {
+    return nullable(field, mapScalarFieldType(field, branded));
+  }
+  if (field.kind === "o2m" || field.kind === "m2m") {
+    return `${capitalize(field.target || "unknown")}[]`;
+  }
+  if (field.kind === "m2a") {
+    return `Array<{ collection: string; item: unknown }>`;
+  }
+  if (field.enum && field.enum.length > 0) {
+    return nullable(field, field.enum.map((v) => JSON.stringify(v)).join(" | "));
+  }
+  if (field.primaryKey) {
+    return nullable(
+      field,
+      mapPrimaryKeyType(coll.primaryKeyType ?? "nanoid", branded, field.branded)
+    );
+  }
+  const tsType = mapScalarFieldType(field, branded);
+  return nullable(field, field.encrypted ? `${tsType} | '***'` : tsType);
+}
+function mapScalarFieldType(field, branded) {
+  const typeMap = {
+    string: "string",
+    text: "string",
+    hash: "string",
+    csv: "string",
+    integer: "number",
+    bigInteger: "number",
+    decimal: "number",
+    boolean: "boolean",
+    json: "unknown",
+    uuid: mapPrimaryKeyType("uuid", branded, field.branded),
+    date: "string",
+    datetime: "string",
+    time: "string",
+    timestamp: "string",
+    geometry: "GeoJSON.Geometry"
+  };
+  return typeMap[field.type] || "unknown";
+}
+function nullable(field, tsType) {
+  if (!field.required || field.nullable) {
+    return `${tsType} | null`;
+  }
+  return tsType;
+}
+function mapPrimaryKeyType(primaryKeyType, branded, brand) {
+  if (primaryKeyType === "integer" || primaryKeyType === "bigInteger") return "number";
+  if (branded) return `Brand<'${brand || "ID"}', string>`;
+  return "ID";
+}
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+function quoteProperty(name) {
+  return JSON.stringify(name);
+}
+
+// src/commands/types.ts
+var DEFAULT_OUT = "lumibase-types.d.ts";
+var DEFAULT_IMPORT_FROM = "lumibase";
+var BANNER = [
+  "// Generated by `lumibase types` \u2014 do not edit by hand.",
+  "// Re-run the command after changing collections or fields."
+].join("\n");
+function renderTypes(manifest, options) {
+  const { branded, importFrom = DEFAULT_IMPORT_FROM } = options;
+  const body = generateTypes(manifest, { format: "single", branded, importSource: importFrom });
+  return `${BANNER}
+
+${body.trimEnd()}
+`;
+}
+function splitList(value) {
+  if (!value) return void 0;
+  const items = value.split(",").map((entry) => entry.trim()).filter(Boolean);
+  return items.length > 0 ? items : void 0;
+}
+async function typesCommand(args, options = {}) {
+  const cwd = options.cwd ?? process4.cwd();
+  const config = resolveConfig(args, { cwd, env: options.env });
+  requireConnection(config);
+  const check = boolFlag(args, "check");
+  const toStdout = boolFlag(args, "stdout");
+  const branded = boolFlag(args, "no-branded") ? false : config.typegen.branded ?? true;
+  const importFrom = stringFlag(args, "import-from") ?? config.typegen.importFrom ?? DEFAULT_IMPORT_FROM;
+  const outPath = resolve2(
+    cwd,
+    stringFlag(args, "out") ?? config.typegen.out ?? DEFAULT_OUT
+  );
+  const manifest = await fetchTypegenManifest(
+    { url: config.url, siteId: config.siteId, token: config.token },
+    {
+      include: splitList(stringFlag(args, "include")) ?? config.typegen.include,
+      exclude: splitList(stringFlag(args, "exclude")) ?? config.typegen.exclude
+    },
+    options.request
+  );
+  const generated = renderTypes(manifest, { branded, importFrom });
+  const collectionCount = manifest.collections.length;
+  if (toStdout) {
+    process4.stdout.write(generated);
+    return 0;
+  }
+  const displayPath = relative(cwd, outPath) || outPath;
+  const existing = existsSync2(outPath) ? readFileSync2(outPath, "utf8") : void 0;
+  if (check) {
+    if (existing === void 0) {
+      throw new CliError(
+        `${displayPath} does not exist.`,
+        "Run `lumibase types` and commit the result."
+      );
+    }
+    if (existing !== generated) {
+      throw new CliError(
+        `${displayPath} is out of date with the live schema.`,
+        "Run `lumibase types` and commit the result."
+      );
+    }
+    log.success(`${displayPath} is up to date (${collectionCount} collections).`);
+    return 0;
+  }
+  if (existing === generated) {
+    log.success(`${displayPath} already up to date (${collectionCount} collections).`);
+    return 0;
+  }
+  mkdirSync(dirname2(outPath), { recursive: true });
+  writeFileSync(outPath, generated, "utf8");
+  log.success(`Wrote ${displayPath} \u2014 ${collectionCount} collections.`);
+  log.dim(`  Generated types import from ${importFrom} \u2014 install it in this project.`);
+  return 0;
+}
+
+// src/cli.ts
+var HELP = `
+${pc3.bold(pc3.cyan("lumibase"))} ${pc3.dim("\u2014 the LumiBase CLI")}
+
+${pc3.bold("Usage")}
+  lumibase <command> [options]
+
+${pc3.bold("Commands")}
+  init [name]     Scaffold a new LumiBase project
+  types           Generate TypeScript types from a live schema
+  doctor          Check configuration and connectivity
+
+${pc3.bold("Connection")}
+  Resolved with precedence flag > environment > ${pc3.cyan("lumibase.config.json")}.
+  The token is never read from the config file.
+
+  --url <url>     CMS base URL          ${pc3.dim("(LUMIBASE_URL)")}
+  --site <id>     Site / tenant id      ${pc3.dim("(LUMIBASE_SITE_ID)")}
+  --token <tok>   Bearer token          ${pc3.dim("(LUMIBASE_TOKEN)")}
+
+${pc3.bold("lumibase types")}
+  --out <path>    Output file           ${pc3.dim(`(default: ${DEFAULT_OUT})`)}
+  --include <a,b> Only these collections
+  --exclude <a,b> Skip these collections
+  --no-branded    Emit plain string ids instead of branded ones
+  --import-from <pkg>  Module the generated file imports from ${pc3.dim("(default: lumibase)")}
+  --check         Fail if the file is missing or stale ${pc3.dim("(use in CI)")}
+  --stdout        Print to stdout instead of writing a file
+
+${pc3.bold("Examples")}
+  ${pc3.dim("$")} lumibase init my-site
+  ${pc3.dim("$")} lumibase types --out src/lumibase-types.d.ts
+  ${pc3.dim("$")} lumibase types --check
+  ${pc3.dim("$")} lumibase doctor
+
+  Docs: ${pc3.cyan("https://docs.lumibase.dev")}
+`;
+async function run(argv) {
+  const args = parseArgs(argv);
+  const command = args._[0];
+  if (boolFlag(args, "version") && !command) {
+    log.plain(readVersion());
+    return 0;
+  }
+  if (!command || boolFlag(args, "help")) {
+    log.plain(HELP);
+    return boolFlag(args, "help") ? 0 : 1;
+  }
+  switch (command) {
+    case "init":
+      return initCommand(argvAfterCommand(argv));
+    case "types":
+      return typesCommand(args);
+    case "doctor":
+      return doctorCommand(args);
+    case "help":
+      log.plain(HELP);
+      return 0;
+    case "version":
+      log.plain(readVersion());
+      return 0;
+    default:
+      throw new CliError(
+        `Unknown command: ${command}`,
+        "Run `lumibase --help` to see the available commands."
+      );
+  }
+}
+
+// src/index.ts
+async function main() {
+  const exitCode = await run(process5.argv.slice(2));
+  process5.exitCode = exitCode;
+}
+main().catch((err) => {
+  if (err instanceof CliError) {
+    log.plain();
+    log.error(err.message);
+    if (err.hint) log.dim(`  ${err.hint}`);
+    log.plain();
+    process5.exitCode = err.exitCode;
+    return;
+  }
+  if (process5.env["DEBUG"]) {
+    console.error(err);
+  } else {
+    log.plain();
+    log.error(err instanceof Error ? err.message : String(err));
+    console.error(pc4.dim("  Run with DEBUG=1 for the full stack trace."));
+    log.plain();
+  }
+  process5.exitCode = 1;
+});

package/dist/lib.d.ts

@@ -0,0 +1 @@
+export * from '@lumibase/sdk';

package/dist/lib.js

@@ -0,0 +1,2 @@
+// src/lib.ts
+export * from "@lumibase/sdk";

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "lumibase",
+  "version": "1.0.0-rc.1",
+  "description": "LumiBase in one package — the JS/TS client (re-exports @lumibase/sdk) plus the `lumibase` CLI: generate TypeScript types from a live schema, check your setup, scaffold a project.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "lumibase": "./bin/lumibase.js"
+  },
+  "main": "./dist/lib.js",
+  "types": "./dist/lib.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/lib.d.ts",
+      "import": "./dist/lib.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "picocolors": "^1.1.1",
+    "@lumibase/sdk": "1.0.0-rc.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.6.2",
+    "vitest": "^4.1.11"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "lumibase",
+    "sdk",
+    "client",
+    "cli",
+    "cms",
+    "headless-cms",
+    "typegen",
+    "codegen",
+    "typescript",
+    "scaffold"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/khuepm/lumibase.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://docs.lumibase.dev",
+  "bugs": {
+    "url": "https://github.com/khuepm/lumibase/issues"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest --run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf .turbo dist"
+  }
+}