@datarails-ai/dr-cli 1.6.185 → 1.6.186

package/dist/cli.js

@@ -8,7 +8,7 @@ import { fileURLToPath as fileURLToPath3 } from "url";
 // package.json
 var package_default = {
   name: "@datarails-ai/dr-cli",
-  version: "1.6.185",
+  version: "1.6.186",
   description: "Datarails CLI",
   type: "module",
   engines: {
@@ -69,7 +69,7 @@ var package_default = {
 };
 
 // src/buildInfo.ts
-var BUILD_TIME = "2026-11-01T20:44:10.716Z";
+var BUILD_TIME = "2026-11-02T07:19:02.800Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -23605,7 +23605,7 @@ async function getById2(client, id, options) {
   return out;
 }
 function scenarioContextQuery(ctx) {
-  return `scenario=${encodeURIComponent(ctx.scenario)}&scenario_cycle=${encodeURIComponent(ctx.scenario_cycle)}&planning_scenario=${encodeURIComponent(ctx.planning_scenario)}`;
+  return `scenario=${encodeURIComponent(ctx.scenario)}&scenario_cycle=${encodeURIComponent(ctx.scenario_cycle)}&cycle_year=${ctx.cycle_year ?? ""}&planning_scenario=${encodeURIComponent(ctx.planning_scenario)}`;
 }
 var NO_DRIVER_404_RE = /: HTTP 404: \{\}\s*$/;
 async function getDriver(client, id, ctx, options) {
@@ -28323,27 +28323,54 @@ import { promises as fs14 } from "fs";
 var DEFAULT_SCENARIO = "Actuals";
 function addScenarioContextFlags(cmd) {
   return cmd.option("--scenario <name>", "Scenario name \u2014 free text, matched exactly", DEFAULT_SCENARIO).option("--cycle <label>", "Scenario cycle label \u2014 free text, matched exactly (default: none)").option(
+    "--cycle-year <yyyy>",
+    "Fiscal year of the --cycle, e.g. 2027 \u2014 required with --cycle, refused without it"
+  ).option(
     "--planning-scenario <name>",
     "Planning scenario name \u2014 free text, matched exactly (default: none)"
   );
 }
+function parseCycleYear(raw2) {
+  const s = raw2.trim();
+  if (!/^\d{4}$/.test(s)) {
+    throw new Error(`invalid --cycle-year "${raw2}" (expected a four-digit fiscal year, e.g. 2027)`);
+  }
+  return Number(s);
+}
 function resolveScenarioContext(opts) {
   const scenario = opts.scenario ?? "";
+  const cycle = opts.cycle ?? "";
+  const cycleYear = opts.cycleYear === void 0 ? null : parseCycleYear(opts.cycleYear);
+  if (cycle !== "" && cycleYear === null) {
+    throw new Error(
+      `--cycle ${JSON.stringify(cycle)} needs --cycle-year <yyyy>: a cycle name repeats every year, so the server addresses a cycle only with its fiscal year`
+    );
+  }
+  if (cycle === "" && cycleYear !== null) {
+    throw new Error("--cycle-year is given only with --cycle <label>");
+  }
   return {
     scenario: scenario === "" ? DEFAULT_SCENARIO : scenario,
-    scenario_cycle: opts.cycle ?? "",
+    scenario_cycle: cycle,
+    cycle_year: cycleYear,
     planning_scenario: opts.planningScenario ?? ""
   };
 }
 function formatScenarioContext(ctx) {
-  return `scenario=${JSON.stringify(ctx.scenario)} cycle=${JSON.stringify(ctx.scenario_cycle)} planning-scenario=${JSON.stringify(ctx.planning_scenario)}`;
+  return `scenario=${JSON.stringify(ctx.scenario)} cycle=${JSON.stringify(ctx.scenario_cycle)} ` + (ctx.cycle_year === null ? "" : `cycle-year=${ctx.cycle_year} `) + `planning-scenario=${JSON.stringify(ctx.planning_scenario)}`;
 }
 function sameScenarioContext(a, b) {
-  return a.scenario === b.scenario && a.scenario_cycle === b.scenario_cycle && a.planning_scenario === b.planning_scenario;
+  const yearUnknown = a.cycle_year === void 0 || b.cycle_year === void 0;
+  return a.scenario === b.scenario && a.scenario_cycle === b.scenario_cycle && (yearUnknown || a.cycle_year === b.cycle_year) && a.planning_scenario === b.planning_scenario;
+}
+function findScenarioContext(rows, ctx) {
+  const exact = rows.findIndex((r) => r.cycle_year !== void 0 && sameScenarioContext(r, ctx));
+  return exact >= 0 ? exact : rows.findIndex((r) => sameScenarioContext(r, ctx));
 }
 function scenarioContextFlags(ctx) {
   const parts = [`--scenario ${shellQuote(ctx.scenario)}`];
   if (ctx.scenario_cycle !== "") parts.push(`--cycle ${shellQuote(ctx.scenario_cycle)}`);
+  if (ctx.cycle_year !== null) parts.push(`--cycle-year ${ctx.cycle_year}`);
   if (ctx.planning_scenario !== "") {
     parts.push(`--planning-scenario ${shellQuote(ctx.planning_scenario)}`);
   }
@@ -28518,6 +28545,7 @@ function renderDriver(out, d) {
   writeRows4(out, [
     ["scenario", dash(d.scenario)],
     ["cycle", dash(d.scenario_cycle)],
+    ["cycle_year", dash(d.cycle_year)],
     ["planning_scenario", dash(d.planning_scenario)],
     ["unit", dash(d.unit)],
     ["is_additive", dash(d.is_additive)],
@@ -28546,12 +28574,15 @@ function renderCalculations(out, calcs) {
     out.write("(no scenario calculations)\n");
     return;
   }
-  const rows = [["ID", "SCENARIO", "CYCLE", "PLANNING_SCENARIO", "FORMULA"]];
+  const rows = [
+    ["ID", "SCENARIO", "CYCLE", "CYCLE_YEAR", "PLANNING_SCENARIO", "FORMULA"]
+  ];
   for (const c of calcs) {
     rows.push([
       dash(c.id),
       dash(c.scenario),
       dash(c.scenario_cycle),
+      dash(c.cycle_year),
       dash(c.planning_scenario),
       c.presented_formula
     ]);
@@ -28681,10 +28712,21 @@ function toCalcPayload(c) {
   return {
     scenario: c.scenario,
     scenario_cycle: c.scenario_cycle,
+    cycle_year: c.cycle_year ?? null,
     planning_scenario: c.planning_scenario,
     presented_formula: c.presented_formula
   };
 }
+function assertKeptRowsHaveYear(id, calculations, skip) {
+  if (!calculations.some((c) => c.cycle_year !== void 0)) return;
+  const bad = calculations.find(
+    (c, i) => i !== skip && c.scenario_cycle !== "" && (c.cycle_year ?? null) === null
+  );
+  if (bad === void 0) return;
+  throw new Error(
+    `metric ${id} keeps a calculation for ${formatScenarioContext({ ...bad, cycle_year: null })}${bad.id === void 0 ? "" : ` (id ${bad.id})`} with no cycle year; the server refuses any calculations list holding a cycle without its fiscal year, so nothing was changed. Fix or remove that calculation in the web app first.`
+  );
+}
 async function readCalculations(client, id, signal) {
   const m = decodeShape(await getById2(client, id, { signal }));
   return { name: m.name ?? "", calculations: m.calculations ?? [] };
@@ -28701,12 +28743,13 @@ async function runCalculationsAdd(cfg) {
   const presented_formula = toWireFormula(cfg.formula);
   const { calculations } = await readCalculations(cfg.client, cfg.id, cfg.signal);
   const current = calculations.map(toCalcPayload);
-  const idx = current.findIndex((c) => sameScenarioContext(c, cfg.ctx));
+  const idx = findScenarioContext(calculations, cfg.ctx);
   if (idx >= 0 && !cfg.replace) {
     throw new Error(
       `metric ${cfg.id} already has a calculation for ${formatScenarioContext(cfg.ctx)} (${current[idx].presented_formula}); pass --replace to overwrite it`
     );
   }
+  assertKeptRowsHaveYear(cfg.id, calculations, idx);
   const entry = { ...cfg.ctx, presented_formula };
   const next = idx >= 0 ? current.map((c, i) => i === idx ? entry : c) : [...current, entry];
   const updated = await update6(
@@ -28747,13 +28790,15 @@ async function runCalculationsRemove(cfg) {
     describe: async () => {
       const { name, calculations } = await readCalculations(cfg.client, cfg.id, cfg.signal);
       const all = calculations.map(toCalcPayload);
-      const hit = all.find((c) => sameScenarioContext(c, cfg.ctx));
+      const idx = findScenarioContext(calculations, cfg.ctx);
+      const hit = all[idx];
       if (hit === void 0) {
         throw new Error(
           `metric ${cfg.id} has no calculation for ${formatScenarioContext(cfg.ctx)}; list them with \`dr metrics calculations list ${cfg.id}\``
         );
       }
-      remaining = all.filter((c) => !sameScenarioContext(c, cfg.ctx));
+      assertKeptRowsHaveYear(cfg.id, calculations, idx);
+      remaining = all.filter((_, i) => i !== idx);
       return [
         `metric: ${JSON.stringify(name === "" ? "(unnamed)" : name)}`,
         `context: ${formatScenarioContext(cfg.ctx)}`,
@@ -28932,7 +28977,7 @@ function collectArray5(value, previous) {
 }
 function wireMetricsDrivers(metrics) {
   const driver = metrics.command("driver").description(
-    "Driver definition and values of a DRIVER metric, per scenario context (--scenario / --cycle / --planning-scenario: free-text names, matched exactly)"
+    "Driver definition and values of a DRIVER metric, per scenario context (--scenario / --cycle / --planning-scenario: free-text names, matched exactly; --cycle-year: the fiscal year, required with --cycle)"
   );
   const driverGetCmd = addScenarioContextFlags(
     driver.command("get").description("Show the driver definition for one scenario context").argument("<id>", "DRIVER metric id (positive integer)")
@@ -29068,7 +29113,7 @@ function wireMetricsDrivers(metrics) {
   addServerFlag(valuesSetCmd);
   addAccountFlag(valuesSetCmd);
   const calculations = metrics.command("calculations").description(
-    "Scenario-bound formulas of a CALC metric, one per scenario context (--scenario / --cycle / --planning-scenario: free-text names, matched exactly)"
+    "Scenario-bound formulas of a CALC metric, one per scenario context (--scenario / --cycle / --planning-scenario: free-text names, matched exactly; --cycle-year: the fiscal year, required with --cycle)"
   );
   const calcListCmd = calculations.command("list").description("List a CALC metric's scenario calculations").argument("<id>", "CALC metric id (positive integer)").option("--json", "Output raw JSON instead of a table", false).action(async (idStr, opts) => {
     const id = parseMetricIdArg(idStr);

package/dist/scopes-map.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "cliVersion": "1.6.185",
+  "cliVersion": "1.6.186",
   "_contract": "Resolve a command path through `aliases` (canonical prefix + alias segment -> canonical path) before any lookup. A path listed in `pendingCommands`, or whose first segment is a key of `pending`, is UNDECIDED, not unrestricted: fail closed or skip it, and never read a path's absence from `commands` as 'no requirement'. An entry carrying `denied` is UNAVAILABLE to any AGENT-SCOPED credential — one whose `scopes` claim carries at least one `resource:action` entry; a claim that is absent, empty, capability-only or wholly unparseable is UNRESTRICTED, and this mark does not apply to it — whatever else that entry says: it is not a ceiling and it is not always-available, its `denied.reason` says why and `denied.until` names the ticket that lifts it, and the absence of `requires` on it must NEVER be read as 'no requirement'. Only an entry in `commands` with an empty `requires` means always-available.",
   "commands": {
     "login": {

package/dist/skills/dr-cli/SKILL.md

@@ -241,7 +241,7 @@ area's gotchas.
 **Metrics (KPIs) & functions** → [reference/metrics.md](reference/metrics.md)
 - `metrics list|get|data|drilldown`
 - `metrics create base|calc|driver`, `metrics update|delete`
-- `metrics driver get|set|delete`, `metrics driver values get|set`, `metrics calculations list|add|remove`, `metrics what-if`: drivers, scenario-bound formulas and what-if runs, addressed per scenario context (`--scenario` / `--cycle` / `--planning-scenario`, matched exactly)
+- `metrics driver get|set|delete`, `metrics driver values get|set`, `metrics calculations list|add|remove`, `metrics what-if`: drivers, scenario-bound formulas and what-if runs, addressed per scenario context (`--scenario` / `--cycle` / `--planning-scenario`, matched exactly; `--cycle` needs `--cycle-year <yyyy>`)
 - `metrics re-aggregate` — rebuild pre-aggregated metric values (targeted ids, or `--all` org-wide); add `--wait [--timeout <s>]` on targeted ids to block until done (exits non-zero on failure/timeout)
 - `metrics migrate` — org-wide metrics+dimensions migration (V1→V2 backfill; `--dry-run` first)
 - `metrics categories list|get|create|update|delete`

package/dist/skills/dr-cli/reference/metrics.md

@@ -146,10 +146,14 @@ cycle management). When either is off it answers 400/403/405 with a message,
 and the CLI prints that message unchanged.
 
 **Scenario context.** `driver …` and `calculations add|remove` address one
-context with `--scenario <name>` (default `Actuals`), `--cycle <label>` and
-`--planning-scenario <name>`. All three are free-text names and must match
-exactly. A context never inherits from another one, so a driver set under
-`Budget` is a different row from the `Actuals` one.
+context with `--scenario <name>` (default `Actuals`), `--cycle <label>`,
+`--cycle-year <yyyy>` and `--planning-scenario <name>`. The three names are
+free text and must match exactly. A context never inherits from another one,
+so a driver set under `Budget` is a different row from the `Actuals` one.
+A cycle name repeats every year, so `--cycle` needs `--cycle-year` (the
+cycle's fiscal year, e.g. `--cycle "0+12" --cycle-year 2027`), and
+`--cycle-year` is refused without `--cycle`. The same cycle in another year
+is another context. `calculations list` shows the year in a CYCLE_YEAR column.
 
 - `metrics create driver --name <n> [--description] [--category <id>]
   [--dimensions <ids>]` creates a DRIVER metric. It has no table, value or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datarails-ai/dr-cli",
-  "version": "1.6.185",
+  "version": "1.6.186",
   "description": "Datarails CLI",
   "type": "module",
   "engines": {