@globio/cli 0.2.2 → 1.0.0

package/README.md

@@ -1,7 +1,12 @@
 # @globio/cli
 
-The official CLI for [Globio](https://globio.stanlink.online)
-— game backend as a service built on Cloudflare Workers.
+The official CLI for [Globio](https://globio.stanlink.online) —
+game backend as a service built on Cloudflare Workers.
+
+## Requirements
+
+- Node.js 18+
+- A Globio account — [console.globio.stanlink.online](https://console.globio.stanlink.online)
 
 ## Install
 
@@ -16,81 +21,280 @@ npm install -g @globio/cli
 ## Quick Start
 
 ```bash
-npx @globio/cli login
-npx @globio/cli init
+# Log in to your Globio account
+globio login
+
+# Initialize a new project
+globio init
+
+# Or non-interactively
+globio init --name "My Game" --org org_xxx --json
 ```
 
-## Migrate from Firebase
+---
+
+## Authentication
 
+Globio CLI authenticates at account level using a Personal
+Access Token (PAT). Two login methods are supported.
+
+**Browser flow** — opens the Globio console for one-click approval:
 ```bash
-# Migrate all Firestore collections to GlobalDoc
-npx @globio/cli migrate firestore \
-  --from ./serviceAccountKey.json \
-  --all
+globio login
+```
 
-# Migrate Firebase Storage to GlobalVault
-npx @globio/cli migrate firebase-storage \
-  --from ./serviceAccountKey.json \
-  --bucket gs://my-game.appspot.com \
-  --all
+**Token flow** — paste a PAT from console settings:
+```bash
+globio login --token glo_pat_xxxxx
 ```
 
-After migration, GlobalDoc indexes are created automatically for every field in your collections.
-Queries using `where()` clauses will work immediately.
+**Named profiles** — manage multiple accounts:
+```bash
+globio login --profile work
+globio login --profile personal
+globio use work
+```
 
-Note: GlobalDoc requires explicit indexes unlike Firestore's automatic indexing.
-The migrate command handles this for you automatically.
+Credentials are stored in `~/.globio/profiles/`
+
+---
 
 ## Commands
 
 ### Auth
+
 ```bash
-globio login       # authenticate
+globio login                        # browser or token flow
+globio login --token <pat>          # non-interactive
+globio login --profile <name>       # named profile
 globio logout
-globio whoami      # show active account and project
+globio logout --profile <name>
+globio whoami
+globio whoami --json
+```
+
+### Profiles
+
+```bash
+globio profiles list
+globio profiles list --json
+globio use <profile>                # switch active profile
 ```
 
 ### Projects
+
 ```bash
 globio projects list
+globio projects list --json
 globio projects use <projectId>
+globio projects create              # interactive
+globio projects create \
+  --name "My Game" \
+  --org <orgId> \
+  --json                            # non-interactive
 ```
 
 ### Services
+
 ```bash
 globio services list
+globio services list --json
 ```
 
-### Functions (GlobalCode)
+### Edge Functions (GlobalCode)
+
 ```bash
 globio functions list
-globio functions create <slug>     # scaffold locally
-globio functions deploy <slug>     # deploy to Globio
+globio functions list --json
+globio functions create <slug>      # scaffold locally
+globio functions deploy <slug>      # deploy to Globio
 globio functions invoke <slug> --input '{"key":"value"}'
+globio functions invoke <slug> --input '{"key":"value"}' --json
 globio functions logs <slug>
+globio functions logs <slug> --json
+globio functions watch <slug>       # live log streaming
 globio functions enable <slug>
 globio functions disable <slug>
 globio functions delete <slug>
 ```
 
+### GC Hooks
+
+GC Hooks fire automatically when events occur in your
+Globio project. They cannot be invoked manually.
+
+```bash
+globio hooks list
+globio hooks list --json
+globio hooks create <slug>          # scaffold locally
+globio hooks deploy <slug> \
+  --trigger id.onSignup             # deploy with trigger
+globio hooks logs <slug>
+globio hooks watch <slug>           # live log streaming
+globio hooks enable <slug>
+globio hooks disable <slug>
+globio hooks delete <slug>
+```
+
+**Available hook triggers:**
+
+| Trigger | Fires when |
+|---|---|
+| `id.onSignup` | New user registers |
+| `id.onSignin` | User signs in |
+| `id.onSignout` | User signs out |
+| `id.onPasswordReset` | Password reset completed |
+| `doc.onCreate` | Document created |
+| `doc.onUpdate` | Document updated |
+| `doc.onDelete` | Document deleted |
+| `mart.onPurchase` | In-game currency purchase |
+| `mart.onPayment` | Fiat payment completed |
+| `sync.onRoomCreate` | Game room created |
+| `sync.onRoomClose` | Game room closed |
+| `sync.onPlayerJoin` | Player joins a room |
+| `sync.onPlayerLeave` | Player leaves a room |
+| `vault.onUpload` | File uploaded |
+| `vault.onDelete` | File deleted |
+| `signal.onDeliver` | Notification delivered |
+
+**Example hook:**
+```javascript
+// init-player.hook.js
+async function handler({ userId, email }, globio) {
+  await globio.doc.set('players', userId, {
+    level: 1, xp: 0, coins: 100
+  });
+  await globio.signal.sendToUser(userId, {
+    title: 'Welcome!',
+    body: 'Your adventure begins.',
+    priority: 'high'
+  });
+}
+```
+
+```bash
+globio hooks deploy init-player --trigger id.onSignup
+```
+
 ### Migrate from Firebase
+
+Migrate Firestore collections and Firebase Storage
+to Globio in one command. Non-destructive — your
+Firebase data stays intact until you delete it manually.
+
+GlobalDoc indexes are created automatically for every
+field during migration. Queries work immediately after.
+
 ```bash
+# Migrate a single Firestore collection
 globio migrate firestore \
   --from ./serviceAccountKey.json \
   --collection players
 
+# Migrate all Firestore collections
 globio migrate firestore \
   --from ./serviceAccountKey.json \
   --all
 
+# Migrate Firebase Storage
 globio migrate firebase-storage \
   --from ./serviceAccountKey.json \
   --bucket gs://my-game.appspot.com \
   --all
+
+# Migrate a specific folder
+globio migrate firebase-storage \
+  --from ./serviceAccountKey.json \
+  --bucket gs://my-game.appspot.com \
+  --folder /avatars
 ```
 
-## Built with Globio
+---
+
+## JSON Output and CI/CD
+
+Every command supports `--json` for machine-readable output.
+Use this in CI/CD pipelines, scripts, and AI agents.
+
+```bash
+globio whoami --json
+globio projects list --json
+globio functions list --json
+globio functions invoke <slug> --input '{}' --json
+globio hooks list --json
+globio services list --json
+```
+
+Combined with non-interactive flags for full automation:
+
+```bash
+# Full CI/CD setup — no prompts
+globio login --token $GLOBIO_PAT --profile ci --json
+globio projects create \
+  --name "My Game" \
+  --org $ORG_ID \
+  --json
+globio functions deploy my-function --json
+```
+
+---
+
+## Live Log Streaming
+
+Stream real-time function and hook execution logs
+to your terminal — including console.log output,
+inputs, results, and errors.
+
+```bash
+globio functions watch matchmaking
+globio hooks watch init-player
+```
+
+Example output:
+```
+  ⇒⇒ globio 1.0.0
+  ──────────────────────────────────────────
+  watching matchmaking · press Ctrl+C to stop
+
+  ● connected — waiting for invocations...
+
+  ✓ 2026-03-15 06:12:01  [http]  3ms
+      input    {"userId":"player_001","rating":1450}
+      log      Querying players with rating 1450
+      log      Found 3 candidates
+      result   {"matched":true,"roomId":"room_abc"}
+```
+
+---
+
+## globio.config.ts
+
+Running `globio init` creates a `globio.config.ts` in
+your project root with your project already configured:
+
+```typescript
+import { Globio } from '@globio/sdk';
+
+export const globio = new Globio({
+  apiKey: process.env.GLOBIO_API_KEY!,
+  projectId: 'proj_xxxxx',
+});
+```
+
+Import it anywhere in your project:
+
+```typescript
+import { globio } from './globio.config';
+
+const player = await globio.doc.get('players', userId);
+```
+
+---
+
+## Links
 
-- [SDK](https://npmjs.com/package/@globio/sdk)
+- [SDK](https://npmjs.com/package/@globio/sdk) — `@globio/sdk`
 - [Console](https://console.globio.stanlink.online)
-- [Docs](https://globio.stanlink.online/docs)
+- [Docs](https://docs.globio.stanl.ink)
+- [Discord](https://discord.gg/bNDvAsVkMY)
+- [GitHub](https://github.com/Globio-Technologies/globio-cli)

package/dist/index.js

@@ -206,10 +206,10 @@ function renderTable(options) {
   );
   return lines.join("\n");
 }
-function header(version11, subtitle) {
+function header(version12, subtitle) {
   const lines = [
     "",
-    orange("  \u21D2\u21D2") + reset + " globio " + dim(version11),
+    orange("  \u21D2\u21D2") + reset + " globio " + dim(version12),
     dim("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500")
   ];
   if (subtitle) {
@@ -234,14 +234,14 @@ var globioGradient = gradientString(
   "#ffba08",
   "#ffd000"
 );
-function printBanner(version11) {
+function printBanner(version12) {
   const art = figlet.textSync("Globio", {
     font: "ANSI Shadow",
     horizontalLayout: "default"
   });
   console.log(globioGradient.multiline(art));
   console.log(
-    globioGradient("  \u21D2\u21D2") + "  Game Backend as a Service  \x1B[2mv" + version11 + "\x1B[0m"
+    globioGradient("  \u21D2\u21D2") + "  Game Backend as a Service  \x1B[2mv" + version12 + "\x1B[0m"
   );
   console.log("");
 }
@@ -643,8 +643,8 @@ async function createIndex(collection, field, fieldType = "string", profile) {
 // src/lib/firebase.ts
 async function initFirebase(serviceAccountPath) {
   const admin = await import("firebase-admin");
-  const { readFileSync: readFileSync5 } = await import("fs");
-  const serviceAccount = JSON.parse(readFileSync5(serviceAccountPath, "utf-8"));
+  const { readFileSync: readFileSync6 } = await import("fs");
+  const serviceAccount = JSON.parse(readFileSync6(serviceAccountPath, "utf-8"));
   if (!admin.default.apps.length) {
     admin.default.initializeApp({
       credential: admin.default.credential.cert(serviceAccount),
@@ -1566,9 +1566,235 @@ async function functionsToggle(slug, active, options = {}) {
   spinner2?.succeed(`${slug} is now ${active ? "active" : "inactive"}`);
 }
 
+// src/commands/hooks.ts
+import { existsSync as existsSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "fs";
+var version9 = getCliVersion();
+function parseJsonField2(value) {
+  if (!value) return null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+var HOOK_TRIGGERS = [
+  "id.onSignup",
+  "id.onSignin",
+  "id.onSignout",
+  "id.onPasswordReset",
+  "doc.onCreate",
+  "doc.onUpdate",
+  "doc.onDelete",
+  "mart.onPurchase",
+  "mart.onPayment",
+  "sync.onRoomCreate",
+  "sync.onRoomClose",
+  "sync.onPlayerJoin",
+  "sync.onPlayerLeave",
+  "vault.onUpload",
+  "vault.onDelete",
+  "signal.onDeliver"
+];
+async function hooksList(options = {}) {
+  const client = getClient(options.profile);
+  const result = await client.code.listHooks();
+  if (options.json) {
+    jsonOutput(
+      result.success ? (result.data ?? []).map((hook) => ({
+        slug: hook.slug,
+        type: hook.type,
+        trigger_event: hook.trigger_event,
+        active: hook.active
+      })) : []
+    );
+  }
+  if (!result.success || !result.data?.length) {
+    console.log(header(version9));
+    console.log("  " + muted("No hooks found.") + "\n");
+    return;
+  }
+  const rows = result.data.map((fn) => [
+    gold(fn.slug),
+    gold(fn.trigger_event ?? "\u2014"),
+    fn.active ? green("active") : inactive("inactive")
+  ]);
+  console.log(header(version9));
+  console.log(
+    renderTable({
+      columns: [
+        { header: "Hook", width: 24 },
+        { header: "Trigger", width: 24 },
+        { header: "Status", width: 10 }
+      ],
+      rows
+    })
+  );
+  console.log("");
+}
+async function hooksCreate(slug, options = {}) {
+  const filename = `${slug}.hook.js`;
+  if (existsSync4(filename)) {
+    if (options.json) {
+      jsonOutput({ success: false, file: filename, error: "File already exists" });
+    }
+    console.log(gold(filename) + reset + " already exists.");
+    return;
+  }
+  const template = `/**
+ * GC Hook: ${slug}
+ * This hook fires automatically when its trigger event occurs.
+ * You cannot invoke it manually.
+ *
+ * The handler receives the event payload and the injected
+ * globio SDK \u2014 use it to orchestrate any Globio service.
+ */
+async function handler(payload, globio) {
+  // payload: event data from the trigger
+  // globio: injected SDK \u2014 access all Globio services
+
+  // Example for id.onSignup:
+  // const { userId, email } = payload;
+  // await globio.doc.set('players', userId, {
+  //   level: 1, xp: 0, coins: 100
+  // });
+}
+`;
+  writeFileSync4(filename, template);
+  if (options.json) {
+    jsonOutput({ success: true, file: filename });
+  }
+  console.log(green("\u2713") + reset + "  Created " + gold(filename) + reset);
+  console.log(muted("  Deploy with: globio hooks deploy " + slug));
+}
+async function hooksDeploy(slug, options) {
+  const filename = options.file ?? `${slug}.hook.js`;
+  if (!existsSync4(filename)) {
+    if (options.json) {
+      jsonOutput({ success: false, error: `File not found: ${filename}` });
+    }
+    console.log(
+      failure("File not found: " + filename) + reset + "  Run: globio hooks create " + slug
+    );
+    process.exit(1);
+  }
+  if (!options.trigger) {
+    if (options.json) {
+      jsonOutput({ success: false, error: "--trigger required for hooks" });
+    }
+    console.log(
+      failure("--trigger required for hooks.") + reset + "\n\n  Available triggers:\n" + HOOK_TRIGGERS.map((trigger) => "    " + gold(trigger) + reset).join("\n")
+    );
+    process.exit(1);
+  }
+  const code = readFileSync5(filename, "utf-8");
+  const client = getClient(options.profile);
+  const existing = await client.code.getFunction(slug).catch(() => null);
+  let result;
+  if (existing?.success) {
+    result = await client.code.updateHook(slug, {
+      code,
+      trigger: options.trigger
+    });
+    if (options.json) {
+      jsonOutput({ success: result.success, slug, action: "updated" });
+    }
+    if (!result.success) {
+      console.log(failure("Deploy failed"));
+      process.exit(1);
+    }
+    console.log(green("\u2713") + reset + "  Updated hook " + gold(slug) + reset);
+    return;
+  }
+  result = await client.code.createHook({
+    name: options.name ?? slug,
+    slug,
+    trigger: options.trigger,
+    code
+  });
+  if (options.json) {
+    jsonOutput({ success: result.success, slug, action: "created" });
+  }
+  if (!result.success) {
+    console.log(failure("Deploy failed"));
+    process.exit(1);
+  }
+  console.log(green("\u2713") + reset + "  Deployed hook " + gold(slug) + reset);
+}
+async function hooksLogs(slug, options = {}) {
+  const limit = options.limit ? parseInt(options.limit, 10) : 20;
+  const client = getClient(options.profile);
+  const result = await client.code.getHookInvocations(slug, limit);
+  if (options.json) {
+    jsonOutput(
+      result.success ? result.data.map((invocation) => ({
+        id: invocation.id,
+        trigger_type: invocation.trigger_type,
+        duration_ms: invocation.duration_ms,
+        success: invocation.success,
+        invoked_at: invocation.invoked_at,
+        logs: parseJsonField2(invocation.logs) ?? [],
+        error_message: invocation.error_message ?? null,
+        input: parseJsonField2(invocation.input),
+        result: parseJsonField2(invocation.result)
+      })) : []
+    );
+  }
+  if (!result.success || !result.data?.length) {
+    console.log(header(version9));
+    console.log("  " + muted("No invocations yet.") + "\n");
+    return;
+  }
+  const rows = result.data.map((inv) => {
+    const date = new Date(inv.invoked_at * 1e3).toISOString().replace("T", " ").slice(0, 19);
+    return [
+      muted(date),
+      muted(inv.duration_ms + "ms"),
+      inv.success ? green("success") : failure("failed")
+    ];
+  });
+  console.log(header(version9));
+  console.log(
+    renderTable({
+      columns: [
+        { header: "Time", width: 21 },
+        { header: "Duration", width: 10 },
+        { header: "Status", width: 10 }
+      ],
+      rows
+    })
+  );
+  console.log("");
+}
+async function hooksToggle(slug, active, options = {}) {
+  const client = getClient(options.profile);
+  const result = await client.code.toggleHook(slug, active);
+  if (options.json) {
+    jsonOutput({ success: result.success, slug, active });
+  }
+  if (!result.success) {
+    console.log(failure("Toggle failed"));
+    process.exit(1);
+  }
+  console.log(
+    green("\u2713") + reset + "  " + gold(slug) + reset + " is now " + (active ? green("active") : inactive("inactive")) + reset
+  );
+}
+async function hooksDelete(slug, options = {}) {
+  const client = getClient(options.profile);
+  const result = await client.code.deleteHook(slug);
+  if (options.json) {
+    jsonOutput({ success: result.success, slug });
+  }
+  if (!result.success) {
+    console.log(failure("Delete failed"));
+    process.exit(1);
+  }
+  console.log(green("\u2713") + reset + "  Deleted hook " + gold(slug) + reset);
+}
+
 // src/commands/watch.ts
 var BASE_URL2 = "https://api.globio.stanlink.online";
-var version9 = getCliVersion();
+var version10 = getCliVersion();
 async function functionsWatch(slug, options = {}) {
   const profileName = options.profile ?? config.getActiveProfile();
   const profile = config.getProfile(profileName ?? "default");
@@ -1578,7 +1804,7 @@ async function functionsWatch(slug, options = {}) {
     );
     process.exit(1);
   }
-  console.log(header(version9));
+  console.log(header(version10));
   console.log(
     "  " + orange("watching") + reset + " " + slug + dim(" \xB7 press Ctrl+C to stop") + "\n"
   );
@@ -1674,10 +1900,10 @@ function renderEvent(event) {
 }
 
 // src/index.ts
-var version10 = getCliVersion();
+var version11 = getCliVersion();
 var program = new Command();
-program.name("globio").description("The official Globio CLI").version(version10).addHelpText("beforeAll", () => {
-  printBanner(version10);
+program.name("globio").description("The official Globio CLI").version(version11).addHelpText("beforeAll", () => {
+  printBanner(version11);
   return "";
 }).addHelpText(
   "after",
@@ -1689,6 +1915,8 @@ Examples:
   $ globio projects list
   $ globio projects use proj_abc123
   $ globio functions deploy my-function
+  $ globio hooks deploy on-signup --trigger id.onSignup
+  $ globio hooks list
   $ globio migrate firestore --from ./key.json --all
 
 Credentials are stored in ~/.globio/profiles/
@@ -1710,7 +1938,7 @@ projects.command("list").description("List projects").option("--profile <name>",
 projects.command("create").description("Create a project").option("--name <name>", "Project name").option("--org <orgId>", "Organization ID").option("--env <environment>", "Environment", "development").option("-p, --profile <name>", "Profile name").option("--json", "Output as JSON").action(projectsCreate);
 projects.command("use <projectId>").description("Set active project").option("--profile <name>", "Use a specific profile").option("--json", "Output as JSON").action(projectsUse);
 program.command("services").description("List available Globio services").option("--profile <name>", "Use a specific profile").option("--json", "Output as JSON").action(servicesList);
-var functions = program.command("functions").alias("fn").description("Manage GlobalCode edge functions");
+var functions = program.command("functions").alias("fn").description("Manage edge functions");
 functions.command("list").description("List all functions").option("--profile <name>", "Use a specific profile").option("--json", "Output as JSON").action(functionsList);
 functions.command("create <slug>").description("Scaffold a new function file locally").option("--profile <name>", "Use a specific profile").option("--json", "Output as JSON").action(functionsCreate);
 functions.command("deploy <slug>").description("Deploy a function to GlobalCode").option("-f, --file <path>", "Path to function file").option("-n, --name <name>", "Display name").option("--profile <name>", "Use a specific profile").option("--json", "Output as JSON").action(functionsDeploy);
@@ -1720,6 +1948,15 @@ functions.command("watch <slug>").description("Stream live function execution lo
 functions.command("delete <slug>").description("Delete a function").option("--profile <name>", "Use a specific profile").option("--json", "Output as JSON").action(functionsDelete);
 functions.command("enable <slug>").description("Enable a function").option("--profile <name>", "Use a specific profile").option("--json", "Output as JSON").action((slug, options) => functionsToggle(slug, true, options));
 functions.command("disable <slug>").description("Disable a function").option("--profile <name>", "Use a specific profile").option("--json", "Output as JSON").action((slug, options) => functionsToggle(slug, false, options));
+var hooks = program.command("hooks").description("Manage GC Hooks").action(hooksList);
+hooks.command("list").description("List all hooks").option("-p, --profile <name>", "Profile name").option("--json", "Output as JSON").action(hooksList);
+hooks.command("create <slug>").description("Scaffold a new hook file locally").option("--json", "Output as JSON").action(hooksCreate);
+hooks.command("deploy <slug>").description("Deploy a hook").option("-f, --file <path>", "Path to hook file").option("-n, --name <name>", "Display name").option("-t, --trigger <event>", "Hook trigger event (e.g. id.onSignup)").option("-p, --profile <name>", "Profile name").option("--json", "Output as JSON").action(hooksDeploy);
+hooks.command("logs <slug>").description("Show hook invocation history").option("-l, --limit <n>", "Number of entries", "20").option("-p, --profile <name>", "Profile name").option("--json", "Output as JSON").action(hooksLogs);
+hooks.command("watch <slug>").description("Stream live hook execution logs").option("-p, --profile <name>", "Profile name").action((slug, opts) => functionsWatch(slug, opts));
+hooks.command("enable <slug>").description("Enable a hook").option("-p, --profile <name>", "Profile name").option("--json", "Output as JSON").action((slug, opts) => hooksToggle(slug, true, opts));
+hooks.command("disable <slug>").description("Disable a hook").option("-p, --profile <name>", "Profile name").option("--json", "Output as JSON").action((slug, opts) => hooksToggle(slug, false, opts));
+hooks.command("delete <slug>").description("Delete a hook").option("-p, --profile <name>", "Profile name").option("--json", "Output as JSON").action(hooksDelete);
 var migrate = program.command("migrate").description("Migrate from Firebase to Globio");
 migrate.command("firestore").description("Migrate Firestore collections to GlobalDoc").requiredOption("--from <path>", "Path to Firebase service account JSON").option("--collection <name>", "Migrate a specific collection").option("--all", "Migrate all collections").option("--profile <name>", "Use a specific profile").option("--json", "Output as JSON").action(migrateFirestore);
 migrate.command("firebase-storage").description("Migrate Firebase Storage to GlobalVault").requiredOption("--from <path>", "Path to Firebase service account JSON").requiredOption("--bucket <name>", "Firebase Storage bucket").option("--folder <path>", "Migrate a specific folder").option("--all", "Migrate all files").option("--profile <name>", "Use a specific profile").option("--json", "Output as JSON").action(migrateFirebaseStorage);

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@globio/cli",
-  "version": "0.2.2",
+  "version": "1.0.0",
   "license": "MIT",
   "exports": "./src/index.ts"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@globio/cli",
-  "version": "0.2.2",
+  "version": "1.0.0",
   "description": "The official CLI for Globio — game backend as a service",
   "type": "module",
   "license": "MIT",
@@ -14,7 +14,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.9.0",
-    "@globio/sdk": "^1.0.0",
+    "@globio/sdk": "^1.1.0",
     "chalk": "^5.3.0",
     "cli-progress": "^3.12.0",
     "commander": "^12.0.0",

package/src/commands/hooks.ts

@@ -0,0 +1,324 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { getClient } from '../lib/sdk.js';
+import {
+  failure,
+  getCliVersion,
+  gold,
+  green,
+  header,
+  inactive,
+  jsonOutput,
+  muted,
+  renderTable,
+  reset,
+} from '../lib/banner.js';
+import type { CodeInvocation } from '@globio/sdk';
+
+const version = getCliVersion();
+
+function parseJsonField<T>(value: string | null | undefined): T | null {
+  if (!value) return null;
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return null;
+  }
+}
+
+const HOOK_TRIGGERS = [
+  'id.onSignup',
+  'id.onSignin',
+  'id.onSignout',
+  'id.onPasswordReset',
+  'doc.onCreate',
+  'doc.onUpdate',
+  'doc.onDelete',
+  'mart.onPurchase',
+  'mart.onPayment',
+  'sync.onRoomCreate',
+  'sync.onRoomClose',
+  'sync.onPlayerJoin',
+  'sync.onPlayerLeave',
+  'vault.onUpload',
+  'vault.onDelete',
+  'signal.onDeliver',
+] as const;
+
+export async function hooksList(
+  options: { profile?: string; json?: boolean } = {}
+) {
+  const client = getClient(options.profile);
+  const result = await client.code.listHooks();
+
+  if (options.json) {
+    jsonOutput(
+      result.success
+        ? (result.data ?? []).map((hook) => ({
+            slug: hook.slug,
+            type: hook.type,
+            trigger_event: hook.trigger_event,
+            active: hook.active,
+          }))
+        : []
+    );
+  }
+
+  if (!result.success || !result.data?.length) {
+    console.log(header(version));
+    console.log('  ' + muted('No hooks found.') + '\n');
+    return;
+  }
+
+  const rows = result.data.map((fn) => [
+    gold(fn.slug),
+    gold(fn.trigger_event ?? '—'),
+    fn.active ? green('active') : inactive('inactive'),
+  ]);
+
+  console.log(header(version));
+  console.log(
+    renderTable({
+      columns: [
+        { header: 'Hook', width: 24 },
+        { header: 'Trigger', width: 24 },
+        { header: 'Status', width: 10 },
+      ],
+      rows,
+    })
+  );
+  console.log('');
+}
+
+export async function hooksCreate(
+  slug: string,
+  options: { json?: boolean } = {}
+) {
+  const filename = `${slug}.hook.js`;
+  if (existsSync(filename)) {
+    if (options.json) {
+      jsonOutput({ success: false, file: filename, error: 'File already exists' });
+    }
+    console.log(gold(filename) + reset + ' already exists.');
+    return;
+  }
+
+  const template = `/**
+ * GC Hook: ${slug}
+ * This hook fires automatically when its trigger event occurs.
+ * You cannot invoke it manually.
+ *
+ * The handler receives the event payload and the injected
+ * globio SDK — use it to orchestrate any Globio service.
+ */
+async function handler(payload, globio) {
+  // payload: event data from the trigger
+  // globio: injected SDK — access all Globio services
+
+  // Example for id.onSignup:
+  // const { userId, email } = payload;
+  // await globio.doc.set('players', userId, {
+  //   level: 1, xp: 0, coins: 100
+  // });
+}
+`;
+
+  writeFileSync(filename, template);
+
+  if (options.json) {
+    jsonOutput({ success: true, file: filename });
+  }
+
+  console.log(green('✓') + reset + '  Created ' + gold(filename) + reset);
+  console.log(muted('  Deploy with: globio hooks deploy ' + slug));
+}
+
+export async function hooksDeploy(
+  slug: string,
+  options: {
+    file?: string;
+    name?: string;
+    trigger?: string;
+    profile?: string;
+    json?: boolean;
+  }
+) {
+  const filename = options.file ?? `${slug}.hook.js`;
+  if (!existsSync(filename)) {
+    if (options.json) {
+      jsonOutput({ success: false, error: `File not found: ${filename}` });
+    }
+    console.log(
+      failure('File not found: ' + filename) +
+        reset +
+        '  Run: globio hooks create ' +
+        slug
+    );
+    process.exit(1);
+  }
+
+  if (!options.trigger) {
+    if (options.json) {
+      jsonOutput({ success: false, error: '--trigger required for hooks' });
+    }
+    console.log(
+      failure('--trigger required for hooks.') +
+        reset +
+        '\n\n  Available triggers:\n' +
+        HOOK_TRIGGERS.map((trigger) => '    ' + gold(trigger) + reset).join('\n')
+    );
+    process.exit(1);
+  }
+
+  const code = readFileSync(filename, 'utf-8');
+  const client = getClient(options.profile);
+  const existing = await client.code.getFunction(slug).catch(() => null);
+
+  let result;
+  if (existing?.success) {
+    result = await client.code.updateHook(slug, {
+      code,
+      trigger: options.trigger as (typeof HOOK_TRIGGERS)[number],
+    });
+
+    if (options.json) {
+      jsonOutput({ success: result.success, slug, action: 'updated' });
+    }
+
+    if (!result.success) {
+      console.log(failure('Deploy failed'));
+      process.exit(1);
+    }
+
+    console.log(green('✓') + reset + '  Updated hook ' + gold(slug) + reset);
+    return;
+  }
+
+  result = await client.code.createHook({
+    name: options.name ?? slug,
+    slug,
+    trigger: options.trigger as (typeof HOOK_TRIGGERS)[number],
+    code,
+  });
+
+  if (options.json) {
+    jsonOutput({ success: result.success, slug, action: 'created' });
+  }
+
+  if (!result.success) {
+    console.log(failure('Deploy failed'));
+    process.exit(1);
+  }
+
+  console.log(green('✓') + reset + '  Deployed hook ' + gold(slug) + reset);
+}
+
+export async function hooksLogs(
+  slug: string,
+  options: { limit?: string; profile?: string; json?: boolean } = {}
+) {
+  const limit = options.limit ? parseInt(options.limit, 10) : 20;
+  const client = getClient(options.profile);
+  const result = await client.code.getHookInvocations(slug, limit);
+
+  if (options.json) {
+    jsonOutput(
+      result.success
+        ? (result.data as Array<CodeInvocation & {
+            logs?: string | null;
+            error_message?: string | null;
+            input?: string | null;
+            result?: string | null;
+          }>).map((invocation) => ({
+            id: invocation.id,
+            trigger_type: invocation.trigger_type,
+            duration_ms: invocation.duration_ms,
+            success: invocation.success,
+            invoked_at: invocation.invoked_at,
+            logs: parseJsonField<string[]>(invocation.logs) ?? [],
+            error_message: invocation.error_message ?? null,
+            input: parseJsonField<Record<string, unknown>>(invocation.input),
+            result: parseJsonField<unknown>(invocation.result),
+          }))
+        : []
+    );
+  }
+
+  if (!result.success || !result.data?.length) {
+    console.log(header(version));
+    console.log('  ' + muted('No invocations yet.') + '\n');
+    return;
+  }
+
+  const rows = result.data.map((inv) => {
+    const date = new Date(inv.invoked_at * 1000)
+      .toISOString()
+      .replace('T', ' ')
+      .slice(0, 19);
+    return [
+      muted(date),
+      muted(inv.duration_ms + 'ms'),
+      inv.success ? green('success') : failure('failed'),
+    ];
+  });
+
+  console.log(header(version));
+  console.log(
+    renderTable({
+      columns: [
+        { header: 'Time', width: 21 },
+        { header: 'Duration', width: 10 },
+        { header: 'Status', width: 10 },
+      ],
+      rows,
+    })
+  );
+  console.log('');
+}
+
+export async function hooksToggle(
+  slug: string,
+  active: boolean,
+  options: { profile?: string; json?: boolean } = {}
+) {
+  const client = getClient(options.profile);
+  const result = await client.code.toggleHook(slug, active);
+
+  if (options.json) {
+    jsonOutput({ success: result.success, slug, active });
+  }
+
+  if (!result.success) {
+    console.log(failure('Toggle failed'));
+    process.exit(1);
+  }
+
+  console.log(
+    green('✓') +
+      reset +
+      '  ' +
+      gold(slug) +
+      reset +
+      ' is now ' +
+      (active ? green('active') : inactive('inactive')) +
+      reset
+  );
+}
+
+export async function hooksDelete(
+  slug: string,
+  options: { profile?: string; json?: boolean } = {}
+) {
+  const client = getClient(options.profile);
+  const result = await client.code.deleteHook(slug);
+
+  if (options.json) {
+    jsonOutput({ success: result.success, slug });
+  }
+
+  if (!result.success) {
+    console.log(failure('Delete failed'));
+    process.exit(1);
+  }
+
+  console.log(green('✓') + reset + '  Deleted hook ' + gold(slug) + reset);
+}

package/src/index.ts

@@ -17,6 +17,14 @@ import {
   functionsDelete,
   functionsToggle,
 } from './commands/functions.js';
+import {
+  hooksList,
+  hooksCreate,
+  hooksDeploy,
+  hooksLogs,
+  hooksToggle,
+  hooksDelete,
+} from './commands/hooks.js';
 import { functionsWatch } from './commands/watch.js';
 import {
   migrateFirestore,
@@ -46,6 +54,8 @@ Examples:
   $ globio projects list
   $ globio projects use proj_abc123
   $ globio functions deploy my-function
+  $ globio hooks deploy on-signup --trigger id.onSignup
+  $ globio hooks list
   $ globio migrate firestore --from ./key.json --all
 
 Credentials are stored in ~/.globio/profiles/
@@ -110,7 +120,7 @@ program.command('services').description('List available Globio services').option
 const functions = program
   .command('functions')
   .alias('fn')
-  .description('Manage GlobalCode edge functions');
+  .description('Manage edge functions');
 
 functions.command('list').description('List all functions').option('--profile <name>', 'Use a specific profile').option('--json', 'Output as JSON').action(functionsList);
 functions.command('create <slug>').description('Scaffold a new function file locally').option('--profile <name>', 'Use a specific profile').option('--json', 'Output as JSON').action(functionsCreate);
@@ -155,6 +165,69 @@ functions
   .option('--json', 'Output as JSON')
   .action((slug, options) => functionsToggle(slug, false, options));
 
+const hooks = program
+  .command('hooks')
+  .description('Manage GC Hooks')
+  .action(hooksList);
+
+hooks
+  .command('list')
+  .description('List all hooks')
+  .option('-p, --profile <name>', 'Profile name')
+  .option('--json', 'Output as JSON')
+  .action(hooksList);
+
+hooks
+  .command('create <slug>')
+  .description('Scaffold a new hook file locally')
+  .option('--json', 'Output as JSON')
+  .action(hooksCreate);
+
+hooks
+  .command('deploy <slug>')
+  .description('Deploy a hook')
+  .option('-f, --file <path>', 'Path to hook file')
+  .option('-n, --name <name>', 'Display name')
+  .option('-t, --trigger <event>', 'Hook trigger event (e.g. id.onSignup)')
+  .option('-p, --profile <name>', 'Profile name')
+  .option('--json', 'Output as JSON')
+  .action(hooksDeploy);
+
+hooks
+  .command('logs <slug>')
+  .description('Show hook invocation history')
+  .option('-l, --limit <n>', 'Number of entries', '20')
+  .option('-p, --profile <name>', 'Profile name')
+  .option('--json', 'Output as JSON')
+  .action(hooksLogs);
+
+hooks
+  .command('watch <slug>')
+  .description('Stream live hook execution logs')
+  .option('-p, --profile <name>', 'Profile name')
+  .action((slug, opts) => functionsWatch(slug, opts));
+
+hooks
+  .command('enable <slug>')
+  .description('Enable a hook')
+  .option('-p, --profile <name>', 'Profile name')
+  .option('--json', 'Output as JSON')
+  .action((slug, opts) => hooksToggle(slug, true, opts));
+
+hooks
+  .command('disable <slug>')
+  .description('Disable a hook')
+  .option('-p, --profile <name>', 'Profile name')
+  .option('--json', 'Output as JSON')
+  .action((slug, opts) => hooksToggle(slug, false, opts));
+
+hooks
+  .command('delete <slug>')
+  .description('Delete a hook')
+  .option('-p, --profile <name>', 'Profile name')
+  .option('--json', 'Output as JSON')
+  .action(hooksDelete);
+
 const migrate = program
   .command('migrate')
   .description('Migrate from Firebase to Globio');