@genex-ai/cli-demo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 me-ai-org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# @genex-ai/cli-demo
+
+Set up your `~/.claude` workspace, authorize, create a game project, and publish.
+This is the `cli` app of the [genex monorepo](../../README.md).
+
+```bash
+genex init <name>     # authorize + create the draft project
+genex publish         # push the built game + list it in the gallery
+```
+
+`genex init` does four things:
+
+1. **Scaffolds your workspace** — copies the bundled templates (skills, agents,
+   commands) into `~/.claude`, *merging* into whatever is already there. Existing
+   files are **never overwritten**.
+2. **Authorizes you** — opens the Genex auth site (web) in your browser. If the
+   browser can't open, it prints the URL to open manually.
+3. **Saves your token** — writes `GENEX_TOKEN` to `~/.genex/env` (per-user;
+   reused across projects).
+4. **Creates the draft project** — generates a per-project SSH deploy key
+   (`genex_key`, gitignored automatically), registers its public half with a new
+   repo via `POST /api/projects`, and stores the project metadata (id, slug,
+   `sshUrl`, urls) in `./.genex/project.json`. The game shows up in your
+   dashboard's **My games** immediately.
+
+`genex publish` reads that metadata, pushes the built game to GitHub over the
+deploy key (best-effort — `index.html` must be at the repo root), then flips the
+project to **published** so it appears in the public gallery. `git push` (updates
+the live Pages site) and the gallery flag are independent; `--no-push` skips the
+push. Defaults: API `https://demo-api.glotech.world`, auth site
+`https://demo-web.glotech.world` — override with `--api-url` / `--auth-url` (or
+`GENEX_API_URL` / `GENEX_AUTH_URL`) for local dev.
+
+## Install / run
+
+From the monorepo root (the CLI runs directly via Node — no build step):
+
+```bash
+pnpm start:cli init          # = node apps/cli/src/index.ts init
+```
+
+Or from this package:
+
+```bash
+pnpm --filter @genex-ai/cli-demo start init
+```
+
+Once published, end users run it with `npx`:
+
+```bash
+npx @genex-ai/cli-demo init
+```
+
+> Requires **Node ≥ 24** (the CLI is executed as TypeScript via Node's native
+> type stripping, matching the rest of the monorepo).
+
+## Usage
+
+```
+genex init [options]
+
+Options
+  --dir <path>         Destination workspace (default: ~/.claude)
+  --env <path>         Path to the .env file to write (default: ./.env)
+  --auth-url <url>     Override the auth site (default: https://genex.dev)
+  --no-auth            Only scaffold templates; skip authorization
+  --force              Overwrite existing files (default: never overwrite)
+  --timeout <seconds>  How long to wait for the auth redirect (default: 300)
+  --quiet              Reduce output
+
+Global
+  -h, --help           Show help
+  -v, --version        Show version
+```
+
+### Examples
+
+```bash
+# Full setup: scaffold + authorize
+genex init
+
+# Just scaffold the workspace, no auth
+genex init --no-auth
+
+# Point at a local auth server during development
+genex init --auth-url http://localhost:3000
+```
+
+> In the monorepo, substitute `pnpm start:cli` for `genex` (e.g.
+> `pnpm start:cli init --no-auth`).
+
+## Configuration
+
+The auth site URL is a single configurable value:
+
+- **Default:** `https://genex.dev` (the `DEFAULT_AUTH_URL` constant in
+  [`src/config.ts`](src/config.ts)).
+- **Override at runtime:** set `GENEX_AUTH_URL`, or pass `--auth-url`.
+
+```bash
+GENEX_AUTH_URL=https://staging.genex.dev genex init
+```
+
+To control which browser is launched, set `GENEX_BROWSER` (or the conventional
+`BROWSER`) to an opener command. It's parsed like a shell command, so arguments
+work and paths containing spaces should be quoted:
+
+```bash
+GENEX_BROWSER="firefox" genex init
+GENEX_BROWSER="open -a Safari" genex init
+GENEX_BROWSER="'/Applications/My Browser.app/Contents/MacOS/My Browser'" genex init
+```
+
+## How authorization works
+
+The CLI uses a loopback-redirect flow (the same pattern as `gh auth login` and
+`gcloud`). The backend only needs to honor this contract:
+
+1. The CLI starts a temporary HTTP server on `http://127.0.0.1:<random-port>`
+   and opens the browser to:
+
+   ```
+   {AUTH_URL}/cli/auth?redirect_uri=http://127.0.0.1:<port>/callback&state=<random>
+   ```
+
+2. After the user logs in, the site returns the token to that `redirect_uri`,
+   either by:
+
+   - **Redirecting (GET):**
+     `http://127.0.0.1:<port>/callback?token=<TOKEN>&state=<random>`, **or**
+   - **Posting (POST):** a request to `http://127.0.0.1:<port>/callback` with a
+     body of `{"token":"<TOKEN>","state":"<random>"}` (JSON) or
+     `token=<TOKEN>&state=<random>` (form-encoded).
+
+   The loopback server sends permissive CORS headers, so a browser `fetch()` to
+   the callback from the auth site's origin works.
+
+   > The `state` value is **required** on the callback — the site must echo back
+   > the exact `state` it received. A missing or mismatched `state` is rejected
+   > (CSRF protection).
+
+3. The CLI verifies `state`, writes `GENEX_TOKEN=<TOKEN>` to `.env`, and shows a
+   success page in the browser.
+
+If the browser can't be opened, the URL is printed and — when run in an
+interactive terminal — a pasted token is also accepted.
+
+> **Windows note:** the `.env` file is created `0600` (owner-only) on
+> macOS/Linux. On Windows, POSIX modes don't apply; the CLI makes a best-effort
+> attempt to restrict the file's ACL to the current user via `icacls`, but if
+> that fails the token file may inherit the directory's permissions. Keep your
+> project directory out of shared/world-readable locations.
+
+## Development
+
+No build step — like the rest of the monorepo, the CLI runs as TypeScript via
+Node's native type stripping. Run these from this package (or use the root
+`pnpm typecheck` / `pnpm test:cli`):
+
+```bash
+pnpm typecheck   # tsc --noEmit (extends ../../tsconfig.base.json)
+pnpm test        # node --test test/*.test.ts
+
+# Try it locally:
+pnpm start init --no-auth --dir ./tmp-claude
+```
+
+Relative imports use explicit `.ts` extensions and only erasable TypeScript
+syntax is allowed — both are monorepo-wide rules (see the root README).
+
+### Project layout
+
+```
+src/
+  index.ts              CLI entry: arg parsing + dispatch
+  config.ts             AUTH_URL constant, path helpers
+  commands/init.ts      the `init` command orchestration
+  lib/
+    copy-templates.ts   recursive merge-copy (never overwrites)
+    env.ts              read/modify/write .env safely
+    auth.ts             loopback server + browser opener
+  utils/                logger + colors (zero runtime deps)
+templates/              copied into ~/.claude by `genex init`
+```
+
+## Publishing
+
+The package ships its TypeScript source (no bundle); consumers run it on
+Node ≥ 24. The published tarball includes only `src/`, `templates/`, `README.md`,
+and `LICENSE` (see the `files` field in `package.json`).
+
+```bash
+pnpm --filter @genex-ai/cli-demo publish --access public
+```
+
+## License
+
+MIT © me-ai-org

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@genex-ai/cli-demo",
+  "version": "0.1.0",
+  "description": "Set up your ~/.claude workspace, authorize, create a game project, and publish (genex CLI).",
+  "type": "module",
+  "bin": {
+    "genex": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "keywords": [
+    "cli",
+    "claude",
+    "genex",
+    "scaffold",
+    "init"
+  ],
+  "author": "me-ai-org",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/me-ai-org/genex-demo.git",
+    "directory": "apps/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/me-ai-org/genex-demo/issues"
+  },
+  "homepage": "https://github.com/me-ai-org/genex-demo/tree/main/apps/cli#readme",
+  "scripts": {
+    "start": "node src/index.ts",
+    "dev": "node --watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test test/*.test.ts"
+  }
+}

package/src/commands/init.ts

@@ -0,0 +1,131 @@
+import path from "node:path";
+import {
+  ENV_TOKEN_KEY,
+  getApiUrl,
+  getAuthUrl,
+  getClaudeDir,
+  getColyseusUrl,
+  getTemplatesDir,
+} from "../config.ts";
+import { copyTemplates } from "../lib/copy-templates.ts";
+import { authorize } from "../lib/auth.ts";
+import { createDraftProject } from "../lib/project.ts";
+import { generateSshKeypair, writeGitignore } from "../lib/ssh.ts";
+import { writeProject, writeUserToken } from "../lib/store.ts";
+import { createLogger } from "../utils/logger.ts";
+import { c } from "../utils/colors.ts";
+
+export interface InitOptions {
+  /** Destination workspace. Defaults to `~/.claude`. */
+  dir?: string;
+  /** Override the auth site (web) URL. */
+  authUrl?: string;
+  /** Override the API base URL (where the project is created). */
+  apiUrl?: string;
+  /** Override the Colyseus relay URL (stored in project metadata). */
+  colyseusUrl?: string;
+  /** Project name. Defaults to the current directory's name. */
+  name?: string;
+  /** Path to the token env file. Defaults to `~/.genex/env`. */
+  envPath?: string;
+  /** Skip the authorization step; only scaffold templates. */
+  noAuth?: boolean;
+  /** Overwrite existing files in the destination (off by default). */
+  force?: boolean;
+  /** Auth redirect wait timeout, in seconds. */
+  timeoutSec?: number;
+  quiet?: boolean;
+}
+
+export async function runInit(opts: InitOptions): Promise<void> {
+  const log = createLogger({ quiet: opts.quiet });
+
+  log.plain(c.bold("genex init"));
+  log.plain("");
+
+  // 1. Scaffold the ~/.claude workspace from bundled templates.
+  const templatesDir = getTemplatesDir();
+  const claudeDir = getClaudeDir(opts.dir);
+
+  log.step(`Setting up your workspace at ${c.cyan(claudeDir)}`);
+  const { copied, skipped } = await copyTemplates(templatesDir, claudeDir, {
+    force: opts.force,
+  });
+
+  if (copied.length > 0) {
+    log.success(`Added ${copied.length} file${copied.length === 1 ? "" : "s"}.`);
+    for (const f of copied) log.dim(`  + ${f}`);
+  }
+  if (skipped.length > 0) {
+    log.info(
+      `Left ${skipped.length} existing file${skipped.length === 1 ? "" : "s"} untouched.`,
+    );
+    for (const f of skipped) log.dim(`  = ${f}`);
+  }
+  if (copied.length === 0 && skipped.length === 0) {
+    log.info("No template files to install.");
+  }
+  log.plain("");
+
+  // 2. Authorize (unless skipped).
+  if (opts.noAuth) {
+    log.info("Skipping authorization (--no-auth).");
+    log.success("Done.");
+    return;
+  }
+
+  const authBaseUrl = getAuthUrl(opts.authUrl);
+  let token: string;
+  try {
+    token = await authorize(authBaseUrl, {
+      log,
+      timeoutMs: opts.timeoutSec ? opts.timeoutSec * 1000 : undefined,
+    });
+  } catch (err) {
+    log.error(err instanceof Error ? err.message : String(err));
+    log.dim("Your workspace files were installed. Re-run `genex init` to finish authorizing.");
+    throw err;
+  }
+
+  log.success("Authorized.");
+
+  // 3. Persist the token to ~/.genex/env (per-user; reused across projects).
+  const { path: tokenPath } = await writeUserToken(token, opts.envPath);
+  log.success(`Saved your token to ${c.cyan(tokenPath)} (${ENV_TOKEN_KEY}).`);
+  log.plain("");
+
+  // 4. Generate a per-project deploy key, then create the draft project so it
+  //    shows up in the dashboard's "My games" immediately. The private key stays
+  //    local (gitignored); only its public half is registered with the repo.
+  const key = await generateSshKeypair(process.cwd(), log);
+  await writeGitignore(process.cwd(), log);
+  if (!key) {
+    log.warn(
+      "Skipping project creation — no deploy key. Install ssh-keygen (OpenSSH) and re-run `genex init`.",
+    );
+    log.plain("");
+    log.success("Workspace ready (no project created yet).");
+    return;
+  }
+
+  const apiUrl = getApiUrl(opts.apiUrl);
+  const colyseusUrl = getColyseusUrl(opts.colyseusUrl);
+  const projectName = opts.name?.trim() || path.basename(process.cwd());
+
+  const meta = await createDraftProject({
+    apiUrl,
+    token,
+    name: projectName,
+    deployKey: key.publicKey,
+    colyseusUrl,
+    dashboardUrl: authBaseUrl,
+    log,
+  });
+  if (meta) {
+    const { path: metaPath } = await writeProject(meta);
+    log.dim(`  saved ${c.cyan(metaPath)}`);
+  }
+
+  log.plain("");
+  log.success("All set. 🚀");
+}

package/src/commands/publish.ts

@@ -0,0 +1,151 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getApiUrl } from "../config.ts";
+import { readProject, readUserToken } from "../lib/store.ts";
+import { KEY_NAME } from "../lib/ssh.ts";
+import { createLogger, type Logger } from "../utils/logger.ts";
+import { c } from "../utils/colors.ts";
+
+export interface PublishOptions {
+  /** Override the API base URL (defaults to the project's stored apiUrl). */
+  apiUrl?: string;
+  /** Override the bearer token (defaults to ~/.genex/env). */
+  token?: string;
+  /** Path to the token env file (defaults to ~/.genex/env). */
+  envPath?: string;
+  /** Skip the git push; only flip the gallery flag. */
+  noPush?: boolean;
+  /** Optional gallery metadata. */
+  title?: string;
+  description?: string;
+  quiet?: boolean;
+}
+
+interface RunResult {
+  code: number;
+  out: string;
+  err: string;
+}
+
+/** Run a command, capturing output. Resolves with the exit code (never throws). */
+function run(cmd: string, args: string[], env?: NodeJS.ProcessEnv): Promise<RunResult> {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, args, { env: env ? { ...process.env, ...env } : process.env });
+    } catch {
+      resolve({ code: -1, out: "", err: `${cmd} not found` });
+      return;
+    }
+    let out = "";
+    let err = "";
+    child.stdout?.on("data", (d) => (out += String(d)));
+    child.stderr?.on("data", (d) => (err += String(d)));
+    child.on("error", () => resolve({ code: -1, out, err: `${cmd} not found` }));
+    child.on("close", (code) => resolve({ code: code ?? -1, out, err }));
+  });
+}
+
+/**
+ * `genex publish` — push the built game to GitHub over the project's deploy key
+ * (best-effort), then flip the project from draft to published in the gallery.
+ *
+ * push (updates the live Pages site) and publish (the gallery flag) are
+ * independent per CLI_INTEGRATION.md, so a failed/absent push (e.g. locally with
+ * the mock provider — no real repo) never blocks the gallery flip.
+ */
+export async function runPublish(opts: PublishOptions): Promise<void> {
+  const log = createLogger({ quiet: opts.quiet });
+  log.plain(c.bold("genex publish"));
+  log.plain("");
+
+  const token = opts.token ?? (await readUserToken(opts.envPath));
+  if (!token) {
+    log.error("Not authorized. Run `genex init` first to sign in.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const meta = await readProject();
+  if (!meta) {
+    log.error("No genex project here. Run `genex init` in this directory first.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const apiUrl = getApiUrl(opts.apiUrl ?? meta.apiUrl);
+
+  // 1. Push the built game (best-effort).
+  if (opts.noPush) {
+    log.info("Skipping git push (--no-push).");
+  } else {
+    await pushGame(meta.sshUrl, log);
+  }
+
+  // 2. Flip the gallery flag (authoritative).
+  log.step("Publishing to the gallery…");
+  let res: Response;
+  try {
+    const body: Record<string, string> = {};
+    if (opts.title) body.title = opts.title;
+    if (opts.description) body.description = opts.description;
+    res = await fetch(`${apiUrl}/api/projects/${meta.id}/publish`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    log.error(`Couldn't reach the API at ${apiUrl}: ${String(err)}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!res.ok) {
+    log.error(`Publish failed (HTTP ${res.status}).`);
+    process.exitCode = 1;
+    return;
+  }
+
+  log.plain("");
+  log.success("Published. 🎉");
+  if (meta.playUrl) {
+    log.dim(`  play: ${meta.playUrl}`);
+    log.dim("  (GitHub Pages rebuilds ~30–90s after a push.)");
+  }
+}
+
+async function pushGame(sshUrl: string, log: Logger): Promise<void> {
+  // GitHub Pages serves the repo root — the game's entry must be index.html there.
+  try {
+    await fs.access(path.join(process.cwd(), "index.html"));
+  } catch {
+    log.warn("No index.html at the project root — GitHub Pages needs one to serve the game.");
+  }
+
+  const isRepo = (await run("git", ["rev-parse", "--git-dir"])).code === 0;
+  if (!isRepo) {
+    log.step("Initializing git…");
+    if ((await run("git", ["init"])).code !== 0) {
+      log.warn("git init failed — skipping push (use `genex publish --no-push` to silence).");
+      return;
+    }
+  }
+
+  await run("git", ["add", "-A"]);
+  const commit = await run("git", ["commit", "-m", "build"]);
+  if (commit.code !== 0 && !/nothing to commit/i.test(commit.out + commit.err)) {
+    log.dim("  (no new commit to push)");
+  }
+
+  log.step("Pushing your game over SSH…");
+  const push = await run("git", ["push", sshUrl, "HEAD:main"], {
+    GIT_SSH_COMMAND: `ssh -i ./${KEY_NAME} -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new`,
+  });
+  if (push.code === 0) {
+    log.success("Pushed to main.");
+  } else {
+    log.warn("git push didn't succeed (expected locally — the mock provider has no real repo).");
+    const tail = push.err.trim().split("\n").slice(-1)[0];
+    if (tail) log.dim(`  ${tail}`);
+  }
+}

package/src/config.ts

@@ -0,0 +1,102 @@
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The Genex authorization SITE — the web app that renders `/cli/auth` + `/login`
+ * (NOT the API). The CLI opens `<authUrl>/cli/auth` in the browser. Override with
+ * `GENEX_AUTH_URL` or `--auth-url` (locally: http://localhost:5173).
+ */
+export const DEFAULT_AUTH_URL = "https://demo-web.glotech.world";
+
+/**
+ * The Genex API base URL (where projects are created + published). Distinct from
+ * the auth site. Override with `GENEX_API_URL` or `--api-url` (locally:
+ * http://localhost:3000).
+ */
+export const DEFAULT_API_URL = "https://demo-api.glotech.world";
+
+/**
+ * The Colyseus multiplayer relay URL. Stored in the project metadata + printed so
+ * the agent's game can `connect({ url, room: slug })`. Override with
+ * `GENEX_COLYSEUS_URL` or `--colyseus-url` (locally: ws://localhost:2567).
+ */
+export const DEFAULT_COLYSEUS_URL = "wss://demo-colyseus.glotech.world";
+
+/** Environment variable name written to `~/.genex/env` after authorizing. */
+export const ENV_TOKEN_KEY = "GENEX_TOKEN";
+
+/** Environment variable that overrides {@link DEFAULT_AUTH_URL}. */
+export const AUTH_URL_ENV = "GENEX_AUTH_URL";
+
+/** Environment variable that overrides {@link DEFAULT_API_URL}. */
+export const API_URL_ENV = "GENEX_API_URL";
+
+/** Environment variable that overrides {@link DEFAULT_COLYSEUS_URL}. */
+export const COLYSEUS_URL_ENV = "GENEX_COLYSEUS_URL";
+
+/**
+ * Resolve the auth site URL, honoring (in order): an explicit override
+ * (the `--auth-url` flag), the `GENEX_AUTH_URL` env var, then the default.
+ * Any trailing slashes are trimmed so we can safely append paths.
+ */
+export function getAuthUrl(override?: string): string {
+  const raw = override || process.env[AUTH_URL_ENV] || DEFAULT_AUTH_URL;
+  return raw.replace(/\/+$/, "");
+}
+
+/**
+ * Resolve the API base URL, honoring (in order): an explicit override (the
+ * `--api-url` flag), the `GENEX_API_URL` env var, then the default. Trailing
+ * slashes are trimmed so we can safely append paths.
+ */
+export function getApiUrl(override?: string): string {
+  const raw = override || process.env[API_URL_ENV] || DEFAULT_API_URL;
+  return raw.replace(/\/+$/, "");
+}
+
+/**
+ * Resolve the Colyseus relay URL, honoring (in order): an explicit override (the
+ * `--colyseus-url` flag), the `GENEX_COLYSEUS_URL` env var, then the default.
+ */
+export function getColyseusUrl(override?: string): string {
+  const raw = override || process.env[COLYSEUS_URL_ENV] || DEFAULT_COLYSEUS_URL;
+  return raw.replace(/\/+$/, "");
+}
+
+/** The per-user Genex config dir (`~/.genex`) holding the auth token. */
+export function getGenexDir(): string {
+  return path.join(os.homedir(), ".genex");
+}
+
+/**
+ * Default location of the per-user env file the token is written to
+ * (`~/.genex/env`), or an explicit path when `--env` is supplied.
+ */
+export function getGenexEnvPath(override?: string): string {
+  if (override) return path.resolve(override);
+  return path.join(getGenexDir(), "env");
+}
+
+/** Absolute path to the bundled `templates/` directory shipped with the package. */
+export function getTemplatesDir(): string {
+  // After bundling, this module lives at `dist/index.js`; templates sit at the
+  // package root, one level up.
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, "..", "templates");
+}
+
+/**
+ * The destination workspace — the user's global `~/.claude` directory by
+ * default, or an explicit path when `--dir` is supplied.
+ */
+export function getClaudeDir(override?: string): string {
+  if (override) return path.resolve(override);
+  return path.join(os.homedir(), ".claude");
+}
+
+/** Default location of the `.env` file we write the token into. */
+export function getEnvPath(override?: string): string {
+  if (override) return path.resolve(override);
+  return path.join(process.cwd(), ".env");
+}