@farthershore/cli 0.3.5 → 0.3.6

package/README.md

@@ -45,8 +45,7 @@ Options:
 
 - `--base-url <url>` — Backend API base URL
 - `--description <text>` — Product description
-- `--display-name <name>` — Display name for the portal
-- `--billing <strategy>` — `subscription` (default), `usage_based`, or `hybrid`
+- `--display-name <name>` — Display name for the product portal
 
 The created repo contains:
 
@@ -57,7 +56,7 @@ The created repo contains:
 
 ### `farthershore validate [file]`
 
-Validate a local `product.yaml` file without making any API calls. Checks structure, required fields, and strategy/model alignment.
+Validate a local `product.yaml` file without making any API calls. Checks structure, required fields, and launch constraints for env-scoped plans and meters.
 
 ```bash
 # Validate product.yaml in current directory
@@ -69,7 +68,7 @@ farthershore validate path/to/product.yaml
 
 ### `farthershore apply [product]`
 
-Run the server-side compiler against the current product configuration. Returns compilation errors and warnings. Exits with code 1 on failure — suitable for CI checks before merging.
+Validate the current repo's `product.yaml` first when applying that repo's product, then run the server-side compiler against the pushed branch state for the product. Unpushed local edits are not part of the remote compile. Returns compilation errors and warnings. Exits with code 1 on failure — suitable for CI checks before merging.
 
 ```bash
 # Inside a product repo (auto-detects from product.yaml)
@@ -137,3 +136,30 @@ git add -A && git commit -m "Configure product" && git push
 | ---------------------- | ------------------------------------------------------- |
 | `FARTHERSHORE_TOKEN`   | API token (overrides stored credentials)                |
 | `FARTHERSHORE_API_URL` | API base URL (default: `https://core.farthershore.com`) |
+
+## Errors and exit codes
+
+The CLI exits `0` on success and `1` on any failure (including
+`commander`-level argument errors). When the API returns a 4XX/5XX, the
+CLI prints the canonical error code in brackets and a one-line
+remediation hint when one is registered:
+
+```text
+Error [STRIPE_NOT_CONFIGURED]: connect Stripe before running billing operations
+Hint: Stripe isn't connected on this product. Connect it in the dashboard before running billing operations.
+```
+
+The bracketed code is stable across releases — quote it in support
+threads.
+
+`farthershore whoami --format json` emits a stable JSON shape suitable
+for CI scripts. On the not-authenticated path it emits
+`{ "authenticated": false }` with exit code `1`.
+
+## CI / agent usage
+
+The CLI is non-interactive whenever a token is available via the
+`--token` flag or `FARTHERSHORE_TOKEN` env var — `set-key` only prompts
+when stdin is a TTY and no token argument was passed, so it's safe to
+script. `validate` and `apply` emit GitHub Actions-formatted annotations
+when run under `CI` / `GITHUB_ACTIONS`.

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { Product, InitProductResponse } from "./types.js";
+import type { Product, InitProductResponse, CompileDiagnostic } from "./types.js";
 export declare function createClient(opts: {
     apiUrl: string;
     token: string;
@@ -28,41 +28,29 @@ export declare function createClient(opts: {
         baseUrl?: string;
         description?: string;
         displayName?: string;
-        billingStrategy?: string;
     }) => Promise<InitProductResponse>;
-    compileProduct: (productId: string) => Promise<{
+    compileProduct: (productId: string, opts?: {
+        branch?: string;
+    }) => Promise<{
         success: boolean;
-        errors?: Array<{
-            code?: string;
-            message: string;
-        }>;
-        warnings?: Array<{
-            code?: string;
-            message: string;
-        }>;
+        errors?: CompileDiagnostic[];
+        warnings?: CompileDiagnostic[];
     }>;
-    managementCompileSelf: () => Promise<{
+    managementCompileSelf: (opts?: {
+        branch?: string;
+    }) => Promise<{
         success: boolean;
         productId: string;
-        errors?: Array<{
-            code?: string;
-            message: string;
-        }>;
-        warnings?: Array<{
-            code?: string;
-            message: string;
-        }>;
+        branch?: string | null;
+        errors?: CompileDiagnostic[];
+        warnings?: CompileDiagnostic[];
     }>;
-    managementCompile: (productId: string) => Promise<{
+    managementCompile: (productId: string, opts?: {
+        branch?: string;
+    }) => Promise<{
         success: boolean;
-        errors?: Array<{
-            code?: string;
-            message: string;
-        }>;
-        warnings?: Array<{
-            code?: string;
-            message: string;
-        }>;
+        errors?: CompileDiagnostic[];
+        warnings?: CompileDiagnostic[];
     }>;
     managementListProducts: () => Promise<Product[]>;
     isMakerToken: () => boolean;

package/dist/client.js

@@ -11,8 +11,24 @@ export function createClient(opts) {
             body: body ? JSON.stringify(body) : undefined,
         });
         if (!res.ok) {
-            const err = await res.json().catch(() => ({ error: res.statusText }));
-            throw new CliError(err.error ?? `API error: ${res.status}`, res.status);
+            // Try the canonical Wave-4 envelope first; fall back to a string
+            // body or the bare statusText so the error path is robust to old
+            // server builds and HTML/text responses (e.g. Cloudflare 502s).
+            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") {
+                // Legacy { error: "..." } shape.
+                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 undefined;
@@ -25,11 +41,12 @@ export function createClient(opts) {
         listProducts: () => request("GET", "/products"),
         initProduct: (data) => request("POST", "/products/init", data),
         // --- Compile ---
-        compileProduct: (productId) => request("POST", `/products/${productId}/compile`),
+        compileProduct: (productId, opts) => request("POST", `/products/${productId}/compile`, opts?.branch ? { branch: opts.branch } : undefined),
         // --- Management (maker token) ---
         // Compile the product associated with the token — no product ID needed.
-        managementCompileSelf: () => request("POST", "/management/compile"),
-        managementCompile: (productId) => request("POST", `/management/products/${productId}/compile`),
+        // Pass `branch` to scope compilation to an env branch's plans.
+        managementCompileSelf: (opts) => request("POST", "/management/compile", opts?.branch ? { branch: opts.branch } : undefined),
+        managementCompile: (productId, opts) => request("POST", `/management/products/${productId}/compile`, opts?.branch ? { branch: opts.branch } : undefined),
         managementListProducts: () => request("GET", "/management/products"),
         isMakerToken: () => opts.token.startsWith("mk_"),
     };

package/dist/commands/apply.js

@@ -1,8 +1,38 @@
+import { execSync } from "node:child_process";
 import { readFileSync, existsSync } from "node:fs";
 import { resolve } from "node:path";
 import YAML from "yaml";
 import * as output from "../output.js";
+import { loadProductYaml, validateProductYaml } from "./validate.js";
 const CI = !!process.env.CI || !!process.env.GITHUB_ACTIONS;
+/**
+ * Detect the git branch the compiler should scope to. Order of preference:
+ *   1. --branch CLI flag (explicit override)
+ *   2. GITHUB_HEAD_REF — pull_request source branch (the branch being proposed)
+ *   3. GITHUB_REF_NAME — push event branch
+ *   4. `git rev-parse --abbrev-ref HEAD` — local dev
+ * Returns undefined when nothing is detectable.
+ */
+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 = execSync("git rev-parse --abbrev-ref HEAD", {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        return local && local !== "HEAD" ? local : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Read the product name/slug from product.yaml in the current directory.
  */
@@ -19,6 +49,62 @@ function readSlugFromProductYaml() {
         return null;
     }
 }
+function validateLocalProductYamlBeforeRemoteCompile() {
+    const filePath = resolve("product.yaml");
+    if (!existsSync(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.\n${loaded.message}`
+            : `Local product.yaml could not be read; remote compile was not started.\n${loaded.message}`;
+        if (CI) {
+            console.log(`::error file=product.yaml::${message}`);
+        }
+        output.error(message);
+        process.exitCode = 1;
+        return false;
+    }
+    const result = validateProductYaml(loaded.spec);
+    if (!result.valid) {
+        if (CI) {
+            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}`);
+            }
+        }
+        output.error("Local product.yaml failed validation; remote compile was not started.\n");
+        for (const err of result.errors) {
+            console.log(`  • ${err}`);
+        }
+        if (result.warnings.length > 0) {
+            console.log();
+            for (const warning of result.warnings) {
+                output.warn(warning);
+            }
+        }
+        process.exitCode = 1;
+        return false;
+    }
+    output.success("Local product.yaml passed validation");
+    for (const warning of result.warnings) {
+        output.warn(warning);
+    }
+    output.info("Remote compile checks the pushed branch state; unpushed local edits are not included.");
+    return true;
+}
+function shouldValidateLocalProductYaml(productArg) {
+    const filePath = resolve("product.yaml");
+    if (!existsSync(filePath))
+        return false;
+    if (!productArg)
+        return true;
+    const localSlug = readSlugFromProductYaml();
+    return (typeof localSlug === "string" &&
+        localSlug.toLowerCase() === productArg.toLowerCase());
+}
 /**
  * Resolve a product identifier to an API product ID.
  * If no arg, reads product.name from product.yaml in the current directory.
@@ -48,29 +134,37 @@ async function resolveProductId(client, arg) {
         return null;
     }
 }
+// Render a diagnostic with an optional plan-key prefix so users can see which
+// plan an error belongs to when the compiler scopes it. `compiledPlanId`
+// itself is an internal pointer — `planKey` is the human-readable label.
+function formatDiag(d) {
+    const prefix = d.code ? `[${d.code}] ` : "";
+    const planLabel = d.planKey ? `(plan: ${d.planKey}) ` : "";
+    return `${prefix}${planLabel}${d.message}`;
+}
 function handleResult(result) {
     // GitHub Actions annotations
     if (CI) {
         for (const err of result.errors ?? []) {
-            console.log(`::error file=product.yaml::${err.code ? `[${err.code}] ` : ""}${err.message}`);
+            console.log(`::error file=product.yaml::${formatDiag(err)}`);
         }
         for (const w of result.warnings ?? []) {
-            console.log(`::warning file=product.yaml::${w.code ? `[${w.code}] ` : ""}${w.message}`);
+            console.log(`::warning file=product.yaml::${formatDiag(w)}`);
         }
     }
     if (result.success) {
-        output.success("Compilation passed");
+        output.success("Remote compile passed");
         if (result.warnings?.length) {
             console.log();
             for (const w of result.warnings) {
-                output.warn(`${w.code ? `[${w.code}] ` : ""}${w.message}`);
+                output.warn(formatDiag(w));
             }
         }
     }
     else {
-        output.error("Compilation failed\n");
+        output.error("Remote compile failed\n");
         for (const err of result.errors ?? []) {
-            console.log(`  • ${err.code ? `[${err.code}] ` : ""}${err.message}`);
+            console.log(`  • ${formatDiag(err)}`);
         }
         process.exitCode = 1;
     }
@@ -78,16 +172,26 @@ function handleResult(result) {
 export function registerApplyCommand(program, getClient) {
     program
         .command("apply [product]")
-        .description("Run the server-side compiler to check if the current config is valid. " +
-        "Pass a product slug, or run inside a product repo to auto-detect from product.yaml.")
-        .action(async (productArg) => {
+        .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 = getClient();
+        const branch = detectBranch(opts.branch);
+        if (shouldValidateLocalProductYaml(productArg) &&
+            !validateLocalProductYamlBeforeRemoteCompile()) {
+            return;
+        }
+        if (branch && CI) {
+            console.log(`::notice::Compiling against branch '${branch}'`);
+        }
         // Fast path for CI: product-scoped maker token with no argument.
         // Server auto-resolves product from the token — no product.yaml,
         // no slug lookup, single API call.
         if (client.isMakerToken() && !productArg) {
             try {
-                const result = await client.managementCompileSelf();
+                const result = await client.managementCompileSelf({ branch });
                 handleResult(result);
                 return;
             }
@@ -112,8 +216,8 @@ export function registerApplyCommand(program, getClient) {
         }
         try {
             const result = client.isMakerToken()
-                ? await client.managementCompile(productId)
-                : await client.compileProduct(productId);
+                ? await client.managementCompile(productId, { branch })
+                : await client.compileProduct(productId, { branch });
             handleResult(result);
         }
         catch (err) {

package/dist/commands/init.js

@@ -6,7 +6,6 @@ export function registerInitCommand(program, getClient) {
         .option("--base-url <url>", "Backend API base URL")
         .option("--description <desc>", "Product description")
         .option("--display-name <name>", "Display name")
-        .option("--billing <strategy>", "Billing strategy: subscription|usage_based|hybrid", "subscription")
         .action(async (name, opts) => {
         const client = getClient();
         const result = await client.initProduct({
@@ -14,9 +13,12 @@ export function registerInitCommand(program, getClient) {
             baseUrl: opts.baseUrl,
             description: opts.description,
             displayName: opts.displayName,
-            billingStrategy: opts.billing,
         });
-        const format = output.outputFormat(program.opts().format);
+        // `program.opts()` is typed `OptionValues` (string-indexed any).
+        // Narrow at the boundary so `outputFormat`'s `string | undefined`
+        // parameter type is satisfied without an unsafe-arg lint.
+        const formatOpt = program.opts().format;
+        const format = output.outputFormat(formatOpt);
         if (format === "json") {
             console.log(output.json(result));
             return;

package/dist/commands/login.js

@@ -59,14 +59,34 @@ export function registerAuthCommands(program) {
         .description("Show current authentication context")
         .action(async () => {
         const config = loadConfig();
+        const formatOpt = program.opts().format;
+        const format = output.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") {
+                // Machine-readable shape — stable contract for CI scripts
+                // ("am I logged in?"). Don't include the token itself.
+                console.log(output.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;
+            }
             output.heading("Current Context");
             console.log(`  Organization: ${ctx.activeOrganization.name ?? ctx.activeOrganization.id}`);
             console.log(`  API URL:      ${config.apiUrl}`);
-            if (process.env.FARTHERSHORE_TOKEN) {
+            if (authSource === "env:FARTHERSHORE_TOKEN") {
                 output.info("  Auth: FARTHERSHORE_TOKEN env var");
             }
             else {
@@ -74,7 +94,12 @@ export function registerAuthCommands(program) {
             }
         }
         catch {
-            output.error("Not authenticated. Run `farthershore set-key` or set FARTHERSHORE_TOKEN.");
+            if (format === "json") {
+                console.log(output.json({ authenticated: false }));
+            }
+            else {
+                output.error("Not authenticated. Run `farthershore set-key` or set FARTHERSHORE_TOKEN.");
+            }
             process.exitCode = 1;
         }
     });

package/dist/commands/validate.d.ts

@@ -1,2 +1,28 @@
 import { Command } from "commander";
+/**
+ * Validate a parsed YAML object against the canonical Zod schema.
+ *
+ * Errors are returned in the same `Plan "key": message` shape the previous
+ * hand-rolled checks produced, so existing CI output stays grep-friendly.
+ * Warnings cover product-quality nudges (no free plan, missing display name)
+ * that don't fail the schema parse but are worth flagging.
+ */
+export declare function validateProductYaml(spec: unknown): {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+};
+/**
+ * Read + parse a product.yaml file. Returns either the parsed spec or
+ * a structured error result. Extracted from the validate command so
+ * the action handler stays under the cognitive-complexity threshold.
+ */
+export declare function loadProductYaml(filePath: string): {
+    ok: true;
+    spec: unknown;
+} | {
+    ok: false;
+    reason: "missing" | "parse";
+    message: string;
+};
 export declare function registerValidateCommand(program: Command): void;

package/dist/commands/validate.js

@@ -2,6 +2,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { resolve } from "node:path";
 import YAML from "yaml";
+import { productSpecSchema, } from "@farther-shore/shared-types/plans";
 import * as output from "../output.js";
 const CI = !!process.env.CI || !!process.env.GITHUB_ACTIONS;
 /**
@@ -25,166 +26,181 @@ function readMainBranchProductName() {
     }
     return null;
 }
-// Inline a lightweight validation since we can't import the core schema directly.
-// Checks structure, required fields, and strategy/model alignment.
-function validateProductYaml(spec) {
-    const errors = [];
+/**
+ * Validate a parsed YAML object against the canonical Zod schema.
+ *
+ * Errors are returned in the same `Plan "key": message` shape the previous
+ * hand-rolled checks produced, so existing CI output stays grep-friendly.
+ * Warnings cover product-quality nudges (no free plan, missing display name)
+ * that don't fail the schema parse but are worth flagging.
+ */
+export function validateProductYaml(spec) {
+    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);
+    // Schema doesn't enforce duplicate plan keys (it would conflict with the
+    // discriminated-union design). Detect here as a separate check so the CLI
+    // surfaces this footgun before the server rejects the apply.
+    const dupeKeys = findDuplicatePlanKeys(result.data);
+    if (dupeKeys.length > 0) {
+        return {
+            valid: false,
+            errors: [`Duplicate plan keys: ${dupeKeys.join(", ")}`],
+            warnings,
+        };
+    }
+    return { valid: true, errors: [], warnings };
+}
+function formatIssue(issue, spec) {
+    const path = issue.path;
+    // Plans are addressed positionally in path (e.g. ["plans", 0, "key"]). Look
+    // up the plan key from the spec so the error message reads
+    // `Plan "starter": pricing is required` instead of `plans.0.pricing: ...`.
+    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} — ${issue.message}`;
+        }
+        return `Plan "${planLabel}": ${issue.message}`;
+    }
+    const dotted = path.length > 0 ? path.join(".") : "(root)";
+    return `${dotted}: ${issue.message}`;
+}
+function deriveWarnings(parsed) {
     const warnings = [];
-    // Check top-level sections
-    const product = spec.product;
-    if (!product)
-        errors.push("Missing 'product' section");
-    else {
-        if (!product.name)
-            errors.push("product.name is required");
-        if (!product.baseUrl || product.baseUrl === "https://api.example.com")
-            errors.push("product.baseUrl must be set to your real API endpoint");
-        if (product.description && product.description.length > 2000)
-            errors.push("product.description exceeds 2000 character limit");
-        if (product.displayName && product.displayName.length > 200)
-            errors.push("product.displayName exceeds 200 character limit");
+    if (parsed.plans.length === 0) {
+        // Schema accepts an empty plan list (default), but a product with no
+        // plans can't go live — surface as a warning so the builder sees the
+        // requirement before pushing.
+        warnings.push("No plans declared — product cannot accept signups yet");
     }
-    const billing = spec.billing;
-    if (!billing)
-        errors.push("Missing 'billing' section");
-    else if (!billing.strategy)
-        errors.push("billing.strategy is required");
-    const metering = spec.metering;
-    if (!metering)
-        errors.push("Missing 'metering' section");
     else {
-        const rawMeters = metering.meters ?? [];
-        if (!Array.isArray(rawMeters)) {
-            errors.push("'metering.meters' must be an array");
+        const hasFree = parsed.plans.some((plan) => {
+            const monthly = "monthlyPriceCents" in plan.pricing
+                ? plan.pricing.monthlyPriceCents
+                : undefined;
+            return monthly === 0;
+        });
+        if (!hasFree) {
+            warnings.push("No free plan — consider adding one for developer adoption");
+        }
+    }
+    if (!parsed.product.displayName ||
+        parsed.product.displayName === parsed.product.name) {
+        warnings.push("product.displayName not set — using product.name on the pricing page");
+    }
+    return warnings;
+}
+function findDuplicatePlanKeys(parsed) {
+    const seen = new Set();
+    const dupes = new Set();
+    for (const plan of parsed.plans) {
+        if (seen.has(plan.key)) {
+            dupes.add(plan.key);
         }
         else {
-            const meters = rawMeters;
-            if (meters.length === 0)
-                errors.push("At least one meter is required in metering.meters");
-            if (meters.length > 10)
-                errors.push("Maximum 10 meters allowed");
+            seen.add(plan.key);
         }
     }
-    const rawPlans = spec.plans ?? [];
-    const plans = Array.isArray(rawPlans)
-        ? rawPlans
-        : [];
-    if (spec.plans != null && !Array.isArray(spec.plans)) {
-        errors.push("'plans' must be an array");
+    return [...dupes];
+}
+/**
+ * Read + parse a product.yaml file. Returns either the parsed spec or
+ * a structured error result. Extracted from the validate command so
+ * the action handler stays under the cognitive-complexity threshold.
+ */
+export function loadProductYaml(filePath) {
+    if (!existsSync(filePath)) {
+        return { ok: false, reason: "missing", message: filePath };
+    }
+    try {
+        const content = readFileSync(filePath, "utf-8");
+        return { ok: true, spec: YAML.parse(content) };
     }
-    if (plans.length === 0)
-        errors.push("At least one plan is required to go live");
-    if (plans.length > 4)
-        errors.push("Maximum 4 plans allowed");
-    // Validate strategy/model alignment
-    const strategy = billing?.strategy;
-    const modelMap = {
-        subscription: "flat_rate",
-        usage_based: "pay_as_you_go",
-        hybrid: "included_usage",
-    };
-    for (const plan of plans) {
-        const pricing = plan.pricing;
-        if (!pricing?.model) {
-            errors.push(`Plan "${plan.key ?? plan.name ?? "?"}": pricing.model is required`);
-        }
-        else if (strategy &&
-            modelMap[strategy] &&
-            pricing.model !== modelMap[strategy]) {
-            errors.push(`Plan "${plan.key ?? "?"}": pricing.model "${pricing.model}" doesn't match billing.strategy "${strategy}" (expected "${modelMap[strategy]}")`);
+    catch (err) {
+        return {
+            ok: false,
+            reason: "parse",
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Print a ValidationResult to stdout, optionally emitting GitHub
+ * Actions annotations. Sets `process.exitCode = 1` on validation
+ * failure so the CLI exits non-zero.
+ */
+function reportValidationResult(result) {
+    if (CI) {
+        for (const err of result.errors) {
+            console.log(`::error file=product.yaml::${err}`);
         }
-        if (!plan.key)
-            errors.push(`Plan "${plan.name ?? "?"}": key is required`);
-        if (!plan.name)
-            errors.push(`Plan "${plan.key ?? "?"}": name is required`);
-        const limits = (plan.limits ?? []);
-        if (limits.length === 0) {
-            errors.push(`Plan "${plan.key ?? "?"}": at least one limit is required`);
+        for (const w of result.warnings) {
+            console.log(`::warning file=product.yaml::${w}`);
         }
-        if (limits.length > 20) {
-            errors.push(`Plan "${plan.key ?? "?"}": maximum 20 limits per plan`);
+    }
+    if (result.errors.length === 0) {
+        output.success("product.yaml is valid");
+        for (const w of result.warnings) {
+            output.warn(w);
         }
+        return;
+    }
+    output.error(`product.yaml has ${result.errors.length} error(s):\n`);
+    for (const err of result.errors) {
+        console.log(`  • ${err}`);
     }
-    // Check for duplicate plan keys
-    const keys = plans.map((p) => p.key).filter(Boolean);
-    const dupes = keys.filter((k, i) => keys.indexOf(k) !== i);
-    if (dupes.length > 0)
-        errors.push(`Duplicate plan keys: ${dupes.join(", ")}`);
-    // Warnings (non-blocking)
-    if (plans.length > 0 &&
-        !plans.some((p) => {
-            const pricing = p.pricing;
-            return pricing?.monthlyPriceCents === 0;
-        })) {
-        warnings.push("No free plan — consider adding one for developer adoption");
+    if (result.warnings.length > 0) {
+        console.log();
+        for (const w of result.warnings) {
+            output.warn(w);
+        }
     }
-    return { valid: errors.length === 0, errors, warnings };
+    process.exitCode = 1;
 }
 export function registerValidateCommand(program) {
     program
         .command("validate [file]")
         .description("Validate a local product.yaml file")
-        .action(async (file) => {
+        // Action body is sync; commander only requires a thenable on
+        // .action when await is used. Drop `async` keyword.
+        .action((file) => {
         const filePath = resolve(file ?? "product.yaml");
-        if (!existsSync(filePath)) {
-            if (CI)
-                console.log(`::error file=product.yaml::File not found: ${filePath}`);
-            output.error(`File not found: ${filePath}`);
-            process.exitCode = 1;
-            return;
-        }
-        let spec;
-        try {
-            const content = readFileSync(filePath, "utf-8");
-            spec = YAML.parse(content);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            if (CI)
-                console.log(`::error file=product.yaml::YAML parse error: ${msg}`);
-            output.error(`Failed to parse YAML: ${msg}`);
+        const loaded = loadProductYaml(filePath);
+        if (!loaded.ok) {
+            if (loaded.reason === "missing") {
+                if (CI)
+                    console.log(`::error file=product.yaml::File not found: ${loaded.message}`);
+                output.error(`File not found: ${loaded.message}`);
+            }
+            else {
+                if (CI)
+                    console.log(`::error file=product.yaml::YAML parse error: ${loaded.message}`);
+                output.error(`Failed to parse YAML: ${loaded.message}`);
+            }
             process.exitCode = 1;
             return;
         }
-        const result = validateProductYaml(spec);
+        const result = validateProductYaml(loaded.spec);
         // Check product.name consistency against main branch
-        const currentName = spec.product
-            ?.name;
+        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}" — product name must not change`);
+                result.valid = false;
             }
         }
-        // GitHub Actions annotations
-        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) {
-            output.success("product.yaml is valid");
-            if (result.warnings.length > 0) {
-                for (const w of result.warnings) {
-                    output.warn(w);
-                }
-            }
-        }
-        else {
-            output.error(`product.yaml has ${result.errors.length} error(s):\n`);
-            for (const err of result.errors) {
-                console.log(`  • ${err}`);
-            }
-            if (result.warnings.length > 0) {
-                console.log();
-                for (const w of result.warnings) {
-                    output.warn(w);
-                }
-            }
-            process.exitCode = 1;
-        }
+        reportValidationResult(result);
     });
 }

package/dist/config.d.ts

@@ -4,6 +4,3 @@ export declare function saveConfig(config: Partial<CliConfig>): void;
 export declare function loadCredentials(): Credentials | null;
 export declare function saveCredentials(creds: Credentials): void;
 export declare function clearCredentials(): void;
-export declare function getConfigPath(productSlug: string): string;
-export declare function writeConfigFile(productSlug: string, content: string): string;
-export declare function readConfigFile(productSlug: string): string | null;

package/dist/config.js

@@ -6,7 +6,6 @@ import { BUILD_API_URL } from "./build-info.js";
 const CONFIG_DIR = join(homedir(), ".farthershore");
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
 const CREDENTIALS_FILE = join(CONFIG_DIR, "credentials.json");
-const CONFIGS_DIR = join(CONFIG_DIR, "configs");
 function ensureDir(dir) {
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -21,10 +20,10 @@ export function loadConfig() {
     if (!existsSync(CONFIG_FILE))
         return DEFAULT_CONFIG;
     try {
-        return {
-            ...DEFAULT_CONFIG,
-            ...JSON.parse(readFileSync(CONFIG_FILE, "utf-8")),
-        };
+        // JSON.parse → `any`; cast to a partial of the typed shape so the
+        // spread doesn't propagate `any` into the returned union.
+        const parsed = JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+        return { ...DEFAULT_CONFIG, ...parsed };
     }
     catch {
         return DEFAULT_CONFIG;
@@ -57,20 +56,3 @@ export function clearCredentials() {
         writeFileSync(CREDENTIALS_FILE, "{}");
     }
 }
-// --- Plan configs ---
-export function getConfigPath(productSlug) {
-    const dir = join(CONFIGS_DIR, productSlug);
-    ensureDir(dir);
-    return join(dir, "plans.yaml");
-}
-export function writeConfigFile(productSlug, content) {
-    const path = getConfigPath(productSlug);
-    writeFileSync(path, content);
-    return path;
-}
-export function readConfigFile(productSlug) {
-    const path = getConfigPath(productSlug);
-    if (!existsSync(path))
-        return null;
-    return readFileSync(path, "utf-8");
-}

package/dist/index.js

@@ -11,6 +11,7 @@ import { registerInitCommand } from "./commands/init.js";
 import { registerValidateCommand } from "./commands/validate.js";
 import { registerApplyCommand } from "./commands/apply.js";
 import { CliError } from "./types.js";
+import { getRemediation } from "./remediation.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(await readFile(join(__dirname, "..", "package.json"), "utf-8"));
 const program = new Command();
@@ -36,13 +37,27 @@ registerValidateCommand(program);
 registerApplyCommand(program, getClient);
 // Global error handler
 program.exitOverride();
+/**
+ * Pretty-print a CliError to stderr, surfacing the canonical `code` (when
+ * present) and a remediation hint registered in `./remediation.ts`. The
+ * code is shown in brackets so support engineers can ask "what was the
+ * code?" without parsing the message.
+ */
+function reportCliError(err) {
+    const codeSuffix = err.code ? ` [${err.code}]` : "";
+    process.stderr.write(`Error${codeSuffix}: ${err.message}\n`);
+    const hint = getRemediation(err.code);
+    if (hint) {
+        process.stderr.write(`Hint: ${hint}\n`);
+    }
+}
 async function main() {
     try {
         await program.parseAsync(process.argv);
     }
     catch (err) {
         if (err instanceof CliError) {
-            process.stderr.write(`Error: ${err.message}\n`);
+            reportCliError(err);
             process.exitCode = 1;
         }
         else if (err instanceof Error) {
@@ -57,4 +72,8 @@ async function main() {
         }
     }
 }
-main();
+// Top-level invocation; CLI entry-point. `void` discards the returned
+// promise explicitly — `main` already handles its own errors and sets
+// `process.exitCode`, so a bare floating call is safe but the marker
+// silences the lint and documents intent.
+void main();

package/dist/output.d.ts

@@ -1,11 +1,8 @@
-export declare function table(headers: string[], rows: string[][]): string;
 export declare function json(data: unknown): string;
 export declare function success(msg: string): void;
 export declare function error(msg: string): void;
 export declare function warn(msg: string): void;
 export declare function info(msg: string): void;
 export declare function heading(msg: string): void;
-export declare function formatPrice(cents: number): string;
-export declare function formatDate(iso: string): string;
 export declare function isTTY(): boolean;
-export declare function outputFormat(flagFormat: string | undefined): "table" | "json" | "yaml";
+export declare function outputFormat(flagFormat: string | undefined): "table" | "json";

package/dist/output.js

@@ -1,14 +1,5 @@
 // Output formatting: tables, JSON, colors
 import chalk from "chalk";
-export function table(headers, rows) {
-    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)));
-    const header = headers.map((h, i) => h.padEnd(widths[i])).join("  ");
-    const separator = widths.map((w) => "─".repeat(w)).join("──");
-    const body = rows
-        .map((row) => row.map((cell, i) => (cell ?? "").padEnd(widths[i])).join("  "))
-        .join("\n");
-    return `${chalk.bold(header)}\n${chalk.dim(separator)}\n${body}`;
-}
 export function json(data) {
     return JSON.stringify(data, null, 2);
 }
@@ -27,21 +18,11 @@ export function info(msg) {
 export function heading(msg) {
     console.log(chalk.bold(msg));
 }
-export function formatPrice(cents) {
-    return `$${(cents / 100).toFixed(2)}`;
-}
-export function formatDate(iso) {
-    return new Date(iso).toLocaleDateString("en-US", {
-        year: "numeric",
-        month: "short",
-        day: "numeric",
-    });
-}
 export function isTTY() {
     return process.stdout.isTTY === true;
 }
 export function outputFormat(flagFormat) {
-    if (flagFormat === "json" || flagFormat === "yaml" || flagFormat === "table")
+    if (flagFormat === "json" || flagFormat === "table")
         return flagFormat;
     return isTTY() ? "table" : "json";
 }

package/dist/remediation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Look up a one-line remediation hint for a server error code. Returns
+ * `undefined` if no hint is registered — callers should treat that as
+ * "show no hint" rather than a fallback string.
+ */
+export declare function getRemediation(code: string | undefined): string | undefined;

package/dist/remediation.js

@@ -0,0 +1,53 @@
+// ---------------------------------------------------------------------------
+// Per-error-code remediation hints.
+//
+// When `core` returns a 4XX/5XX with a known `error.code`, the CLI prints
+// the code alongside the message AND a 1-line "next step" so users (and
+// agents) don't have to grep docs to figure out what to do.
+//
+// Codes are kept as raw strings — the CLI doesn't depend on the SDK, and
+// pulling in `@farther-shore/sdk` just for a string union would be more
+// coupling than this is worth. If a code is missing here, no remediation
+// is shown — fail-safe, never wrong.
+// ---------------------------------------------------------------------------
+const 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.",
+};
+/**
+ * Look up a one-line remediation hint for a server error code. Returns
+ * `undefined` if no hint is registered — callers should treat that as
+ * "show no hint" rather than a fallback string.
+ */
+export function getRemediation(code) {
+    if (!code)
+        return undefined;
+    return REMEDIATIONS[code];
+}

package/dist/types.d.ts

@@ -1,3 +1,16 @@
+import type { BuilderPlan } from "@farther-shore/shared-types/plans";
+/**
+ * Diagnostic emitted by core's /compile endpoints. The `compiledPlanId` and
+ * `planKey` fields (added in core v0.14.0) scope a diagnostic to a specific
+ * plan; both stay optional so diagnostics from older core builds still
+ * typecheck while the new shape rolls out.
+ */
+export type CompileDiagnostic = {
+    code?: string;
+    message: string;
+    compiledPlanId?: string;
+    planKey?: string;
+};
 export type Product = {
     id: string;
     name: string;
@@ -10,16 +23,13 @@ export type Product = {
     createdAt: string;
     plans: Plan[];
 };
-export type Plan = {
-    id: string;
-    key: string;
-    name: string;
-    description: string | null;
-    type: string;
-    monthlyPriceCents: number;
-    isActive: boolean;
-    selfServeEnabled: boolean;
-};
+/**
+ * `Plan` here is the canonical shared-types `BuilderPlan` projection: a
+ * `PlanSpec` extended with server-owned fields (id, productId, environmentId,
+ * isActive, createdAt). Adding a field to `planSpecSchema` automatically
+ * surfaces it on this type — drift between CLI and server is a compile error.
+ */
+export type Plan = BuilderPlan;
 export type CliConfig = {
     apiUrl: string;
     activeOrg?: string;
@@ -42,7 +52,22 @@ export type InitProductResponse = {
         agentsMdUrl: string | null;
     };
 };
+/**
+ * Error thrown by the CLI for any non-success path. Carries the canonical
+ * `code` from core's `{ error: { code, message, details? } }` envelope so
+ * the global error handler can print the code alongside the message and
+ * dispatch a remediation hint when one is registered for that code.
+ *
+ * `code`/`details` are optional because the same class also gets thrown for
+ * local (non-API) failures — e.g. "no token configured" — where there's no
+ * server-side code to surface.
+ */
 export declare class CliError extends Error {
     status?: number | undefined;
-    constructor(message: string, status?: number | undefined);
+    readonly code?: string;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, status?: number | undefined, extra?: {
+        code?: string;
+        details?: Record<string, unknown>;
+    });
 }

package/dist/types.js

@@ -1,9 +1,23 @@
 // Shared types for the FartherShore CLI
+/**
+ * Error thrown by the CLI for any non-success path. Carries the canonical
+ * `code` from core's `{ error: { code, message, details? } }` envelope so
+ * the global error handler can print the code alongside the message and
+ * dispatch a remediation hint when one is registered for that code.
+ *
+ * `code`/`details` are optional because the same class also gets thrown for
+ * local (non-API) failures — e.g. "no token configured" — where there's no
+ * server-side code to surface.
+ */
 export class CliError extends Error {
     status;
-    constructor(message, status) {
+    code;
+    details;
+    constructor(message, status, extra) {
         super(message);
         this.status = status;
         this.name = "CliError";
+        this.code = extra?.code;
+        this.details = extra?.details;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/cli",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "FartherShore CLI — create and configure API products",
   "type": "module",
   "bin": {
@@ -10,7 +10,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"
@@ -24,7 +24,8 @@
     "build": "tsc",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
-    "lint": "prettier --check \"src/**/*.ts\"",
+    "lint": "prettier --check \"src/**/*.ts\" && eslint .",
+    "lint:fix": "eslint . --fix",
     "typecheck": "tsc --noEmit"
   },
   "keywords": [
@@ -38,15 +39,20 @@
   "author": "Farther Shore",
   "license": "MIT",
   "dependencies": {
+    "@farther-shore/shared-types": "^0.28.2",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
-    "yaml": "^2.8.3"
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^22.19.17",
+    "eslint": "^9.39.4",
+    "eslint-plugin-sonarjs": "^4.0.3",
     "prettier": "^3.8.1",
     "tsx": "^4.21.0",
     "typescript": "^6.0.2",
+    "typescript-eslint": "^8.59.0",
     "vitest": "^3.2.4"
   }
 }