@farthershore/cli 0.3.9 → 0.3.11

package/dist/commands/plan.js

@@ -1,234 +0,0 @@
-import { findPlan, loadAcceptedSpec, plans, printResult, resolveProductId, stringArrayAt, updateSpec, } from "./helpers.js";
-export function registerPlanCommands(program, getClient) {
-    const plan = program
-        .command("plan")
-        .description("Manage free and paid plans in the accepted product config")
-        .addHelpText("after", `
-Agent notes:
-  Plans are keyed by plan name/key, not by usage type.
-  Only one free plan is allowed. Free plans should include a hard enforced limit.
-  Duplicate paid prices are rejected server-side. Use --dry-run before risky changes.
-  Limit format is meter:window:capacity:enforcement, for example ai_tokens:month:100000:enforce.
-
-Examples:
-  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 plan list --format json
-`);
-    plan
-        .command("list")
-        .option("--product <product>", "Product id or name")
-        .addHelpText("after", `
-Example:
-  farthershore plan list --format json
-`)
-        .action(async (opts) => {
-        const client = getClient();
-        const productId = await resolveProductId(client, opts.product);
-        const spec = await loadAcceptedSpec(client, productId);
-        printResult(program, "Plans loaded", {
-            ok: true,
-            productId,
-            plans: plans(spec),
-        });
-    });
-    plan
-        .command("add <key>")
-        .option("--product <product>", "Product id or name")
-        .option("--name <name>", "Plan display name")
-        .option("--free", "Create a free hard-limited plan")
-        .option("--price-monthly <cents>", "Monthly price in cents", parseInteger)
-        .option("--credits-monthly-micros <micros>", "Monthly included credits", parseInteger)
-        .option("--meter <meter>", "Included meter; repeatable", collect, [])
-        .option("--feature <feature>", "Enabled feature; repeatable", collect, [])
-        .option("--limit <limit>", "Limit meter:window:capacity:enforcement; repeatable", collect, [])
-        .option("--dry-run", "Validate without mutating")
-        .addHelpText("after", `
-Examples:
-  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 plan add starter --price-monthly 900 --meter requests --feature weather_read --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 existing = plans(spec);
-        const index = existing.findIndex((candidate) => candidate.key === key);
-        const nextPlan = buildPlan(key, opts);
-        if (index === -1)
-            existing.push(nextPlan);
-        else
-            existing[index] = { ...existing[index], ...nextPlan };
-        await updateSpec(program, client, productId, spec, {
-            dryRun: opts.dryRun,
-            message: `Plan "${key}" saved`,
-        });
-    });
-    plan
-        .command("set-price <key>")
-        .option("--product <product>", "Product id or name")
-        .requiredOption("--monthly <cents>", "Monthly price in cents", parseInteger)
-        .option("--currency <currency>", "Currency", "USD")
-        .option("--dry-run", "Validate without mutating")
-        .addHelpText("after", `
-Example:
-  farthershore plan set-price pro --monthly 4900 --dry-run --format json
-`)
-        .action(async (key, opts) => {
-        await mutatePlan(program, getClient(), opts.product, key, opts.dryRun, (plan) => {
-            plan.free = false;
-            plan.price = { monthly: opts.monthly, currency: opts.currency };
-            plan.pricing = {
-                model: "flat_rate",
-                monthlyPriceCents: opts.monthly,
-                billingInterval: "month",
-            };
-        });
-    });
-    plan
-        .command("set-limit <key>")
-        .option("--product <product>", "Product id or name")
-        .requiredOption("--limit <limit>", "Limit meter:window:capacity:enforcement")
-        .option("--dry-run", "Validate without mutating")
-        .addHelpText("after", `
-Examples:
-  farthershore plan set-limit free --limit ai_tokens:month:100000:enforce --format json
-  farthershore plan set-limit pro --limit ai_tokens:month:1000000:track --dry-run --format json
-`)
-        .action(async (key, opts) => {
-        await mutatePlan(program, getClient(), opts.product, key, opts.dryRun, (plan) => {
-            const next = parseLimit(opts.limit);
-            const limits = Array.isArray(plan.limits)
-                ? plan.limits
-                : [];
-            const index = limits.findIndex((limit) => limit.meter === next.meter || limit.dimension === next.meter);
-            if (index === -1)
-                limits.push(next);
-            else
-                limits[index] = next;
-            plan.limits = limits;
-        });
-    });
-    plan
-        .command("set-credits <key>")
-        .option("--product <product>", "Product id or name")
-        .requiredOption("--monthly-micros <micros>", "Monthly included credits", parseInteger)
-        .option("--dry-run", "Validate without mutating")
-        .addHelpText("after", `
-Example:
-  farthershore plan set-credits pro --monthly-micros 500000000 --format json
-`)
-        .action(async (key, opts) => {
-        await mutatePlan(program, getClient(), opts.product, key, opts.dryRun, (plan) => {
-            plan.credits = { monthlyIncludedMicros: opts.monthlyMicros };
-        });
-    });
-    plan
-        .command("add-feature <key>")
-        .argument("<feature>")
-        .option("--product <product>", "Product id or name")
-        .option("--dry-run", "Validate without mutating")
-        .addHelpText("after", `
-Example:
-  farthershore plan add-feature pro chat_completions --format json
-`)
-        .action(async (key, feature, opts) => {
-        await mutatePlan(program, getClient(), opts.product, key, opts.dryRun, (plan) => {
-            const features = stringArrayAt(plan, "features");
-            if (!features.includes(feature))
-                features.push(feature);
-        });
-    });
-    plan
-        .command("remove-feature <key>")
-        .argument("<feature>")
-        .option("--product <product>", "Product id or name")
-        .option("--dry-run", "Validate without mutating")
-        .addHelpText("after", `
-Example:
-  farthershore plan remove-feature starter chat_completions --dry-run --format json
-`)
-        .action(async (key, feature, opts) => {
-        await mutatePlan(program, getClient(), opts.product, key, opts.dryRun, (plan) => {
-            plan.features = stringArrayAt(plan, "features").filter((candidate) => candidate !== feature);
-        });
-    });
-    plan
-        .command("remove <key>")
-        .option("--product <product>", "Product id or name")
-        .option("--dry-run", "Validate without mutating")
-        .addHelpText("after", `
-Example:
-  farthershore plan remove starter --dry-run --format json
-`)
-        .action(async (key, opts) => {
-        const client = getClient();
-        const productId = await resolveProductId(client, opts.product);
-        const spec = await loadAcceptedSpec(client, productId);
-        spec.plans = plans(spec).filter((candidate) => candidate.key !== key);
-        await updateSpec(program, client, productId, spec, {
-            dryRun: opts.dryRun,
-            message: `Plan "${key}" removed`,
-        });
-    });
-}
-function buildPlan(key, opts) {
-    const monthly = opts.free ? 0 : (opts.priceMonthly ?? 0);
-    const plan = {
-        key,
-        name: opts.name ?? titleize(key),
-        free: opts.free === true,
-        price: { monthly, currency: "USD" },
-        pricing: {
-            model: "flat_rate",
-            monthlyPriceCents: monthly,
-            billingInterval: "month",
-        },
-        usage: { meters: opts.meter },
-        features: opts.feature,
-        limits: opts.limit.map(parseLimit),
-    };
-    if (opts.creditsMonthlyMicros !== undefined) {
-        plan.credits = { monthlyIncludedMicros: opts.creditsMonthlyMicros };
-    }
-    return plan;
-}
-async function mutatePlan(program, client, productArg, key, dryRun, mutate) {
-    const productId = await resolveProductId(client, productArg);
-    const spec = await loadAcceptedSpec(client, productId);
-    mutate(findPlan(spec, key));
-    await updateSpec(program, client, productId, spec, {
-        dryRun,
-        message: `Plan "${key}" updated`,
-    });
-}
-function parseLimit(value) {
-    const [meter, windowName, capacity, enforcement] = value.split(":");
-    if (!meter || !windowName || !capacity) {
-        throw new Error("Limit must be meter:window:capacity[:enforce|track]");
-    }
-    return {
-        meter,
-        window: { type: "named", name: windowName },
-        capacity: Number(capacity),
-        enforcement: enforcement ?? "enforce",
-    };
-}
-function collect(value, previous) {
-    previous.push(value);
-    return previous;
-}
-function parseInteger(value) {
-    const parsed = Number.parseInt(value, 10);
-    if (!Number.isFinite(parsed))
-        throw new Error(`Invalid integer: ${value}`);
-    return parsed;
-}
-function titleize(value) {
-    return value
-        .split(/[-_]/)
-        .filter(Boolean)
-        .map((part) => part.slice(0, 1).toUpperCase() + part.slice(1))
-        .join(" ");
-}

package/dist/commands/product.d.ts

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

package/dist/commands/product.js

@@ -1,137 +0,0 @@
-import { saveConfig } from "../config.js";
-import * as output from "../output.js";
-import { commandFormat, printResult, resolveProductId } from "./helpers.js";
-export function registerProductCommands(program, getClient) {
-    const product = program
-        .command("product")
-        .description("Manage products and inspect the latest accepted internal product config")
-        .addHelpText("after", `
-Agent notes:
-  Product commands use core APIs, not local files. After product create, the product is selected in ~/.farthershore/config.json.
-  GitHub, UI, and CLI edits are proposals. product config/status read the accepted internal config.
-
-Examples:
-  farthershore product create weather-api --base-url https://api.example.com --strategy prepaid_credits --format json
-  farthershore product status --format json
-  farthershore product config --format yaml
-  farthershore product attempts --format json
-`);
-    product
-        .command("create <name>")
-        .description("Create a product, initialize accepted config, and select it for later commands")
-        .requiredOption("--base-url <url>", "Backend API base URL")
-        .option("--strategy <strategy>", "Product billing strategy: free_trial, flat_subscription, included_usage, subscription_overage, pay_as_you_go, prepaid_credits", "flat_subscription")
-        .option("--description <desc>", "Product description")
-        .option("--display-name <name>", "Display name")
-        .option("--dry-run", "Print the create request without mutating")
-        .addHelpText("after", `
-Examples:
-  farthershore product create weather-api --base-url https://api.example.com --format json
-  farthershore product create ai-gateway --base-url https://api.example.com --strategy prepaid_credits --format json
-
-Next commands:
-  farthershore meter add --help
-  farthershore feature add --help
-  farthershore plan add --help
-`)
-        .action(async (name, opts) => {
-        if (opts.dryRun) {
-            printResult(program, "Product create dry run", {
-                ok: true,
-                dryRun: true,
-                proposal: {
-                    name,
-                    baseUrl: opts.baseUrl,
-                    description: opts.description,
-                    displayName: opts.displayName,
-                    billingStrategy: opts.strategy,
-                    subscriberChangePolicy: {
-                        default: "preserve_current_period",
-                        proration: "none",
-                    },
-                },
-                nextActions: ["Run without --dry-run to create the product"],
-            });
-            return;
-        }
-        const client = getClient();
-        const result = await client.initProduct({
-            name,
-            baseUrl: opts.baseUrl,
-            description: opts.description,
-            displayName: opts.displayName,
-            billingStrategy: opts.strategy,
-            subscriberChangePolicy: {
-                default: "preserve_current_period",
-                proration: "none",
-            },
-        });
-        saveConfig({
-            activeProductId: result.product.id,
-            activeProductName: result.product.name,
-        });
-        printResult(program, `Created product "${result.product.name}"`, {
-            ok: true,
-            productId: result.product.id,
-            product: result.product,
-            repo: result.repo,
-            githubSyncStatus: result.product
-                .acceptedProductSpecGithubSyncStatus ?? null,
-            nextActions: [
-                "Add meters, features, and plans",
-                "Run farthershore apply --dry-run --format json",
-            ],
-        });
-    });
-    product
-        .command("status")
-        .description("Show selected product status")
-        .option("--product <product>", "Product id or name")
-        .addHelpText("after", `
-Example:
-  farthershore product status --format json
-`)
-        .action(async (opts) => {
-        const client = getClient();
-        const productId = await resolveProductId(client, opts.product);
-        const config = await client.getProductConfig(productId);
-        printResult(program, "Product status loaded", {
-            ok: true,
-            productId,
-            ...(typeof config === "object" && config ? config : {}),
-        });
-    });
-    product
-        .command("config")
-        .description("Show latest accepted internal product config as json or yaml")
-        .option("--product <product>", "Product id or name")
-        .option("--format <format>", "Output format: json or yaml")
-        .addHelpText("after", `
-Examples:
-  farthershore product config --format json
-  farthershore product config --format yaml
-`)
-        .action(async (opts) => {
-        const client = getClient();
-        const productId = await resolveProductId(client, opts.product);
-        const format = opts.format ?? commandFormat(program);
-        if (format === "yaml") {
-            console.log(await client.getProductConfigYaml(productId));
-            return;
-        }
-        console.log(output.json(await client.getProductConfig(productId)));
-    });
-    product
-        .command("attempts")
-        .description("Show rejected product config attempts")
-        .option("--product <product>", "Product id or name")
-        .addHelpText("after", `
-Example:
-  farthershore product attempts --format json
-`)
-        .action(async (opts) => {
-        const client = getClient();
-        const productId = await resolveProductId(client, opts.product);
-        console.log(output.json(await client.getProductAttempts(productId)));
-    });
-}

package/dist/commands/transition.d.ts

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

package/dist/commands/transition.js

@@ -1,80 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
-import YAML from "yaml";
-import * as output from "../output.js";
-import { loadAcceptedSpec, resolveProductId } from "./helpers.js";
-import { analyzePlanTransition } from "./plan-transition.js";
-export function registerTransitionCommands(program, getClient) {
-    const transition = program
-        .command("transition")
-        .description("Preview subscriber impact for product config changes")
-        .addHelpText("after", `
-Agent notes:
-  New subscribers use accepted config immediately. Existing subscribers follow billing.subscriberChangePolicy.
-  Preview before price, feature, limit, credit, rating, or strategy changes.
-
-Examples:
-  farthershore transition preview --format json
-  farthershore transition preview --to product.yaml --format json
-`);
-    transition
-        .command("preview")
-        .description("Compare the latest accepted config to a proposed config and show subscriber transition impact")
-        .option("--product <product>", "Product id or name")
-        .option("--to <file>", "Proposed product YAML file")
-        .option("--format <format>", "Output format: table or json")
-        .addHelpText("after", `
-Examples:
-  farthershore transition preview --format json
-  farthershore transition preview --to product.yaml --format json
-
-Output includes:
-  ok, productId, transitionPreview, errors, warnings, nextActions
-`)
-        .action(async (opts) => {
-        const client = getClient();
-        const productId = await resolveProductId(client, opts.product);
-        const accepted = await loadAcceptedSpec(client, productId);
-        const proposed = loadProposedSpec(opts.to) ?? accepted;
-        const analysis = analyzePlanTransition({
-            fromSpec: accepted,
-            toSpec: proposed,
-            fromLabel: "acceptedProductSpec",
-            toLabel: opts.to ?? "acceptedProductSpec",
-        });
-        const globalOpts = program.opts();
-        const format = opts.format ?? output.outputFormat(globalOpts.format);
-        if (format === "json") {
-            console.log(output.json({
-                ok: analysis.valid,
-                productId,
-                transitionPreview: analysis,
-                errors: analysis.errors,
-                warnings: analysis.warnings,
-                nextActions: analysis.agentHints,
-            }));
-            if (!analysis.valid)
-                process.exitCode = 1;
-            return;
-        }
-        if (analysis.valid)
-            output.success("Transition preview passed");
-        else
-            output.error("Transition preview failed");
-        for (const change of analysis.changes) {
-            console.log(`  • ${change.message} -> ${change.subscriberAction}`);
-        }
-        for (const warning of analysis.warnings)
-            output.warn(warning);
-        for (const error of analysis.errors)
-            output.error(error);
-        if (!analysis.valid)
-            process.exitCode = 1;
-    });
-}
-function loadProposedSpec(file) {
-    const path = resolve(file ?? "product.yaml");
-    if (!existsSync(path))
-        return null;
-    return YAML.parse(readFileSync(path, "utf-8"));
-}

package/dist/commands/validate.d.ts

@@ -1,28 +0,0 @@
-import { Command } from "commander";
-/**
- * Validate a parsed YAML object against the canonical Zod schema.
- *
- * Errors are returned in the same `Plan "key": message` shape the previous
- * hand-rolled checks produced, so existing CI output stays grep-friendly.
- * Warnings cover product-quality nudges (no free plan, missing display name)
- * that don't fail the schema parse but are worth flagging.
- */
-export declare function validateProductYaml(spec: unknown): {
-    valid: boolean;
-    errors: string[];
-    warnings: string[];
-};
-/**
- * Read + parse a product.yaml file. Returns either the parsed spec or
- * a structured error result. Extracted from the validate command so
- * the action handler stays under the cognitive-complexity threshold.
- */
-export declare function loadProductYaml(filePath: string): {
-    ok: true;
-    spec: unknown;
-} | {
-    ok: false;
-    reason: "missing" | "parse";
-    message: string;
-};
-export declare function registerValidateCommand(program: Command): void;