@farthershore/cli 0.3.7 → 0.3.8

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

package/dist/commands/helpers.js

@@ -0,0 +1,93 @@
+import { loadConfig } from "../config.js";
+import * as output from "../output.js";
+export function commandFormat(program) {
+    return output.outputFormat(program.opts().format);
+}
+export function printResult(program, humanMessage, payload) {
+    if (commandFormat(program) === "json") {
+        console.log(output.json(payload));
+        return;
+    }
+    output.success(humanMessage);
+}
+export async function resolveProductId(client, productArg) {
+    const config = loadConfig();
+    if (productArg) {
+        if (productArg.length === 36)
+            return productArg;
+        const products = client.isMakerToken()
+            ? await client.managementListProducts()
+            : await client.listProducts();
+        const product = products.find((p) => p.id === productArg ||
+            p.name.toLowerCase() === productArg.toLowerCase());
+        if (product)
+            return product.id;
+    }
+    if (config.activeProductId)
+        return config.activeProductId;
+    throw new Error("No product selected. Pass --product <id-or-name> or run `farthershore product create` first.");
+}
+export async function resolvePlanId(client, productId, planArg) {
+    if (planArg.length === 36)
+        return planArg;
+    const products = client.isMakerToken()
+        ? await client.managementListProducts()
+        : await client.listProducts();
+    const product = products.find((p) => p.id === productId);
+    const plan = product?.plans?.find((p) => p.id === planArg ||
+        p.key === planArg ||
+        p.name.toLowerCase() === planArg.toLowerCase());
+    if (!plan)
+        throw new Error(`Plan "${planArg}" not found`);
+    return plan.id;
+}
+export async function loadAcceptedSpec(client, productId) {
+    const config = (await client.getProductConfig(productId));
+    if (!config.acceptedConfig ||
+        typeof config.acceptedConfig !== "object" ||
+        Array.isArray(config.acceptedConfig)) {
+        throw new Error("Product has no accepted internal config yet.");
+    }
+    return config.acceptedConfig;
+}
+export function plans(spec) {
+    if (!Array.isArray(spec.plans))
+        spec.plans = [];
+    return spec.plans;
+}
+export function objectAt(parent, key) {
+    const current = parent[key];
+    if (current && typeof current === "object" && !Array.isArray(current)) {
+        return current;
+    }
+    const next = {};
+    parent[key] = next;
+    return next;
+}
+export function stringArrayAt(parent, key) {
+    if (!Array.isArray(parent[key]))
+        parent[key] = [];
+    const values = parent[key];
+    const strings = values.filter((value) => typeof value === "string");
+    if (strings.length !== values.length)
+        parent[key] = strings;
+    return parent[key];
+}
+export function findPlan(spec, planKey) {
+    const plan = plans(spec).find((candidate) => candidate.key === planKey);
+    if (!plan)
+        throw new Error(`Plan "${planKey}" not found`);
+    return plan;
+}
+export async function updateSpec(program, client, productId, spec, opts) {
+    const result = await client.updateProductConfig(productId, spec, {
+        dryRun: opts?.dryRun,
+    });
+    printResult(program, opts?.message ?? "Product config updated", {
+        ok: true,
+        productId,
+        dryRun: opts?.dryRun === true,
+        ...(typeof result === "object" && result ? result : {}),
+    });
+    return result;
+}

package/dist/commands/init.js

@@ -0,0 +1,43 @@
+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")
+        .action(async (name, opts) => {
+        const client = getClient();
+        const result = await client.initProduct({
+            name,
+            baseUrl: opts.baseUrl,
+            description: opts.description,
+            displayName: opts.displayName,
+        });
+        // `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;
+        }
+        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

@@ -0,0 +1,129 @@
+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) {
+    const auth = program.command("auth").description("Manage authentication");
+    auth
+        .command("set-key [token]")
+        .description("Set your API token")
+        .action(async (tokenArg) => {
+        await setKey(tokenArg);
+    });
+    program
+        .command("set-key [token]")
+        .description("Set your API token (interactive or pass as argument)")
+        .action(async (tokenArg) => {
+        await setKey(tokenArg);
+    });
+    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();
+        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 (authSource === "env:FARTHERSHORE_TOKEN") {
+                output.info("  Auth: FARTHERSHORE_TOKEN env var");
+            }
+            else {
+                output.info("  Auth: ~/.farthershore/credentials.json");
+            }
+        }
+        catch {
+            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;
+        }
+    });
+    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");
+    });
+}
+async function setKey(tokenArg) {
+    let token = tokenArg?.trim();
+    if (!token) {
+        if (!process.stdin.isTTY) {
+            output.error("No token provided. Pass it as an argument: farthershore auth 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;
+    }
+}

package/dist/commands/meter.d.ts

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

package/dist/commands/meter.js

@@ -0,0 +1,94 @@
+import { loadAcceptedSpec, objectAt, printResult, resolveProductId, updateSpec, } from "./helpers.js";
+export function registerMeterCommands(program, getClient) {
+    const meter = program.command("meter").description("Manage usage meters");
+    meter
+        .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);
+        const usage = objectAt(spec, "usage");
+        printResult(program, "Meters loaded", {
+            ok: true,
+            productId,
+            meters: objectAt(usage, "meters"),
+        });
+    });
+    meter
+        .command("add <key>")
+        .option("--product <product>", "Product id or name")
+        .option("--selector <field>", "Selector field, for example model")
+        .option("--measure <measure>", "Measure name; repeatable", collect, [])
+        .option("--rating <source>", "Rating source", "fixed")
+        .option("--catalog <catalog>", "Catalog key for provider_catalog rating")
+        .option("--resolver <resolver>", "Resolver id for external/custom rating")
+        .option("--amount-field <path>", "Amount field for upstream_reported rating")
+        .option("--currency-field <path>", "Currency field for upstream_reported rating")
+        .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 usage = objectAt(spec, "usage");
+        const meters = objectAt(usage, "meters");
+        meters[key] = {
+            ...(opts.selector ? { selector: opts.selector } : {}),
+            measures: opts.measure.length > 0 ? opts.measure : ["count"],
+            rating: ratingFromOptions(opts),
+        };
+        await updateSpec(program, client, productId, spec, {
+            dryRun: opts.dryRun,
+            message: `Meter "${key}" saved`,
+        });
+    });
+    meter
+        .command("rating set <key>")
+        .option("--product <product>", "Product id or name")
+        .requiredOption("--rating <source>", "Rating source")
+        .option("--catalog <catalog>", "Catalog key for provider_catalog rating")
+        .option("--resolver <resolver>", "Resolver id for external/custom rating")
+        .option("--amount-field <path>", "Amount field for upstream_reported rating")
+        .option("--currency-field <path>", "Currency field for upstream_reported rating")
+        .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 usage = objectAt(spec, "usage");
+        const meters = objectAt(usage, "meters");
+        const current = meters[key];
+        if (!current || typeof current !== "object" || Array.isArray(current)) {
+            throw new Error(`Meter "${key}" not found`);
+        }
+        current.rating = ratingFromOptions(opts);
+        await updateSpec(program, client, productId, spec, {
+            dryRun: opts.dryRun,
+            message: `Meter "${key}" rating saved`,
+        });
+    });
+}
+function collect(value, previous) {
+    previous.push(value);
+    return previous;
+}
+function ratingFromOptions(opts) {
+    if (opts.rating === "provider_catalog") {
+        return {
+            source: opts.rating,
+            catalog: opts.catalog ?? "default",
+            pricePolicy: "pass_through",
+        };
+    }
+    if (opts.rating === "upstream_reported") {
+        return {
+            source: opts.rating,
+            amountField: opts.amountField ?? "usage.cost_micros",
+            ...(opts.currencyField ? { currencyField: opts.currencyField } : {}),
+        };
+    }
+    if (opts.rating === "external_rate_api" || opts.rating === "custom") {
+        return { source: opts.rating, resolver: opts.resolver ?? "default" };
+    }
+    return { source: "fixed", rates: {} };
+}

package/dist/commands/plan-transition.d.ts

@@ -0,0 +1,40 @@
+import { Command } from "commander";
+type ChangeKind = "strategy_changed" | "price_increase" | "price_decrease" | "feature_added" | "feature_removed" | "limit_increased" | "limit_reduced" | "credit_increased" | "credit_reduced" | "rating_changed" | "plan_added" | "plan_removed";
+type SubscriberAction = "preserve_current_period" | "switch_immediately" | "switch_immediately_prorate" | "new_subscribers_only";
+type TransitionChange = {
+    kind: ChangeKind;
+    planKey?: string;
+    meter?: string;
+    feature?: string;
+    from?: unknown;
+    to?: unknown;
+    subscriberAction: SubscriberAction;
+    requiresAcknowledgment: boolean;
+    message: string;
+};
+type TransitionAnalysis = {
+    valid: boolean;
+    from: string;
+    to: string;
+    strategy: {
+        from?: string;
+        to?: string;
+    };
+    policy: {
+        default: SubscriberAction;
+        proration: string;
+        when: Record<string, SubscriberAction>;
+    };
+    changes: TransitionChange[];
+    errors: string[];
+    warnings: string[];
+    agentHints: string[];
+};
+export declare function analyzePlanTransition(options: {
+    fromSpec: unknown;
+    toSpec: unknown;
+    fromLabel?: string;
+    toLabel?: string;
+}): TransitionAnalysis;
+export declare function registerPlanTransitionCommand(program: Command): void;
+export {};