@farthershore/cli 0.3.7 → 0.3.9

package/README.md

@@ -25,6 +25,9 @@ farthershore set-key
 # Non-interactive — pass token directly
 farthershore set-key mk_xxx
 
+# Agent-friendly alias
+farthershore auth set-key mk_xxx
+
 # Environment variable (CI / agents)
 export FARTHERSHORE_TOKEN=mk_xxx
 ```
@@ -54,6 +57,125 @@ The created repo contains:
 - `docs/` — developer portal documentation
 - `.skills/` — task-specific instructions
 
+### `farthershore product create <name>`
+
+Create a product through the API and select it as the active product for
+subsequent CLI commands. This is the fastest path for an agent that wants
+to configure a product without opening the UI.
+
+```bash
+farthershore product create weather-api \
+  --base-url https://api.example.com \
+  --strategy prepaid_credits \
+  --format json
+```
+
+### `farthershore product status`
+
+Return the latest accepted internal product config metadata, including
+the accepted config hash and GitHub sync state.
+
+```bash
+farthershore product status --format json
+```
+
+### `farthershore product config`
+
+Print the latest accepted product config from FartherShore. GitHub, the
+UI, and the CLI are proposal surfaces; the accepted internal config is the
+valid source of truth.
+
+```bash
+farthershore product config --format json
+farthershore product config --format yaml
+```
+
+### `farthershore product attempts`
+
+List rejected config proposals. Invalid proposals are recorded for
+diagnostics but do not replace the accepted internal config or mutate live
+product state.
+
+```bash
+farthershore product attempts --format json
+```
+
+### `farthershore meter`
+
+Create and manage usage meters on the accepted product config.
+
+```bash
+farthershore meter add ai_tokens \
+  --selector model \
+  --measure input_tokens \
+  --measure output_tokens \
+  --rating provider_catalog \
+  --catalog llm_models \
+  --format json
+
+farthershore meter list --format json
+```
+
+### `farthershore feature`
+
+Create features and bind or unbind them from plans.
+
+```bash
+farthershore feature add chat_completions \
+  --route POST:/v1/chat/completions \
+  --format json
+
+farthershore feature bind chat_completions --plan pro --format json
+```
+
+### `farthershore plan`
+
+Create and update plans in the accepted product config. Server-side
+validation remains authoritative for rules like one free plan, duplicate
+paid prices, and product-level billing strategy consistency.
+
+```bash
+farthershore plan add free \
+  --free \
+  --limit ai_tokens:month:100000:enforce \
+  --feature chat_completions \
+  --format json
+
+farthershore plan add pro \
+  --price-monthly 2900 \
+  --credits-monthly-micros 500000000 \
+  --meter ai_tokens \
+  --feature chat_completions \
+  --format json
+```
+
+### `farthershore billing`
+
+Read or change the product-level billing strategy and subscriber change
+policy.
+
+```bash
+farthershore billing strategy get --format json
+
+farthershore billing strategy set prepaid_credits \
+  --transition preserve_current_period \
+  --format json
+
+farthershore billing policy set \
+  --default preserve_current_period \
+  --proration none \
+  --format json
+```
+
+### `farthershore transition preview`
+
+Preview how billing-affecting config changes apply to existing
+subscribers before applying them.
+
+```bash
+farthershore transition preview --format json
+```
+
 ### `farthershore validate [file]`
 
 Validate a local `product.yaml` file without making any API calls. Checks structure, required fields, and launch constraints for env-scoped plans and meters.
@@ -76,6 +198,9 @@ farthershore apply
 
 # Or pass the product slug
 farthershore apply my-weather-api
+
+# Validate and remote-compile without applying
+farthershore apply --dry-run --format json
 ```
 
 ### `farthershore set-key [token]`
@@ -120,6 +245,41 @@ farthershore validate
 git add -A && git commit -m "Configure product" && git push
 ```
 
+Agents can also complete the flow entirely through API-backed CLI
+commands:
+
+```bash
+farthershore auth set-key "$FARTHERSHORE_TOKEN"
+farthershore product create weather-api \
+  --base-url https://api.example.com \
+  --strategy prepaid_credits \
+  --format json
+farthershore meter add ai_tokens \
+  --selector model \
+  --measure input_tokens \
+  --measure output_tokens \
+  --rating provider_catalog \
+  --catalog llm_models \
+  --format json
+farthershore feature add chat_completions \
+  --route POST:/v1/chat/completions \
+  --format json
+farthershore plan add free \
+  --free \
+  --limit ai_tokens:month:100000:enforce \
+  --feature chat_completions \
+  --format json
+farthershore plan add pro \
+  --price-monthly 2900 \
+  --credits-monthly-micros 500000000 \
+  --meter ai_tokens \
+  --feature chat_completions \
+  --format json
+farthershore transition preview --format json
+farthershore apply --dry-run --format json
+farthershore product status --format json
+```
+
 ## Global Flags
 
 | Flag              | Description                          |

package/dist/auth.js

@@ -0,0 +1,17 @@
+// 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

@@ -0,0 +1,10 @@
+// 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.d.ts

@@ -23,14 +23,43 @@ export declare function createClient(opts: {
         }>;
     }>;
     listProducts: () => Promise<Product[]>;
+    createProduct: (data: {
+        name: string;
+        baseUrl?: string;
+        description?: string;
+        displayName?: string;
+        billingStrategy?: string;
+        subscriberChangePolicy?: unknown;
+    }) => Promise<Product>;
     initProduct: (data: {
         name: string;
         baseUrl?: string;
         description?: string;
         displayName?: string;
+        billingStrategy?: string;
+        subscriberChangePolicy?: unknown;
     }) => Promise<InitProductResponse>;
+    updateProduct: (productId: string, data: Record<string, unknown>, opts?: {
+        env?: string;
+    }) => Promise<Product>;
+    createPlan: (productId: string, data: unknown, opts?: {
+        env?: string;
+    }) => Promise<unknown>;
+    updatePlan: (productId: string, planId: string, data: unknown, opts?: {
+        env?: string;
+    }) => Promise<unknown>;
+    deletePlan: (productId: string, planId: string, opts?: {
+        env?: string;
+    }) => Promise<void>;
+    getProductConfig: (productId: string) => Promise<unknown>;
+    getProductConfigYaml: (productId: string) => Promise<string>;
+    getProductAttempts: (productId: string) => Promise<unknown>;
+    updateProductConfig: (productId: string, spec: unknown, opts?: {
+        dryRun?: boolean;
+    }) => Promise<unknown>;
     compileProduct: (productId: string, opts?: {
         branch?: string;
+        dryRun?: boolean;
     }) => Promise<{
         success: boolean;
         errors?: CompileDiagnostic[];
@@ -38,6 +67,7 @@ export declare function createClient(opts: {
     }>;
     managementCompileSelf: (opts?: {
         branch?: string;
+        dryRun?: boolean;
     }) => Promise<{
         success: boolean;
         productId: string;
@@ -47,6 +77,7 @@ export declare function createClient(opts: {
     }>;
     managementCompile: (productId: string, opts?: {
         branch?: string;
+        dryRun?: boolean;
     }) => Promise<{
         success: boolean;
         errors?: CompileDiagnostic[];

package/dist/client.js

@@ -0,0 +1,82 @@
+// 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) {
+            // 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;
+        return res.json();
+    }
+    async function requestText(method, path) {
+        const res = await fetch(`${opts.apiUrl}${path}`, {
+            method,
+            headers: { Authorization: `Bearer ${opts.token}` },
+        });
+        if (!res.ok)
+            throw new CliError(res.statusText, res.status);
+        return res.text();
+    }
+    return {
+        // --- Auth ---
+        bootstrap: () => request("POST", "/builder/context/bootstrap"),
+        // --- Products ---
+        listProducts: () => request("GET", "/products"),
+        createProduct: (data) => request("POST", "/products", data),
+        initProduct: (data) => request("POST", "/products/init", data),
+        updateProduct: (productId, data, opts) => request("PATCH", `/products/${productId}${opts?.env ? `?env=${encodeURIComponent(opts.env)}` : ""}`, data),
+        createPlan: (productId, data, opts) => request("POST", `/products/${productId}/plans${opts?.env ? `?env=${encodeURIComponent(opts.env)}` : ""}`, data),
+        updatePlan: (productId, planId, data, opts) => request("PATCH", `/products/${productId}/plans/${planId}${opts?.env ? `?env=${encodeURIComponent(opts.env)}` : ""}`, data),
+        deletePlan: (productId, planId, opts) => request("DELETE", `/products/${productId}/plans/${planId}${opts?.env ? `?env=${encodeURIComponent(opts.env)}` : ""}`),
+        getProductConfig: (productId) => request("GET", `/products/${productId}/config?format=json`),
+        getProductConfigYaml: (productId) => requestText("GET", `/products/${productId}/config?format=yaml`),
+        getProductAttempts: (productId) => request("GET", `/products/${productId}/config-attempts`),
+        updateProductConfig: (productId, spec, opts) => request("PATCH", `/products/${productId}/config`, {
+            spec,
+            dryRun: opts?.dryRun === true,
+        }),
+        // --- Compile ---
+        compileProduct: (productId, opts) => request("POST", `/products/${productId}/compile`, compileBody(opts)),
+        // --- 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: (opts) => request("POST", "/management/compile", compileBody(opts)),
+        managementCompile: (productId, opts) => request("POST", `/management/products/${productId}/compile`, compileBody(opts)),
+        managementListProducts: () => request("GET", "/management/products"),
+        isMakerToken: () => opts.token.startsWith("mk_"),
+    };
+}
+function compileBody(opts) {
+    const body = {};
+    if (opts?.branch)
+        body.branch = opts.branch;
+    if (opts?.dryRun)
+        body.dryRun = true;
+    return Object.keys(body).length > 0 ? body : undefined;
+}

package/dist/commands/apply.js

@@ -0,0 +1,296 @@
+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.
+ */
+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;
+    }
+}
+function validateLocalProductYamlBeforeRemoteCompile(format) {
+    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}`);
+        }
+        if (format === "json") {
+            console.log(output.json({
+                ok: false,
+                success: false,
+                phase: "local_validation",
+                errors: [{ message }],
+                warnings: [],
+                nextActions: ["Fix product.yaml and run apply again"],
+            }));
+        }
+        else {
+            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}`);
+            }
+        }
+        if (format === "json") {
+            console.log(output.json({
+                ok: false,
+                success: false,
+                phase: "local_validation",
+                errors: result.errors.map((message) => ({ message })),
+                warnings: result.warnings.map((message) => ({ message })),
+                nextActions: ["Fix product.yaml and run apply again"],
+            }));
+        }
+        else {
+            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;
+    }
+    if (format !== "json") {
+        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.
+ * 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 compileOptions(branch, dryRun) {
+    return {
+        ...(branch ? { branch } : {}),
+        ...(dryRun ? { dryRun: true } : {}),
+    };
+}
+// 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, format) {
+    // GitHub Actions annotations
+    if (CI) {
+        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 (format === "json") {
+        console.log(output.json({
+            ok: result.success,
+            success: result.success,
+            errors: result.errors ?? [],
+            warnings: result.warnings ?? [],
+            nextActions: result.success
+                ? ["Product config is valid for apply"]
+                : ["Fix errors and run farthershore apply --dry-run --format json"],
+        }));
+        if (!result.success)
+            process.exitCode = 1;
+        return;
+    }
+    if (result.success) {
+        output.success("Remote compile passed");
+        if (result.warnings?.length) {
+            console.log();
+            for (const w of result.warnings) {
+                output.warn(formatDiag(w));
+            }
+        }
+    }
+    else {
+        output.error("Remote compile failed\n");
+        for (const err of result.errors ?? []) {
+            console.log(`  • ${formatDiag(err)}`);
+        }
+        process.exitCode = 1;
+    }
+}
+export function registerApplyCommand(program, getClient) {
+    program
+        .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)")
+        .option("--dry-run", "Run local validation and remote compile without applying product state")
+        .addHelpText("after", `
+Agent notes:
+  apply first validates local product.yaml when it matches the target product, then asks core to compile the pushed branch state.
+  Unpushed local edits are not included in remote compile. Push or use CLI config commands for API-backed changes.
+  Use --format json for stable output: ok, success, errors, warnings, nextActions.
+
+Examples:
+  farthershore apply --dry-run --format json
+  farthershore apply my-weather-api --dry-run --format json
+  farthershore apply my-weather-api --branch feature/billing-change --dry-run --format json
+`)
+        .action(async (productArg, opts) => {
+        const client = getClient();
+        const globalFormat = program.opts().format;
+        const format = globalFormat === "json" ? "json" : "table";
+        const branch = detectBranch(opts.branch);
+        const compileOpts = compileOptions(branch, opts.dryRun);
+        if (shouldValidateLocalProductYaml(productArg) &&
+            !validateLocalProductYamlBeforeRemoteCompile(format)) {
+            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(compileOpts);
+                handleResult(result, format);
+                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, {
+                    ...compileOpts,
+                })
+                : await client.compileProduct(productId, {
+                    ...compileOpts,
+                });
+            handleResult(result, format);
+        }
+        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/billing.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import type { ApiClient } from "../client.js";
+export declare function registerBillingCommands(program: Command, getClient: () => ApiClient): void;