@golden-frijoles/cli 0.5.0 → 0.6.0

package/README.md

@@ -95,6 +95,19 @@ already exists **moves** to this metric. The dry run says so before anything is
 reuse its key. The server validates the block and prints its `issues` on a 400. A file that still has the template's
 `<…>` placeholders is refused before anything is sent.
 
+## Reading a result: `gf north-star readings`, `gf experiments decision`
+
+An agent reading an epic's result (the plugin's `epic-read`) fetches the number itself through these two reads. Any
+project member can run them; `--json` prints the body the agent parses.
+
+```bash
+gf north-star readings grounded_bets_share --to 2026-11-04 --json   # the input's readings; `latest` is the number
+gf experiments decision smart-defaults --json                        # the experiment's decision record
+```
+
+`latest` is the last reading on or before `--to`; an input with no reading yet says so rather than reporting zero.
+Cite them as `north-star:<input>@<latest.date>` and `ab:<experiment>`.
+
 ## Exit codes
 
 | Code | Name | Means |

package/dist/commands/index.js

@@ -14,6 +14,7 @@ const flags_write_1 = require("./flags-write");
 const flags_history_1 = require("./flags-history");
 const flags_sync_1 = require("./flags-sync");
 const north_star_1 = require("./north-star");
+const result_reads_1 = require("./result-reads");
 const keys_1 = require("./keys");
 const doctor_1 = require("./doctor");
 const config_1 = require("./config");
@@ -41,6 +42,8 @@ exports.COMMANDS = [
     flags_history_1.flagsHistoryCommand,
     flags_sync_1.flagsSyncCommand,
     north_star_1.northStarSetCommand,
+    result_reads_1.northStarReadingsCommand,
+    result_reads_1.experimentsDecisionCommand,
     keys_1.keysLsCommand,
     keys_1.keysCreateCommand,
     keys_1.keysRevokeCommand,

package/dist/commands/result-reads.d.ts

@@ -0,0 +1,36 @@
+import type { Command } from '../command';
+export type InputReadingsBody = {
+    project: string;
+    metric: string | null;
+    input: {
+        key: string;
+        name: string;
+        valueSource: string;
+    };
+    readings: Array<{
+        date: string;
+        value: number;
+    }>;
+    latest: {
+        date: string;
+        value: number;
+    } | null;
+};
+export type ExperimentDecisionBody = {
+    project: string;
+    key: string;
+    version: number;
+    lifecycle: string;
+    decisions: {
+        state: 'undecided' | 'decided';
+        current: {
+            outcome?: string;
+            chosenVariantKey?: string | null;
+            rationale?: string;
+            createdAt?: string;
+        } | null;
+        history: unknown[];
+    };
+};
+export declare const northStarReadingsCommand: Command;
+export declare const experimentsDecisionCommand: Command;

package/dist/commands/result-reads.js

@@ -0,0 +1,123 @@
+"use strict";
+// result-record · Story 3.2 (D16) — the two reads an agent fetches an epic's result through.
+//
+//   gf north-star readings <input> [--to <day>]      an input's readings, and the latest on or before --to
+//   gf experiments decision <key> [--version <n>]    an experiment's decision record (latest version by default)
+//
+// Both are `--json`-first: `epic-read` spawns them and reads the body, so the JSON is the contract and the table is for
+// a person. Both go through `/api/v1/cli/*`, which checks membership exactly as the console does (404 elsewhere).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.experimentsDecisionCommand = exports.northStarReadingsCommand = void 0;
+const args_1 = require("../args");
+const exit_codes_1 = require("../exit-codes");
+const output_1 = require("../output");
+const flags_read_1 = require("./flags-read");
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+exports.northStarReadingsCommand = {
+    path: ['north-star', 'readings'],
+    summary: "one North Star input's readings, and the latest on or before a day",
+    usage: 'gf north-star readings <input> [--to <YYYY-MM-DD>] [--project <slug>] [--json]',
+    needsAuth: true,
+    detail: `An agent reading an epic's result calls this: \`latest\` is the number it reports, and
+  \`north-star:<input>@<latest.date>\` is the evidence it writes. Nothing is invented: an input
+  with no reading on or before --to says so, rather than reporting zero.`,
+    flags: [
+        { name: 'to', value: '<YYYY-MM-DD>', describe: 'cut the readings at this day (default: all of them)' },
+        { name: 'project', value: '<slug>', describe: 'the project (default: the remembered one)' },
+    ],
+    async run(context) {
+        const input = context.args.positionals[0];
+        if (!input) {
+            context.emit.fail('invalid', 'Name the input: `gf north-star readings <input-key>`.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        const to = (0, args_1.flagValue)(context.args, 'to');
+        if (to !== undefined && !DAY.test(to)) {
+            context.emit.fail('invalid', '--to must be a day written YYYY-MM-DD.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        const project = (0, flags_read_1.resolveProject)(context);
+        if (!project)
+            return (0, flags_read_1.missingProject)(context);
+        const result = await context.api.get('api/v1/cli/north-star/readings', {
+            project,
+            input,
+            ...(to ? { to } : {}),
+        });
+        if (result.kind === 'network') {
+            context.emit.fail('server_error', result.message);
+            return exit_codes_1.EXIT.SERVER;
+        }
+        if (result.kind === 'error') {
+            context.emit.fail(result.code, result.message);
+            return (0, exit_codes_1.exitForServerCode)(result.code);
+        }
+        const body = result.body;
+        const human = body.readings.length === 0
+            ? `${body.input.key}: no readings${to ? ` on or before ${to}` : ''} yet.`
+            : [
+                `${body.input.key} (${body.input.name}) — latest ${body.latest.value} on ${body.latest.date}`,
+                (0, output_1.table)(['DAY', 'VALUE'], body.readings.slice(-10).map((r) => [r.date, String(r.value)])),
+            ].join('\n');
+        context.emit.ok({
+            project: body.project,
+            metric: body.metric,
+            input: body.input,
+            readings: body.readings,
+            latest: body.latest,
+        }, human);
+        return exit_codes_1.EXIT.OK;
+    },
+};
+exports.experimentsDecisionCommand = {
+    path: ['experiments', 'decision'],
+    summary: "an experiment's decision record (the latest version unless --version)",
+    usage: 'gf experiments decision <key> [--version <n>] [--project <slug>] [--json]',
+    needsAuth: true,
+    detail: `What was decided about an A/B test, from the experiment's append-only decision ledger.
+  An agent reading an epic's result cites it as \`ab:<key>\`.`,
+    flags: [
+        { name: 'version', value: '<n>', describe: 'the definition version (default: the latest)' },
+        { name: 'project', value: '<slug>', describe: 'the project (default: the remembered one)' },
+    ],
+    async run(context) {
+        const key = context.args.positionals[0];
+        if (!key) {
+            context.emit.fail('invalid', 'Name the experiment: `gf experiments decision <key>`.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        const version = (0, args_1.flagValue)(context.args, 'version');
+        if (version !== undefined && !/^[1-9]\d{0,6}$/.test(version)) {
+            context.emit.fail('invalid', '--version must be a whole number from 1.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        const project = (0, flags_read_1.resolveProject)(context);
+        if (!project)
+            return (0, flags_read_1.missingProject)(context);
+        const result = await context.api.get('api/v1/cli/experiments/decision', {
+            project,
+            experiment: key,
+            ...(version ? { version } : {}),
+        });
+        if (result.kind === 'network') {
+            context.emit.fail('server_error', result.message);
+            return exit_codes_1.EXIT.SERVER;
+        }
+        if (result.kind === 'error') {
+            context.emit.fail(result.code, result.message);
+            return (0, exit_codes_1.exitForServerCode)(result.code);
+        }
+        const body = result.body;
+        const current = body.decisions.current;
+        context.emit.ok({
+            project: body.project,
+            key: body.key,
+            version: body.version,
+            lifecycle: body.lifecycle,
+            decisions: body.decisions,
+        }, current
+            ? `${body.key} v${body.version} (${body.lifecycle}) — decided: ${current.outcome ?? 'recorded'}${current.chosenVariantKey ? ` (${current.chosenVariantKey})` : ''}${current.rationale ? `\n  ${current.rationale}` : ''}`
+            : `${body.key} v${body.version} (${body.lifecycle}) — no decision recorded yet.`);
+        return exit_codes_1.EXIT.OK;
+    },
+};

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.5.0";
+export declare const VERSION = "0.6.0";

package/dist/version.js

@@ -10,4 +10,4 @@ exports.VERSION = void 0;
 //
 // It is a literal, and `version.test.ts` asserts it equals `package.json`'s — so the two cannot
 // drift, and the drift is caught by the unit gate rather than by someone reading `gf --version`.
-exports.VERSION = '0.5.0';
+exports.VERSION = '0.6.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@golden-frijoles/cli",
   "private": false,
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The Golden Frijoles CLI — create, roll out and kill feature flags from a terminal, or from an agent.",
   "bin": {
     "gf": "./dist/bin.js"