@farthershore/cli 0.3.6 → 0.3.8

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/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

@@ -34,20 +34,49 @@ export function createClient(opts) {
             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`, opts?.branch ? { branch: opts.branch } : undefined),
+        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", opts?.branch ? { branch: opts.branch } : undefined),
-        managementCompile: (productId, opts) => request("POST", `/management/products/${productId}/compile`, opts?.branch ? { branch: opts.branch } : undefined),
+        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

@@ -49,7 +49,7 @@ function readSlugFromProductYaml() {
         return null;
     }
 }
-function validateLocalProductYamlBeforeRemoteCompile() {
+function validateLocalProductYamlBeforeRemoteCompile(format) {
     const filePath = resolve("product.yaml");
     if (!existsSync(filePath))
         return true;
@@ -61,7 +61,19 @@ function validateLocalProductYamlBeforeRemoteCompile() {
         if (CI) {
             console.log(`::error file=product.yaml::${message}`);
         }
-        output.error(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;
     }
@@ -75,24 +87,38 @@ function validateLocalProductYamlBeforeRemoteCompile() {
                 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 (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"],
+            }));
         }
-        if (result.warnings.length > 0) {
-            console.log();
-            for (const warning of result.warnings) {
-                output.warn(warning);
+        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;
     }
-    output.success("Local product.yaml passed validation");
-    for (const warning of result.warnings) {
-        output.warn(warning);
+    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.");
     }
-    output.info("Remote compile checks the pushed branch state; unpushed local edits are not included.");
     return true;
 }
 function shouldValidateLocalProductYaml(productArg) {
@@ -134,6 +160,12 @@ async function resolveProductId(client, arg) {
         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.
@@ -142,7 +174,7 @@ function formatDiag(d) {
     const planLabel = d.planKey ? `(plan: ${d.planKey}) ` : "";
     return `${prefix}${planLabel}${d.message}`;
 }
-function handleResult(result) {
+function handleResult(result, format) {
     // GitHub Actions annotations
     if (CI) {
         for (const err of result.errors ?? []) {
@@ -152,6 +184,20 @@ function handleResult(result) {
             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) {
@@ -176,11 +222,15 @@ export function registerApplyCommand(program, getClient) {
         "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")
         .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()) {
+            !validateLocalProductYamlBeforeRemoteCompile(format)) {
             return;
         }
         if (branch && CI) {
@@ -191,8 +241,8 @@ export function registerApplyCommand(program, getClient) {
         // no slug lookup, single API call.
         if (client.isMakerToken() && !productArg) {
             try {
-                const result = await client.managementCompileSelf({ branch });
-                handleResult(result);
+                const result = await client.managementCompileSelf(compileOpts);
+                handleResult(result, format);
                 return;
             }
             catch (err) {
@@ -216,9 +266,13 @@ export function registerApplyCommand(program, getClient) {
         }
         try {
             const result = client.isMakerToken()
-                ? await client.managementCompile(productId, { branch })
-                : await client.compileProduct(productId, { branch });
-            handleResult(result);
+                ? 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";

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;

package/dist/commands/billing.js

@@ -0,0 +1,59 @@
+import { loadAcceptedSpec, objectAt, printResult, resolveProductId, updateSpec, } from "./helpers.js";
+export function registerBillingCommands(program, getClient) {
+    const billing = program.command("billing").description("Manage billing");
+    const strategy = billing.command("strategy").description("Billing strategy");
+    strategy
+        .command("get")
+        .option("--product <product>", "Product id or name")
+        .action(async (opts) => {
+        const client = getClient();
+        const productId = await resolveProductId(client, opts.product);
+        const config = (await client.getProductConfig(productId));
+        printResult(program, "Billing strategy loaded", {
+            ok: true,
+            productId,
+            strategy: config.acceptedConfig?.billing?.strategy ?? null,
+        });
+    });
+    strategy
+        .command("set <strategy>")
+        .option("--product <product>", "Product id or name")
+        .option("--transition <action>", "Default subscriber transition action", "preserve_current_period")
+        .option("--proration <mode>", "Proration mode", "none")
+        .option("--dry-run", "Validate without mutating")
+        .action(async (nextStrategy, opts) => {
+        const client = getClient();
+        const productId = await resolveProductId(client, opts.product);
+        const spec = await loadAcceptedSpec(client, productId);
+        const billing = objectAt(spec, "billing");
+        billing.strategy = nextStrategy;
+        billing.subscriberChangePolicy = {
+            default: opts.transition,
+            proration: opts.proration,
+        };
+        await updateSpec(program, client, productId, spec, {
+            dryRun: opts.dryRun,
+            message: "Billing strategy updated",
+        });
+    });
+    billing
+        .command("policy set")
+        .option("--product <product>", "Product id or name")
+        .option("--default <action>", "Default subscriber action", "preserve_current_period")
+        .option("--proration <mode>", "Proration mode", "none")
+        .option("--dry-run", "Validate without mutating")
+        .action(async (opts) => {
+        const client = getClient();
+        const productId = await resolveProductId(client, opts.product);
+        const spec = await loadAcceptedSpec(client, productId);
+        const billing = objectAt(spec, "billing");
+        billing.subscriberChangePolicy = {
+            default: opts.default,
+            proration: opts.proration,
+        };
+        await updateSpec(program, client, productId, spec, {
+            dryRun: opts.dryRun,
+            message: "Billing policy updated",
+        });
+    });
+}

package/dist/commands/feature.d.ts

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

package/dist/commands/feature.js

@@ -0,0 +1,80 @@
+import { findPlan, loadAcceptedSpec, objectAt, printResult, resolveProductId, stringArrayAt, updateSpec, } from "./helpers.js";
+export function registerFeatureCommands(program, getClient) {
+    const feature = program.command("feature").description("Manage features");
+    feature
+        .command("list")
+        .option("--product <product>", "Product id or name")
+        .action(async (opts) => {
+        const client = getClient();
+        const productId = await resolveProductId(client, opts.product);
+        const spec = await loadAcceptedSpec(client, productId);
+        printResult(program, "Features loaded", {
+            ok: true,
+            productId,
+            features: objectAt(spec, "features"),
+        });
+    });
+    feature
+        .command("add <key>")
+        .option("--product <product>", "Product id or name")
+        .option("--route <route>", "Route binding METHOD:/path; repeatable", collect, [])
+        .option("--dry-run", "Validate without mutating")
+        .action(async (key, opts) => {
+        const client = getClient();
+        const productId = await resolveProductId(client, opts.product);
+        const spec = await loadAcceptedSpec(client, productId);
+        const features = objectAt(spec, "features");
+        features[key] = { routes: opts.route.map(parseRoute) };
+        await updateSpec(program, client, productId, spec, {
+            dryRun: opts.dryRun,
+            message: `Feature "${key}" saved`,
+        });
+    });
+    feature
+        .command("bind <key>")
+        .requiredOption("--plan <plan>", "Plan key")
+        .option("--product <product>", "Product id or name")
+        .option("--dry-run", "Validate without mutating")
+        .action(async (key, opts) => {
+        const client = getClient();
+        const productId = await resolveProductId(client, opts.product);
+        const spec = await loadAcceptedSpec(client, productId);
+        const plan = findPlan(spec, opts.plan);
+        const features = stringArrayAt(plan, "features");
+        if (!features.includes(key))
+            features.push(key);
+        await updateSpec(program, client, productId, spec, {
+            dryRun: opts.dryRun,
+            message: `Feature "${key}" bound to "${opts.plan}"`,
+        });
+    });
+    feature
+        .command("unbind <key>")
+        .requiredOption("--plan <plan>", "Plan key")
+        .option("--product <product>", "Product id or name")
+        .option("--dry-run", "Validate without mutating")
+        .action(async (key, opts) => {
+        const client = getClient();
+        const productId = await resolveProductId(client, opts.product);
+        const spec = await loadAcceptedSpec(client, productId);
+        const plan = findPlan(spec, opts.plan);
+        plan.features = stringArrayAt(plan, "features").filter((featureKey) => featureKey !== key);
+        await updateSpec(program, client, productId, spec, {
+            dryRun: opts.dryRun,
+            message: `Feature "${key}" unbound from "${opts.plan}"`,
+        });
+    });
+}
+function collect(value, previous) {
+    previous.push(value);
+    return previous;
+}
+function parseRoute(value) {
+    const separator = value.indexOf(":");
+    if (separator === -1)
+        return { method: "*", path: value };
+    return {
+        method: value.slice(0, separator).toUpperCase(),
+        path: value.slice(separator + 1),
+    };
+}

package/dist/commands/helpers.d.ts

@@ -0,0 +1,15 @@
+import type { Command } from "commander";
+import type { ApiClient } from "../client.js";
+export declare function commandFormat(program: Command): "table" | "json";
+export declare function printResult(program: Command, humanMessage: string, payload: Record<string, unknown>): void;
+export declare function resolveProductId(client: ApiClient, productArg?: string): Promise<string>;
+export declare function resolvePlanId(client: ApiClient, productId: string, planArg: string): Promise<string>;
+export declare function loadAcceptedSpec(client: ApiClient, productId: string): Promise<Record<string, unknown>>;
+export declare function plans(spec: Record<string, unknown>): Array<Record<string, unknown>>;
+export declare function objectAt(parent: Record<string, unknown>, key: string): Record<string, unknown>;
+export declare function stringArrayAt(parent: Record<string, unknown>, key: string): string[];
+export declare function findPlan(spec: Record<string, unknown>, planKey: string): Record<string, unknown>;
+export declare function updateSpec(program: Command, client: ApiClient, productId: string, spec: Record<string, unknown>, opts?: {
+    dryRun?: boolean;
+    message?: string;
+}): Promise<unknown>;