@farthershore/cli 0.3.9 → 0.3.11

package/dist/commands/plan-transition.js

@@ -1,504 +0,0 @@
-import { execSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
-import YAML from "yaml";
-import * as output from "../output.js";
-import { loadProductYaml, validateProductYaml } from "./validate.js";
-const CI = !!process.env.CI || !!process.env.GITHUB_ACTIONS;
-const DEFAULT_ACTION = "preserve_current_period";
-const DEFAULT_WHEN = {
-    price_increase: "preserve_current_period",
-    price_decrease: "switch_immediately",
-    feature_added: "switch_immediately",
-    feature_removed: "preserve_current_period",
-    limit_increased: "switch_immediately",
-    limit_reduced: "preserve_current_period",
-    credit_increased: "switch_immediately",
-    credit_reduced: "preserve_current_period",
-    rating_changed: "preserve_current_period",
-    strategy_changed: "preserve_current_period",
-    plan_removed: "preserve_current_period",
-    plan_added: "switch_immediately",
-};
-export function analyzePlanTransition(options) {
-    const from = asRecord(options.fromSpec);
-    const to = asRecord(options.toSpec);
-    const policy = readPolicy(to);
-    const changes = [];
-    const errors = [];
-    const warnings = [];
-    const fromStrategy = readStrategy(from);
-    const toStrategy = readStrategy(to);
-    if (fromStrategy !== toStrategy) {
-        changes.push(makeChange(policy, {
-            kind: "strategy_changed",
-            from: fromStrategy,
-            to: toStrategy,
-            message: `Product strategy changes from ${fromStrategy ?? "unset"} to ${toStrategy ?? "unset"}`,
-        }));
-    }
-    const fromPlans = planMap(from);
-    const toPlans = planMap(to);
-    for (const [planKey, oldPlan] of fromPlans) {
-        const nextPlan = toPlans.get(planKey);
-        if (!nextPlan) {
-            changes.push(makeChange(policy, {
-                kind: "plan_removed",
-                planKey,
-                from: planKey,
-                to: null,
-                message: `Plan "${planKey}" was removed`,
-            }));
-            continue;
-        }
-        comparePlan(planKey, oldPlan, nextPlan, policy, changes);
-    }
-    for (const planKey of toPlans.keys()) {
-        if (!fromPlans.has(planKey)) {
-            changes.push(makeChange(policy, {
-                kind: "plan_added",
-                planKey,
-                from: null,
-                to: planKey,
-                message: `Plan "${planKey}" was added`,
-            }));
-        }
-    }
-    compareRatings(from, to, policy, changes);
-    for (const change of changes) {
-        if (change.kind === "plan_removed" &&
-            change.subscriberAction !== "new_subscribers_only") {
-            const replacement = planReplacement(to, change.planKey);
-            if (!replacement) {
-                errors.push(`Plan "${change.planKey}": removed plan must define archive.transitionTo or use new_subscribers_only`);
-            }
-        }
-        if (change.requiresAcknowledgment) {
-            errors.push(acknowledgmentMessage(change.kind));
-        }
-    }
-    if (changes.length === 0) {
-        warnings.push("No billing-affecting changes detected");
-    }
-    const agentHints = buildAgentHints(changes, errors);
-    return {
-        valid: errors.length === 0,
-        from: options.fromLabel ?? "from",
-        to: options.toLabel ?? "product.yaml",
-        strategy: { from: fromStrategy, to: toStrategy },
-        policy,
-        changes,
-        errors,
-        warnings,
-        agentHints,
-    };
-}
-export function registerPlanTransitionCommand(program) {
-    program
-        .command("plan-transition")
-        .description("Preview billing-affecting product.yaml changes and the subscriber transition policy they imply. Designed for agents and CI before apply.")
-        .option("--from <file>", "Base product.yaml to compare from")
-        .option("--to <file>", "Proposed product.yaml to compare to", "product.yaml")
-        .option("--from-git <ref>", "Read base product.yaml from a git ref, e.g. main:product.yaml")
-        .option("--format <format>", "Output format: table or json", "table")
-        .action((opts) => {
-        const toPath = resolve(opts.to);
-        const toLoaded = loadProductYaml(toPath);
-        if (!toLoaded.ok) {
-            fail(`Could not read proposed product.yaml: ${toLoaded.message}`);
-            return;
-        }
-        const localValidation = validateProductYaml(toLoaded.spec);
-        if (!localValidation.valid) {
-            printValidationFailure(localValidation.errors, opts.format);
-            return;
-        }
-        const base = loadBaseSpec(opts);
-        if (!base.ok) {
-            fail(base.message);
-            return;
-        }
-        const analysis = analyzePlanTransition({
-            fromSpec: base.spec,
-            toSpec: toLoaded.spec,
-            fromLabel: base.label,
-            toLabel: opts.to,
-        });
-        if (opts.format === "json") {
-            console.log(output.json(analysis));
-        }
-        else {
-            printHumanAnalysis(analysis);
-        }
-        if (CI) {
-            for (const err of analysis.errors) {
-                console.log(`::error file=product.yaml::${err}`);
-            }
-            for (const warning of analysis.warnings) {
-                console.log(`::warning file=product.yaml::${warning}`);
-            }
-        }
-        if (!analysis.valid)
-            process.exitCode = 1;
-    });
-}
-function comparePlan(planKey, oldPlan, nextPlan, policy, changes) {
-    const oldPrice = monthlyPrice(oldPlan);
-    const nextPrice = monthlyPrice(nextPlan);
-    if (nextPrice > oldPrice) {
-        changes.push(makeChange(policy, {
-            kind: "price_increase",
-            planKey,
-            from: oldPrice,
-            to: nextPrice,
-            message: `Plan "${planKey}" price increases from ${oldPrice} to ${nextPrice}`,
-        }));
-    }
-    else if (nextPrice < oldPrice) {
-        changes.push(makeChange(policy, {
-            kind: "price_decrease",
-            planKey,
-            from: oldPrice,
-            to: nextPrice,
-            message: `Plan "${planKey}" price decreases from ${oldPrice} to ${nextPrice}`,
-        }));
-    }
-    compareStringSet(planKey, "feature", features(oldPlan), features(nextPlan), policy, changes);
-    compareLimits(planKey, oldPlan, nextPlan, policy, changes);
-    compareCredits(planKey, oldPlan, nextPlan, policy, changes);
-}
-function compareStringSet(planKey, label, oldValues, nextValues, policy, changes) {
-    for (const value of nextValues) {
-        if (!oldValues.has(value)) {
-            changes.push(makeChange(policy, {
-                kind: "feature_added",
-                planKey,
-                feature: value,
-                from: null,
-                to: value,
-                message: `Plan "${planKey}" adds ${label} "${value}"`,
-            }));
-        }
-    }
-    for (const value of oldValues) {
-        if (!nextValues.has(value)) {
-            changes.push(makeChange(policy, {
-                kind: "feature_removed",
-                planKey,
-                feature: value,
-                from: value,
-                to: null,
-                message: `Plan "${planKey}" removes ${label} "${value}"`,
-            }));
-        }
-    }
-}
-function compareLimits(planKey, oldPlan, nextPlan, policy, changes) {
-    const oldLimits = limitsByMeter(oldPlan);
-    const nextLimits = limitsByMeter(nextPlan);
-    for (const [meter, nextCapacity] of nextLimits) {
-        const oldCapacity = oldLimits.get(meter);
-        if (oldCapacity === undefined)
-            continue;
-        if (nextCapacity > oldCapacity) {
-            changes.push(makeChange(policy, {
-                kind: "limit_increased",
-                planKey,
-                meter,
-                from: oldCapacity,
-                to: nextCapacity,
-                message: `Plan "${planKey}" limit for "${meter}" increases from ${oldCapacity} to ${nextCapacity}`,
-            }));
-        }
-        else if (nextCapacity < oldCapacity) {
-            changes.push(makeChange(policy, {
-                kind: "limit_reduced",
-                planKey,
-                meter,
-                from: oldCapacity,
-                to: nextCapacity,
-                message: `Plan "${planKey}" limit for "${meter}" reduces from ${oldCapacity} to ${nextCapacity}`,
-            }));
-        }
-    }
-}
-function compareCredits(planKey, oldPlan, nextPlan, policy, changes) {
-    const oldCredits = includedCredits(oldPlan);
-    const nextCredits = includedCredits(nextPlan);
-    if (nextCredits > oldCredits) {
-        changes.push(makeChange(policy, {
-            kind: "credit_increased",
-            planKey,
-            from: oldCredits,
-            to: nextCredits,
-            message: `Plan "${planKey}" credits increase from ${oldCredits} to ${nextCredits}`,
-        }));
-    }
-    else if (nextCredits < oldCredits) {
-        changes.push(makeChange(policy, {
-            kind: "credit_reduced",
-            planKey,
-            from: oldCredits,
-            to: nextCredits,
-            message: `Plan "${planKey}" credits reduce from ${oldCredits} to ${nextCredits}`,
-        }));
-    }
-}
-function compareRatings(from, to, policy, changes) {
-    const oldRatings = ratingsByMeter(from);
-    const nextRatings = ratingsByMeter(to);
-    for (const [meter, nextRating] of nextRatings) {
-        const oldRating = oldRatings.get(meter);
-        if (oldRating !== undefined &&
-            stableJson(oldRating) !== stableJson(nextRating)) {
-            changes.push(makeChange(policy, {
-                kind: "rating_changed",
-                meter,
-                from: oldRating,
-                to: nextRating,
-                message: `Meter "${meter}" rating changed`,
-            }));
-        }
-    }
-}
-function makeChange(policy, input) {
-    const subscriberAction = actionFor(policy, input.kind);
-    return {
-        ...input,
-        subscriberAction,
-        requiresAcknowledgment: requiresAcknowledgment(input.kind, subscriberAction),
-    };
-}
-function actionFor(policy, kind) {
-    return policy.when[kind] ?? policy.default;
-}
-function requiresAcknowledgment(kind, action) {
-    if (action !== "switch_immediately" &&
-        action !== "switch_immediately_prorate") {
-        return false;
-    }
-    return (kind === "price_increase" ||
-        kind === "feature_removed" ||
-        kind === "limit_reduced" ||
-        kind === "credit_reduced");
-}
-function acknowledgmentMessage(kind) {
-    if (kind === "price_increase") {
-        return "Immediate price increases require billing.subscriberChangePolicy.allowImmediatePriceIncrease: true";
-    }
-    return `Immediate ${kind} requires billing.subscriberChangePolicy.allowImmediateEntitlementReduction: true`;
-}
-function readPolicy(spec) {
-    const billing = asRecord(spec.billing);
-    const policy = asRecord(billing.subscriberChangePolicy);
-    const when = asRecord(policy.when);
-    const defaultAction = subscriberAction(policy.default) ?? DEFAULT_ACTION;
-    return {
-        default: defaultAction,
-        proration: typeof policy.proration === "string" ? policy.proration : "none",
-        when: Object.fromEntries(Object.entries(DEFAULT_WHEN).map(([key, fallback]) => [
-            key,
-            subscriberAction(when[key]) ?? fallback ?? defaultAction,
-        ])),
-    };
-}
-function subscriberAction(value) {
-    if (value === "preserve_current_period" ||
-        value === "switch_immediately" ||
-        value === "switch_immediately_prorate" ||
-        value === "new_subscribers_only") {
-        return value;
-    }
-    return undefined;
-}
-function readStrategy(spec) {
-    const billing = asRecord(spec.billing);
-    return typeof billing.strategy === "string" ? billing.strategy : undefined;
-}
-function planMap(spec) {
-    const plans = Array.isArray(spec.plans) ? spec.plans : [];
-    const map = new Map();
-    for (const plan of plans) {
-        const record = asRecord(plan);
-        if (typeof record.key === "string")
-            map.set(record.key, record);
-    }
-    return map;
-}
-function monthlyPrice(plan) {
-    const price = asRecord(plan.price);
-    const pricing = asRecord(plan.pricing);
-    if (typeof price.monthly === "number")
-        return price.monthly;
-    return typeof pricing.monthlyPriceCents === "number"
-        ? pricing.monthlyPriceCents
-        : 0;
-}
-function features(plan) {
-    const compact = Array.isArray(plan.features) ? plan.features : [];
-    const gates = asRecord(plan.featureGates);
-    const values = compact.filter((value) => typeof value === "string");
-    for (const [key, enabled] of Object.entries(gates)) {
-        if (enabled === true)
-            values.push(key);
-    }
-    return new Set(values);
-}
-function limitsByMeter(plan) {
-    const limits = Array.isArray(plan.limits) ? plan.limits : [];
-    const map = new Map();
-    for (const rawLimit of limits) {
-        const limit = asRecord(rawLimit);
-        const meter = stringValue(limit.meter) ?? stringValue(limit.dimension);
-        if (!meter || typeof limit.capacity !== "number")
-            continue;
-        map.set(meter, limit.capacity);
-    }
-    return map;
-}
-function includedCredits(plan) {
-    const credits = asRecord(plan.credits);
-    return typeof credits.monthlyIncludedMicros === "number"
-        ? credits.monthlyIncludedMicros
-        : 0;
-}
-function ratingsByMeter(spec) {
-    const usage = asRecord(spec.usage);
-    const meters = asRecord(usage.meters);
-    const map = new Map();
-    for (const [meter, raw] of Object.entries(meters)) {
-        const rating = asRecord(raw).rating;
-        if (rating !== undefined)
-            map.set(meter, rating);
-    }
-    return map;
-}
-function planReplacement(spec, planKey) {
-    if (!planKey)
-        return undefined;
-    const plan = planMap(spec).get(planKey);
-    const archive = asRecord(plan?.archive);
-    return typeof archive.transitionTo === "string"
-        ? archive.transitionTo
-        : undefined;
-}
-function asRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value)
-        ? value
-        : {};
-}
-function stringValue(value) {
-    return typeof value === "string" ? value : undefined;
-}
-function stableJson(value) {
-    if (Array.isArray(value))
-        return `[${value.map(stableJson).join(",")}]`;
-    if (value && typeof value === "object") {
-        return `{${Object.entries(value)
-            .sort(([a], [b]) => a.localeCompare(b))
-            .map(([key, val]) => `${JSON.stringify(key)}:${stableJson(val)}`)
-            .join(",")}}`;
-    }
-    return JSON.stringify(value);
-}
-function buildAgentHints(changes, errors) {
-    const hints = [];
-    if (errors.length > 0) {
-        hints.push("Fix errors before running farthershore apply.");
-    }
-    if (changes.some((change) => change.kind === "plan_removed")) {
-        hints.push("For removed plans with active subscribers, add archive.transitionTo or set the relevant policy to new_subscribers_only.");
-    }
-    if (changes.some((change) => change.requiresAcknowledgment)) {
-        hints.push("Avoid immediate harmful changes unless the YAML explicitly acknowledges them.");
-    }
-    if (changes.length > 0) {
-        hints.push("New subscribers use the proposed product.yaml immediately; listed subscriberAction values apply to existing subscribers.");
-    }
-    return hints;
-}
-function loadBaseSpec(opts) {
-    if (opts.fromGit) {
-        try {
-            const content = execSync(`git show ${shellQuote(opts.fromGit)}`, {
-                encoding: "utf-8",
-                stdio: ["pipe", "pipe", "pipe"],
-            });
-            return { ok: true, spec: YAML.parse(content), label: opts.fromGit };
-        }
-        catch {
-            return { ok: false, message: `Could not read ${opts.fromGit} from git` };
-        }
-    }
-    if (opts.from) {
-        const fromPath = resolve(opts.from);
-        const loaded = loadProductYaml(fromPath);
-        if (!loaded.ok)
-            return { ok: false, message: loaded.message };
-        return { ok: true, spec: loaded.spec, label: opts.from };
-    }
-    for (const ref of ["main:product.yaml", "master:product.yaml"]) {
-        try {
-            const content = execSync(`git show ${ref}`, {
-                encoding: "utf-8",
-                stdio: ["pipe", "pipe", "pipe"],
-            });
-            return { ok: true, spec: YAML.parse(content), label: ref };
-        }
-        catch {
-            continue;
-        }
-    }
-    if (existsSync(resolve("product.yaml"))) {
-        return {
-            ok: false,
-            message: "No base product.yaml found. Pass --from old-product.yaml or --from-git main:product.yaml.",
-        };
-    }
-    return {
-        ok: false,
-        message: "No product.yaml found. Pass --to product.yaml.",
-    };
-}
-function shellQuote(value) {
-    return `'${value.replaceAll("'", "'\\''")}'`;
-}
-function printHumanAnalysis(analysis) {
-    output.heading(`Plan transition: ${analysis.from} → ${analysis.to}`);
-    console.log(`Strategy: ${analysis.strategy.from ?? "unset"} → ${analysis.strategy.to ?? "unset"}`);
-    console.log(`Default existing-subscriber action: ${analysis.policy.default}`);
-    if (analysis.changes.length === 0) {
-        output.success("No billing-affecting changes detected");
-    }
-    else {
-        for (const change of analysis.changes) {
-            const ack = change.requiresAcknowledgment
-                ? " requires acknowledgment"
-                : "";
-            console.log(`  • ${change.message} → ${change.subscriberAction}${ack}`);
-        }
-    }
-    for (const warning of analysis.warnings)
-        output.warn(warning);
-    for (const err of analysis.errors)
-        output.error(err);
-    for (const hint of analysis.agentHints)
-        output.info(`hint: ${hint}`);
-}
-function printValidationFailure(errors, format) {
-    if (format === "json") {
-        console.log(output.json({ valid: false, errors }));
-    }
-    else {
-        output.error("Proposed product.yaml is invalid");
-        for (const err of errors)
-            console.log(`  • ${err}`);
-    }
-    process.exitCode = 1;
-}
-function fail(message) {
-    if (CI)
-        console.log(`::error file=product.yaml::${message}`);
-    output.error(message);
-    process.exitCode = 1;
-}

package/dist/commands/plan.d.ts

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