@farthershore/cli 0.3.9 → 0.3.11

package/dist/commands/feature.js

@@ -1,109 +0,0 @@
-import { findPlan, loadAcceptedSpec, objectAt, printResult, resolveProductId, stringArrayAt, updateSpec, } from "./helpers.js";
-export function registerFeatureCommands(program, getClient) {
-    const feature = program
-        .command("feature")
-        .description("Manage route-bound product features")
-        .addHelpText("after", `
-Agent notes:
-  Features gate routes. Add a feature with one or more METHOD:/path routes, then bind it to plans.
-  Use METHOD:* only when the feature should cover all methods for a path.
-
-Examples:
-  farthershore feature add chat_completions --route POST:/v1/chat/completions --format json
-  farthershore feature bind chat_completions --plan pro --format json
-  farthershore feature list --format json
-`);
-    feature
-        .command("list")
-        .option("--product <product>", "Product id or name")
-        .addHelpText("after", `
-Example:
-  farthershore feature list --format json
-`)
-        .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")
-        .addHelpText("after", `
-Examples:
-  farthershore feature add chat_completions --route POST:/v1/chat/completions --format json
-  farthershore feature add weather_read --route GET:/v1/weather --route GET:/v1/forecast --dry-run --format json
-`)
-        .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")
-        .addHelpText("after", `
-Example:
-  farthershore feature bind chat_completions --plan pro --format json
-`)
-        .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")
-        .addHelpText("after", `
-Example:
-  farthershore feature unbind chat_completions --plan starter --format json
-`)
-        .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

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

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

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

package/dist/commands/init.js

@@ -1,43 +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")
-        .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.d.ts

@@ -1,2 +0,0 @@
-import { Command } from "commander";
-export declare function registerAuthCommands(program: Command): void;

package/dist/commands/login.js

@@ -1,144 +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) {
-    const auth = program
-        .command("auth")
-        .description("Manage authentication")
-        .addHelpText("after", `
-Agent notes:
-  Prefer FARTHERSHORE_TOKEN in CI/agent environments. Use auth set-key for local persistent credentials.
-
-Examples:
-  farthershore auth set-key "$FARTHERSHORE_TOKEN"
-  farthershore whoami --format json
-`);
-    auth
-        .command("set-key [token]")
-        .description("Set your API token")
-        .addHelpText("after", `
-Examples:
-  farthershore auth set-key mk_xxx
-  farthershore auth set-key "$FARTHERSHORE_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

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

package/dist/commands/meter.js

@@ -1,121 +0,0 @@
-import { loadAcceptedSpec, objectAt, printResult, resolveProductId, updateSpec, } from "./helpers.js";
-export function registerMeterCommands(program, getClient) {
-    const meter = program
-        .command("meter")
-        .description("Manage product usage meters and rating sources")
-        .addHelpText("after", `
-Agent notes:
-  Meters define what usage is measured. Plans reference meters; plans do not define provider-specific rates.
-  Rating sources: fixed, provider_catalog, upstream_reported, external_rate_api, custom.
-
-Examples:
-  farthershore meter add ai_tokens --selector model --measure input_tokens --measure output_tokens --rating provider_catalog --catalog llm_models --format json
-  farthershore meter add requests --measure count --rating fixed --format json
-  farthershore meter list --format json
-`);
-    meter
-        .command("list")
-        .option("--product <product>", "Product id or name")
-        .addHelpText("after", `
-Example:
-  farthershore meter list --format json
-`)
-        .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, provider_catalog, upstream_reported, external_rate_api, custom", "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")
-        .addHelpText("after", `
-Examples:
-  farthershore meter add ai_tokens --selector model --measure input_tokens --measure output_tokens --rating provider_catalog --catalog llm_models --format json
-  farthershore meter add requests --measure count --rating fixed --dry-run --format json
-  farthershore meter add upstream_cost --measure cost_micros --rating upstream_reported --amount-field usage.cost_micros --format json
-`)
-        .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: fixed, provider_catalog, upstream_reported, external_rate_api, custom")
-        .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")
-        .addHelpText("after", `
-Examples:
-  farthershore meter rating set ai_tokens --rating provider_catalog --catalog llm_models --format json
-  farthershore meter rating set upstream_cost --rating upstream_reported --amount-field usage.cost_micros --dry-run --format json
-`)
-        .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

@@ -1,40 +0,0 @@
-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 {};