@farthershore/cli 0.3.7 → 0.3.8

package/dist/commands/product.js

@@ -0,0 +1,101 @@
+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");
+    product
+        .command("create <name>")
+        .description("Create a product and select it for subsequent CLI commands")
+        .requiredOption("--base-url <url>", "Backend API base URL")
+        .option("--strategy <strategy>", "Product billing strategy", "flat_subscription")
+        .option("--description <desc>", "Product description")
+        .option("--display-name <name>", "Display name")
+        .option("--dry-run", "Print the create request without mutating")
+        .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")
+        .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")
+        .option("--product <product>", "Product id or name")
+        .option("--format <format>", "Output format: json or 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")
+        .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,63 @@
+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");
+    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")
+        .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,206 @@
+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")
+        // 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);
+    });
+}

package/dist/config.js

@@ -0,0 +1,58 @@
+// ~/.farthershore/ config management
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { BUILD_API_URL } from "./build-info.js";
+const CONFIG_DIR = join(homedir(), ".farthershore");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+const CREDENTIALS_FILE = join(CONFIG_DIR, "credentials.json");
+function ensureDir(dir) {
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+// --- Config ---
+const DEFAULT_CONFIG = {
+    apiUrl: BUILD_API_URL,
+    defaultFormat: "table",
+};
+export function loadConfig() {
+    ensureDir(CONFIG_DIR);
+    if (!existsSync(CONFIG_FILE))
+        return DEFAULT_CONFIG;
+    try {
+        // JSON.parse → `any`; cast to a partial of the typed shape so the
+        // spread doesn't propagate `any` into the returned union.
+        const parsed = JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+        return { ...DEFAULT_CONFIG, ...parsed };
+    }
+    catch {
+        return DEFAULT_CONFIG;
+    }
+}
+export function saveConfig(config) {
+    ensureDir(CONFIG_DIR);
+    const current = loadConfig();
+    writeFileSync(CONFIG_FILE, JSON.stringify({ ...current, ...config }, null, 2) + "\n");
+}
+// --- Credentials ---
+export function loadCredentials() {
+    if (!existsSync(CREDENTIALS_FILE))
+        return null;
+    try {
+        return JSON.parse(readFileSync(CREDENTIALS_FILE, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveCredentials(creds) {
+    ensureDir(CONFIG_DIR);
+    writeFileSync(CREDENTIALS_FILE, JSON.stringify(creds, null, 2) + "\n", {
+        mode: 0o600,
+    });
+}
+export function clearCredentials() {
+    if (existsSync(CREDENTIALS_FILE)) {
+        writeFileSync(CREDENTIALS_FILE, "{}");
+    }
+}