@glassanalytics/cli 0.2.0 → 0.2.1

package/dist/glass.js

@@ -2,7 +2,25 @@
 
 // packages/cli/src/index.ts
 import { parseArgs } from "node:util";
-import { GLASS_VERSION as GLASS_VERSION3 } from "@glassanalytics/core/version";
+
+// packages/core/src/version.ts
+var GLASS_VERSION = "0.2.1";
+var UPGRADE_COMMAND = "npx @glassanalytics/cli@latest upgrade";
+function parseSemver(version) {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function isNewerThan(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return a !== b && a > b;
+  for (let i = 0; i < 3; i++) {
+    const d = pa[i] - pb[i];
+    if (d) return d > 0;
+  }
+  return false;
+}
 
 // packages/cli/src/config.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -366,16 +384,110 @@ async function experiments(sub, key2, rest, flags2) {
 }
 
 // packages/cli/src/commands/init.ts
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync5 } from "node:fs";
-import { join as join5 } from "node:path";
-import { randomToken } from "@glassanalytics/core/ids";
-import { FRAMEWORKS, detectFramework } from "@glassanalytics/core/instrument";
-import { GLASS_VERSION as GLASS_VERSION2 } from "@glassanalytics/core/version";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync6 } from "node:fs";
+import { join as join6 } from "node:path";
+
+// packages/core/src/ids.ts
+function randomBytes(n) {
+  const bytes = new Uint8Array(n);
+  crypto.getRandomValues(bytes);
+  return bytes;
+}
+function hex(bytes) {
+  let out = "";
+  for (const b of bytes) out += b.toString(16).padStart(2, "0");
+  return out;
+}
+function randomToken(bytes = 32) {
+  return hex(randomBytes(bytes));
+}
+
+// packages/core/src/instrument.ts
+var scriptTag = (o) => `<script defer src="${o.host}/s.js" data-project="${o.project}"></script>`;
+var browserCapture = (event, props) => `window.glass?.capture(${JSON.stringify(event)}${props && Object.keys(props).length ? `, ${JSON.stringify(props)}` : ""});`;
+var moduleCapture = (event, props) => `import { glass } from '@glassanalytics/web';
+
+glass.capture(${JSON.stringify(event)}${props && Object.keys(props).length ? `, ${JSON.stringify(props)}` : ""});`;
+var FRAMEWORKS = {
+  html: {
+    name: "Plain HTML",
+    snippet: (o) => ({ file: "index.html (inside <head>, on every page)", code: scriptTag(o), capture: browserCapture })
+  },
+  nextjs: {
+    name: "Next.js",
+    snippet: (o) => ({
+      file: "app/layout.tsx (App Router) or pages/_app.tsx",
+      code: `import Script from 'next/script';
+
+// inside <body>:
+<Script src="${o.host}/s.js" data-project="${o.project}" strategy="afterInteractive" />`,
+      capture: browserCapture
+    })
+  },
+  astro: {
+    name: "Astro",
+    snippet: (o) => ({ file: "src/layouts/Layout.astro (inside <head>)", code: scriptTag(o).replace("<script", "<script is:inline"), capture: browserCapture })
+  },
+  sveltekit: {
+    name: "SvelteKit",
+    snippet: (o) => ({ file: "src/app.html (inside <head>)", code: scriptTag(o), capture: browserCapture })
+  },
+  nuxt: {
+    name: "Nuxt",
+    snippet: (o) => ({
+      file: "nuxt.config.ts",
+      code: `export default defineNuxtConfig({
+  app: { head: { script: [{ src: '${o.host}/s.js', defer: true, 'data-project': '${o.project}' }] } },
+});`,
+      capture: browserCapture
+    })
+  },
+  remix: {
+    name: "Remix / React Router",
+    snippet: (o) => ({ file: "app/root.tsx (inside <head>)", code: scriptTag(o).replace("defer ", "defer={true} "), capture: browserCapture })
+  },
+  vite: {
+    name: "Vite (React, Vue, Svelte, Solid\u2026)",
+    snippet: (o) => ({
+      file: "src/main.ts (or main.tsx) \u2014 after `npm install @glassanalytics/web`",
+      code: `import { glass } from '@glassanalytics/web';
+
+glass.init({ host: '${o.host}', project: '${o.project}' });`,
+      capture: moduleCapture
+    })
+  },
+  worker: {
+    name: "Cloudflare Worker / server-side",
+    snippet: (o) => ({
+      file: "any server code",
+      code: `// Server-side capture: POST events to Glass.
+await fetch('${o.host}/e', {
+  method: 'POST',
+  body: JSON.stringify({ project: '${o.project}', events: [{ id: crypto.randomUUID(), event: 'order_paid', ts: Date.now(), distinct_id: userId, user_id: userId, props: { amount: 42 } }] }),
+});`,
+      capture: (event, props) => `await fetch(GLASS_HOST + '/e', { method: 'POST', body: JSON.stringify({ project: GLASS_PROJECT, events: [{ id: crypto.randomUUID(), event: ${JSON.stringify(event)}, ts: Date.now(), distinct_id: userId, user_id: userId, props: ${JSON.stringify(props ?? {})} }] }) });`
+    })
+  }
+};
+function detectFramework(pkg) {
+  if (!pkg) return "html";
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const has = (name) => Object.hasOwn(deps, name);
+  if (has("next")) return "nextjs";
+  if (has("astro")) return "astro";
+  if (has("@sveltejs/kit")) return "sveltekit";
+  if (has("nuxt")) return "nuxt";
+  if (has("@remix-run/react") || has("react-router")) return "remix";
+  if (has("vite")) return "vite";
+  if (has("wrangler") || has("hono")) return "worker";
+  return "html";
+}
+var EVENT_NAMING_GUIDE = 'Name events object_action in snake_case and past tense (signup_completed, plan_upgraded, invite_sent). Put variable details in properties ({ plan: "pro" }), never in the event name. Never send emails, names or other personal data as properties.';
+var EVENT_DOCUMENTATION_GUIDE = 'After a custom event is shipping, call define_event (or `glass events <name> --describe "\u2026"`). The description must say how and when the event is fired (which user action or code path). Document every property with what it means and which values to expect (e.g. description: "Fired when the user finishes checkout after payment succeeds."; properties: { plan: "Chosen plan id (free|pro|enterprise)", amount: "Charge in the account currency" }). list_events returns undocumented custom events \u2014 document those before relying on them in funnels or trends.';
 
 // packages/cli/src/agent-files.ts
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { dirname as dirname2, join as join2 } from "node:path";
-import { EVENT_NAMING_GUIDE } from "@glassanalytics/core/instrument";
 var START = "<!-- glass:start -->";
 var END = "<!-- glass:end -->";
 function agentsSection(o) {
@@ -392,8 +504,16 @@ Tracking (project \`${o.project}\`):
 - Install (${o.snippet.file}): \`${o.snippet.code.split("\n").pop()}\`
 - Custom events: \`glass.capture('signup_completed', { plan: 'pro' })\`. After login: \`glass.identify(user.id, { plan })\`.
 - ${EVENT_NAMING_GUIDE}
-- After adding an event and deploying, confirm it arrives: \`npx @glassanalytics/cli events <name>\`. Document it: \`npx @glassanalytics/cli events <name> --describe "\u2026"\`.
+- After adding an event and deploying, confirm it arrives: \`npx @glassanalytics/cli events <name>\` (or MCP \`describe_event\`).
+- ${EVENT_DOCUMENTATION_GUIDE}
+- Prefer MCP \`define_event\` so you can set both the event description and each property's meaning in one call.
 - Feature flags: \`glass.flag('key')\` returns "on", a variant key, or null. Create with \`npx @glassanalytics/cli flags set <key> --rollout 10\`.
+
+Upgrades (the Worker version is pinned in \`.glass/config.json\`):
+- \`.github/workflows/glass.yml\` deploys whatever \`.glass/\` holds when it changes on the default branch. If that file is missing, run \`npx @glassanalytics/cli ci\` and add the \`CLOUDFLARE_API_TOKEN\` repository secret.
+- To upgrade: \`npx @glassanalytics/cli@latest upgrade\` stages the new Worker and migrations into \`.glass/\` without deploying. Commit and push (or open a PR); CI deploys. Ask before pushing if pushes also deploy the site.
+- Do not deploy Glass from a laptop (\`glass upgrade --local\`, wrangler) once the workflow exists, and never commit \`.glass/credentials.json\`.
+- \`glass upgrade\` refuses to replace a newer Worker with an older CLI. If it does, use \`@latest\`; do not pass \`--allow-downgrade\`.
 ${END}`;
 }
 function upsertSection(path, section, createIfMissing) {
@@ -418,7 +538,7 @@ Glass is deployed at ${o.host} (project \`${o.project}\`). Prefer the \`glass\`
 
 ## Answer a question about usage
 
-1. \`overview\` for the period (visitors, top pages, errors, events that moved).
+1. \`overview\` for the period (visitors, top pages, errors, events that moved). If it (or MCP init) says an upgrade is available, tell the user; with their go-ahead, follow "Upgrade Glass" below.
 2. \`list_events\` to get exact event names \u2014 never guess them.
 3. The right query: \`query_trends\` (counts over time), \`query_funnel\` (conversion through steps), \`query_retention\` (who comes back), \`sql\` when nothing else fits.
 4. Report numbers with the dashboard link and SQL from the result.
@@ -428,7 +548,13 @@ Glass is deployed at ${o.host} (project \`${o.project}\`). Prefer the \`glass\`
 1. \`instrument\` with the event name returns the exact code for this framework.
 2. ${EVENT_NAMING_GUIDE}
 3. After deploying, \`describe_event\` (or \`npx @glassanalytics/cli events <name>\`) confirms events arrive with the expected properties.
-4. \`define_event\` documents what the event means.
+4. Always \`define_event\` next. ${EVENT_DOCUMENTATION_GUIDE}
+
+## First session on a project
+
+1. \`overview\` then \`list_events\`.
+2. For every name in \`undocumented\`, read the code that fires it (or ask), then \`define_event\` with how/when it fires and property meanings.
+3. Do not invent funnel or trend queries against undocumented custom events until those descriptions exist.
 
 ## Debug a user problem
 
@@ -436,6 +562,13 @@ Glass is deployed at ${o.host} (project \`${o.project}\`). Prefer the \`glass\`
 2. \`list_replays\` with \`with_errors: true\` (or a \`person\`) to find affected sessions.
 3. \`summarise_replay\` to read what happened: pages, labelled clicks, rage clicks, errors.
 
+## Upgrade Glass
+
+1. \`npx @glassanalytics/cli@latest upgrade\`. With \`.github/workflows/glass.yml\` present this only stages \`.glass/\` (Worker, migrations, pinned version); nothing deploys.
+2. No workflow yet? \`npx @glassanalytics/cli ci\` writes it; the repo needs secret \`CLOUDFLARE_API_TOKEN\` (\`gh secret set CLOUDFLARE_API_TOKEN\`).
+3. Commit \`.glass/\` and push to the default branch (or open a PR). The Glass workflow migrates D1 and deploys.
+4. \`npx @glassanalytics/cli status\` confirms the new version is live.
+
 ## Run an experiment
 
 1. \`create_experiment\` with a goal event (creates a control/test flag).
@@ -472,10 +605,164 @@ function writeAgentFiles(o) {
   return written;
 }
 
+// packages/cli/src/ci.ts
+import { execFileSync } from "node:child_process";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { dirname as dirname3, join as join3 } from "node:path";
+var CI_WORKFLOW_PATH = ".github/workflows/glass.yml";
+var CI_SECRET = "CLOUDFLARE_API_TOKEN";
+var MARKER = "# Generated by `glass ci`.";
+function inCi(env = process.env) {
+  return env.CI === "true" || env.CI === "1" || env.GITHUB_ACTIONS === "true";
+}
+function hasCiWorkflow(root) {
+  return existsSync3(join3(root, CI_WORKFLOW_PATH));
+}
+function defaultBranch(root) {
+  const git = (args) => {
+    try {
+      return execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    } catch {
+      return "";
+    }
+  };
+  const head = git(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]).replace(/^origin\//, "");
+  return head || git(["branch", "--show-current"]) || "main";
+}
+function ciWorkflow(o) {
+  return `${MARKER} Deploys the Glass analytics Worker from .glass/.
+#
+# The version is pinned in .glass/config.json. To upgrade:
+#   npx @glassanalytics/cli@latest upgrade   # stages the new Worker into .glass/
+#   git commit .glass && git push            # this workflow migrates and deploys it
+#
+# Needs repository secret ${o.secret}: a Cloudflare API token with
+# Workers Scripts Edit, D1 Edit, Workers R2 Storage Edit, Account Settings Read
+# (and Zone Workers Routes Edit if .glass/config.json has a route).
+# Worker secrets (API keys) are set by \`glass init\` and survive deploys.
+name: Glass
+
+on:
+  push:
+    branches: [${o.branch}]
+    paths: ['.glass/**', '${CI_WORKFLOW_PATH}']
+  workflow_dispatch:
+
+concurrency:
+  group: glass-deploy
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Deploy the Glass version pinned in .glass/config.json
+        run: |
+          version="$(node -p "require('./.glass/config.json').version")"
+          npx -y "@glassanalytics/cli@\${version}" upgrade --ci
+        env:
+          CLOUDFLARE_API_TOKEN: \${{ secrets.${o.secret} }}
+`;
+}
+function writeCiWorkflow(root, options = {}) {
+  const branch = options.branch ?? defaultBranch(root);
+  const secret = options.secret ?? CI_SECRET;
+  const path = join3(root, CI_WORKFLOW_PATH);
+  const next = ciWorkflow({ branch, secret });
+  if (existsSync3(path)) {
+    const current = readFileSync3(path, "utf8");
+    if (!current.startsWith(MARKER)) return { path: CI_WORKFLOW_PATH, status: "kept", branch, secret };
+    if (current === next) return { path: CI_WORKFLOW_PATH, status: "kept", branch, secret };
+    writeFileSync3(path, next);
+    return { path: CI_WORKFLOW_PATH, status: "updated", branch, secret };
+  }
+  mkdirSync3(dirname3(path), { recursive: true });
+  writeFileSync3(path, next);
+  return { path: CI_WORKFLOW_PATH, status: "created", branch, secret };
+}
+function ciNextSteps(o) {
+  return [
+    `Add repository secret ${o.secret} (a Cloudflare API token; same scopes as init): gh secret set ${o.secret}`,
+    `Commit .glass/ (not credentials.json, which is git-ignored) and ${CI_WORKFLOW_PATH}, then push to ${o.branch}.`,
+    "Upgrade later with `npx @glassanalytics/cli@latest upgrade`: it stages the new version into .glass/ without deploying. Commit and push; the workflow deploys it.",
+    "Do not deploy Glass from a laptop once this workflow exists. `glass upgrade --local` overrides that for emergencies only."
+  ];
+}
+
 // packages/cli/src/cloudflare/provision.ts
-import { copyFileSync, mkdirSync as mkdirSync3, readdirSync, rmSync, writeFileSync as writeFileSync3 } from "node:fs";
-import { join as join3 } from "node:path";
-import { LAKE_TABLES, streamSchemaFile } from "@glassanalytics/core/lake";
+import { copyFileSync, mkdirSync as mkdirSync4, readdirSync, rmSync, writeFileSync as writeFileSync4 } from "node:fs";
+import { join as join4 } from "node:path";
+
+// packages/core/src/events.ts
+var EVENT_COLUMNS = [
+  "id",
+  "project",
+  "event",
+  "ts_ms",
+  "distinct_id",
+  "user_id",
+  "person_id",
+  "session_id",
+  "url",
+  "host",
+  "path",
+  "referrer",
+  "referrer_host",
+  "title",
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_term",
+  "utm_content",
+  "country",
+  "region",
+  "city",
+  "device",
+  "browser",
+  "os",
+  "flags",
+  "props",
+  "person_props",
+  "lib",
+  "received_ms"
+];
+
+// packages/core/src/lake.ts
+var INTEGER_COLUMNS = /* @__PURE__ */ new Set(["ts_ms", "received_ms"]);
+var OPTIONAL_COLUMNS = /* @__PURE__ */ new Set(["user_id"]);
+var LAKE_TABLES = {
+  events: {
+    stream: "glass_events",
+    fields: [
+      ...EVENT_COLUMNS.map(
+        (name) => ({
+          name,
+          type: INTEGER_COLUMNS.has(name) ? "int64" : "string",
+          required: !OPTIONAL_COLUMNS.has(name)
+        })
+      ),
+      { name: "ts", type: "timestamp", required: true }
+    ]
+  },
+  identities: {
+    stream: "glass_identities",
+    fields: [
+      { name: "project", type: "string", required: true },
+      { name: "distinct_id", type: "string", required: true },
+      { name: "person_id", type: "string", required: true },
+      { name: "created_at", type: "int64", required: true }
+    ]
+  }
+};
+function streamSchemaFile(table2) {
+  return { fields: [...LAKE_TABLES[table2].fields] };
+}
 
 // packages/cli/src/cloudflare/wrangler.ts
 import { spawn } from "node:child_process";
@@ -605,9 +892,9 @@ async function ensureLake(wrangler, options, report) {
     const sinkName = `${streamName}_sink`;
     let stream = await findByName(wrangler, "streams", streamName);
     if (!stream) {
-      const schemaPath = join3(options.dir, "schemas", `${table2}.json`);
-      mkdirSync3(join3(options.dir, "schemas"), { recursive: true });
-      writeFileSync3(schemaPath, `${JSON.stringify(streamSchemaFile(table2), null, 2)}
+      const schemaPath = join4(options.dir, "schemas", `${table2}.json`);
+      mkdirSync4(join4(options.dir, "schemas"), { recursive: true });
+      writeFileSync4(schemaPath, `${JSON.stringify(streamSchemaFile(table2), null, 2)}
 `);
       await must(wrangler, ["pipelines", "streams", "create", streamName, "--schema-file", schemaPath, "--http-enabled", "false"]);
       stream = await findByName(wrangler, "streams", streamName);
@@ -677,10 +964,10 @@ ${JSON.stringify(wrangler, null, 2)}
 `;
 }
 function installWorkerFiles(dir, bundleDir) {
-  mkdirSync3(join3(dir, "migrations"), { recursive: true });
-  copyFileSync(join3(bundleDir, "worker.js"), join3(dir, "worker.js"));
-  for (const file of readdirSync(join3(bundleDir, "migrations"))) {
-    copyFileSync(join3(bundleDir, "migrations", file), join3(dir, "migrations", file));
+  mkdirSync4(join4(dir, "migrations"), { recursive: true });
+  copyFileSync(join4(bundleDir, "worker.js"), join4(dir, "worker.js"));
+  for (const file of readdirSync(join4(bundleDir, "migrations"))) {
+    copyFileSync(join4(bundleDir, "migrations", file), join4(dir, "migrations", file));
   }
 }
 async function deploy(wrangler, configPath) {
@@ -691,8 +978,8 @@ async function migrate(wrangler, database, configPath) {
   await must(wrangler, ["d1", "migrations", "apply", database, "--remote", "--config", configPath]);
 }
 async function putSecrets(wrangler, secrets, configPath, dir) {
-  const file = join3(dir, ".secrets.tmp.json");
-  writeFileSync3(file, JSON.stringify(secrets), { mode: 384 });
+  const file = join4(dir, ".secrets.tmp.json");
+  writeFileSync4(file, JSON.stringify(secrets), { mode: 384 });
   try {
     await must(wrangler, ["secret", "bulk", file, "--config", configPath]);
   } finally {
@@ -747,26 +1034,65 @@ async function choose(question, items, label, flag) {
 }
 
 // packages/cli/src/commands/upgrade.ts
-import { existsSync as existsSync3, writeFileSync as writeFileSync4 } from "node:fs";
-import { join as join4 } from "node:path";
+import { existsSync as existsSync4, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join5 } from "node:path";
 import { fileURLToPath } from "node:url";
-import { GLASS_VERSION } from "@glassanalytics/core/version";
 function workerBundleDir() {
   const candidates = [new URL("./worker/", import.meta.url), new URL("../../../worker/dist/", import.meta.url)];
   for (const c of candidates) {
     const dir = fileURLToPath(c);
-    if (existsSync3(join4(dir, "worker.js")) && existsSync3(join4(dir, "migrations"))) return dir;
+    if (existsSync4(join5(dir, "worker.js")) && existsSync4(join5(dir, "migrations"))) return dir;
   }
   throw new UsageError("The Worker bundle is missing.", "If you are working on Glass itself, run `pnpm build` first.");
 }
+async function liveVersion(host, fetcher) {
+  if (!host) return null;
+  try {
+    const res = await fetcher(`${host}/health`, { signal: AbortSignal.timeout(5e3) });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return typeof body.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  }
+}
 async function upgrade(options, deps = {}) {
-  const root = projectRoot();
+  const root = deps.root ?? projectRoot();
+  const env = deps.env ?? process.env;
   const config = loadConfig(root);
+  if (!config) throw new UsageError("No Glass deployment in this project.", "Run `npx @glassanalytics/cli init` first.");
+  const ci2 = options.ci ?? inCi(env);
   const credentials = loadCredentials(root);
-  if (!config || !credentials) throw new UsageError("No Glass deployment in this project.", "Run `npx @glassanalytics/cli init` first.");
-  const token = options.token ?? process.env.CLOUDFLARE_API_TOKEN ?? await ask("Cloudflare API token", { flag: "--token (or CLOUDFLARE_API_TOKEN)", secret: true });
-  const wrangler = (deps.wrangler ?? createWrangler)({ token, accountId: config.accountId }, root);
+  if (!credentials && !ci2) throw new UsageError("No .glass/credentials.json in this project.", "Run `npx @glassanalytics/cli init` again to restore keys, or deploy from CI (`glass upgrade --ci`), which leaves Worker secrets as they are.");
   const dir = glassDir(root);
+  const bundle = deps.bundleDir ?? workerBundleDir();
+  const live = await liveVersion(config.host, deps.fetcher ?? fetch);
+  const deployed = [config.version, live].filter((v) => Boolean(v)).sort((a, b) => isNewerThan(a, b) ? -1 : 1)[0];
+  if (deployed && isNewerThan(deployed, GLASS_VERSION) && !options.allowDowngrade) {
+    throw new UsageError(
+      `This deployment runs Glass ${deployed}, which is newer than this CLI (${GLASS_VERSION}). Nothing was changed.`,
+      `Run \`${UPGRADE_COMMAND}\` (or npx @glassanalytics/cli@${deployed} or later). --allow-downgrade forces the older Worker.`
+    );
+  }
+  const from = config.version;
+  if (hasCiWorkflow(root) && !ci2 && !options.local) {
+    installWorkerFiles(dir, bundle);
+    config.version = GLASS_VERSION;
+    writeFileSync5(join5(dir, "wrangler.jsonc"), renderWranglerConfig(config));
+    saveConfig(config, root);
+    const branch = defaultBranch(root);
+    if (options.json) {
+      printJson({ from, to: GLASS_VERSION, staged: true, deploy: CI_WORKFLOW_PATH, next: `Commit .glass/ and push to ${branch}` });
+      return;
+    }
+    ok(`Staged Glass ${from === GLASS_VERSION ? GLASS_VERSION : `${from} \u2192 ${GLASS_VERSION}`} in .glass/ (nothing deployed)`);
+    line(`  Commit .glass/ and push to ${branch}; ${CI_WORKFLOW_PATH} migrates and deploys it.`);
+    line(color.dim("  Deploying from this machine instead: glass upgrade --local"));
+    return;
+  }
+  const token = options.token ?? env.CLOUDFLARE_API_TOKEN ?? (ci2 ? void 0 : await ask("Cloudflare API token", { flag: "--token (or CLOUDFLARE_API_TOKEN)", secret: true }));
+  if (!token) throw new UsageError("CLOUDFLARE_API_TOKEN is not set.", `In CI, map the repository secret to it (see ${CI_WORKFLOW_PATH}).`);
+  const wrangler = (deps.wrangler ?? createWrangler)({ token, accountId: config.accountId }, root);
   const report = (status2, label, detail) => {
     if (options.json) return;
     (status2 === "skipped" ? skip : ok)(`${label}${detail ? color.dim(` (${detail})`) : ""}`);
@@ -774,28 +1100,48 @@ async function upgrade(options, deps = {}) {
   if (!config.replay && await ensureBucket(wrangler, `${config.name}-replays`, config.eu, report, "session replay")) {
     config.replay = { bucket: `${config.name}-replays` };
   }
-  installWorkerFiles(dir, workerBundleDir());
-  const configPath = join4(dir, "wrangler.jsonc");
-  writeFileSync4(configPath, renderWranglerConfig(config));
+  installWorkerFiles(dir, bundle);
+  const configPath = join5(dir, "wrangler.jsonc");
+  writeFileSync5(configPath, renderWranglerConfig(config));
   await migrate(wrangler, config.d1.name, configPath);
   report("ok", "Migrations applied");
   await deploy(wrangler, configPath);
-  await putSecrets(
-    wrangler,
-    {
-      GLASS_ADMIN_KEY: credentials.adminKey,
-      GLASS_READ_KEY: credentials.readKey,
-      GLASS_SALT_SECRET: credentials.saltSecret
-      // CF_API_TOKEN (lake mode) is set by init and left alone here, so a narrower token you set stays.
-    },
-    configPath,
-    dir
-  );
-  const from = config.version;
+  if (credentials) {
+    await putSecrets(
+      wrangler,
+      {
+        GLASS_ADMIN_KEY: credentials.adminKey,
+        GLASS_READ_KEY: credentials.readKey,
+        GLASS_SALT_SECRET: credentials.saltSecret
+        // CF_API_TOKEN (lake mode) is set by init and left alone here, so a narrower token you set stays.
+      },
+      configPath,
+      dir
+    );
+  } else {
+    report("skipped", "Worker secrets", "no credentials.json here; the keys set by init stay in place");
+  }
   config.version = GLASS_VERSION;
   saveConfig(config, root);
-  if (options.json) printJson({ from, to: GLASS_VERSION, host: config.host, replay: Boolean(config.replay) });
+  if (options.json) printJson({ from, to: GLASS_VERSION, host: config.host, replay: Boolean(config.replay), staged: false });
   else ok(`Glass ${from === GLASS_VERSION ? GLASS_VERSION : `${from} upgraded to ${GLASS_VERSION}`} is live at ${config.host}`);
+  if (!ci2 && !hasCiWorkflow(root) && !options.json) {
+    line(color.dim(`  Tip: \`glass ci\` writes ${CI_WORKFLOW_PATH} so future upgrades deploy from CI instead of this machine.`));
+  }
+}
+function ci(options, deps = {}) {
+  const root = deps.root ?? projectRoot();
+  if (!loadConfig(root)) throw new UsageError("No Glass deployment in this project.", "Run `npx @glassanalytics/cli init` first.");
+  const result = writeCiWorkflow(root, { branch: options.branch, secret: options.secret });
+  const next = ciNextSteps(result);
+  if (options.json) {
+    printJson({ ...result, next });
+    return;
+  }
+  (result.status === "kept" ? skip : ok)(`${result.path} ${result.status === "kept" ? "already exists (left as is)" : result.status}`);
+  line();
+  line(color.bold("Finish CI setup"));
+  for (const [i, step] of next.entries()) line(`  ${i + 1}. ${step}`);
 }
 async function status(options) {
   const conn = connection();
@@ -804,18 +1150,24 @@ async function status(options) {
   const events2 = await call("GET", `/api/events?days=1${conn.project ? `&project=${conn.project}` : ""}`).catch(() => ({ events: [] }));
   const total = events2.events.reduce((a, e) => a + e.count, 0);
   const last = events2.events.map((e) => e.lastSeen).sort().at(-1);
-  const mcp = existsSync3(join4(projectRoot(), ".mcp.json"));
+  const mcp = existsSync4(join5(projectRoot(), ".mcp.json"));
+  const cliMismatch = health.version !== GLASS_VERSION;
+  const npmNewer = Boolean(health.latest && isNewerThan(health.latest, health.version));
+  const upgradeAvailable = Boolean(health.upgradeAvailable) || cliMismatch || npmNewer;
+  const upgradeCommand = health.upgradeCommand ?? UPGRADE_COMMAND;
   const result = {
     host: conn.host,
     project: conn.project,
     version: health.version,
+    latest: health.latest ?? null,
     cliVersion: GLASS_VERSION,
     store: health.store,
     replay: health.replay,
     eventsLast24h: total,
     lastEvent: last ?? null,
     mcpConfigured: mcp,
-    upgradeAvailable: health.version !== GLASS_VERSION,
+    upgradeAvailable,
+    upgradeCommand,
     account: config?.accountId
   };
   if (options.json) return printJson(result);
@@ -823,7 +1175,13 @@ async function status(options) {
   (total ? ok : skip)(total ? `${total.toLocaleString("en-US")} events in the last 24 hours, latest ${last}` : "No events in the last 24 hours. Is the snippet installed?");
   (health.replay ? ok : skip)(health.replay ? "Session replay enabled" : "Session replay disabled (no R2 bucket); `glass upgrade` retries");
   (mcp ? ok : skip)(mcp ? "MCP server configured in .mcp.json" : "No .mcp.json; run `glass init` again to write agent files");
-  if (result.upgradeAvailable) skip(`This CLI is Glass ${GLASS_VERSION}; the Worker runs ${health.version}. Run \`glass upgrade\`.`);
+  if (health.latest && isNewerThan(health.latest, health.version)) {
+    skip(`Glass ${health.latest} is available (this deployment is ${health.version}). Run: ${upgradeCommand}`);
+  } else if (cliMismatch) {
+    skip(`This CLI is Glass ${GLASS_VERSION}; the Worker runs ${health.version}. Run: ${upgradeCommand}`);
+  } else {
+    ok(`Up to date (Glass ${health.version})`);
+  }
 }
 function key(options) {
   const conn = connection();
@@ -838,7 +1196,7 @@ function key(options) {
 // packages/cli/src/commands/init.ts
 function defaultProjectId(root) {
   try {
-    const pkg = JSON.parse(readFileSync3(join5(root, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync4(join6(root, "package.json"), "utf8"));
     const id = (pkg.name ?? "").replace(/^@[^/]+\//, "").toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
     if (id) return id.slice(0, 63);
   } catch {
@@ -847,7 +1205,7 @@ function defaultProjectId(root) {
 }
 function readPackageJson(root) {
   try {
-    return JSON.parse(readFileSync3(join5(root, "package.json"), "utf8"));
+    return JSON.parse(readFileSync4(join6(root, "package.json"), "utf8"));
   } catch {
     return null;
   }
@@ -910,7 +1268,7 @@ async function init(options, deps = {}) {
         wantReplay ? `R2 bucket "${name}-replays"` : null,
         lake ? `R2 bucket "${name}-data" with data catalog, Pipelines streams/sinks for events and identities` : null
       ].filter(Boolean),
-      files: [".glass/config.json", ".glass/wrangler.jsonc", ".glass/worker.js", ".glass/migrations/", ".glass/credentials.json (git-ignored)", "AGENTS.md", ".claude/skills/glass/SKILL.md", ".mcp.json"]
+      files: [".glass/config.json", ".glass/wrangler.jsonc", ".glass/worker.js", ".glass/migrations/", ".glass/credentials.json (git-ignored)", "AGENTS.md", ".claude/skills/glass/SKILL.md", ".mcp.json", ...options.ci === false ? [] : [CI_WORKFLOW_PATH]]
     };
     if (quiet) printJson(plan);
     else {
@@ -944,12 +1302,12 @@ async function init(options, deps = {}) {
       lake: lakeConfig,
       route,
       eu,
-      version: GLASS_VERSION2
+      version: GLASS_VERSION
     };
     const credentials = loadCredentials(root) ?? { adminKey: randomToken(), readKey: randomToken(), saltSecret: randomToken() };
     installWorkerFiles(dir, deps.bundleDir ?? workerBundleDir());
-    const configPath = join5(dir, "wrangler.jsonc");
-    writeFileSync5(configPath, renderWranglerConfig(config));
+    const configPath = join6(dir, "wrangler.jsonc");
+    writeFileSync6(configPath, renderWranglerConfig(config));
     saveCredentials(credentials, root);
     await migrate(wrangler, d1.name, configPath);
     report("ok", "Database migrated");
@@ -984,8 +1342,11 @@ async function init(options, deps = {}) {
     const framework = detectFramework(readPackageJson(root));
     const snippet = FRAMEWORKS[framework].snippet({ host: config.host, project });
     const written = options.agentFiles === false ? [] : writeAgentFiles({ root, host: config.host, project, snippet });
+    const workflow = options.ci === false ? null : writeCiWorkflow(root);
+    if (workflow && workflow.status !== "kept") written.push(workflow.path);
+    const ci2 = workflow ? { workflow: workflow.path, status: workflow.status, branch: workflow.branch, secret: workflow.secret, next: ciNextSteps(workflow) } : null;
     if (quiet) {
-      printJson({ host: config.host, project, dashboard: `${config.host}/app`, framework, snippet, written, steps });
+      printJson({ host: config.host, project, dashboard: `${config.host}/app`, framework, snippet, written, ci: ci2, steps });
       return;
     }
     line();
@@ -1001,6 +1362,12 @@ async function init(options, deps = {}) {
       for (const f of written) line(`  ${f}`);
       line(`  .glass/ ${color.dim("(deployment config: commit it; credentials.json is git-ignored)")}`);
     }
+    if (ci2) {
+      line();
+      line(color.bold("Upgrades deploy from CI"));
+      line(color.dim(`  ${ci2.workflow} deploys the version pinned in .glass/config.json. Agents: finish these steps now.`));
+      for (const [i, step] of ci2.next.entries()) line(`  ${i + 1}. ${step}`);
+    }
     line();
     line(`Dashboard: ${color.cyan(`${config.host}/app`)} ${color.dim("(sign in with the key from `npx @glassanalytics/cli key`)")}`);
   } catch (err) {
@@ -1053,8 +1420,27 @@ async function mcpBridge(options = {}) {
   await Promise.all(pending);
 }
 
+// packages/cli/src/upgrade-check.ts
+var checked = false;
+async function warnIfOutdated(options = {}) {
+  if (checked || options.json) return;
+  checked = true;
+  try {
+    const health = await call("GET", "/health");
+    const command = health.upgradeCommand ?? UPGRADE_COMMAND;
+    if (health.upgradeAvailable && health.latest) {
+      skip(`Glass ${health.latest} is available (this deployment is ${health.version}). Run: ${command}`);
+      return;
+    }
+    if (health.version !== GLASS_VERSION) {
+      skip(`Worker is Glass ${health.version}; this CLI is ${GLASS_VERSION}. Run: ${command}`);
+    }
+  } catch {
+  }
+}
+
 // packages/cli/src/index.ts
-var HELP = `${color.bold("glass")} ${GLASS_VERSION3}: agent-first analytics in your own Cloudflare account
+var HELP = `${color.bold("glass")} ${GLASS_VERSION}: agent-first analytics in your own Cloudflare account
 
 ${color.bold("Set up")}
   glass init                     Deploy Glass and wire it into this project
@@ -1067,8 +1453,16 @@ ${color.bold("Set up")}
     --eu                           Keep data in the EU jurisdiction
     --no-replay                    Skip session replay storage
     --no-agent-files               Don't write AGENTS.md, SKILL.md or .mcp.json
+    --no-ci                        Don't write .github/workflows/glass.yml
     --dry-run                      Show what would be created
-  glass upgrade                  Redeploy this version of Glass and migrate
+  glass upgrade                  Move to this CLI's version of Glass and migrate
+                                   With .github/workflows/glass.yml: stage into .glass/ only;
+                                   commit and push, and CI deploys it
+    --ci                           Deploy as CI (no prompts; default when CI=true)
+    --local                        Deploy from here even though a CI workflow exists
+    --allow-downgrade              Replace a newer deployed Worker with this older one
+  glass ci [--branch main]       Write the workflow that deploys Glass from CI
+    --secret <name>                Repo secret with the Cloudflare token (default CLOUDFLARE_API_TOKEN)
   glass status                   Check the deployment end to end
   glass key [--read]             Print the dashboard URL and API key
 
@@ -1081,7 +1475,7 @@ ${color.bold("Ask questions")}
     common: --from, --to, --where prop=value[,\u2026], --project, --sql (print SQL)
   glass sql "SELECT \u2026"           Read-only SQL against your events
   glass events [name]            Tracked events, or one event's properties
-    --describe "<text>"            Document an event
+    --describe "<text>"            How/when the event fires (document custom events)
   glass person <id> [--delete]   One person's properties and events (or erase them)
   glass replays [--errors]       Recorded sessions
   glass replays summary <id>     A session as a text transcript
@@ -1107,6 +1501,8 @@ var STRING_OPTIONS = [
   "project",
   "name",
   "route",
+  "branch",
+  "secret",
   "from",
   "to",
   "event",
@@ -1136,7 +1532,7 @@ var STRING_OPTIONS = [
   "hypothesis",
   "variant"
 ];
-var BOOLEAN_OPTIONS = ["json", "lake", "eu", "no-replay", "no-agent-files", "dry-run", "read", "sql", "errors", "enable", "disable", "delete"];
+var BOOLEAN_OPTIONS = ["json", "lake", "eu", "no-replay", "no-agent-files", "no-ci", "ci", "local", "allow-downgrade", "dry-run", "read", "sql", "errors", "enable", "disable", "delete"];
 async function main(argv) {
   const { values, positionals } = parseArgs({
     args: argv,
@@ -1151,8 +1547,12 @@ async function main(argv) {
   });
   const flags2 = values;
   const [command, sub, arg, ...rest] = positionals;
-  if (flags2.version) return line(GLASS_VERSION3);
+  if (flags2.version) return line(GLASS_VERSION);
   if (!command || command === "help" || flags2.help && !command) return line(HELP);
+  const skipUpgradeWarn = /* @__PURE__ */ new Set(["init", "upgrade", "deploy", "ci", "status", "doctor", "mcp", "key"]);
+  if (command && !skipUpgradeWarn.has(command)) {
+    await warnIfOutdated({ json: Boolean(flags2.json) });
+  }
   switch (command) {
     case "init":
       return init({
@@ -1165,12 +1565,21 @@ async function main(argv) {
         eu: flags2.eu === true ? true : void 0,
         replay: flags2["no-replay"] ? false : void 0,
         agentFiles: flags2["no-agent-files"] ? false : void 0,
+        ci: flags2["no-ci"] ? false : void 0,
         dryRun: Boolean(flags2["dry-run"]),
         json: Boolean(flags2.json)
       });
     case "upgrade":
     case "deploy":
-      return upgrade({ token: str3(flags2.token), json: Boolean(flags2.json) });
+      return upgrade({
+        token: str3(flags2.token),
+        json: Boolean(flags2.json),
+        ci: flags2.ci === true ? true : void 0,
+        local: Boolean(flags2.local),
+        allowDowngrade: Boolean(flags2["allow-downgrade"])
+      });
+    case "ci":
+      return ci({ branch: str3(flags2.branch), secret: str3(flags2.secret), json: Boolean(flags2.json) });
     case "status":
     case "doctor":
       return status({ json: Boolean(flags2.json) });