@rodyssey/cli 0.2.1 → 0.3.0

package/README.md

@@ -1,17 +1,103 @@
 # ro-cli
 
-To install dependencies:
+The Rodyssey CLI (`@rodyssey/cli`) — scaffolds, deploys, configures, and ships webapp projects to the rodyssey CMS.
+
+## Installation
+
+The package installs three binaries: `ro` (recommended), `rocli`, and `@rodyssey/cli` (the canonical long form). Pick any.
+
+### Global install (most users)
+
+```bash
+# via Bun
+bun install -g @rodyssey/cli
+
+# via npm
+npm install -g @rodyssey/cli
+
+# verify
+ro --version
+```
+
+### Per-project (no global install)
 
 ```bash
+# Run any time without installing
+bunx @rodyssey/cli@latest auth login -e development
+bunx @rodyssey/cli@latest app create my-app --auto
+```
+
+### Develop against this repo (live-edit the CLI itself)
+
+```bash
+git clone git@github.com:airconcepts/ro-cli.git
+cd ro-cli
 bun install
+bun run build           # produces dist/cli.js with the ro/rocli shebangs
+
+# Register your local checkout as the global `ro` / `rocli` / `@rodyssey/cli`:
+bun link
+
+# Now `ro` everywhere points at this checkout's dist/cli.js
+ro --version            # prints whatever package.json says locally
+
+# When done, unlink to restore the published version:
+bun unlink              # from inside ro-cli/
+bun install -g @rodyssey/cli    # reinstall the published one
 ```
 
-To run:
+If you want to keep **both** the published `ro` and a local-dev version side-by-side without re-linking constantly, add a shell alias for the dev tree:
 
 ```bash
-bun run index.ts
+# in ~/.zshrc or ~/.bashrc
+alias rocli-dev='bun /absolute/path/to/ro-cli/src/cli.ts'
 ```
 
+`rocli-dev` then runs your live TypeScript via Bun (no rebuild needed), while `ro` keeps pointing at the globally-installed published version. The SKILL.md recognizes both names.
+
+## Using with AI agents
+
+The CLI ships with a [SKILL.md](.claude/skills/rodyssey-cli/SKILL.md) that teaches an AI coding agent how to drive `ro` correctly — command map, auth/scope model, deploy-vs-session-token distinction, `app config set` PATCH delta semantics, `global-config` set-vs-patch, and the gotchas that aren't obvious from `--help`.
+
+**To use it in your own project** (assumes Claude Code; adapt the path for other agent frameworks):
+
+```bash
+mkdir -p .claude/skills/rodyssey-cli
+curl -L https://raw.githubusercontent.com/airconcepts/ro-cli/main/.claude/skills/rodyssey-cli/SKILL.md \
+  -o .claude/skills/rodyssey-cli/SKILL.md
+```
+
+Or just copy [`.claude/skills/rodyssey-cli/SKILL.md`](.claude/skills/rodyssey-cli/SKILL.md) verbatim into your project's skills directory. Once loaded, your agent will recognize `ro app *` / `ro auth *` / `ro global-config *` commands, suggest the right subcommand for natural-language requests, and avoid the common footguns (e.g., echoing a `config get` response back into `config set --details` and wiping data).
+
+## Authentication
+
+`ro auth login -e <env>` runs a PKCE browser flow against the CMS. The consent screen
+lets the user authorize the CLI to act as themselves or as a service account they host,
+and pick which scopes to grant. The token is persisted at `~/.rodyssey/config.json`
+under `auth.<env>` along with an `identity` block describing who the token represents.
+
+`ro auth me -e <env>` reads that local session and prints which environment + identity
+is active. Examples:
+
+```
+$ ro auth me -e development
+Environment: development
+CMS URL:     https://development-cms.rodyssey.ai
+Logged in as: alex@example.com
+Granted scopes: webapps:create, webapps:deploy-token:create, cms:global-config:read
+
+$ ro auth me -e development        # after authorizing as a service account
+Environment: development
+CMS URL:     https://development-cms.rodyssey.ai
+Logged in as service account: deploy-bot (id: sa-abc-123)
+Granted scopes: webapps:create, feed:post
+```
+
+Add `--remote` to also call `/api/auth/me` for a freshness check.
+
+Sessions that pre-date the identity-aware flow render as `Logged in (legacy session —
+no identity block stored)`. Re-running `ro auth login -e <env>` refreshes them.
+
 ## Template Upgrade
 
 `app upgrade-template` backfills additive template files that are missing from

package/dist/cli.js

@@ -2071,14 +2071,16 @@ var {
 // package.json
 var package_default = {
   name: "@rodyssey/cli",
-  version: "0.2.1",
+  version: "0.3.0",
   description: "Scaffold new projects from airconcepts templates",
   repository: {
     type: "git",
     url: "git+https://github.com/airconcepts/ro-cli.git"
   },
   bin: {
-    "@rodyssey/cli": "dist/cli.js"
+    "@rodyssey/cli": "dist/cli.js",
+    ro: "dist/cli.js",
+    rocli: "dist/cli.js"
   },
   files: [
     "dist"
@@ -2123,19 +2125,47 @@ var CMS_BASE_URLS = {
   staging: "https://staging-cms.rodyssey.ai",
   production: "https://cms.rodyssey.ai"
 };
-var CONFIG_FILE = join(homedir(), ".rodyssey", "config.json");
+function describeSession(session) {
+  const base = { env: session.env, cmsUrl: session.cmsUrl };
+  if (session.identity?.type === "service-account") {
+    return {
+      ...base,
+      identityLine: `Logged in as service account: ${session.identity.label} (id: ${session.identity.id})`,
+      scopesLine: `Granted scopes: ${session.identity.scopes.join(", ")}`
+    };
+  }
+  if (session.identity?.type === "user") {
+    return {
+      ...base,
+      identityLine: `Logged in as: ${session.identity.label}`,
+      scopesLine: `Granted scopes: ${session.identity.scopes.join(", ")}`
+    };
+  }
+  return {
+    ...base,
+    identityLine: "Logged in (legacy session — no identity block stored)"
+  };
+}
+function configPath() {
+  const override = process.env.RODYSSEY_CONFIG_DIR;
+  if (override)
+    return join(override, "config.json");
+  return join(homedir(), ".rodyssey", "config.json");
+}
 function readConfig() {
-  if (!existsSync(CONFIG_FILE))
+  const file = configPath();
+  if (!existsSync(file))
     return {};
   try {
-    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+    return JSON.parse(readFileSync(file, "utf-8"));
   } catch {
     return {};
   }
 }
 function writeConfig(config) {
-  mkdirSync(dirname(CONFIG_FILE), { recursive: true });
-  writeFileSync(CONFIG_FILE, `${JSON.stringify(config, null, 2)}
+  const file = configPath();
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(config, null, 2)}
 `, "utf-8");
 }
 function getAuthConfig(config) {
@@ -2167,6 +2197,38 @@ function extractUser(payload) {
     return;
   return payload.user ?? (isObject(payload.data) ? payload.data.user : undefined);
 }
+function parseIdentity(raw) {
+  if (!isObject(raw))
+    return;
+  if (raw.type !== "user" && raw.type !== "service-account")
+    return;
+  if (typeof raw.id !== "string" || typeof raw.label !== "string")
+    return;
+  if (!Array.isArray(raw.scopes) || !raw.scopes.every((s) => typeof s === "string")) {
+    return;
+  }
+  return {
+    type: raw.type,
+    id: raw.id,
+    label: raw.label,
+    scopes: raw.scopes
+  };
+}
+function extractSessionFromTokenResponse(payload, ctx) {
+  const token = extractToken(payload);
+  if (!token) {
+    throw new Error(`CMS token response did not include an auth token:
+${JSON.stringify(payload, null, 2)}`);
+  }
+  const identity = isObject(payload) ? parseIdentity(payload.identity) : undefined;
+  const user = extractUser(payload);
+  const session = { env: ctx.env, cmsUrl: ctx.cmsUrl, token };
+  if (user !== undefined)
+    session.user = user;
+  if (identity)
+    session.identity = identity;
+  return session;
+}
 async function readResponsePayload(response) {
   const text = await response.text();
   if (!text)
@@ -2365,17 +2427,7 @@ ${authorizationUrl.toString()}
     throw new Error(`CMS token exchange failed: ${response.status} ${response.statusText}
 ${JSON.stringify(payload, null, 2)}`);
   }
-  const token = extractToken(payload);
-  if (!token) {
-    throw new Error(`CMS token response did not include an auth token:
-${JSON.stringify(payload, null, 2)}`);
-  }
-  const session = {
-    env: options.env,
-    cmsUrl,
-    token,
-    user: extractUser(payload)
-  };
+  const session = extractSessionFromTokenResponse(payload, { env: options.env, cmsUrl });
   if (options.persist !== false) {
     storeSession(session);
   }
@@ -2383,18 +2435,25 @@ ${JSON.stringify(payload, null, 2)}`);
 }
 async function me(options) {
   const storedSession = getStoredSession(options.env);
+  if (!storedSession) {
+    throw new Error(`No local CMS session found for [${options.env}]. Run \`ro auth login --env ${options.env}\` first.`);
+  }
+  const description = describeSession(storedSession);
+  console.log(`Environment: ${description.env}`);
+  console.log(`CMS URL:     ${description.cmsUrl}`);
+  console.log(description.identityLine);
+  if (description.scopesLine)
+    console.log(description.scopesLine);
   if (!options.remote) {
-    if (!storedSession) {
-      throw new Error(`No local CMS session found for [${options.env}]. Run \`ro auth login --env ${options.env}\` first.`);
-    }
     return {
       env: storedSession.env,
       cmsUrl: storedSession.cmsUrl,
       loggedIn: true,
+      identity: storedSession.identity ?? null,
       user: storedSession.user ?? null
     };
   }
-  const cmsUrl = resolveCmsUrl(options.env, options.cmsUrl || storedSession?.cmsUrl);
+  const cmsUrl = resolveCmsUrl(options.env, options.cmsUrl || storedSession.cmsUrl);
   const response = await fetch(options.meUrl || `${cmsUrl}/api/auth/me`, {
     method: "GET",
     headers: {
@@ -2407,6 +2466,9 @@ async function me(options) {
     throw new Error(`CMS me failed: ${response.status} ${response.statusText}
 ${JSON.stringify(payload, null, 2)}`);
   }
+  console.log(`
+Server view:`);
+  console.log(JSON.stringify(payload, null, 2));
   return payload;
 }
 
@@ -5047,6 +5109,19 @@ async function updateGameSdk() {
 }
 
 // src/cli.ts
+function renderError(err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(`
+Error: ${msg}`);
+  if (process.env.RO_DEBUG && err instanceof Error && err.stack) {
+    console.error(`
+${err.stack}`);
+  }
+  console.error();
+  process.exit(1);
+}
+process.on("unhandledRejection", renderError);
+process.on("uncaughtException", renderError);
 var TEMPLATES2 = {
   webapp: {
     name: "webapp",
@@ -5110,8 +5185,7 @@ function addAuthCommands(parent) {
     console.log(`\uD83D\uDCCD CMS URL: ${session.cmsUrl}`);
   });
   auth.command("me").description("Show the locally stored CMS login session").option("-e, --env <environment>", "CMS environment (local | development | staging | production)", "development").option("--remote", "Call the CMS /me endpoint instead of only reading the local session").option("--cms-url <url>", "CMS base URL for --remote. Defaults to the selected environment or stored session").option("--me-url <url>", "Full me endpoint URL for --remote. Defaults to <cms-url>/api/auth/me").action(async (options) => {
-    const currentUser = await me(options);
-    console.log(JSON.stringify(currentUser, null, 2));
+    await me(options);
   });
   return auth;
 }

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@rodyssey/cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Scaffold new projects from airconcepts templates",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/airconcepts/ro-cli.git"
   },
   "bin": {
-    "@rodyssey/cli": "dist/cli.js"
+    "@rodyssey/cli": "dist/cli.js",
+    "ro": "dist/cli.js",
+    "rocli": "dist/cli.js"
   },
   "files": [
     "dist"