@farthershore/cli 0.3.5 → 0.3.7

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/cli",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "FartherShore CLI — create and configure API products",
   "type": "module",
   "bin": {
@@ -10,7 +10,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"
@@ -21,10 +21,13 @@
   },
   "scripts": {
     "dev": "tsx src/index.ts",
-    "build": "tsc",
+    "build": "rm -rf dist && npm run build:types && npm run build:bundle",
+    "build:types": "tsc --emitDeclarationOnly",
+    "build:bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node22 --outfile=dist/index.js --external:chalk --external:commander --external:yaml --external:zod && chmod +x dist/index.js",
     "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": [
@@ -40,13 +43,19 @@
   "dependencies": {
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
-    "yaml": "^2.8.3"
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@farther-shore/shared-types": "^0.28.2",
     "@types/node": "^22.19.17",
+    "esbuild": "^0.28.0",
+    "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"
   }
 }

package/dist/auth.js

@@ -1,17 +0,0 @@
-// Token resolution: env var → credentials file → error
-import { loadCredentials } from "./config.js";
-import { CliError } from "./types.js";
-export function resolveToken(overrideToken) {
-    // 1. Explicit override (--token flag)
-    if (overrideToken)
-        return overrideToken;
-    // 2. Environment variable
-    const envToken = process.env.FARTHERSHORE_TOKEN;
-    if (envToken)
-        return envToken;
-    // 3. Stored credentials (from `farthershore login`)
-    const creds = loadCredentials();
-    if (creds?.token)
-        return creds.token;
-    throw new CliError("Not authenticated. Run `farthershore set-key` or set FARTHERSHORE_TOKEN environment variable.");
-}

package/dist/build-info.js

@@ -1,10 +0,0 @@
-// Build-time constants baked into the CLI binary at publish time.
-//
-// To publish a staging variant:
-//   1. Change BUILD_API_URL below to the staging URL
-//   2. Change the npm package name/tag in package.json
-//   3. Run `npm publish`
-//
-// The CLI uses this as the default API URL — users don't need to set
-// FARTHERSHORE_API_URL or pass --api-url for their target environment.
-export const BUILD_API_URL = "https://core.farthershore.com";

package/dist/client.js

@@ -1,36 +0,0 @@
-// Typed API client for the FartherShore platform
-import { CliError } from "./types.js";
-export 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) : undefined,
-        });
-        if (!res.ok) {
-            const err = await res.json().catch(() => ({ error: res.statusText }));
-            throw new CliError(err.error ?? `API error: ${res.status}`, res.status);
-        }
-        if (res.status === 204)
-            return undefined;
-        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) => request("POST", `/products/${productId}/compile`),
-        // --- 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`),
-        managementListProducts: () => request("GET", "/management/products"),
-        isMakerToken: () => opts.token.startsWith("mk_"),
-    };
-}

package/dist/commands/apply.js

@@ -1,127 +0,0 @@
-import { readFileSync, existsSync } from "node:fs";
-import { resolve } from "node:path";
-import YAML from "yaml";
-import * as output from "../output.js";
-const CI = !!process.env.CI || !!process.env.GITHUB_ACTIONS;
-/**
- * Read the product name/slug from product.yaml in the current directory.
- */
-function readSlugFromProductYaml() {
-    const yamlPath = resolve("product.yaml");
-    if (!existsSync(yamlPath))
-        return null;
-    try {
-        const spec = YAML.parse(readFileSync(yamlPath, "utf-8"));
-        const product = spec.product;
-        return product?.name ?? null;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Resolve a product identifier to an API product ID.
- * If no arg, reads product.name from product.yaml in the current directory.
- * If arg looks like a UUID, uses it directly. Otherwise treats it as a slug.
- */
-async function resolveProductId(client, arg) {
-    const slug = arg ?? readSlugFromProductYaml();
-    if (!slug)
-        return null;
-    // UUID — use directly
-    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;
-    }
-    // Slug — resolve via product list (use management API for maker tokens)
-    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) {
-        // Don't swallow network errors silently
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`Warning: Failed to resolve product slug: ${msg}\n`);
-        return null;
-    }
-}
-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}`);
-        }
-        for (const w of result.warnings ?? []) {
-            console.log(`::warning file=product.yaml::${w.code ? `[${w.code}] ` : ""}${w.message}`);
-        }
-    }
-    if (result.success) {
-        output.success("Compilation passed");
-        if (result.warnings?.length) {
-            console.log();
-            for (const w of result.warnings) {
-                output.warn(`${w.code ? `[${w.code}] ` : ""}${w.message}`);
-            }
-        }
-    }
-    else {
-        output.error("Compilation failed\n");
-        for (const err of result.errors ?? []) {
-            console.log(`  • ${err.code ? `[${err.code}] ` : ""}${err.message}`);
-        }
-        process.exitCode = 1;
-    }
-}
-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) => {
-        const client = getClient();
-        // 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();
-                handleResult(result);
-                return;
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : "Compilation check failed";
-                if (CI)
-                    console.log(`::error::${msg}`);
-                output.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";
-            output.error(hint);
-            process.exitCode = 1;
-            return;
-        }
-        try {
-            const result = client.isMakerToken()
-                ? await client.managementCompile(productId)
-                : await client.compileProduct(productId);
-            handleResult(result);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : "Compilation check failed";
-            if (CI)
-                console.log(`::error::${msg}`);
-            output.error(msg);
-            process.exitCode = 1;
-        }
-    });
-}

package/dist/commands/init.js

@@ -1,41 +0,0 @@
-import * as output from "../output.js";
-export function registerInitCommand(program, getClient) {
-    program
-        .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")
-        .option("--billing <strategy>", "Billing strategy: subscription|usage_based|hybrid", "subscription")
-        .action(async (name, opts) => {
-        const client = getClient();
-        const result = await client.initProduct({
-            name,
-            baseUrl: opts.baseUrl,
-            description: opts.description,
-            displayName: opts.displayName,
-            billingStrategy: opts.billing,
-        });
-        const format = output.outputFormat(program.opts().format);
-        if (format === "json") {
-            console.log(output.json(result));
-            return;
-        }
-        output.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 — add your base URL, plans, and meters");
-        console.log("    4. Push to main — a valid config goes live automatically");
-        console.log();
-        if (result.agent.agentsMdUrl) {
-            console.log(`  Docs: ${result.agent.agentsMdUrl}`);
-        }
-    });
-}

package/dist/commands/login.js

@@ -1,95 +0,0 @@
-import * as readline from "node:readline/promises";
-import { createClient } from "../client.js";
-import { loadConfig, saveConfig, saveCredentials, clearCredentials, } from "../config.js";
-import { resolveToken } from "../auth.js";
-import * as output from "../output.js";
-export function registerAuthCommands(program) {
-    program
-        .command("set-key [token]")
-        .description("Set your API token (interactive or pass as argument)")
-        .action(async (tokenArg) => {
-        let token = tokenArg?.trim();
-        if (!token) {
-            // Interactive mode
-            if (!process.stdin.isTTY) {
-                output.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) {
-            output.error("No token provided.");
-            process.exitCode = 1;
-            return;
-        }
-        const config = loadConfig();
-        try {
-            const client = createClient({ apiUrl: config.apiUrl, token });
-            const ctx = await client.bootstrap();
-            saveCredentials({
-                token,
-                orgId: ctx.activeOrganization.id,
-                userId: ctx.user.id,
-            });
-            output.success("Authenticated");
-            console.log(`  Organization: ${ctx.activeOrganization.name ?? ctx.activeOrganization.id}`);
-        }
-        catch {
-            output.error("Invalid token. Check it and try again.");
-            process.exitCode = 1;
-        }
-    });
-    program
-        .command("logout")
-        .description("Clear stored credentials")
-        .action(() => {
-        clearCredentials();
-        output.success("Credentials cleared.");
-    });
-    program
-        .command("whoami")
-        .description("Show current authentication context")
-        .action(async () => {
-        const config = loadConfig();
-        try {
-            const token = resolveToken();
-            const client = createClient({ apiUrl: config.apiUrl, token });
-            const ctx = await client.bootstrap();
-            output.heading("Current Context");
-            console.log(`  Organization: ${ctx.activeOrganization.name ?? ctx.activeOrganization.id}`);
-            console.log(`  API URL:      ${config.apiUrl}`);
-            if (process.env.FARTHERSHORE_TOKEN) {
-                output.info("  Auth: FARTHERSHORE_TOKEN env var");
-            }
-            else {
-                output.info("  Auth: ~/.farthershore/credentials.json");
-            }
-        }
-        catch {
-            output.error("Not authenticated. Run `farthershore set-key` or set FARTHERSHORE_TOKEN.");
-            process.exitCode = 1;
-        }
-    });
-    program
-        .command("set-url <url>")
-        .description("Override the API base URL (for staging/testing)")
-        .action((url) => {
-        saveConfig({ apiUrl: url });
-        output.success(`API URL set to ${url}`);
-    });
-    program
-        .command("reset-url")
-        .description("Reset the API URL to production default")
-        .action(() => {
-        saveConfig({ apiUrl: "https://core.farthershore.com" });
-        output.success("API URL reset to https://core.farthershore.com");
-    });
-}

package/dist/commands/validate.js

@@ -1,190 +0,0 @@
-import { readFileSync, existsSync } from "node:fs";
-import { execSync } from "node:child_process";
-import { resolve } from "node:path";
-import YAML from "yaml";
-import * as output from "../output.js";
-const CI = !!process.env.CI || !!process.env.GITHUB_ACTIONS;
-/**
- * Read product.yaml from the main branch using git, without checking it out.
- * Returns null if not in a git repo or main doesn't have the file.
- */
-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;
-}
-// 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 = [];
-    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");
-    }
-    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");
-        }
-        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");
-        }
-    }
-    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");
-    }
-    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]}")`);
-        }
-        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`);
-        }
-        if (limits.length > 20) {
-            errors.push(`Plan "${plan.key ?? "?"}": maximum 20 limits per plan`);
-        }
-    }
-    // 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");
-    }
-    return { valid: errors.length === 0, errors, warnings };
-}
-export function registerValidateCommand(program) {
-    program
-        .command("validate [file]")
-        .description("Validate a local product.yaml file")
-        .action(async (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}`);
-            process.exitCode = 1;
-            return;
-        }
-        const result = validateProductYaml(spec);
-        // Check product.name consistency against main branch
-        const currentName = 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`);
-            }
-        }
-        // 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;
-        }
-    });
-}