@wirechunk/cli 0.0.9 → 0.1.0

package/README.md

@@ -0,0 +1,75 @@
+# Wirechunk CLI
+
+The Wirechunk CLI (`wirechunk`) is the official command-line tool for Wirechunk. It provides essential utilities for platform management and is the primary tool for developing Wirechunk extensions.
+
+## Installation
+
+```
+npm install -D @wirechunk/cli
+```
+
+## Getting Started with Extension Development
+
+The CLI simplifies the extension development workflow by allowing you to run a local instance of the Wirechunk core platform that loads your extension code directly.
+
+### Prerequisites
+
+- **Node.js**: Must be version 24+.
+- **Docker**: Required for running the core development server.
+
+### Development Workflow
+
+1.  **Configure Environment**:
+    Ensure you have a `.env` file with the necessary configuration, including a core database URL (e.g., `WIRECHUNK_CORE_DATABASE_URL`). You can override the core dev server image with `WIRECHUNK_CORE_DEV_SERVER_IMAGE`; otherwise the CLI uses the latest.
+
+2.  **Start the Core Server**:
+    Run the development server which spins up a Docker container with the Wirechunk platform. It mounts your current working directory inside the container, allowing hot reload for frontend code as you develop.
+
+    ```
+    wirechunk ext-dev start-core
+    ```
+
+    - Adds `-d` to run in detached mode.
+    - Exposes port `8080` (Web) and `9001` (Vite).
+
+3.  **Create Extension**:
+    Register your extension with the platform to generate an ID and configure your environment. If your `extension.json` enables a database, this command will set up the connection details automatically.
+
+    ```
+    wirechunk create-extension --dev
+    ```
+
+## Key Commands
+
+### Extension Management
+
+- **`wirechunk create-extension`**: Register a new extension on the platform.
+- **`wirechunk create-extension-version`**: Publish a new version of an extension. Uploads configuration and code.
+
+### Platform & User Management
+
+- **`wirechunk bootstrap`**: Initialize a new platform.
+- **`wirechunk create-user`**: Create a new user account. Useful for setting up test users or initial admins.
+- **`wirechunk edit-admin`**: Grant or revoke admin privileges for a user on a platform.
+
+### Development Utilities (`ext-dev`)
+
+- **`wirechunk ext-dev start-core`**: Starts the local Docker-based development server.
+- **`wirechunk ext-dev init-db`**: Initializes a development database for an extension.
+- **`wirechunk ext-dev get-db-url`**: writes `DATABASE_URL` to `.env.local` (or `.env.<env-mode>.local`) with the extension’s development database connection string.
+
+### Utility
+
+- **`wirechunk version`**: Prints the CLI version.
+
+## Configuration
+
+The CLI automatically loads environment variables from `.env` and `.env.local` files in your current directory.
+
+You can specify a custom environment mode using the `--env-mode` flag:
+
+```
+wirechunk --env-mode test create-user ...
+```
+
+This will load variables from `.env.test` and `.env.test.local` in addition to the standard files.

package/build/main.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import EventEmitter from "node:events";
 import require$$1$1, { spawn } from "node:child_process";
-import require$$2$2, { resolve as resolve$1 } from "node:path";
+import require$$2$2, { resolve as resolve$1, dirname } from "node:path";
 import require$$3$1, { readFileSync, existsSync } from "node:fs";
 import process$2 from "node:process";
 import os from "node:os";
@@ -31,7 +31,7 @@ import require$$0$d from "os";
 import require$$1$4 from "tty";
 import require$$0$e from "constants";
 import require$$5$1 from "assert";
-import require$$2$4 from "node:url";
+import require$$2$4, { fileURLToPath } from "node:url";
 import require$$2$3 from "node:string_decoder";
 import require$$0$f from "zlib";
 var commonjsGlobal = typeof globalThis !== "undefined" ? globalThis : typeof window !== "undefined" ? window : typeof global !== "undefined" ? global : typeof self !== "undefined" ? self : {};
@@ -6834,7 +6834,7 @@ let Doc$1 = class Doc {
     return new F(...args, lines.join("\n"));
   }
 };
-const version$1 = {
+const version$2 = {
   major: 4,
   minor: 1,
   patch: 13
@@ -6844,7 +6844,7 @@ const $ZodType$1 = /* @__PURE__ */ $constructor$1("$ZodType", (inst, def) => {
   inst ?? (inst = {});
   inst._zod.def = def;
   inst._zod.bag = inst._zod.bag || {};
-  inst._zod.version = version$1;
+  inst._zod.version = version$2;
   const checks = [...inst._zod.def.checks ?? []];
   if (inst._zod.traits.has("$ZodCheck")) {
     checks.unshift(inst);
@@ -23897,7 +23897,7 @@ class Doc2 {
     return new F(...args, lines.join("\n"));
   }
 }
-const version = {
+const version$1 = {
   major: 4,
   minor: 1,
   patch: 13
@@ -23907,7 +23907,7 @@ const $ZodType = /* @__PURE__ */ $constructor("$ZodType", (inst, def) => {
   inst ?? (inst = {});
   inst._zod.def = def;
   inst._zod.bag = inst._zod.bag || {};
-  inst._zod.version = version;
+  inst._zod.version = version$1;
   const checks = [...inst._zod.def.checks ?? []];
   if (inst._zod.traits.has("$ZodCheck")) {
     checks.unshift(inst);
@@ -26007,9 +26007,11 @@ function superRefine(fn) {
 const localhostRegex1 = /localhost:\d{2,4}$/;
 const localhostRegex2 = /localhost$/;
 const isLocalhost = (domain) => localhostRegex1.test(domain) || localhostRegex2.test(domain);
+const envModeSymbol = Symbol("envMode");
+const mainEnvFilePathSymbol = Symbol("mainEnvFilePath");
+const mainEnvFileExistsSymbol = Symbol("mainEnvFileExists");
 const envFilePath = ".env";
 const envLocalFilePath = ".env.local";
-const hasEnvFile = existsSync(envFilePath);
 const requireApiToken = (env2) => {
   if (!env2.WIRECHUNK_API_TOKEN) {
     console.error(
@@ -26023,10 +26025,10 @@ const requireCoreDbUrl = (env2) => {
   const url = env2.WIRECHUNK_CORE_DATABASE_URL;
   if (!url) {
     const message = "Missing WIRECHUNK_CORE_DATABASE_URL in environment";
-    if (hasEnvFile) {
+    if (env2[mainEnvFileExistsSymbol]) {
       console.error(message);
     } else {
-      console.error(`${message}, no ${envFilePath} file found`);
+      console.error(`${message}, no ${env2[mainEnvFilePathSymbol]} file found`);
     }
     process$2.exit(1);
   }
@@ -26045,16 +26047,20 @@ const coreServerUrlFromEnv = (env2) => {
 };
 const parseEnv = async (envMode) => {
   const env2 = {};
-  if (hasEnvFile) {
-    const envFileRaw = await readFile(envFilePath, "utf8");
-    Object.assign(env2, parseEnv$1(envFileRaw));
-  }
+  const mainEnvFilePath = envMode ? `.env.${envMode}` : envFilePath;
+  const mainEnvFileExists = existsSync(mainEnvFilePath);
   if (envMode) {
-    const modeFilePath = `.env.${envMode}`;
-    if (existsSync(modeFilePath)) {
-      const modeFileRaw = await readFile(modeFilePath, "utf8");
+    if (existsSync(envFilePath)) {
+      const envFileRaw = await readFile(envFilePath, "utf8");
+      Object.assign(env2, parseEnv$1(envFileRaw));
+    }
+    if (mainEnvFileExists) {
+      const modeFileRaw = await readFile(mainEnvFilePath, "utf8");
       Object.assign(env2, parseEnv$1(modeFileRaw));
     }
+  } else if (mainEnvFileExists) {
+    const envFileRaw = await readFile(mainEnvFilePath, "utf8");
+    Object.assign(env2, parseEnv$1(envFileRaw));
   }
   if (existsSync(envLocalFilePath)) {
     const envLocalFileRaw = await readFile(envLocalFilePath, "utf8");
@@ -26070,7 +26076,10 @@ const parseEnv = async (envMode) => {
   Object.assign(env2, process$2.env);
   return {
     ...env2,
-    WIRECHUNK_CORE_SERVER_URL: coreServerUrlFromEnv(env2)
+    WIRECHUNK_CORE_SERVER_URL: coreServerUrlFromEnv(env2),
+    [envModeSymbol]: envMode,
+    [mainEnvFilePathSymbol]: mainEnvFilePath,
+    [mainEnvFileExistsSymbol]: mainEnvFileExists
   };
 };
 var dist$1 = {};
@@ -66402,6 +66411,7 @@ const initDb = async (opts, env2) => {
     coreDbUrl: coreDbUrlObject
   });
 };
+const defaultDevServerImage = "us-docker.pkg.dev/wirechunk/dev-server/core:latest";
 const parseStartFlag = (value, name) => {
   const trimmed = value?.trim();
   if (!trimmed) {
@@ -66414,11 +66424,7 @@ const parseStartFlag = (value, name) => {
   process.exit(1);
 };
 const startCore = async (opts, env2) => {
-  const image = env2.WIRECHUNK_CORE_DEV_SERVER_IMAGE;
-  if (!image) {
-    console.error("Missing WIRECHUNK_CORE_DEV_SERVER_IMAGE in environment");
-    process.exit(1);
-  }
+  const image = env2.WIRECHUNK_CORE_DEV_SERVER_IMAGE?.trim() || defaultDevServerImage;
   const databaseUrl = env2.WIRECHUNK_CORE_DATABASE_URL_DOCKER || env2.WIRECHUNK_CORE_DATABASE_URL;
   if (!databaseUrl) {
     console.error(
@@ -66486,18 +66492,41 @@ const startCore = async (opts, env2) => {
     process.exit(exitCode);
   }
 };
+const hasVersion = (value) => typeof value === "object" && value !== null && "version" in value;
+const packageJsonPath = resolve$1(dirname(fileURLToPath(import.meta.url)), "../package.json");
+const getCliVersion = () => {
+  const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+  if (!hasVersion(parsed) || typeof parsed.version !== "string" || parsed.version.length === 0) {
+    throw new Error("package.json is missing a version string");
+  }
+  return parsed.version;
+};
+const version = (_options) => {
+  console.log(getCliVersion());
+};
 const program = new Command().name("wirechunk").option("--verbose", "output debug logging").option(
   "--env-mode <mode>",
-  'the mode to use for finding .env files to load environment variables, such as "test" to load .env, .env.test, .env.local, and .env.test.local; also for finding config files to include when creating an extension or extension version, such as config.production.json'
+  'the mode to use for finding .env files to load environment variables, such as "test" to load .env, .env.test, .env.local, and .env.test.local (in that order); also for finding config files to include when creating an extension or extension version, such as config.production.json'
 ).description(`The official Wirechunk CLI
 
-By default, environment variables are loaded from the .env file in the current working directory,
-then the .env.local file, and then from the environment. Variables from the environment have the
-highest precedence.
+By default, environment variables are loaded from the .env file in the current working directory, then the .env.local file, and then from the environment.
+
+When --env-mode is used, variables are loaded from .env, then .env.<mode>, then .env.local, then .env.<mode>.local, and finally from the environment.
+
+Variables loaded later overwrite those loaded earlier. Variables from the environment have the highest precedence.
 
 Environment variables used by some commands:
   WIRECHUNK_CORE_SERVER_URL (the core admin server URL for commands using the API)
-  WIRECHUNK_CORE_DATABASE_URL (the core database URL for commands requiring direct database access)`);
+  WIRECHUNK_CORE_DATABASE_URL (the core database URL for commands requiring direct database access)
+  WIRECHUNK_API_TOKEN (the API token for authentication)
+  WIRECHUNK_CORE_JWT_SECRET (the JWT secret for creating new tokens)`);
+const withOptions = (action) => async (options, cmd) => {
+  const mergedOptions = { ...program.opts(), ...options };
+  if (mergedOptions.verbose) {
+    console.log(`Running ${chalk.green.bold(cmd.name())}`);
+  }
+  return action(mergedOptions);
+};
 const withOptionsAndEnv = (action) => async (options, cmd) => {
   const mergedOptions = { ...program.opts(), ...options };
   if (mergedOptions.verbose) {
@@ -66506,6 +66535,7 @@ const withOptionsAndEnv = (action) => async (options, cmd) => {
   const env2 = await parseEnv(mergedOptions.envMode);
   return action(mergedOptions, env2);
 };
+program.command("version").description("print the CLI version").action(withOptions(version));
 program.command("bootstrap").description("create a platform").option("--dev", "bootstrap with development defaults").option("--name <string>", "the name of the platform").option("--handle <string>", "the handle of the platform").option("--admin-site-domain <string>", "the domain of the admin site (dashboard)").action(withOptionsAndEnv(bootstrap));
 program.command("create-extension").description("create an extension").option("--platform-id <string>", "the ID of the platform").option("--name <string>", "the name of the extension").option(
   "--config-file <string>",

package/package.json

@@ -1,22 +1,8 @@
 {
   "name": "@wirechunk/cli",
-  "version": "0.0.9",
+  "version": "0.1.0",
   "private": false,
   "type": "module",
-  "scripts": {
-    "lint": "eslint --fix",
-    "lint:check": "eslint",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "typecheck": "tsc",
-    "typecheck-src": "tsc --skipLibCheck",
-    "typecheck-src:tsgo": "tsgo --skipLibCheck",
-    "test": "echo 'no tests yet'",
-    "build": "npm run build:clean && npm run build:cli",
-    "build:clean": "rm -rf build",
-    "build:cli": "vite build",
-    "prepublishOnly": "npm run typecheck-src && npm run lint:check && npm run build"
-  },
   "bin": {
     "wirechunk": "build/main.js"
   },
@@ -35,8 +21,6 @@
     "@commander-js/extra-typings": "^14.0.0",
     "@graphql-typed-document-node/core": "^3.2.0",
     "@types/archiver": "^6.0.3",
-    "@wirechunk/backend-lib": "0.0.0",
-    "@wirechunk/lib": "0.0.0",
     "archiver": "^7.0.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",