@slothmoney/agent-cli 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.18.0 - 2026-08-25
+
+- Add optional `--period YYYY-MM` to `budget status` for current and historical
+  Sloth budget periods.
+- Replace signed spending-only status with clear money-in, money-out, and net
+  activity for Income, Transfer, None, ordinary, custom, and uncategorized
+  transactions.
+- Accept the old current-status response temporarily during the coordinated
+  backend rollout; historical responses use the new strict contract.
+- Add a release preflight that compares local, packed, globally installed, and
+  npm-registry versions and checks every nested help route.
+
 ## 0.17.0 - 2026-08-25
 
 - Run applied transaction-assignment batches through resumable server

package/README.md

@@ -428,20 +428,27 @@ The result includes the budget period and status, currency, the effective plan,
 stored funding amounts when available, categories, line items, and planned
 amounts in pence.
 
-Read current assigned, spent, and available money without aggregating
-transactions yourself:
+Read booked activity for the current or a historical Sloth period:
 
 ```bash
 sloth-agent budget status --scope personal
+sloth-agent budget status --scope personal --period 2026-07
 ```
 
-The server applies its normal once-per-UTC-day automatic transaction refresh
-policy before returning the current Sloth period dates and signed booked
-activity. For each category, `availablePence` is
-`assignedPence - spentPence`; a negative value is over budget, and refunds
-reduce `spentPence`. Check `refresh`,
-`activity.uncategorizedSpentPence`, and `activity.unmappedSpentPence` before
-using the result to suggest a reallocation. This command is read-only.
+The period key names the calendar month containing that Sloth period's start
+boundary. Its end date can fall in the following month.
+
+The current period uses Sloth's normal once-per-UTC-day transaction refresh;
+historical periods are cache-only and return `refresh: null`. Activity contains
+nonnegative `moneyInPence` and `moneyOutPence` plus their difference as
+`netPence`. Income, Transfer, explicit None, budget categories, and observed
+custom categories are normal rows. A transaction with no category at all is
+reported separately under `activity.uncategorized`.
+
+`budget` contains assigned, spent, and available category amounts when a
+trustworthy period plan exists. It is `null` when it does not; activity still
+returns. The response includes only the period budget currency and silently
+ignores rows in other currencies. This command is read-only.
 
 Update selected line-item amounts by creating `budget.json`:
 
@@ -638,9 +645,12 @@ sloth-agent investments --account-ref sloth_account_v1_...
 Investment reads are cache-only and do not refresh a brokerage. Holding
 quantities, unit prices, market values, currencies, and freshness are returned
 in provider-native terms. They are not converted or guaranteed to reconcile
-to an account total reported in another currency. Caller-owned personal and
-joint linked investment accounts are included; partner-owned accounts, manual
-holdings, and investment activities are not.
+to an account total reported in another currency. An investment account total
+and its nested holdings describe the same portfolio, so do not add them
+together. Do not add values in different currencies without an explicit
+conversion. Caller-owned personal and joint linked investment accounts are
+included; partner-owned accounts, manual holdings, and investment activities
+are not.
 
 List your goals:
 
@@ -789,11 +799,16 @@ command with the same input resumes the same server operation.
 ```bash
 npm ci
 npm run verify
+npm run release:preflight
 ```
 
 `npm run test:package` packs the exact npm artifact, installs it into a clean
 temporary project, and runs the installed binary.
 
+`npm run release:preflight` reports the local, packed, globally installed, and
+npm-registry versions, then exercises every parser command's nested help. It
+fails when a parent help page stops advertising one of its child commands.
+
 ## Releasing
 
 Releases are published only through the trusted `Publish npm release` GitHub

package/dist/args.js

@@ -486,7 +486,7 @@ function parseBudget(args, baseUrl) {
                 ? 'budget move'
                 : 'budget';
     const { values, apply } = parseNamedOptions(args, commandLabel, new Set(status
-        ? ['--scope']
+        ? ['--scope', '--period']
         : update
             ? ['--scope', '--period', '--input']
             : move
@@ -498,17 +498,13 @@ function parseBudget(args, baseUrl) {
     if (scope !== 'personal' && scope !== 'joint') {
         throw new UsageError('--scope must be personal or joint');
     }
-    if (status) {
-        return withBaseUrl({
-            command: 'budget-status',
-            scope: scope,
-        }, baseUrl);
-    }
     const period = values.get('--period');
     const common = {
         scope: scope,
         ...(period === undefined ? {} : { periodKey: parseGoalMonthKey(period, '--period') }),
     };
+    if (status)
+        return withBaseUrl({ command: 'budget-status', ...common }, baseUrl);
     if (!update && !move)
         return withBaseUrl({ command: 'budget', ...common }, baseUrl);
     if (move) {

package/dist/cli.js

@@ -6,7 +6,7 @@ import { ICON_KEYS } from './category-metadata.js';
 import { parseApiResponse, parseAssignmentOperationResponse, toLegacyAssignmentResponse, validateAssignmentPayload, validateBudgetMovementResponse, validateBudgetUpdatePayload, validateNotificationRulePayload, validateReceiptConfirmation, } from './contracts.js';
 import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.17.0';
+export const CLI_VERSION = '0.18.0';
 const REQUEST_TIMEOUT_MS = 60_000;
 const MAX_CONTRACT_PDF_BYTES = 6_000_000;
 const API_ORIGIN_HELP_LINES = [
@@ -35,7 +35,7 @@ export function usageText() {
         '  sloth-agent accounts remove --account-ref REF [--apply]',
         '  sloth-agent investments [--account-ref REF] [--base-url URL]',
         '  sloth-agent budget --scope personal|joint [--period YYYY-MM] [--base-url URL]',
-        '  sloth-agent budget status --scope personal|joint [--base-url URL]',
+        '  sloth-agent budget status --scope personal|joint [--period YYYY-MM] [--base-url URL]',
         '  sloth-agent budget update --scope personal|joint [--period YYYY-MM]',
         '    --input budget.json [--apply] [--base-url URL]',
         '  sloth-agent budget move --scope personal|joint [--period YYYY-MM]',
@@ -461,7 +461,7 @@ export function budgetHelpText() {
         '',
         'Options:',
         '  --scope personal|joint  Required. Budget ownership scope.',
-        '  --period YYYY-MM        Optional. Defaults to the current Sloth budget period.',
+        '  --period YYYY-MM        Optional. Month containing the period start; defaults to the current Sloth period.',
         '  --base-url URL          Optional. Override the API origin.',
         '  -h, --help              Show this help.',
         ...API_ORIGIN_HELP_LINES,
@@ -480,29 +480,28 @@ export function budgetStatusHelpText() {
     return [
         'Sloth Agent CLI — budget status',
         '',
-        'Read assigned, spent, and available money for the current Sloth budget period.',
+        'Read booked activity and any trustworthy budget for one Sloth budget period.',
         '',
         'Usage:',
-        '  sloth-agent budget status --scope personal|joint [--base-url URL]',
+        '  sloth-agent budget status --scope personal|joint [--period YYYY-MM] [--base-url URL]',
         '',
         'Options:',
         '  --scope personal|joint  Required. Budget ownership scope.',
+        '  --period YYYY-MM        Optional. Month containing the period start; defaults to the current Sloth period.',
         '  --base-url URL          Optional. Override the API origin.',
         '  -h, --help              Show this help.',
         ...API_ORIGIN_HELP_LINES,
         '',
         'Access and freshness:',
         '  This command is read-only, requires agent:read, and never changes the budget.',
-        '  The server applies its normal once-per-UTC-day automatic transaction refresh policy.',
-        '  Inspect refresh.status and refresh.reason before relying on the result.',
+        '  Current periods use the normal transaction refresh policy; historical periods are cache-only.',
+        '  A historical response returns refresh as null.',
         '',
         'Output:',
-        '  categories[].assignedPence is the money assigned to the category.',
-        '  categories[].spentPence is signed booked activity; refunds reduce it.',
-        '  categories[].availablePence equals assignedPence minus spentPence.',
-        '  Negative availablePence means the category is over budget.',
-        '  activity contains the period dates, transaction count, uncategorizedSpentPence,',
-        '  and unmappedSpentPence. Review either nonzero value before moving money.',
+        '  activity.categories includes Income, Transfer, None, and ordinary categories.',
+        '  moneyInPence and moneyOutPence are nonnegative; netPence is money in minus money out.',
+        '  A transaction with no category appears under activity.uncategorized.',
+        '  budget contains the period plan and balances, or budget is null when no trustworthy plan exists.',
     ].join('\n');
 }
 export function budgetUpdateHelpText() {
@@ -962,11 +961,11 @@ export function rulesHelpText() {
         'Rules do not create transactions or recurring predictions.',
         '',
         'Commands:',
-        '  rules list           List every saved notification rule.',
-        '  rules get            Read the rule for one transaction.',
-        '  rules set            Preview or save a rule for one transaction.',
-        '  rules delete         Preview or remove a rule.',
-        '  rules scan-contract  Validate or scan a PDF for its renewal date.',
+        '  sloth-agent rules list           List every saved notification rule.',
+        '  sloth-agent rules get            Read the rule for one transaction.',
+        '  sloth-agent rules set            Preview or save a rule for one transaction.',
+        '  sloth-agent rules delete         Preview or remove a rule.',
+        '  sloth-agent rules scan-contract  Validate or scan a PDF for its renewal date.',
         '',
         'Use the exact transactionRef returned by sloth-agent transactions.',
         ...API_ORIGIN_HELP_LINES,
@@ -2065,7 +2064,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
         }
         if (parsed.command === 'budget' || parsed.command === 'budget-status') {
             const query = new URLSearchParams({ scope: parsed.scope });
-            if (parsed.command === 'budget' && parsed.periodKey !== undefined) {
+            if (parsed.periodKey !== undefined) {
                 query.set('periodKey', parsed.periodKey);
             }
             const response = await fetchImplementation(`${baseUrl}/api/agent/v1/${parsed.command === 'budget' ? 'budgets' : 'budget-status'}?${query.toString()}`, {

package/dist/contracts.js

@@ -666,6 +666,12 @@ function isBudgetCategory(value) {
         && Array.isArray(value.lineItems)
         && value.lineItems.every(isBudgetLineItem));
 }
+function isBudgetFunding(value) {
+    return value === null || (isObject(value)
+        && hasOnlyFields(value, ['toAssignPence', 'nextPeriodReservePence'])
+        && isSafeInteger(value.toAssignPence)
+        && isSafeInteger(value.nextPeriodReservePence));
+}
 function isBudgetResponse(value) {
     return (isObject(value)
         && hasOnlyFields(value, [
@@ -686,15 +692,11 @@ function isBudgetResponse(value) {
         && isCurrency(value.currency)
         && typeof value.effectiveFromPeriodKey === 'string'
         && /^\d{4}-(0[1-9]|1[0-2])$/.test(value.effectiveFromPeriodKey)
-        && (value.funding === null
-            || (isObject(value.funding)
-                && hasOnlyFields(value.funding, ['toAssignPence', 'nextPeriodReservePence'])
-                && isSafeInteger(value.funding.toAssignPence)
-                && isSafeInteger(value.funding.nextPeriodReservePence)))
+        && isBudgetFunding(value.funding)
         && Array.isArray(value.categories)
         && value.categories.every(isBudgetCategory));
 }
-function isBudgetStatusResponse(value) {
+function isLegacyBudgetStatusResponse(value) {
     if (!isObject(value)
         || !hasOnlyFields(value, [
             'scope',
@@ -715,11 +717,7 @@ function isBudgetStatusResponse(value) {
         && isCurrency(value.currency)
         && typeof value.effectiveFromPeriodKey === 'string'
         && /^\d{4}-(0[1-9]|1[0-2])$/.test(value.effectiveFromPeriodKey)
-        && (value.funding === null
-            || (isObject(value.funding)
-                && hasOnlyFields(value.funding, ['toAssignPence', 'nextPeriodReservePence'])
-                && isSafeInteger(value.funding.toAssignPence)
-                && isSafeInteger(value.funding.nextPeriodReservePence)))
+        && isBudgetFunding(value.funding)
         && isObject(value.activity)
         && hasOnlyFields(value.activity, [
             'startDate',
@@ -756,6 +754,82 @@ function isBudgetStatusResponse(value) {
             && Number.isSafeInteger(category.assignedPence - category.spentPence)
             && category.availablePence === category.assignedPence - category.spentPence)));
 }
+function isActivityAmounts(value) {
+    return isObject(value)
+        && hasOnlyFields(value, ['moneyInPence', 'moneyOutPence', 'netPence'])
+        && isNonnegativeSafeInteger(value.moneyInPence)
+        && isNonnegativeSafeInteger(value.moneyOutPence)
+        && isSafeInteger(value.netPence)
+        && Number.isSafeInteger(value.moneyInPence - value.moneyOutPence)
+        && value.netPence === value.moneyInPence - value.moneyOutPence;
+}
+function isBudgetActivityStatusResponse(value) {
+    if (!isObject(value) || !hasOnlyFields(value, [
+        'scope', 'periodKey', 'periodStatus', 'currency', 'period', 'refresh', 'activity', 'budget',
+    ]))
+        return false;
+    if (!isObject(value.period) || !hasOnlyFields(value.period, [
+        'startDate', 'endDate', 'dateRangeSource',
+    ]))
+        return false;
+    if (!isObject(value.activity) || !hasOnlyFields(value.activity, [
+        'transactionCount', 'categories', 'uncategorized',
+    ]))
+        return false;
+    const activityCategories = value.activity.categories;
+    if (!Array.isArray(activityCategories) || !activityCategories.every((category) => (isObject(category)
+        && hasOnlyFields(category, ['id', 'name', 'moneyInPence', 'moneyOutPence', 'netPence'])
+        && typeof category.id === 'string'
+        && category.id.trim().length > 0
+        && typeof category.name === 'string'
+        && category.name.trim().length > 0
+        && isActivityAmounts({
+            moneyInPence: category.moneyInPence,
+            moneyOutPence: category.moneyOutPence,
+            netPence: category.netPence,
+        }))))
+        return false;
+    const budget = value.budget;
+    if (budget !== null && (!isObject(budget)
+        || !hasOnlyFields(budget, ['effectiveFromPeriodKey', 'funding', 'categories'])
+        || typeof budget.effectiveFromPeriodKey !== 'string'
+        || !/^\d{4}-(0[1-9]|1[0-2])$/.test(budget.effectiveFromPeriodKey)
+        || !isBudgetFunding(budget.funding)
+        || !Array.isArray(budget.categories)
+        || !budget.categories.every((category) => (isObject(category)
+            && hasOnlyFields(category, [
+                'id', 'name', 'plannedPence', 'assignedPence', 'spentPence', 'availablePence',
+            ])
+            && typeof category.id === 'string'
+            && category.id.trim().length > 0
+            && typeof category.name === 'string'
+            && category.name.trim().length > 0
+            && isNonnegativeSafeInteger(category.plannedPence)
+            && isSafeInteger(category.assignedPence)
+            && isSafeInteger(category.spentPence)
+            && isSafeInteger(category.availablePence)
+            && Number.isSafeInteger(category.assignedPence - category.spentPence)
+            && category.availablePence === category.assignedPence - category.spentPence))))
+        return false;
+    return (value.scope === 'personal' || value.scope === 'joint')
+        && typeof value.periodKey === 'string'
+        && /^\d{4}-(0[1-9]|1[0-2])$/.test(value.periodKey)
+        && (value.periodStatus === 'current' || value.periodStatus === 'historical')
+        && isCurrency(value.currency)
+        && isIsoDate(value.period.startDate)
+        && isIsoDate(value.period.endDate)
+        && value.period.startDate <= value.period.endDate
+        && (value.period.dateRangeSource === 'stored'
+            || value.period.dateRangeSource === 'legacy_settings_fallback')
+        && isNonnegativeSafeInteger(value.activity.transactionCount)
+        && isActivityAmounts(value.activity.uncategorized)
+        && (value.periodStatus === 'historical'
+            ? value.refresh === null
+            : isRefreshStatus(value.refresh));
+}
+function isBudgetStatusResponse(value) {
+    return isLegacyBudgetStatusResponse(value) || isBudgetActivityStatusResponse(value);
+}
 function isBudgetMovementResponse(value) {
     return (isObject(value)
         && hasOnlyFields(value, [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slothmoney/agent-cli",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
     "test": "vitest run",
     "test:package": "node scripts/test-package.mjs",
     "test:registry": "node scripts/test-registry-package.mjs",
+    "release:preflight": "node scripts/release-preflight.mjs",
     "typecheck": "tsc --noEmit",
     "verify": "npm run lint && npm run typecheck && npm test && npm run build && npm run test:package"
   },