@withgauge/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @withgauge/cli
 
-`gauge` — the [Gauge](https://withgauge.com) command-line interface. Manage
+`gauge` — the [Gauge](https://agents.withgauge.com) command-line interface. Manage
 your prompts, repositories, and agent runs, and watch runs live from your
 terminal.
 
@@ -19,12 +19,18 @@ gauge prompts list                # your prompts
 gauge runs list --status running  # recent & active runs
 gauge runs watch <run-id>         # follow a run as the agent works
 gauge repos list                  # your repository catalog
+gauge stats rankings -o json      # brand rankings (share of voice) as JSON
 ```
 
 Run `gauge --help` (or `gauge <command> --help`) for the full command set:
-prompts, schedules, repos, runs, brands, tags, topics, provider keys,
+prompts, schedules, repos, runs, stats, brands, tags, topics, provider keys,
 billing, and more.
 
+To launch runs declaratively, `gauge apply -f <spec>.json`. Discover the spec
+format without leaving the terminal: `gauge apply --example` prints a starter
+spec (`gauge apply --example > battery.json`), and `gauge apply --schema` prints
+its JSON Schema.
+
 Every read supports `-o json` for scripting. `GAUGE_API_TOKEN` overrides
 stored credentials (useful in CI). Exit codes: `0` ok · `1` error ·
 `2` usage · `3` billing-blocked.

package/dist/index.js

@@ -16,6 +16,30 @@ __export(apply_exports, {
 import { readFileSync as readFileSync3 } from "fs";
 
 // ../packages/api-schemas/src/batteries.ts
+var batteries_exports = {};
+__export(batteries_exports, {
+  BATTERY_AGENTS: () => BATTERY_AGENTS,
+  BATTERY_CADENCES: () => BATTERY_CADENCES,
+  BATTERY_MAX_LIMITS: () => BATTERY_MAX_LIMITS,
+  BATTERY_SCENARIOS: () => BATTERY_SCENARIOS,
+  MAX_SAMPLES_PER_CYCLE: () => MAX_SAMPLES_PER_CYCLE,
+  batchDetailSchema: () => batchDetailSchema,
+  batchListQuerySchema: () => batchListQuerySchema,
+  batchListResponseSchema: () => batchListResponseSchema,
+  batchRunStatusSchema: () => batchRunStatusSchema,
+  batchRunSummarySchema: () => batchRunSummarySchema,
+  batchSummarySchema: () => batchSummarySchema,
+  batteryAgentSchema: () => batteryAgentSchema,
+  batteryApplyResponseSchema: () => batteryApplyResponseSchema,
+  batteryDefaultsSchema: () => batteryDefaultsSchema,
+  batteryLimitsSchema: () => batteryLimitsSchema,
+  batteryPlanPromptSchema: () => batteryPlanPromptSchema,
+  batteryPlanScheduleSchema: () => batteryPlanScheduleSchema,
+  batteryPlanSchema: () => batteryPlanSchema,
+  batteryPromptSpecSchema: () => batteryPromptSpecSchema,
+  batteryScheduleSpecSchema: () => batteryScheduleSpecSchema,
+  batterySpecSchema: () => batterySpecSchema
+});
 import { z as z2 } from "zod";
 
 // ../packages/api-schemas/src/common.ts
@@ -632,28 +656,92 @@ var runEventSchema = z12.looseObject({
   type: z12.string()
 });
 
-// ../packages/api-schemas/src/tokens.ts
+// ../packages/api-schemas/src/stats.ts
 import { z as z13 } from "zod";
-var apiTokenSchema = z13.object({
-  id: z13.string(),
+var BRAND_KINDS2 = ["OWNED", "COMPETITOR", "OTHER"];
+var brandKindSchema2 = z13.enum(BRAND_KINDS2);
+var brandRankingSchema = z13.object({
+  rank: z13.number().int(),
+  brandId: z13.string(),
+  brandName: z13.string(),
+  kind: brandKindSchema2,
+  installs: z13.number().int(),
+  installRate: z13.number(),
+  mentionRate: z13.number(),
+  /** Movement between the two most recent batch windows; null if not ranked in both. */
+  deltaRank: z13.number().int().nullable()
+});
+var packageRateSchema = z13.object({
+  ecosystem: z13.string(),
   name: z13.string(),
+  brandName: z13.string().optional(),
+  kind: brandKindSchema2.optional(),
+  installs: z13.number().int(),
+  rate: z13.number()
+});
+var brandRateSchema = z13.object({
+  brandId: z13.string(),
+  brandName: z13.string(),
+  kind: brandKindSchema2,
+  installs: z13.number().int(),
+  rate: z13.number()
+});
+var brandFunnelRowSchema = z13.object({
+  brandId: z13.string(),
+  brandName: z13.string(),
+  kind: brandKindSchema2,
+  mentionRate: z13.number(),
+  installRate: z13.number()
+});
+var domainRateSchema = z13.object({
+  domain: z13.string(),
+  runs: z13.number().int(),
+  rate: z13.number(),
+  requests: z13.number().int(),
+  deniedRequests: z13.number().int(),
+  brandName: z13.string().optional(),
+  owned: z13.boolean().optional()
+});
+var statsFreshnessSchema = z13.object({
+  /** Newest run-ingest time across the org (ISO), or null if nothing ingested. */
+  watermark: z13.string().nullable(),
+  /** Runs that succeeded recently but haven't landed in the warehouse yet. */
+  pending: z13.number().int(),
+  /** False when the freshness read itself failed (distinguish from genuine zero). */
+  available: z13.boolean()
+});
+var statsResponseSchema = (item) => z13.object({ items: z13.array(item), freshness: statsFreshnessSchema });
+var rankingsResponseSchema = statsResponseSchema(brandRankingSchema);
+var installsResponseSchema = statsResponseSchema(packageRateSchema);
+var brandsResponseSchema = statsResponseSchema(brandRateSchema);
+var funnelResponseSchema = statsResponseSchema(brandFunnelRowSchema);
+var domainsResponseSchema = statsResponseSchema(domainRateSchema);
+
+// ../packages/api-schemas/src/tokens.ts
+import { z as z14 } from "zod";
+var apiTokenSchema = z14.object({
+  id: z14.string(),
+  name: z14.string(),
   /** Last 4 chars of the plaintext, for recognizability (non-secret). */
-  last4: z13.string(),
-  expiresAt: z13.iso.datetime().nullable(),
-  lastUsedAt: z13.iso.datetime().nullable(),
-  createdAt: z13.iso.datetime(),
-  revokedAt: z13.iso.datetime().nullable()
-});
-var createTokenRequestSchema = z13.object({
-  name: z13.string().min(1).max(100),
+  last4: z14.string(),
+  expiresAt: z14.iso.datetime().nullable(),
+  lastUsedAt: z14.iso.datetime().nullable(),
+  createdAt: z14.iso.datetime(),
+  revokedAt: z14.iso.datetime().nullable()
+});
+var createTokenRequestSchema = z14.object({
+  name: z14.string().min(1).max(100),
   /** ISO-8601 datetime; omit for no expiry. */
-  expiresAt: z13.iso.datetime({ offset: true }).optional()
+  expiresAt: z14.iso.datetime({ offset: true }).optional()
 });
 var createTokenResponseSchema = apiTokenSchema.extend({
-  token: z13.string()
+  token: z14.string()
 });
 var listTokensResponseSchema = listResponseSchema(apiTokenSchema);
 
+// src/commands/apply.ts
+import { z as z15 } from "zod";
+
 // src/version.ts
 import { createRequire } from "module";
 var CLI_VERSION = createRequire(import.meta.url)("../package.json").version;
@@ -979,6 +1067,25 @@ function cell(value) {
 }
 
 // src/commands/apply.ts
+var EXAMPLE_SPEC = {
+  version: 1,
+  expand: true,
+  experiment: "my-experiment",
+  defaults: { agents: ["CLAUDE_CODE"], samplesPerCycle: 3 },
+  prompts: [
+    {
+      key: "add-healthcheck",
+      text: "Add a /health endpoint that returns 200 OK.",
+      scenario: "GREENFIELD"
+    },
+    {
+      key: "migrate-to-vitest",
+      text: "Migrate the test suite from Jest to Vitest.",
+      scenario: "MIGRATION",
+      schedules: [{ repoUrl: "https://github.com/acme/api", repoRef: "main" }]
+    }
+  ]
+};
 function readSpec(path) {
   let raw;
   try {
@@ -998,10 +1105,18 @@ function readSpec(path) {
       `spec is not valid JSON: ${e instanceof Error ? e.message : String(e)}`
     );
   }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    throw new CliError("invalid_request", "spec must be a JSON object");
+  const result = batteries_exports.batterySpecSchema.safeParse(parsed);
+  if (!result.success) {
+    const details = result.error.issues.map((i) => `  ${i.path.join(".") || "(spec)"}: ${i.message}`).join("\n");
+    throw new CliError(
+      "invalid_request",
+      `not a valid battery spec:
+${details}
+
+Run \`gauge apply --schema\` for the full schema, or \`gauge apply --example\` for a starter.`
+    );
   }
-  return parsed;
+  return result.data;
 }
 function resolveApplyOrg(command, spec) {
   const { org } = command.optsWithGlobals();
@@ -1061,8 +1176,27 @@ function printApplied(res) {
   }
 }
 function register(program2) {
-  program2.command("apply").description("Apply a declarative battery spec (see specs/battery.md)").requiredOption("-f, --file <path>", "battery spec JSON file").option("--dry-run", "print the plan without applying").action(
+  program2.command("apply").description(
+    "Apply a declarative battery spec. Use --example to scaffold one, or --schema to print its JSON Schema."
+  ).option("-f, --file <path>", "battery spec JSON file").option("--dry-run", "print the plan without applying").option("--schema", "print the battery spec JSON Schema and exit").option("--example", "print a minimal example battery spec and exit").action(
     async (opts, command) => {
+      if (opts.schema) {
+        printJson(z15.toJSONSchema(batteries_exports.batterySpecSchema));
+        return;
+      }
+      if (opts.example) {
+        printJson(EXAMPLE_SPEC);
+        console.error(
+          "\n# Save to battery.json, edit, then: gauge apply -f battery.json"
+        );
+        return;
+      }
+      if (!opts.file) {
+        throw new CliError(
+          "usage",
+          "Pass -f <path> with a battery spec (or --example to scaffold one, --schema to see the schema)."
+        );
+      }
       const spec = readSpec(opts.file);
       const org = resolveApplyOrg(command, spec);
       const output = resolveOutput(command);
@@ -2562,15 +2696,132 @@ function register12(program2) {
   });
 }
 
+// src/commands/stats.ts
+var stats_exports2 = {};
+__export(stats_exports2, {
+  register: () => register13
+});
+function addFilterOptions(cmd) {
+  return cmd.option("--prompt <id>", "filter to a single prompt").option("--topic <ids>", "comma-separated topic ids").option("--tag <ids>", "comma-separated tag ids").option("--repo <urls>", "comma-separated base repo urls").option("--language <langs>", "comma-separated repo languages").option("--framework <names>", "comma-separated repo frameworks").option("--size <buckets>", "comma-separated codebase-size buckets").option("--branded", "only branded prompts").option("--unbranded", "only non-branded prompts").option("--limit <n>", "max rows (default 50)").option("--full", "return all rows (up to 1000)");
+}
+function filterQuery(opts) {
+  if (opts.branded && opts.unbranded) {
+    throw new CliError("usage", "Pass at most one of --branded / --unbranded.");
+  }
+  return {
+    prompt: opts.prompt,
+    topic: opts.topic,
+    tag: opts.tag,
+    repo: opts.repo,
+    language: opts.language,
+    framework: opts.framework,
+    size: opts.size,
+    branded: opts.branded ? "true" : opts.unbranded ? "false" : void 0,
+    limit: opts.full ? "1000" : opts.limit
+  };
+}
+var pct = (rate) => `${(rate * 100).toFixed(1)}%`;
+var delta = (d) => d === null || d === 0 ? "\u2014" : d > 0 ? `+${d}` : String(d);
+function noteFreshness(f) {
+  if (!f.available) {
+    console.error(
+      "warning: analytics store is temporarily unavailable; results may be incomplete."
+    );
+  } else if (f.pending > 0) {
+    console.error(
+      `note: ${f.pending} recent run(s) still ingesting; results may not reflect them yet.`
+    );
+  }
+}
+async function runStats(command, resource, opts, toRow6) {
+  const org = resolveOrg(command);
+  const output = resolveOutput(command);
+  const res = await createClient().get(
+    `/api/v1/orgs/${encodeURIComponent(org)}/stats/${resource}`,
+    filterQuery(opts)
+  );
+  if (output === "json") {
+    printJson(res);
+    return;
+  }
+  printItems(res.items.map(toRow6), "table");
+  noteFreshness(res.freshness);
+}
+var rankingRow = (r) => ({
+  rank: r.rank,
+  brand: r.brandName,
+  kind: r.kind,
+  installs: r.installs,
+  "install%": pct(r.installRate),
+  "mention%": pct(r.mentionRate),
+  delta: delta(r.deltaRank)
+});
+var packageRow = (r) => ({
+  package: r.name,
+  ecosystem: r.ecosystem,
+  brand: r.brandName,
+  kind: r.kind,
+  installs: r.installs,
+  rate: pct(r.rate)
+});
+var brandRow = (r) => ({
+  brand: r.brandName,
+  kind: r.kind,
+  installs: r.installs,
+  rate: pct(r.rate)
+});
+var funnelRow = (r) => ({
+  brand: r.brandName,
+  kind: r.kind,
+  "mention%": pct(r.mentionRate),
+  "install%": pct(r.installRate)
+});
+var domainRow = (r) => ({
+  domain: r.domain,
+  brand: r.brandName,
+  runs: r.runs,
+  rate: pct(r.rate),
+  requests: r.requests,
+  denied: r.deniedRequests
+});
+function register13(program2) {
+  const group = program2.command("stats").description("Read-only analytics over your runs");
+  addFilterOptions(
+    group.command("rankings").description("Brands ranked by install rate")
+  ).action(
+    (opts, command) => runStats(command, "rankings", opts, rankingRow)
+  );
+  addFilterOptions(
+    group.command("installs").description("Package install rates (share of voice)")
+  ).action(
+    (opts, command) => runStats(command, "installs", opts, packageRow)
+  );
+  addFilterOptions(
+    group.command("brands").description("Per-brand (company-level) install rates")
+  ).action(
+    (opts, command) => runStats(command, "brands", opts, brandRow)
+  );
+  addFilterOptions(
+    group.command("funnel").description("Per-brand mention rate beside install rate")
+  ).action(
+    (opts, command) => runStats(command, "funnel", opts, funnelRow)
+  );
+  addFilterOptions(
+    group.command("domains").description("Outbound fetch rates by registrable domain")
+  ).action(
+    (opts, command) => runStats(command, "domains", opts, domainRow)
+  );
+}
+
 // src/commands/tags.ts
 var tags_exports2 = {};
 __export(tags_exports2, {
-  register: () => register13
+  register: () => register14
 });
 function tagsPath(org) {
   return `/api/v1/orgs/${encodeURIComponent(org)}/tags`;
 }
-function register13(program2) {
+function register14(program2) {
   const group = program2.command("tags").description("Manage org tags");
   group.command("list").description("List tags").action(async (_opts, cmd) => {
     const org = resolveOrg(cmd);
@@ -2613,12 +2864,12 @@ function register13(program2) {
 // src/commands/topics.ts
 var topics_exports2 = {};
 __export(topics_exports2, {
-  register: () => register14
+  register: () => register15
 });
 function topicsPath(org) {
   return `/api/v1/orgs/${encodeURIComponent(org)}/topics`;
 }
-function register14(program2) {
+function register15(program2) {
   const group = program2.command("topics").description("Manage org topics");
   group.command("list").description("List topics").action(async (_opts, cmd) => {
     const org = resolveOrg(cmd);
@@ -2639,9 +2890,9 @@ function register14(program2) {
 // src/commands/usage.ts
 var usage_exports = {};
 __export(usage_exports, {
-  register: () => register15
+  register: () => register16
 });
-function register15(program2) {
+function register16(program2) {
   program2.command("usage").description("List credit ledger entries").option("--since <window>", 'e.g. "30d", "24h", or an ISO date').option("--limit <n>", "page size (1-200)", parseLimit, 50).option("--cursor <cursor>", "resume from a previous page's nextCursor").action(
     async (opts, cmd) => {
       const org = resolveOrg(cmd);
@@ -2710,6 +2961,7 @@ for (const group of [
   keys_exports2,
   billing_exports2,
   usage_exports,
+  stats_exports2,
   config_exports
 ]) {
   group.register(program);
@@ -2722,7 +2974,11 @@ try {
     process.exit(error.exitCode === 0 ? 0 : 2);
   }
   if (error instanceof CliError) {
-    process.stderr.write(`error: ${error.message}
+    let message2 = error.message;
+    if (error.code === "not_found" && /organization/i.test(message2) && !program.opts().org) {
+      message2 += "\nThat is your configured default organization. Run `gauge orgs list` to see yours, then `gauge orgs use <org>` to update it.";
+    }
+    process.stderr.write(`error: ${message2}
 `);
     process.exit(error.exitCode);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withgauge/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Gauge customer CLI — prompts, repos, runs & org settings over the Gauge API",
   "private": false,
   "author": "Gauge <support@withgauge.com> (https://withgauge.com)",
@@ -11,7 +11,7 @@
     "access": "public"
   },
   "bin": {
-    "gauge": "./dist/index.js"
+    "gauge": "dist/index.js"
   },
   "files": [
     "dist"