@farthershore/cli 0.3.5 → 0.3.7

package/README.md

@@ -45,8 +45,7 @@ Options:
 
 - `--base-url <url>` — Backend API base URL
 - `--description <text>` — Product description
-- `--display-name <name>` — Display name for the portal
-- `--billing <strategy>` — `subscription` (default), `usage_based`, or `hybrid`
+- `--display-name <name>` — Display name for the product portal
 
 The created repo contains:
 
@@ -57,7 +56,7 @@ The created repo contains:
 
 ### `farthershore validate [file]`
 
-Validate a local `product.yaml` file without making any API calls. Checks structure, required fields, and strategy/model alignment.
+Validate a local `product.yaml` file without making any API calls. Checks structure, required fields, and launch constraints for env-scoped plans and meters.
 
 ```bash
 # Validate product.yaml in current directory
@@ -69,7 +68,7 @@ farthershore validate path/to/product.yaml
 
 ### `farthershore apply [product]`
 
-Run the server-side compiler against the current product configuration. Returns compilation errors and warnings. Exits with code 1 on failure — suitable for CI checks before merging.
+Validate the current repo's `product.yaml` first when applying that repo's product, then run the server-side compiler against the pushed branch state for the product. Unpushed local edits are not part of the remote compile. Returns compilation errors and warnings. Exits with code 1 on failure — suitable for CI checks before merging.
 
 ```bash
 # Inside a product repo (auto-detects from product.yaml)
@@ -137,3 +136,30 @@ git add -A && git commit -m "Configure product" && git push
 | ---------------------- | ------------------------------------------------------- |
 | `FARTHERSHORE_TOKEN`   | API token (overrides stored credentials)                |
 | `FARTHERSHORE_API_URL` | API base URL (default: `https://core.farthershore.com`) |
+
+## Errors and exit codes
+
+The CLI exits `0` on success and `1` on any failure (including
+`commander`-level argument errors). When the API returns a 4XX/5XX, the
+CLI prints the canonical error code in brackets and a one-line
+remediation hint when one is registered:
+
+```text
+Error [STRIPE_NOT_CONFIGURED]: connect Stripe before running billing operations
+Hint: Stripe isn't connected on this product. Connect it in the dashboard before running billing operations.
+```
+
+The bracketed code is stable across releases — quote it in support
+threads.
+
+`farthershore whoami --format json` emits a stable JSON shape suitable
+for CI scripts. On the not-authenticated path it emits
+`{ "authenticated": false }` with exit code `1`.
+
+## CI / agent usage
+
+The CLI is non-interactive whenever a token is available via the
+`--token` flag or `FARTHERSHORE_TOKEN` env var — `set-key` only prompts
+when stdin is a TTY and no token argument was passed, so it's safe to
+script. `validate` and `apply` emit GitHub Actions-formatted annotations
+when run under `CI` / `GITHUB_ACTIONS`.

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { Product, InitProductResponse } from "./types.js";
+import type { Product, InitProductResponse, CompileDiagnostic } from "./types.js";
 export declare function createClient(opts: {
     apiUrl: string;
     token: string;
@@ -28,41 +28,29 @@ export declare function createClient(opts: {
         baseUrl?: string;
         description?: string;
         displayName?: string;
-        billingStrategy?: string;
     }) => Promise<InitProductResponse>;
-    compileProduct: (productId: string) => Promise<{
+    compileProduct: (productId: string, opts?: {
+        branch?: string;
+    }) => Promise<{
         success: boolean;
-        errors?: Array<{
-            code?: string;
-            message: string;
-        }>;
-        warnings?: Array<{
-            code?: string;
-            message: string;
-        }>;
+        errors?: CompileDiagnostic[];
+        warnings?: CompileDiagnostic[];
     }>;
-    managementCompileSelf: () => Promise<{
+    managementCompileSelf: (opts?: {
+        branch?: string;
+    }) => Promise<{
         success: boolean;
         productId: string;
-        errors?: Array<{
-            code?: string;
-            message: string;
-        }>;
-        warnings?: Array<{
-            code?: string;
-            message: string;
-        }>;
+        branch?: string | null;
+        errors?: CompileDiagnostic[];
+        warnings?: CompileDiagnostic[];
     }>;
-    managementCompile: (productId: string) => Promise<{
+    managementCompile: (productId: string, opts?: {
+        branch?: string;
+    }) => Promise<{
         success: boolean;
-        errors?: Array<{
-            code?: string;
-            message: string;
-        }>;
-        warnings?: Array<{
-            code?: string;
-            message: string;
-        }>;
+        errors?: CompileDiagnostic[];
+        warnings?: CompileDiagnostic[];
     }>;
     managementListProducts: () => Promise<Product[]>;
     isMakerToken: () => boolean;

package/dist/commands/validate.d.ts

@@ -1,2 +1,28 @@
 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;

package/dist/config.d.ts

@@ -4,6 +4,3 @@ export declare function saveConfig(config: Partial<CliConfig>): void;
 export declare function loadCredentials(): Credentials | null;
 export declare function saveCredentials(creds: Credentials): void;
 export declare function clearCredentials(): void;
-export declare function getConfigPath(productSlug: string): string;
-export declare function writeConfigFile(productSlug: string, content: string): string;
-export declare function readConfigFile(productSlug: string): string | null;