@farthershore/cli 0.3.7 → 0.3.9

package/dist/commands/plan.js

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

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

package/dist/commands/product.js

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

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

package/dist/commands/transition.js

@@ -0,0 +1,80 @@
+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.js

@@ -0,0 +1,216 @@
+import { readFileSync, existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { resolve } from "node:path";
+import YAML from "yaml";
+import { productSpecSchema, } from "@farther-shore/shared-types/plans";
+import * as output from "../output.js";
+const CI = !!process.env.CI || !!process.env.GITHUB_ACTIONS;
+/**
+ * Read product.yaml from the main branch using git, without checking it out.
+ * Returns null if not in a git repo or main doesn't have the file.
+ */
+function readMainBranchProductName() {
+    for (const branch of ["main", "master"]) {
+        try {
+            const yaml = execSync(`git show ${branch}:product.yaml 2>/dev/null`, {
+                encoding: "utf-8",
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            const spec = YAML.parse(yaml);
+            const product = spec.product;
+            return product?.name ?? null;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * 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 function validateProductYaml(spec) {
+    const result = productSpecSchema.safeParse(spec);
+    if (!result.success) {
+        return {
+            valid: false,
+            errors: result.error.issues.map((issue) => formatIssue(issue, spec)),
+            warnings: [],
+        };
+    }
+    const warnings = deriveWarnings(result.data);
+    // Schema doesn't enforce duplicate plan keys (it would conflict with the
+    // discriminated-union design). Detect here as a separate check so the CLI
+    // surfaces this footgun before the server rejects the apply.
+    const dupeKeys = findDuplicatePlanKeys(result.data);
+    if (dupeKeys.length > 0) {
+        return {
+            valid: false,
+            errors: [`Duplicate plan keys: ${dupeKeys.join(", ")}`],
+            warnings,
+        };
+    }
+    return { valid: true, errors: [], warnings };
+}
+function formatIssue(issue, spec) {
+    const path = issue.path;
+    // Plans are addressed positionally in path (e.g. ["plans", 0, "key"]). Look
+    // up the plan key from the spec so the error message reads
+    // `Plan "starter": pricing is required` instead of `plans.0.pricing: ...`.
+    if (path.length >= 2 && path[0] === "plans" && typeof path[1] === "number") {
+        const plans = spec?.plans ?? [];
+        const plan = plans[path[1]];
+        const planLabel = plan?.key ?? plan?.name ?? `#${path[1]}`;
+        const fieldPath = path.slice(2).join(".");
+        if (fieldPath) {
+            return `Plan "${planLabel}": ${fieldPath} — ${issue.message}`;
+        }
+        return `Plan "${planLabel}": ${issue.message}`;
+    }
+    const dotted = path.length > 0 ? path.join(".") : "(root)";
+    return `${dotted}: ${issue.message}`;
+}
+function deriveWarnings(parsed) {
+    const warnings = [];
+    if (parsed.plans.length === 0) {
+        // Schema accepts an empty plan list (default), but a product with no
+        // plans can't go live — surface as a warning so the builder sees the
+        // requirement before pushing.
+        warnings.push("No plans declared — product cannot accept signups yet");
+    }
+    else {
+        const hasFree = parsed.plans.some((plan) => {
+            const monthly = "monthlyPriceCents" in plan.pricing
+                ? plan.pricing.monthlyPriceCents
+                : undefined;
+            return monthly === 0;
+        });
+        if (!hasFree) {
+            warnings.push("No free plan — consider adding one for developer adoption");
+        }
+    }
+    if (!parsed.product.displayName ||
+        parsed.product.displayName === parsed.product.name) {
+        warnings.push("product.displayName not set — using product.name on the pricing page");
+    }
+    return warnings;
+}
+function findDuplicatePlanKeys(parsed) {
+    const seen = new Set();
+    const dupes = new Set();
+    for (const plan of parsed.plans) {
+        if (seen.has(plan.key)) {
+            dupes.add(plan.key);
+        }
+        else {
+            seen.add(plan.key);
+        }
+    }
+    return [...dupes];
+}
+/**
+ * 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 function loadProductYaml(filePath) {
+    if (!existsSync(filePath)) {
+        return { ok: false, reason: "missing", message: filePath };
+    }
+    try {
+        const content = readFileSync(filePath, "utf-8");
+        return { ok: true, spec: YAML.parse(content) };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: "parse",
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Print a ValidationResult to stdout, optionally emitting GitHub
+ * Actions annotations. Sets `process.exitCode = 1` on validation
+ * failure so the CLI exits non-zero.
+ */
+function reportValidationResult(result) {
+    if (CI) {
+        for (const err of result.errors) {
+            console.log(`::error file=product.yaml::${err}`);
+        }
+        for (const w of result.warnings) {
+            console.log(`::warning file=product.yaml::${w}`);
+        }
+    }
+    if (result.errors.length === 0) {
+        output.success("product.yaml is valid");
+        for (const w of result.warnings) {
+            output.warn(w);
+        }
+        return;
+    }
+    output.error(`product.yaml has ${result.errors.length} error(s):\n`);
+    for (const err of result.errors) {
+        console.log(`  • ${err}`);
+    }
+    if (result.warnings.length > 0) {
+        console.log();
+        for (const w of result.warnings) {
+            output.warn(w);
+        }
+    }
+    process.exitCode = 1;
+}
+export function registerValidateCommand(program) {
+    program
+        .command("validate [file]")
+        .description("Validate a local product.yaml file without API calls")
+        .addHelpText("after", `
+Agent notes:
+  Use validate before committing product.yaml changes. This is local schema validation only.
+  Use apply --dry-run for remote compiler validation against pushed branch state.
+
+Examples:
+  farthershore validate
+  farthershore validate product.yaml
+  farthershore apply --dry-run --format json
+`)
+        // Action body is sync; commander only requires a thenable on
+        // .action when await is used. Drop `async` keyword.
+        .action((file) => {
+        const filePath = resolve(file ?? "product.yaml");
+        const loaded = loadProductYaml(filePath);
+        if (!loaded.ok) {
+            if (loaded.reason === "missing") {
+                if (CI)
+                    console.log(`::error file=product.yaml::File not found: ${loaded.message}`);
+                output.error(`File not found: ${loaded.message}`);
+            }
+            else {
+                if (CI)
+                    console.log(`::error file=product.yaml::YAML parse error: ${loaded.message}`);
+                output.error(`Failed to parse YAML: ${loaded.message}`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const result = validateProductYaml(loaded.spec);
+        // Check product.name consistency against main branch
+        const currentName = loaded.spec
+            ?.product?.name;
+        if (currentName) {
+            const mainName = readMainBranchProductName();
+            if (mainName && mainName !== currentName) {
+                result.errors.push(`product.name "${currentName}" differs from main branch "${mainName}" — product name must not change`);
+                result.valid = false;
+            }
+        }
+        reportValidationResult(result);
+    });
+}