@farthershore/cli 0.3.5 → 0.3.7

package/dist/index.js

@@ -1,60 +1,1251 @@
 #!/usr/bin/env node
+
+// src/index.ts
 import { Command } from "commander";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-import { createClient } from "./client.js";
-import { resolveToken } from "./auth.js";
-import { loadConfig } from "./config.js";
-import { registerAuthCommands } from "./commands/login.js";
-import { registerInitCommand } from "./commands/init.js";
-import { registerValidateCommand } from "./commands/validate.js";
-import { registerApplyCommand } from "./commands/apply.js";
-import { CliError } from "./types.js";
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(await readFile(join(__dirname, "..", "package.json"), "utf-8"));
-const program = new Command();
-program
-    .name("farthershore")
-    .description("FartherShore CLI — create and manage API products")
-    .version(pkg.version)
-    .option("--token <token>", "Override auth token")
-    .option("--api-url <url>", "Override API base URL")
-    .option("--format <format>", "Output format: table, json");
-// Lazy client — created on first use with resolved auth
-function getClient() {
+import { dirname, join as join2 } from "node:path";
+
+// src/types.ts
+var CliError = class extends Error {
+  constructor(message, status, extra) {
+    super(message);
+    this.status = status;
+    this.name = "CliError";
+    this.code = extra?.code;
+    this.details = extra?.details;
+  }
+  status;
+  code;
+  details;
+};
+
+// src/client.ts
+function createClient(opts) {
+  async function request(method, path, body) {
+    const res = await fetch(`${opts.apiUrl}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${opts.token}`,
+        "Content-Type": "application/json"
+      },
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const parsed = await res.json().catch(() => null);
+      const errEnvelope = parsed && typeof parsed === "object" && parsed.error;
+      let message = res.statusText;
+      let code;
+      let details;
+      if (typeof errEnvelope === "string") {
+        message = errEnvelope;
+      } else if (errEnvelope && typeof errEnvelope === "object") {
+        message = errEnvelope.message ?? message;
+        code = errEnvelope.code;
+        details = errEnvelope.details;
+      }
+      throw new CliError(message, res.status, { code, details });
+    }
+    if (res.status === 204) return void 0;
+    return res.json();
+  }
+  return {
+    // --- Auth ---
+    bootstrap: () => request("POST", "/builder/context/bootstrap"),
+    // --- Products ---
+    listProducts: () => request("GET", "/products"),
+    initProduct: (data) => request("POST", "/products/init", data),
+    // --- Compile ---
+    compileProduct: (productId, opts2) => request(
+      "POST",
+      `/products/${productId}/compile`,
+      opts2?.branch ? { branch: opts2.branch } : void 0
+    ),
+    // --- Management (maker token) ---
+    // Compile the product associated with the token — no product ID needed.
+    // Pass `branch` to scope compilation to an env branch's plans.
+    managementCompileSelf: (opts2) => request(
+      "POST",
+      "/management/compile",
+      opts2?.branch ? { branch: opts2.branch } : void 0
+    ),
+    managementCompile: (productId, opts2) => request(
+      "POST",
+      `/management/products/${productId}/compile`,
+      opts2?.branch ? { branch: opts2.branch } : void 0
+    ),
+    managementListProducts: () => request("GET", "/management/products"),
+    isMakerToken: () => opts.token.startsWith("mk_")
+  };
+}
+
+// src/config.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// src/build-info.ts
+var BUILD_API_URL = "https://core.farthershore.com";
+
+// src/config.ts
+var CONFIG_DIR = join(homedir(), ".farthershore");
+var CONFIG_FILE = join(CONFIG_DIR, "config.json");
+var CREDENTIALS_FILE = join(CONFIG_DIR, "credentials.json");
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 448 });
+}
+var DEFAULT_CONFIG = {
+  apiUrl: BUILD_API_URL,
+  defaultFormat: "table"
+};
+function loadConfig() {
+  ensureDir(CONFIG_DIR);
+  if (!existsSync(CONFIG_FILE)) return DEFAULT_CONFIG;
+  try {
+    const parsed = JSON.parse(
+      readFileSync(CONFIG_FILE, "utf-8")
+    );
+    return { ...DEFAULT_CONFIG, ...parsed };
+  } catch {
+    return DEFAULT_CONFIG;
+  }
+}
+function saveConfig(config) {
+  ensureDir(CONFIG_DIR);
+  const current = loadConfig();
+  writeFileSync(
+    CONFIG_FILE,
+    JSON.stringify({ ...current, ...config }, null, 2) + "\n"
+  );
+}
+function loadCredentials() {
+  if (!existsSync(CREDENTIALS_FILE)) return null;
+  try {
+    return JSON.parse(readFileSync(CREDENTIALS_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function saveCredentials(creds) {
+  ensureDir(CONFIG_DIR);
+  writeFileSync(CREDENTIALS_FILE, JSON.stringify(creds, null, 2) + "\n", {
+    mode: 384
+  });
+}
+function clearCredentials() {
+  if (existsSync(CREDENTIALS_FILE)) {
+    writeFileSync(CREDENTIALS_FILE, "{}");
+  }
+}
+
+// src/auth.ts
+function resolveToken(overrideToken) {
+  if (overrideToken) return overrideToken;
+  const envToken = process.env.FARTHERSHORE_TOKEN;
+  if (envToken) return envToken;
+  const creds = loadCredentials();
+  if (creds?.token) return creds.token;
+  throw new CliError(
+    "Not authenticated. Run `farthershore set-key` or set FARTHERSHORE_TOKEN environment variable."
+  );
+}
+
+// src/commands/login.ts
+import * as readline from "node:readline/promises";
+
+// src/output.ts
+import chalk from "chalk";
+function json(data) {
+  return JSON.stringify(data, null, 2);
+}
+function success(msg) {
+  console.log(chalk.green(`\u2713 ${msg}`));
+}
+function error(msg) {
+  console.error(chalk.red(`\u2717 ${msg}`));
+}
+function warn(msg) {
+  console.warn(chalk.yellow(`\u26A0 ${msg}`));
+}
+function info(msg) {
+  console.log(chalk.dim(msg));
+}
+function heading(msg) {
+  console.log(chalk.bold(msg));
+}
+function isTTY() {
+  return process.stdout.isTTY === true;
+}
+function outputFormat(flagFormat) {
+  if (flagFormat === "json" || flagFormat === "table") return flagFormat;
+  return isTTY() ? "table" : "json";
+}
+
+// src/commands/login.ts
+function registerAuthCommands(program2) {
+  program2.command("set-key [token]").description("Set your API token (interactive or pass as argument)").action(async (tokenArg) => {
+    let token = tokenArg?.trim();
+    if (!token) {
+      if (!process.stdin.isTTY) {
+        error(
+          "No token provided. Pass it as an argument: farthershore set-key <token>"
+        );
+        process.exitCode = 1;
+        return;
+      }
+      console.log("Set your FartherShore API token\n");
+      console.log(
+        "  Create a token at https://farthershore.com/settings/tokens\n"
+      );
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+      });
+      token = (await rl.question("Token: ")).trim();
+      rl.close();
+    }
+    if (!token) {
+      error("No token provided.");
+      process.exitCode = 1;
+      return;
+    }
     const config = loadConfig();
-    const globalOpts = program.opts();
-    const token = resolveToken(globalOpts.token);
-    const apiUrl = globalOpts.apiUrl ?? process.env.FARTHERSHORE_API_URL ?? config.apiUrl;
-    return createClient({ apiUrl, token });
+    try {
+      const client = createClient({ apiUrl: config.apiUrl, token });
+      const ctx = await client.bootstrap();
+      saveCredentials({
+        token,
+        orgId: ctx.activeOrganization.id,
+        userId: ctx.user.id
+      });
+      success("Authenticated");
+      console.log(
+        `  Organization: ${ctx.activeOrganization.name ?? ctx.activeOrganization.id}`
+      );
+    } catch {
+      error("Invalid token. Check it and try again.");
+      process.exitCode = 1;
+    }
+  });
+  program2.command("logout").description("Clear stored credentials").action(() => {
+    clearCredentials();
+    success("Credentials cleared.");
+  });
+  program2.command("whoami").description("Show current authentication context").action(async () => {
+    const config = loadConfig();
+    const formatOpt = program2.opts().format;
+    const format = outputFormat(formatOpt);
+    try {
+      const token = resolveToken();
+      const client = createClient({ apiUrl: config.apiUrl, token });
+      const ctx = await client.bootstrap();
+      const authSource = process.env.FARTHERSHORE_TOKEN ? "env:FARTHERSHORE_TOKEN" : "credentials-file";
+      if (format === "json") {
+        console.log(
+          json({
+            organization: {
+              id: ctx.activeOrganization.id,
+              name: ctx.activeOrganization.name ?? null,
+              slug: ctx.activeOrganization.slug ?? null
+            },
+            user: { id: ctx.user.id },
+            apiUrl: config.apiUrl,
+            authSource
+          })
+        );
+        return;
+      }
+      heading("Current Context");
+      console.log(
+        `  Organization: ${ctx.activeOrganization.name ?? ctx.activeOrganization.id}`
+      );
+      console.log(`  API URL:      ${config.apiUrl}`);
+      if (authSource === "env:FARTHERSHORE_TOKEN") {
+        info("  Auth: FARTHERSHORE_TOKEN env var");
+      } else {
+        info("  Auth: ~/.farthershore/credentials.json");
+      }
+    } catch {
+      if (format === "json") {
+        console.log(json({ authenticated: false }));
+      } else {
+        error(
+          "Not authenticated. Run `farthershore set-key` or set FARTHERSHORE_TOKEN."
+        );
+      }
+      process.exitCode = 1;
+    }
+  });
+  program2.command("set-url <url>").description("Override the API base URL (for staging/testing)").action((url) => {
+    saveConfig({ apiUrl: url });
+    success(`API URL set to ${url}`);
+  });
+  program2.command("reset-url").description("Reset the API URL to production default").action(() => {
+    saveConfig({ apiUrl: "https://core.farthershore.com" });
+    success("API URL reset to https://core.farthershore.com");
+  });
+}
+
+// src/commands/init.ts
+function registerInitCommand(program2, getClient2) {
+  program2.command("init <name>").description(
+    "Create a new product with a GitHub repo for agent-first configuration"
+  ).option("--base-url <url>", "Backend API base URL").option("--description <desc>", "Product description").option("--display-name <name>", "Display name").action(
+    async (name, opts) => {
+      const client = getClient2();
+      const result = await client.initProduct({
+        name,
+        baseUrl: opts.baseUrl,
+        description: opts.description,
+        displayName: opts.displayName
+      });
+      const formatOpt = program2.opts().format;
+      const format = outputFormat(formatOpt);
+      if (format === "json") {
+        console.log(json(result));
+        return;
+      }
+      success(`Created product "${result.product.name}" (DRAFT)`);
+      console.log();
+      if (result.repo) {
+        console.log(`  Repository:  ${result.repo.htmlUrl}`);
+        console.log(`  Clone:       git clone ${result.repo.cloneUrl}`);
+        console.log();
+      }
+      console.log("  Next steps:");
+      console.log("    1. Clone the repository");
+      console.log(
+        "    2. Read AGENTS.md for the full configuration reference"
+      );
+      console.log(
+        "    3. Edit product.yaml \u2014 add your base URL, plans, and meters"
+      );
+      console.log(
+        "    4. Push to main \u2014 a valid config goes live automatically"
+      );
+      console.log();
+      if (result.agent.agentsMdUrl) {
+        console.log(`  Docs: ${result.agent.agentsMdUrl}`);
+      }
+    }
+  );
+}
+
+// src/commands/validate.ts
+import { readFileSync as readFileSync2, existsSync as existsSync2 } from "node:fs";
+import { execSync } from "node:child_process";
+import { resolve } from "node:path";
+import YAML from "yaml";
+
+// node_modules/@farther-shore/shared-types/dist/plans/limits-schema.js
+import { z } from "zod";
+var limitDimensionSchema = z.string().min(1);
+var namedWindowSchema = z.object({
+  type: z.literal("named"),
+  name: z.enum(["second", "minute", "hour", "day", "week", "month"])
+});
+var customWindowSchema = z.object({
+  type: z.literal("custom"),
+  seconds: z.number().int().positive(),
+  label: z.string().optional()
+});
+var limitWindowSpecSchema = z.discriminatedUnion("type", [
+  namedWindowSchema,
+  customWindowSchema
+]);
+var planLimitRuleSchema = z.object({
+  dimension: limitDimensionSchema,
+  window: limitWindowSpecSchema,
+  capacity: z.number().nonnegative(),
+  enforcement: z.enum(["enforce", "track"]).optional()
+});
+var planLimitsSchema = z.array(planLimitRuleSchema).max(20);
+
+// node_modules/@farther-shore/shared-types/dist/plans/spec.js
+import { z as z3 } from "zod";
+
+// node_modules/@farther-shore/shared-types/dist/webhooks/events.js
+import { z as z2 } from "zod";
+var WEBHOOK_EVENT_NAMES = [
+  "subscription.created",
+  "subscription.updated",
+  "subscription.canceled",
+  "payment.succeeded",
+  "payment.failed",
+  "rate_limit.exceeded",
+  "entitlement.changed",
+  "usage.threshold_reached"
+];
+var webhookEventNameSchema = z2.enum(WEBHOOK_EVENT_NAMES);
+
+// node_modules/@farther-shore/shared-types/dist/plans/spec.js
+var productIdentitySchema = z3.object({
+  subdomain: z3.string().min(1).max(63).regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, "Subdomain must be lowercase alphanumeric with optional hyphens")
+});
+var meterDefinitionSchema = z3.object({
+  key: z3.string().min(1).max(64).regex(/^[a-z0-9_]+$/, "Meter key must be lowercase alphanumeric with underscores"),
+  display: z3.string().min(1).max(100),
+  type: z3.enum(["built-in", "custom"]).default("custom"),
+  unit: z3.string().max(20).optional()
+});
+var pricingTierSchema = z3.object({
+  upToAmount: z3.number().int().positive().nullable(),
+  unitPrice: z3.number().nonnegative(),
+  flatPrice: z3.number().nonnegative().optional()
+});
+var meteredDimensionSchema = z3.object({
+  dimension: z3.string().min(1),
+  includedUnits: z3.number().int().nonnegative().default(0),
+  overagePerUnitMicrocents: z3.number().int().nonnegative().default(0),
+  tiers: z3.array(pricingTierSchema).optional(),
+  pricingMode: z3.enum(["graduated", "volume"]).optional()
+});
+var legacyPlanPricingBaseSchema = {
+  monthlyPriceCents: z3.number().int().nonnegative().default(0),
+  billingInterval: z3.enum(["month", "year"]).default("month"),
+  trialDays: z3.number().int().nonnegative().optional(),
+  monthlyBudgetCents: z3.number().int().positive().optional(),
+  // F5 (Verification Loop 1): explicit Stripe price ref. When set, the
+  // compiler's `enforce-variant-rules` invariant 7 verifies that a
+  // variant's stripePriceId differs from its parent's — a variant
+  // sharing the parent's Stripe price would cause double-charges on
+  // the variant cohort. Optional because variants can also be
+  // ensure-or-create'd by the Stripe-publish step (Phase B), in which
+  // case the lineage uses the auto-generated price refs.
+  stripePriceId: z3.string().min(1).optional()
+};
+var measureExpressionSchema = z3.object({
+  expr: z3.string().min(1).max(1e3)
+});
+var configurableUsageTierSchema = z3.object({
+  upTo: z3.number().positive().nullable(),
+  unitAmountMicros: z3.number().int().nonnegative()
+});
+var configurableUsagePriceSchema = z3.discriminatedUnion("kind", [
+  z3.object({
+    kind: z3.literal("flat"),
+    amountMicros: z3.number().int().nonnegative()
+  }),
+  z3.object({
+    kind: z3.literal("per_unit"),
+    unitAmountMicros: z3.number().int().nonnegative(),
+    unit: z3.string().max(20).optional()
+  }),
+  z3.object({
+    kind: z3.literal("graduated"),
+    intraRequest: z3.boolean().default(false),
+    tiers: z3.array(configurableUsageTierSchema).min(1)
+  }),
+  z3.object({
+    kind: z3.literal("volume_retroactive"),
+    tiers: z3.array(configurableUsageTierSchema).min(1)
+  }),
+  z3.object({
+    kind: z3.literal("formula"),
+    expr: z3.string().min(1).max(1e3)
+  })
+]);
+var configurableUsageDiscountSchema = z3.discriminatedUnion("kind", [
+  z3.object({
+    kind: z3.literal("percentage"),
+    basisPoints: z3.number().int().positive().max(1e4),
+    appliesToDimensions: z3.array(z3.string().min(1)).optional()
+  }),
+  z3.object({
+    kind: z3.literal("fixed_micros"),
+    amountMicros: z3.number().int().nonnegative(),
+    appliesToDimensions: z3.array(z3.string().min(1)).optional()
+  })
+]);
+var configurableUsageCommitmentsSchema = z3.object({
+  minimumMonthlySpendMicros: z3.number().int().nonnegative().optional(),
+  includedCreditMicros: z3.number().int().nonnegative().optional()
+}).refine((value) => value.minimumMonthlySpendMicros !== void 0 || value.includedCreditMicros !== void 0, {
+  message: "commitments must declare at least one of minimumMonthlySpendMicros or includedCreditMicros"
+});
+var configurableUsageReportingSchema = z3.object({
+  mode: z3.literal("builder_attested"),
+  header: z3.string().min(1).max(100).optional(),
+  signatureHeader: z3.string().min(1).max(100).optional(),
+  schema: z3.record(z3.string(), z3.enum(["int", "float", "string", "boolean"]))
+});
+var configurableUsageRateCardEntrySchema = z3.object({
+  dimension: z3.string().min(1),
+  unit: z3.string().max(20).optional(),
+  measure: measureExpressionSchema,
+  price: configurableUsagePriceSchema
+});
+var planPricingSchema = z3.discriminatedUnion("model", [
+  z3.object({
+    model: z3.literal("flat_rate"),
+    ...legacyPlanPricingBaseSchema
+  }),
+  z3.object({
+    model: z3.literal("included_usage"),
+    ...legacyPlanPricingBaseSchema
+  }),
+  z3.object({
+    model: z3.literal("pay_as_you_go"),
+    ...legacyPlanPricingBaseSchema
+  }),
+  z3.object({
+    model: z3.literal("configurable_usage"),
+    billingInterval: z3.enum(["month", "year"]).default("month"),
+    trialDays: z3.number().int().nonnegative().optional(),
+    rateCard: z3.array(configurableUsageRateCardEntrySchema).min(1),
+    discounts: z3.array(configurableUsageDiscountSchema).default([]),
+    commitments: configurableUsageCommitmentsSchema.optional(),
+    reporting: configurableUsageReportingSchema.optional(),
+    // F5 (Verification Loop 1): see legacyPlanPricingBaseSchema —
+    // configurable_usage plans expose the same optional Stripe price
+    // ref so invariant 7 has something to compare on variants of
+    // configurable_usage parents.
+    stripePriceId: z3.string().min(1).optional()
+  })
+]);
+var proRationOnRollbackSchema = z3.enum(["NONE", "PRORATE", "CREDIT"]).default("NONE");
+var planVariantSchema = z3.object({
+  /**
+   * Stable variant id — used as the second half of the CompiledPlan
+   * lineage key, so changing it counts as create-new + archive-old.
+   * Lower-case kebab-case to match URL-share-link readability.
+   */
+  id: z3.string().min(1).max(64).regex(/^[a-z0-9_-]+$/, "Variant id must be lowercase alphanumeric with hyphens/underscores"),
+  /** Human-readable label for dashboards / observability. */
+  label: z3.string().max(200).optional(),
+  /**
+   * Rollout percentage (0-100). 0 = paused (variant exists but no new
+   * assignments); 100 = full takeover (effectively a forced graduation
+   * for new subscribers, but legacy subs stay on parent until period end).
+   */
+  rolloutPercent: z3.number().int().min(0).max(100),
+  /**
+   * Seed for the deterministic hash function. Rotating the seed
+   * invalidates existing variant assignments — useful for re-running an
+   * experiment with a fresh cohort.
+   */
+  assignmentSeed: z3.string().min(1).max(100).default("default"),
+  /**
+   * What happens to billing when this variant gets rolled back AND the
+   * subscriber has already been billed for the experimental price:
+   *   - NONE (default): next period bills at parent price; no refund
+   *   - PRORATE: Stripe `proration_behavior=create_prorations` → mid-period credit
+   *   - CREDIT: full credit for the variant-priced charge as customer balance
+   * Out-of-scope: auto-refund. Builders use `billing.refund` if needed.
+   */
+  prorationOnRollback: proRationOnRollbackSchema,
+  // Optional overrides — missing fields inherit from the parent plan.
+  pricing: planPricingSchema.optional(),
+  limits: z3.array(planLimitRuleSchema).max(20).optional(),
+  featureGates: z3.record(z3.string(), z3.boolean()).optional(),
+  overageBehavior: z3.enum(["block", "allow_and_bill"]).optional(),
+  meteredDimensions: z3.array(meteredDimensionSchema).optional()
+});
+var planSpecSchema = z3.object({
+  key: z3.string().min(1).max(64).regex(/^[a-z0-9_-]+$/, "Plan key must be lowercase alphanumeric with hyphens/underscores"),
+  name: z3.string().min(1).max(100),
+  description: z3.string().max(500).optional(),
+  details: z3.array(z3.string().max(200)).max(10).optional(),
+  pricing: planPricingSchema,
+  limits: z3.array(planLimitRuleSchema).max(20).default([]),
+  featureGates: z3.record(z3.string(), z3.boolean()).optional(),
+  overageBehavior: z3.enum(["block", "allow_and_bill"]).default("block"),
+  selfServeEnabled: z3.boolean().default(true),
+  meteredDimensions: z3.array(meteredDimensionSchema).optional(),
+  /**
+   * Phase A0 — multi-stable plan support.
+   *
+   * `legacy: true` marks a plan version that should be kept alive
+   * indefinitely for the existing subscriber cohort, alongside a new
+   * ACTIVE plan in the same lineage. Compiles into `CompiledPlan` with
+   * status `LEGACY_STABLE`. The plan is hidden from the public Pricing
+   * page; new subscribers cannot join. Removing a `legacy: true` plan
+   * from YAML while subs are pinned to it is a compile error (would
+   * orphan the cohort).
+   */
+  legacy: z3.boolean().optional().default(false),
+  /**
+   * Phase A0 — A/B testing variants of this plan. Each variant compiles
+   * into a sibling `CompiledPlan` with status `EXPERIMENTAL` and
+   * `experimentParentId` pointing at this plan's CompiledPlan.
+   *
+   * Constraints (enforced at compile time):
+   *   - Cannot coexist with `legacy: true` on the same plan
+   *   - Variant `id` must be unique within the variants array
+   *   - Variant `pricing.stripePriceId` must differ from parent's
+   */
+  variants: z3.array(planVariantSchema).max(4).optional(),
+  archive: z3.object({
+    at: z3.string().datetime().optional(),
+    transitionTo: z3.string().optional(),
+    strategy: z3.enum(["auto", "explicit", "block"]).default("auto")
+  }).optional()
+});
+var WEBHOOK_SECRET_PLACEHOLDER_PATTERN = /^\$\{[A-Z][A-Z0-9_]{0,127}\}$/;
+var webhookSecretSchema = z3.string().min(3).max(200).refine((value) => WEBHOOK_SECRET_PLACEHOLDER_PATTERN.test(value), {
+  message: "secret must use ${VAR} interpolation syntax (e.g. ${WEBHOOK_SECRET}); raw secrets in YAML are rejected. Define the env var in the per-product secret store and reference it here."
+});
+var webhookRetryPolicySchema = z3.object({
+  maxAttempts: z3.number().int().min(1).max(20).default(5),
+  backoff: z3.enum(["exponential", "fixed"]).default("exponential")
+});
+var webhookEndpointSchema = z3.object({
+  /**
+   * Stable endpoint id — used as the third key of the
+   * `(productId, environmentId, id)` uniqueness tuple. Idempotent upsert
+   * keys on this id; renaming an id is delete + recreate.
+   */
+  id: z3.string().min(1).max(64).regex(/^[a-z0-9_-]+$/, "Webhook endpoint id must be lowercase alphanumeric with hyphens/underscores"),
+  /** Public HTTPS URL the dispatcher POSTs to. */
+  url: z3.string().url("webhooks.endpoints[].url must be a valid URL"),
+  /**
+   * Signing secret. MUST be a `${VAR}` placeholder; raw secrets in YAML
+   * are rejected by invariant 8. The seal pass resolves this against the
+   * per-product secret store at compile time and stamps the resolved
+   * value onto the WebhookEndpoint row.
+   */
+  secret: webhookSecretSchema,
+  /**
+   * Subset of the central event catalog this endpoint subscribes to.
+   * Each value is validated against `webhookEventNameSchema` —
+   * unknown events fail invariant 9.
+   */
+  events: z3.array(webhookEventNameSchema).min(1, "webhooks.endpoints[].events must subscribe to \u2265 1 event"),
+  enabled: z3.boolean().default(true),
+  retryPolicy: webhookRetryPolicySchema.default({
+    maxAttempts: 5,
+    backoff: "exponential"
+  })
+});
+var webhooksBlockSchema = z3.object({
+  endpoints: z3.array(webhookEndpointSchema).max(50).default([])
+});
+var planOverrideSchema = z3.object({
+  pricing: planPricingSchema.optional(),
+  limits: z3.array(planLimitRuleSchema).max(20).optional(),
+  featureGates: z3.record(z3.string(), z3.boolean()).optional(),
+  overageBehavior: z3.enum(["block", "allow_and_bill"]).optional(),
+  selfServeEnabled: z3.boolean().optional(),
+  meteredDimensions: z3.array(meteredDimensionSchema).optional(),
+  legacy: z3.boolean().optional()
+}).strict();
+var webhookEndpointOverrideSchema = z3.object({
+  url: z3.string().url().optional(),
+  secret: webhookSecretSchema.optional(),
+  events: z3.array(webhookEventNameSchema).optional(),
+  enabled: z3.boolean().optional(),
+  retryPolicy: webhookRetryPolicySchema.partial().optional()
+}).strict();
+var environmentOverrideBlockSchema = z3.object({
+  plans: z3.record(z3.string(), planOverrideSchema).optional(),
+  webhooks: z3.object({
+    endpoints: z3.record(z3.string(), webhookEndpointOverrideSchema).optional()
+  }).strict().optional()
+}).strict();
+var environmentsBlockSchema = z3.record(z3.string().min(1).max(64), environmentOverrideBlockSchema);
+var productSpecSchema = z3.object({
+  product: z3.object({
+    name: z3.string().min(1).max(100),
+    displayName: z3.string().max(200).optional(),
+    description: z3.string().max(2e3).optional(),
+    baseUrl: z3.string().url("baseUrl must be a valid URL"),
+    sandboxBaseUrl: z3.string().url("sandboxBaseUrl must be a valid URL").optional(),
+    visibility: z3.enum(["public", "private"]).default("public"),
+    // Branding
+    logoUrl: z3.string().url().optional(),
+    primaryColor: z3.string().regex(/^#[0-9a-fA-F]{6}$/).optional(),
+    // Environment
+    envBranchPrefix: z3.string().max(50).nullable().optional()
+  }),
+  gateway: z3.object({
+    authHeader: z3.string().min(1).max(100).default("x-api-key"),
+    upstreamAuth: z3.object({
+      type: z3.enum(["none", "static_bearer"]),
+      token: z3.string().optional()
+    }).default({ type: "none" })
+  }),
+  metering: z3.object({
+    meters: z3.array(meterDefinitionSchema).min(1).max(10),
+    billOn4xx: z3.boolean().default(false)
+  }),
+  billing: z3.object({
+    strategy: z3.enum(["subscription", "usage_based", "hybrid"]),
+    gracePeriodDays: z3.number().int().nonnegative().default(3)
+  }),
+  plans: z3.array(planSpecSchema).max(4).default([]),
+  /**
+   * Phase B0 — Platform-as-Backend mode. Optional top-level webhook
+   * subscription block. Compiles into `WebhookEndpoint` rows via the
+   * `emit-webhooks` pass (idempotent upsert, soft-delete on absence).
+   *
+   * Once a product has compiled with a `webhooks` block, API mutations
+   * on those endpoints fail with `409 MANAGED_BY_YAML` — see
+   * `core/src/routes/management-webhooks.ts`. Tie-breaker: YAML wins
+   * over API state if an endpoint id appears in both.
+   */
+  webhooks: webhooksBlockSchema.optional(),
+  /**
+   * Phase B0 — Per-environment overrides. Deep-merges onto the base
+   * spec at compile time, scoped by environment id (resolved from the
+   * pushing branch via `branch-environment-resolver.ts`).
+   *
+   * Out-of-scope: overriding `customerAuthStrategy` is not allowed —
+   * that field stays provisioner-controlled.
+   */
+  environments: environmentsBlockSchema.optional()
+});
+var productPhaseSchema = z3.object({
+  product: productSpecSchema.shape.product
+});
+var gatewayPhaseSchema = z3.object({
+  gateway: productSpecSchema.shape.gateway
+});
+var meteringPhaseSchema = z3.object({
+  metering: productSpecSchema.shape.metering
+});
+var plansPhaseSchema = z3.object({
+  plans: productSpecSchema.shape.plans
+});
+
+// src/commands/validate.ts
+var CI = !!process.env.CI || !!process.env.GITHUB_ACTIONS;
+function readMainBranchProductName() {
+  for (const branch of ["main", "master"]) {
+    try {
+      const yaml = execSync(`git show ${branch}:product.yaml 2>/dev/null`, {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+      const spec = YAML.parse(yaml);
+      const product = spec.product;
+      return product?.name ?? null;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+function validateProductYaml(spec) {
+  const rawErrors = validateBillingPolicyGuards(spec);
+  if (rawErrors.length > 0) {
+    return { valid: false, errors: rawErrors, warnings: [] };
+  }
+  const result = productSpecSchema.safeParse(spec);
+  if (!result.success) {
+    return {
+      valid: false,
+      errors: result.error.issues.map((issue) => formatIssue(issue, spec)),
+      warnings: []
+    };
+  }
+  const warnings = deriveWarnings(result.data);
+  const dupeKeys = findDuplicatePlanKeys(result.data);
+  if (dupeKeys.length > 0) {
+    return {
+      valid: false,
+      errors: [`Duplicate plan keys: ${dupeKeys.join(", ")}`],
+      warnings
+    };
+  }
+  const duplicatePrices = findDuplicatePaidPrices(spec);
+  if (duplicatePrices.length > 0) {
+    return {
+      valid: false,
+      errors: duplicatePrices.map(
+        (price) => `Duplicate paid plan price: ${price}`
+      ),
+      warnings
+    };
+  }
+  return { valid: true, errors: [], warnings };
+}
+function validateBillingPolicyGuards(spec) {
+  const errors = [];
+  if (!isRecord(spec)) return errors;
+  if ("usagePricing" in spec) {
+    errors.push(
+      "usagePricing is not supported; define usage.meters.*.rating instead"
+    );
+  }
+  const billing = isRecord(spec.billing) ? spec.billing : void 0;
+  const policy = isRecord(billing?.subscriberChangePolicy) ? billing.subscriberChangePolicy : void 0;
+  const when = isRecord(policy?.when) ? policy.when : {};
+  if (isImmediateAction(when.price_increase) && policy?.allowImmediatePriceIncrease !== true) {
+    errors.push(
+      "billing.subscriberChangePolicy.when.price_increase cannot switch immediately without allowImmediatePriceIncrease: true"
+    );
+  }
+  for (const key of [
+    "feature_removed",
+    "limit_reduced",
+    "credit_reduced"
+  ]) {
+    if (isImmediateAction(when[key]) && policy?.allowImmediateEntitlementReduction !== true) {
+      errors.push(
+        `billing.subscriberChangePolicy.when.${key} cannot switch immediately without allowImmediateEntitlementReduction: true`
+      );
+    }
+  }
+  const plans = Array.isArray(spec.plans) ? spec.plans : [];
+  const freePlans = plans.filter(
+    (plan) => isRecord(plan) && plan.free === true
+  );
+  if (freePlans.length > 1) {
+    errors.push("Only one free plan is allowed per product");
+  }
+  for (const plan of freePlans) {
+    if (!isRecord(plan)) continue;
+    const key = typeof plan.key === "string" ? plan.key : "free";
+    if (effectivePlanPrice(plan) > 0) {
+      errors.push(`Plan "${key}": free plan must have zero price`);
+    }
+    if (!hasHardEnforcedLimit(plan)) {
+      errors.push(
+        `Plan "${key}": free plan must define at least one enforced hard limit`
+      );
+    }
+  }
+  return errors;
+}
+function isImmediateAction(action) {
+  return action === "switch_immediately" || action === "switch_immediately_prorate";
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function effectivePlanPrice(plan) {
+  const compactPrice = isRecord(plan.price) ? plan.price : void 0;
+  const pricing = isRecord(plan.pricing) ? plan.pricing : void 0;
+  const compactMonthly = compactPrice?.monthly;
+  if (typeof compactMonthly === "number") return compactMonthly;
+  const legacyMonthly = pricing?.monthlyPriceCents;
+  return typeof legacyMonthly === "number" ? legacyMonthly : 0;
+}
+function hasHardEnforcedLimit(plan) {
+  const limits = Array.isArray(plan.limits) ? plan.limits : [];
+  return limits.some((limit) => {
+    if (!isRecord(limit)) return false;
+    const enforcement = limit.enforcement;
+    const hard = limit.hard;
+    return enforcement === "enforce" || hard === true;
+  });
+}
+function findDuplicatePaidPrices(spec) {
+  if (!isRecord(spec) || !Array.isArray(spec.plans)) return [];
+  const seen = /* @__PURE__ */ new Map();
+  const dupes = /* @__PURE__ */ new Set();
+  for (const plan of spec.plans) {
+    if (!isRecord(plan) || plan.free === true) continue;
+    const amount = effectivePlanPrice(plan);
+    if (amount <= 0) continue;
+    const pricing = isRecord(plan.pricing) ? plan.pricing : {};
+    const price = isRecord(plan.price) ? plan.price : {};
+    const currency = typeof price.currency === "string" ? price.currency : typeof pricing.currency === "string" ? pricing.currency : "usd";
+    const interval = "monthly" in price ? "month" : typeof pricing.billingInterval === "string" ? pricing.billingInterval : "month";
+    const key = `${currency}:${interval}:${amount}`;
+    if (seen.has(key)) dupes.add(key);
+    else seen.set(key, typeof plan.key === "string" ? plan.key : key);
+  }
+  return [...dupes];
+}
+function formatIssue(issue, spec) {
+  const path = issue.path;
+  if (path.length >= 2 && path[0] === "plans" && typeof path[1] === "number") {
+    const plans = spec?.plans ?? [];
+    const plan = plans[path[1]];
+    const planLabel = plan?.key ?? plan?.name ?? `#${path[1]}`;
+    const fieldPath = path.slice(2).join(".");
+    if (fieldPath) {
+      return `Plan "${planLabel}": ${fieldPath} \u2014 ${issue.message}`;
+    }
+    return `Plan "${planLabel}": ${issue.message}`;
+  }
+  const dotted = path.length > 0 ? path.join(".") : "(root)";
+  return `${dotted}: ${issue.message}`;
+}
+function deriveWarnings(parsed) {
+  const warnings = [];
+  if (parsed.plans.length === 0) {
+    warnings.push("No plans declared \u2014 product cannot accept signups yet");
+  } else {
+    const hasFree = parsed.plans.some((plan) => {
+      const monthly = "monthlyPriceCents" in plan.pricing ? plan.pricing.monthlyPriceCents : void 0;
+      return monthly === 0;
+    });
+    if (!hasFree) {
+      warnings.push(
+        "No free plan \u2014 consider adding one for developer adoption"
+      );
+    }
+  }
+  if (!parsed.product.displayName || parsed.product.displayName === parsed.product.name) {
+    warnings.push(
+      "product.displayName not set \u2014 using product.name on the pricing page"
+    );
+  }
+  return warnings;
+}
+function findDuplicatePlanKeys(parsed) {
+  const seen = /* @__PURE__ */ new Set();
+  const dupes = /* @__PURE__ */ new Set();
+  for (const plan of parsed.plans) {
+    if (seen.has(plan.key)) {
+      dupes.add(plan.key);
+    } else {
+      seen.add(plan.key);
+    }
+  }
+  return [...dupes];
+}
+function loadProductYaml(filePath) {
+  if (!existsSync2(filePath)) {
+    return { ok: false, reason: "missing", message: filePath };
+  }
+  try {
+    const content = readFileSync2(filePath, "utf-8");
+    return { ok: true, spec: YAML.parse(content) };
+  } catch (err) {
+    return {
+      ok: false,
+      reason: "parse",
+      message: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+function reportValidationResult(result) {
+  if (CI) {
+    for (const err of result.errors) {
+      console.log(`::error file=product.yaml::${err}`);
+    }
+    for (const w of result.warnings) {
+      console.log(`::warning file=product.yaml::${w}`);
+    }
+  }
+  if (result.errors.length === 0) {
+    success("product.yaml is valid");
+    for (const w of result.warnings) {
+      warn(w);
+    }
+    return;
+  }
+  error(`product.yaml has ${result.errors.length} error(s):
+`);
+  for (const err of result.errors) {
+    console.log(`  \u2022 ${err}`);
+  }
+  if (result.warnings.length > 0) {
+    console.log();
+    for (const w of result.warnings) {
+      warn(w);
+    }
+  }
+  process.exitCode = 1;
+}
+function registerValidateCommand(program2) {
+  program2.command("validate [file]").description("Validate a local product.yaml file").action((file) => {
+    const filePath = resolve(file ?? "product.yaml");
+    const loaded = loadProductYaml(filePath);
+    if (!loaded.ok) {
+      if (loaded.reason === "missing") {
+        if (CI)
+          console.log(
+            `::error file=product.yaml::File not found: ${loaded.message}`
+          );
+        error(`File not found: ${loaded.message}`);
+      } else {
+        if (CI)
+          console.log(
+            `::error file=product.yaml::YAML parse error: ${loaded.message}`
+          );
+        error(`Failed to parse YAML: ${loaded.message}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    const result = validateProductYaml(loaded.spec);
+    const currentName = loaded.spec?.product?.name;
+    if (currentName) {
+      const mainName = readMainBranchProductName();
+      if (mainName && mainName !== currentName) {
+        result.errors.push(
+          `product.name "${currentName}" differs from main branch "${mainName}" \u2014 product name must not change`
+        );
+        result.valid = false;
+      }
+    }
+    reportValidationResult(result);
+  });
+}
+
+// src/commands/apply.ts
+import { execSync as execSync2 } from "node:child_process";
+import { readFileSync as readFileSync3, existsSync as existsSync3 } from "node:fs";
+import { resolve as resolve2 } from "node:path";
+import YAML2 from "yaml";
+var CI2 = !!process.env.CI || !!process.env.GITHUB_ACTIONS;
+function detectBranch(explicit) {
+  if (explicit) return explicit;
+  const ghHead = process.env.GITHUB_HEAD_REF;
+  if (ghHead) return ghHead;
+  const ghRef = process.env.GITHUB_REF_NAME;
+  if (ghRef) return ghRef;
+  try {
+    const local = execSync2("git rev-parse --abbrev-ref HEAD", {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+    return local && local !== "HEAD" ? local : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function readSlugFromProductYaml() {
+  const yamlPath = resolve2("product.yaml");
+  if (!existsSync3(yamlPath)) return null;
+  try {
+    const spec = YAML2.parse(readFileSync3(yamlPath, "utf-8"));
+    const product = spec.product;
+    return product?.name ?? null;
+  } catch {
+    return null;
+  }
+}
+function validateLocalProductYamlBeforeRemoteCompile() {
+  const filePath = resolve2("product.yaml");
+  if (!existsSync3(filePath)) return true;
+  const loaded = loadProductYaml(filePath);
+  if (!loaded.ok) {
+    const message = loaded.reason === "parse" ? `Local product.yaml failed to parse; remote compile was not started.
+${loaded.message}` : `Local product.yaml could not be read; remote compile was not started.
+${loaded.message}`;
+    if (CI2) {
+      console.log(`::error file=product.yaml::${message}`);
+    }
+    error(message);
+    process.exitCode = 1;
+    return false;
+  }
+  const result = validateProductYaml(loaded.spec);
+  if (!result.valid) {
+    if (CI2) {
+      for (const err of result.errors) {
+        console.log(`::error file=product.yaml::${err}`);
+      }
+      for (const warning of result.warnings) {
+        console.log(`::warning file=product.yaml::${warning}`);
+      }
+    }
+    error(
+      "Local product.yaml failed validation; remote compile was not started.\n"
+    );
+    for (const err of result.errors) {
+      console.log(`  \u2022 ${err}`);
+    }
+    if (result.warnings.length > 0) {
+      console.log();
+      for (const warning of result.warnings) {
+        warn(warning);
+      }
+    }
+    process.exitCode = 1;
+    return false;
+  }
+  success("Local product.yaml passed validation");
+  for (const warning of result.warnings) {
+    warn(warning);
+  }
+  info(
+    "Remote compile checks the pushed branch state; unpushed local edits are not included."
+  );
+  return true;
+}
+function shouldValidateLocalProductYaml(productArg) {
+  const filePath = resolve2("product.yaml");
+  if (!existsSync3(filePath)) return false;
+  if (!productArg) return true;
+  const localSlug = readSlugFromProductYaml();
+  return typeof localSlug === "string" && localSlug.toLowerCase() === productArg.toLowerCase();
+}
+async function resolveProductId(client, arg) {
+  const slug = arg ?? readSlugFromProductYaml();
+  if (!slug) return null;
+  if (slug.length === 36 && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(slug)) {
+    return slug;
+  }
+  try {
+    const products = client.isMakerToken() ? await client.managementListProducts() : await client.listProducts();
+    const match = products.find(
+      (p) => p.name === slug || p.name.toLowerCase() === slug.toLowerCase()
+    );
+    return match?.id ?? null;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`Warning: Failed to resolve product slug: ${msg}
+`);
+    return null;
+  }
+}
+function formatDiag(d) {
+  const prefix = d.code ? `[${d.code}] ` : "";
+  const planLabel = d.planKey ? `(plan: ${d.planKey}) ` : "";
+  return `${prefix}${planLabel}${d.message}`;
+}
+function handleResult(result) {
+  if (CI2) {
+    for (const err of result.errors ?? []) {
+      console.log(`::error file=product.yaml::${formatDiag(err)}`);
+    }
+    for (const w of result.warnings ?? []) {
+      console.log(`::warning file=product.yaml::${formatDiag(w)}`);
+    }
+  }
+  if (result.success) {
+    success("Remote compile passed");
+    if (result.warnings?.length) {
+      console.log();
+      for (const w of result.warnings) {
+        warn(formatDiag(w));
+      }
+    }
+  } else {
+    error("Remote compile failed\n");
+    for (const err of result.errors ?? []) {
+      console.log(`  \u2022 ${formatDiag(err)}`);
+    }
+    process.exitCode = 1;
+  }
+}
+function registerApplyCommand(program2, getClient2) {
+  program2.command("apply [product]").description(
+    "Validate the current repo's product.yaml before remote compile when applying that repo's product, then run the server-side compiler against the pushed branch state for this product. Unpushed local edits are not included. Pass a product slug, or run inside a product repo to auto-detect from product.yaml. Automatically scopes to the current git branch so env branches compile against their own plans."
+  ).option(
+    "--branch <branch>",
+    "Override the branch used for env-scoped compilation (default: auto-detected)"
+  ).action(
+    async (productArg, opts) => {
+      const client = getClient2();
+      const branch = detectBranch(opts.branch);
+      if (shouldValidateLocalProductYaml(productArg) && !validateLocalProductYamlBeforeRemoteCompile()) {
+        return;
+      }
+      if (branch && CI2) {
+        console.log(`::notice::Compiling against branch '${branch}'`);
+      }
+      if (client.isMakerToken() && !productArg) {
+        try {
+          const result = await client.managementCompileSelf({ branch });
+          handleResult(result);
+          return;
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : "Compilation check failed";
+          if (CI2) console.log(`::error::${msg}`);
+          error(msg);
+          process.exitCode = 1;
+          return;
+        }
+      }
+      const productId = await resolveProductId(client, productArg);
+      if (!productId) {
+        const hint = productArg ? `Product "${productArg}" not found. Check the name and try again.` : "No product specified and no product.yaml found.\n  Run from inside a product repo, or pass the slug: farthershore apply my-api";
+        error(hint);
+        process.exitCode = 1;
+        return;
+      }
+      try {
+        const result = client.isMakerToken() ? await client.managementCompile(productId, { branch }) : await client.compileProduct(productId, { branch });
+        handleResult(result);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "Compilation check failed";
+        if (CI2) console.log(`::error::${msg}`);
+        error(msg);
+        process.exitCode = 1;
+      }
+    }
+  );
+}
+
+// src/remediation.ts
+var REMEDIATIONS = {
+  // --- Auth ---
+  UNAUTHORIZED: "Token is invalid or revoked. Run `farthershore set-key` to update it.",
+  FORBIDDEN: "Your token doesn't have access to this resource. Check the org / product scope.",
+  INVALID_ACCESS_KEY: "Token format is wrong. Generate a new one at https://farthershore.com/settings/tokens.",
+  MAKER_TOKEN_REVOKED: "This maker token was revoked. Mint a new one in the product settings.",
+  MAKER_TOKEN_NO_PRODUCT: "Maker token is not bound to a product. Re-create it from the product page.",
+  // --- Stripe ---
+  STRIPE_NOT_CONFIGURED: "Stripe isn't connected on this product. Connect it in the dashboard before running billing operations.",
+  STRIPE_BALANCE_OUTSTANDING: "Customer has an outstanding balance. Resolve the invoice in Stripe before retrying.",
+  CHECKOUT_SESSION_FAILED: "Stripe rejected the checkout request. Check that the plan exists and Stripe credentials are valid.",
+  // --- Product / config ---
+  PRODUCT_NOT_FOUND: "Check the product slug. Run `farthershore` (no args) for a list of products you can see.",
+  PRODUCT_REPO_NOT_LINKED: "Link a GitHub repo to this product before running `apply`.",
+  PRODUCT_YAML_NOT_FOUND: "No product.yaml on the target branch. Push a config file before running `apply`.",
+  YAML_PARSE_ERROR: "product.yaml is not valid YAML. Run `farthershore validate` locally to see the parse error.",
+  GITHUB_NOT_CONNECTED: "Connect GitHub on the org page before running `init` (it provisions the repo).",
+  BRANCH_NO_MATCHING_ENV: "The current branch isn't mapped to an environment. Add a branch rule in product settings or pass --branch explicitly.",
+  // --- Plans / pricing ---
+  PLAN_NOT_FOUND: "Plan key doesn't exist on this product. Check `plans:` in product.yaml.",
+  PLAN_HAS_ACTIVE_SUBSCRIPTIONS: "Plan has active subscribers and can't be deleted. Migrate them to another plan first.",
+  PLAN_SLUG_CONFLICT: "Another plan already uses this key. Pick a unique key in product.yaml.",
+  SLUG_CONFLICT: "This product slug is taken. Pick a different name.",
+  SLUG_BLOCKED: "This slug is reserved or blocked. Pick a different name.",
+  SLUG_RESERVED: "This slug is reserved by Farther Shore. Pick a different name.",
+  SLUG_INVALID_FORMAT: "Slug must be lowercase letters, digits, and hyphens (no leading/trailing hyphen).",
+  // --- Generic ---
+  RATE_LIMIT_EXCEEDED: "You've hit the rate limit. Wait a moment and retry.",
+  VALIDATION_ERROR: "Request is malformed. The `details` field has the field-level errors.",
+  CONFLICT: "The resource is in a state that conflicts with the request. Inspect `details` to learn more."
+};
+function getRemediation(code) {
+  if (!code) return void 0;
+  return REMEDIATIONS[code];
+}
+
+// src/index.ts
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(
+  await readFile(join2(__dirname, "..", "package.json"), "utf-8")
+);
+var program = new Command();
+program.name("farthershore").description("FartherShore CLI \u2014 create and manage API products").version(pkg.version).option("--token <token>", "Override auth token").option("--api-url <url>", "Override API base URL").option("--format <format>", "Output format: table, json");
+function getClient() {
+  const config = loadConfig();
+  const globalOpts = program.opts();
+  const token = resolveToken(globalOpts.token);
+  const apiUrl = globalOpts.apiUrl ?? process.env.FARTHERSHORE_API_URL ?? config.apiUrl;
+  return createClient({ apiUrl, token });
 }
-// Register commands
 registerAuthCommands(program);
 registerInitCommand(program, getClient);
 registerValidateCommand(program);
 registerApplyCommand(program, getClient);
-// Global error handler
 program.exitOverride();
+function reportCliError(err) {
+  const codeSuffix = err.code ? ` [${err.code}]` : "";
+  process.stderr.write(`Error${codeSuffix}: ${err.message}
+`);
+  const hint = getRemediation(err.code);
+  if (hint) {
+    process.stderr.write(`Hint: ${hint}
+`);
+  }
+}
 async function main() {
-    try {
-        await program.parseAsync(process.argv);
-    }
-    catch (err) {
-        if (err instanceof CliError) {
-            process.stderr.write(`Error: ${err.message}\n`);
-            process.exitCode = 1;
-        }
-        else if (err instanceof Error) {
-            const code = err.code;
-            if (code === "commander.helpDisplayed" || code === "commander.version") {
-                // Not an error — normal exit
-            }
-            else if (err.message !== "(outputHelp)") {
-                process.stderr.write(`Error: ${err.message}\n`);
-                process.exitCode = 1;
-            }
-        }
+  try {
+    await program.parseAsync(process.argv);
+  } catch (err) {
+    if (err instanceof CliError) {
+      reportCliError(err);
+      process.exitCode = 1;
+    } else if (err instanceof Error) {
+      const code = err.code;
+      if (code === "commander.helpDisplayed" || code === "commander.version") {
+      } else if (err.message !== "(outputHelp)") {
+        process.stderr.write(`Error: ${err.message}
+`);
+        process.exitCode = 1;
+      }
     }
+  }
 }
-main();
+void main();