@slothmoney/agent-cli 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.19.0 - 2026-08-26
+
+- Make every Goal use one explicit personal Goal-funding account and expose
+  the calculated `forecastMonthKey`, effective priority, account details, and
+  `forecastBasis` in Goal results.
+- Make `goals create` preview against Sloth's active scenario on the server;
+  preview performs no writes and `--apply` remains the write boundary.
+- Add `--account-ref` and `--priority` to Goal creation, allow account
+  reassignment during Goal updates, and rename account eligibility to
+  `isGoalFundingAccount` / `--goal-funding-account`.
+- Surface corrective API error codes without adding affordability judgments or
+  desired-date comparisons to the CLI.
+
+## 0.18.1 - 2026-08-25
+
+- Require the deployed historical-activity response for `budget status` and
+  remove the temporary validator for the retired current-only response.
+- Report every PATH-resolved `sloth-agent` installation during release
+  preflight, so Homebrew and Node-version-manager copies cannot silently drift.
+
 ## 0.18.0 - 2026-08-25
 
 - Add optional `--period YYYY-MM` to `budget status` for current and historical

package/README.md

@@ -584,7 +584,7 @@ sloth-agent accounts
 The command is read-only and cache-only: it does not refresh linked banks or
 change account data. Each result contains an opaque `accountRef`, personal or
 joint ownership, connected or manual source, native balance/currency when
-known, `lastBalanceUpdatedAt`, `connectionState`, and `isGoalSavingsSource`.
+known, `lastBalanceUpdatedAt`, `connectionState`, and `isGoalFundingAccount`.
 Missing values are JSON
 `null`; currencies are never converted or combined. Partner personal accounts
 are excluded, while enabled shared joint accounts follow Sloth's existing
@@ -604,9 +604,9 @@ Copy the value from `sloth-agent accounts`. Account references are the public
 account identifier for transaction filtering.
 
 Account changes are previews unless `--apply` is present. Connected accounts
-support only goal-savings membership. Manual current accounts support their
+support only Goal-funding eligibility. Manual current accounts support their
 institution, name, currency, and ownership. Manual balance accounts also
-support balance, Savings/Investments type, and goal-savings membership.
+support balance, Savings/Investments type, and Goal-funding eligibility.
 Partner-owned shared accounts return an explanatory error.
 
 ```bash
@@ -618,11 +618,11 @@ sloth-agent accounts update \
   --ownership individual \
   --balance-amount 12500.75 \
   --account-type investments \
-  --goal-savings-source false
+  --goal-funding-account false
 
 sloth-agent accounts update \
   --account-ref sloth_account_v1_... \
-  --goal-savings-source false \
+  --goal-funding-account false \
   --apply
 ```
 
@@ -664,16 +664,24 @@ Goal writes are previews unless `--apply` is present:
 sloth-agent goals create \
   --name "Emergency fund" \
   --target-amount 12000 \
-  --type keep
+  --type keep \
+  --account-ref sloth_account_v1_...
 
 sloth-agent goals create \
   --name "Wedding" \
   --target-amount 22000 \
   --target-month 2027-06 \
   --type spend \
+  --account-ref sloth_account_v1_... \
   --apply
 ```
 
+Without `--apply`, Goal creation authenticates and asks Sloth to calculate the
+Goal without writing it. Preview and apply use the same active-scenario planner
+and return `forecastMonthKey`, the effective priority, the funding account, and
+`forecastBasis`. A null forecast includes the final projected month. The CLI
+does not compare the desired and forecast dates or return affordability advice.
+
 Every goal is either Keep or Spend. A Keep goal continues reserving its funded
 money. A Spend goal reserves money until you explicitly mark it spent. Goal
 list, create, and update output includes lowercase `goalType` and nullable
@@ -687,6 +695,7 @@ move it in the priority order:
 sloth-agent goals update \
   --goal-id goal-id \
   --target-month 2027-12 \
+  --account-ref sloth_account_v1_... \
   --type spend \
   --apply
 
@@ -715,13 +724,10 @@ required recovery action. Restoring clears `spentAt` and returns the goal to
 allocation at its saved priority. Deleting a goal also removes its forecast
 assignments and drift history.
 
-Goal sharing remains app-managed. Change an active shared goal's pot-tracked
-target amount in the Sloth Budget app, where account balances can be
-reallocated across goals in priority order. Goal list output includes a
+Goal sharing remains app-managed. Goal list output includes a
 one-based `priority`; `1` is highest. Moving one goal automatically shifts the
-goals between its old and new positions. The priority option must be used on
-its own. Forecast assignments and shared pot progress are browser-owned
-derived state and refresh when the owner next opens the Forecast screen.
+goals between its old and new positions. Sloth recalculates the active-scenario
+roadmap before every applied Goal mutation and returns the updated forecast.
 
 Read uncategorised contributions to the joint budget:
 
@@ -805,9 +811,10 @@ 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.
+`npm run release:preflight` reports the local, packed, npm-registry, and every
+PATH-resolved globally installed version, then exercises every parser command's
+nested help. It fails when a parent help page stops advertising one of its
+child commands.
 
 ## Releasing
 

package/dist/args.js

@@ -389,7 +389,7 @@ function parseAccounts(args, baseUrl) {
             '--ownership',
             '--balance-amount',
             '--account-type',
-            '--goal-savings-source',
+            '--goal-funding-account',
         ]));
         const institutionName = values.get('--institution-name');
         const accountName = values.get('--account-name');
@@ -397,7 +397,7 @@ function parseAccounts(args, baseUrl) {
         const ownershipValue = values.get('--ownership');
         const balanceValue = values.get('--balance-amount');
         const accountTypeValue = values.get('--account-type');
-        const sourceValue = values.get('--goal-savings-source');
+        const sourceValue = values.get('--goal-funding-account');
         if (currencyValue !== undefined && !/^[A-Za-z]{3}$/.test(currencyValue)) {
             throw new UsageError('--currency must be a three-letter currency code');
         }
@@ -412,7 +412,7 @@ function parseAccounts(args, baseUrl) {
             throw new UsageError('--account-type must be savings or investments');
         }
         if (sourceValue !== undefined && sourceValue !== 'true' && sourceValue !== 'false') {
-            throw new UsageError('--goal-savings-source must be true or false');
+            throw new UsageError('--goal-funding-account must be true or false');
         }
         const update = {
             ...(institutionName === undefined
@@ -429,7 +429,7 @@ function parseAccounts(args, baseUrl) {
             ...(accountTypeValue === undefined
                 ? {}
                 : { accountType: accountTypeValue }),
-            ...(sourceValue === undefined ? {} : { isGoalSavingsSource: sourceValue === 'true' }),
+            ...(sourceValue === undefined ? {} : { isGoalFundingAccount: sourceValue === 'true' }),
         };
         if (Object.keys(update).length === 0) {
             throw new UsageError('accounts update requires at least one field to update');
@@ -652,6 +652,8 @@ function parseGoals(args, baseUrl) {
         let targetAmount;
         let targetMonthKey;
         let goalType;
+        let fundingAccountRef;
+        let priority;
         let apply = false;
         for (let index = 0; index < args.length; index += 1) {
             const argument = args[index];
@@ -667,7 +669,9 @@ function parseGoals(args, baseUrl) {
             if (option !== '--name'
                 && option !== '--target-amount'
                 && option !== '--target-month'
-                && option !== '--type') {
+                && option !== '--type'
+                && option !== '--account-ref'
+                && option !== '--priority') {
                 throw new UsageError(`Unknown goals create option: ${argument}`);
             }
             const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, option), option);
@@ -682,9 +686,15 @@ function parseGoals(args, baseUrl) {
             else if (option === '--target-month') {
                 targetMonthKey = setOnce(targetMonthKey, parseGoalMonthKey(value, option), option);
             }
-            else {
+            else if (option === '--type') {
                 goalType = setOnce(goalType, parseGoalType(value), option);
             }
+            else if (option === '--account-ref') {
+                fundingAccountRef = setOnce(fundingAccountRef, parseAccountRef(value), option);
+            }
+            else {
+                priority = setOnce(priority, parseGoalPriority(value), option);
+            }
         }
         if (!name)
             throw new UsageError('goals create requires --name <name>');
@@ -694,12 +704,17 @@ function parseGoals(args, baseUrl) {
         if (goalType === undefined) {
             throw new UsageError('goals create requires --type <keep|spend>');
         }
+        if (fundingAccountRef === undefined) {
+            throw new UsageError('goals create requires --account-ref <accountRef>');
+        }
         return withBaseUrl({
             command: 'goals-create',
             name,
             targetAmount,
             ...(targetMonthKey === undefined ? {} : { targetMonthKey }),
             goalType,
+            fundingAccountRef,
+            ...(priority === undefined ? {} : { priority }),
             apply,
         }, baseUrl);
     }
@@ -709,6 +724,7 @@ function parseGoals(args, baseUrl) {
         let targetAmount;
         let targetMonthKey;
         let goalType;
+        let fundingAccountRef;
         let priority;
         let apply = false;
         for (let index = 0; index < args.length; index += 1) {
@@ -734,6 +750,7 @@ function parseGoals(args, baseUrl) {
                 && option !== '--target-amount'
                 && option !== '--target-month'
                 && option !== '--type'
+                && option !== '--account-ref'
                 && option !== '--priority') {
                 throw new UsageError(`Unknown goals update option: ${argument}`);
             }
@@ -758,6 +775,9 @@ function parseGoals(args, baseUrl) {
             else if (option === '--priority') {
                 priority = setOnce(priority, parseGoalPriority(value), option);
             }
+            else if (option === '--account-ref') {
+                fundingAccountRef = setOnce(fundingAccountRef, parseAccountRef(value), option);
+            }
             else {
                 goalType = setOnce(goalType, parseGoalType(value), option);
             }
@@ -768,16 +788,10 @@ function parseGoals(args, baseUrl) {
             && targetAmount === undefined
             && targetMonthKey === undefined
             && goalType === undefined
+            && fundingAccountRef === undefined
             && priority === undefined) {
             throw new UsageError('goals update requires at least one field to update');
         }
-        if (priority !== undefined
-            && (name !== undefined
-                || targetAmount !== undefined
-                || targetMonthKey !== undefined
-                || goalType !== undefined)) {
-            throw new UsageError('--priority must be used on its own');
-        }
         return withBaseUrl({
             command: 'goals-update',
             goalId,
@@ -785,6 +799,7 @@ function parseGoals(args, baseUrl) {
             ...(targetAmount === undefined ? {} : { targetAmount }),
             ...(targetMonthKey === undefined ? {} : { targetMonthKey }),
             ...(goalType === undefined ? {} : { goalType }),
+            ...(fundingAccountRef === undefined ? {} : { fundingAccountRef }),
             ...(priority === undefined ? {} : { priority }),
             apply,
         }, baseUrl);

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.18.0';
+export const CLI_VERSION = '0.19.0';
 const REQUEST_TIMEOUT_MS = 60_000;
 const MAX_CONTRACT_PDF_BYTES = 6_000_000;
 const API_ORIGIN_HELP_LINES = [
@@ -61,7 +61,8 @@ export function usageText() {
         '  sloth-agent receipts remove --transaction-ref REF --revision N [--apply]',
         '  sloth-agent goals [list] [--base-url URL]',
         '  sloth-agent goals create --name NAME --target-amount AMOUNT',
-        '    --type keep|spend [--target-month YYYY-MM] [--apply] [--base-url URL]',
+        '    --type keep|spend --account-ref REF [--target-month YYYY-MM]',
+        '    [--priority POSITION] [--apply] [--base-url URL]',
         '  sloth-agent goals update --goal-id ID [fields] [--apply] [--base-url URL]',
         '  sloth-agent goals mark-spent --goal-id ID [--apply] [--base-url URL]',
         '  sloth-agent goals restore --goal-id ID [--apply] [--base-url URL]',
@@ -354,7 +355,7 @@ export function accountsHelpText() {
         '  accounts[].ownership   personal or joint',
         '  accounts[].balanceAmount and currency in the native currency when known',
         '  accounts[].connectionState and lastBalanceUpdatedAt for freshness',
-        '  accounts[].isGoalSavingsSource whether the owner uses it for goal savings',
+        '  accounts[].isGoalFundingAccount whether Goals may use the account',
     ].join('\n');
 }
 export function accountsUpdateHelpText() {
@@ -376,13 +377,13 @@ export function accountsUpdateHelpText() {
         '  --ownership individual|joint       Manual account ownership.',
         '  --balance-amount AMOUNT             Balance-only account balance.',
         '  --account-type savings|investments Balance-only account type.',
-        '  --goal-savings-source true|false   Goal-savings membership.',
+        '  --goal-funding-account true|false   Whether Goals may use this account.',
         '',
         'Write behavior:',
         '  Without --apply, returns a JSON preview without credentials or a network request.',
         '  With --apply, requires agent:write on a write-enabled token and updates saved Sloth metadata.',
-        '  Connected accounts support only --goal-savings-source.',
-        '  Manual current accounts cannot change type, balance, or goal-savings membership.',
+        '  Connected accounts support only --goal-funding-account.',
+        '  Manual current accounts cannot change type, balance, or Goal-funding membership.',
         '  Partner-owned shared accounts cannot be changed.',
         '  Unknown, disconnected, or inaccessible references return Account not found.',
         ...API_ORIGIN_HELP_LINES,
@@ -720,7 +721,7 @@ export function goalsHelpText() {
     return [
         'Sloth Agent CLI — goals',
         '',
-        'List, create, update, mark spent, restore, or delete your savings goals.',
+        'List, preview, create, update, mark spent, restore, or delete account-funded Goals.',
         '',
         'Commands:',
         '  sloth-agent goals list      List goals; "sloth-agent goals" is equivalent.',
@@ -754,9 +755,9 @@ export function goalsListHelpText() {
         '  This command is read-only.',
         '',
         'Output:',
-        '  JSON containing currency and goals. Each goal contains id, name, priority,',
-        '  targetAmount, targetMonthKey, goalType, nullable spentAt, and',
-        '  sharedWithPartner.',
+        '  JSON containing currency, forecastBasis, and goals. Each goal includes its',
+        '  effectivePriority, funding account, desired targetMonthKey, and calculated',
+        '  forecastMonthKey.',
     ].join('\n');
 }
 export function goalsCreateHelpText() {
@@ -766,30 +767,33 @@ export function goalsCreateHelpText() {
         'Preview or create a goal.',
         '',
         'Usage:',
-        '  sloth-agent goals create --name NAME --target-amount AMOUNT --type keep|spend [options]',
+        '  sloth-agent goals create --name NAME --target-amount AMOUNT --type keep|spend --account-ref REF [options]',
         '',
         'Options:',
         '  --name NAME                 Required. Goal name, 1 to 200 characters.',
         '  --target-amount AMOUNT      Required. Positive major-unit amount with up to 2 decimals.',
         '  --type keep|spend           Required. Keep reserves funded money; Spend is spent later.',
-        '  --target-month YYYY-MM      Optional. Target calendar month.',
+        '  --account-ref REF           Required. Personal Goal-funding account from accounts list.',
+        '  --target-month YYYY-MM      Optional. Desired calendar month; it does not change the forecast.',
+        '  --priority POSITION         Optional. One-based priority; defaults to append.',
         '  --apply                     Optional. Create the goal in Sloth Money.',
         '  --base-url URL              Optional. Override the API origin.',
         '  -h, --help                  Show this help.',
         ...API_ORIGIN_HELP_LINES,
         '',
         'Safety:',
-        '  Without --apply, the command returns a dry-run preview and does not write.',
+        '  Without --apply, the command authenticates and asks Sloth to calculate the Goal.',
+        '  The server performs no writes for a preview.',
         '  Applying requires a write-enabled token created with Allow changes.',
-        '  New goals are private to the owner and appended to the existing goal order.',
+        '  New goals are private to the owner and append unless --priority is supplied.',
         '',
         'Example:',
-        '  sloth-agent goals create --name "Emergency fund" --target-amount 12000 --type keep',
-        '  sloth-agent goals create --name "Wedding" --target-amount 22000 --type spend --target-month 2027-06 --apply',
+        '  sloth-agent goals create --name "Emergency fund" --target-amount 12000 --type keep --account-ref REF',
+        '  sloth-agent goals create --name "Wedding" --target-amount 22000 --type spend --account-ref REF --target-month 2027-06 --apply',
         '',
         'Output:',
-        '  Preview mode returns dryRun, method, endpoint, and payload.',
-        '  Apply mode returns the persisted goal and currency from the 201 response.',
+        '  Preview and apply return the Goal, currency, calculated forecastMonthKey,',
+        '  effective priority, funding-account details, and forecastBasis.',
     ].join('\n');
 }
 export function goalsUpdateHelpText() {
@@ -808,6 +812,7 @@ export function goalsUpdateHelpText() {
         '  --target-month YYYY-MM       Optional. Replace the target month.',
         '  --clear-target-month         Optional. Remove the target month.',
         '  --type keep|spend            Optional. Change how funded money is treated.',
+        '  --account-ref REF            Optional. Reassign to another personal Goal-funding account.',
         '  --priority POSITION          Optional. Positive whole-number position; 1 is highest.',
         '  --apply                      Optional. Write the partial update.',
         '  --base-url URL               Optional. Override the API origin.',
@@ -816,17 +821,13 @@ export function goalsUpdateHelpText() {
         '',
         'Constraints:',
         '  Provide at least one field to update.',
-        '  Priority must be updated on its own.',
         '  Priority 1 is highest. The position cannot exceed the current goal count.',
         '  Moving a goal shifts the intervening goals automatically.',
-        '  Forecast assignments and shared progress refresh when the owner next opens',
-        '  the Forecast screen.',
+        '  Sloth recalculates the Goal roadmap before saving the update.',
         '  Set and clear target-month options are mutually exclusive.',
         '  Restore a spent goal before changing its type.',
-        '  Change active shared pot target amounts in the Sloth Budget app, where',
-        '  account balances can be reconciled across goals in priority order.',
-        '  Sharing remains app-managed. Updates to an already shared goal remain visible',
-        '  to the connected partner.',
+        '  Sharing remains app-managed. Updates to a shared Goal remain visible to the',
+        '  connected partner, but its assigned account remains private to the owner.',
         '',
         'Safety:',
         '  Without --apply, the command returns a dry-run preview and does not write.',
@@ -838,7 +839,8 @@ export function goalsUpdateHelpText() {
         '',
         'Output:',
         '  Preview mode returns dryRun, method, endpoint, and payload.',
-        '  Apply mode returns the complete persisted goal and currency.',
+        '  Apply mode returns the complete persisted Goal, calculated forecastMonthKey,',
+        '  effective priority, funding-account details, currency, and forecastBasis.',
     ].join('\n');
 }
 export function goalsMarkSpentHelpText() {
@@ -1207,23 +1209,6 @@ export function commandHelpText(topic) {
 function writeJson(write, data) {
     write(`${JSON.stringify(data, null, 2)}\n`);
 }
-function withListedGoalPriorities(value) {
-    const response = value;
-    return {
-        ...response,
-        goals: response.goals.map((goal, index) => ({
-            ...goal,
-            priority: index + 1,
-        })),
-    };
-}
-function withUpdatedGoalPriority(value, priority) {
-    const response = value;
-    return {
-        ...response,
-        goal: { ...response.goal, priority },
-    };
-}
 function redact(value, token) {
     return token ? value.split(token).join('[REDACTED]') : value;
 }
@@ -1404,7 +1389,11 @@ async function parseHttpResponse(response, token) {
             && typeof data.error === 'string')
             ? data.error
             : `Agent API request failed with status ${response.status}`;
-        throw new ApiError(redact(message, token), response.status);
+        const code = (data
+            && typeof data === 'object'
+            && 'code' in data
+            && typeof data.code === 'string') ? data.code : undefined;
+        throw new ApiError(redact(message, token), response.status, code);
     }
     return data;
 }
@@ -1891,7 +1880,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             return 0;
         }
         if (parsed.command === 'goals-create') {
-            const endpoint = `${baseUrl}/api/agent/v1/goals`;
+            const endpoint = `${baseUrl}/api/agent/v1/goals${parsed.apply ? '' : '/preview'}`;
             const payload = {
                 name: parsed.name,
                 targetAmount: parsed.targetAmount,
@@ -1899,16 +1888,9 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
                     ? {}
                     : { targetMonthKey: parsed.targetMonthKey }),
                 goalType: parsed.goalType,
+                fundingAccountRef: parsed.fundingAccountRef,
+                ...(parsed.priority === undefined ? {} : { priority: parsed.priority }),
             };
-            if (!parsed.apply) {
-                writeJson(writeStdout, {
-                    dryRun: true,
-                    endpoint,
-                    method: 'POST',
-                    payload,
-                });
-                return 0;
-            }
             const response = await fetchImplementation(endpoint, {
                 method: 'POST',
                 headers: {
@@ -1918,7 +1900,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
                 body: JSON.stringify(payload),
                 signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
             });
-            const data = parseApiResponse('goals-create', await parseHttpResponse(response, token));
+            const data = parseApiResponse(parsed.apply ? 'goals-create' : 'goals-preview', await parseHttpResponse(response, token));
             writeJson(writeStdout, data);
             return 0;
         }
@@ -1938,6 +1920,9 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
                     ...(parsed.goalType === undefined
                         ? {}
                         : { goalType: parsed.goalType }),
+                    ...(parsed.fundingAccountRef === undefined
+                        ? {}
+                        : { fundingAccountRef: parsed.fundingAccountRef }),
                     ...(parsed.priority === undefined
                         ? {}
                         : { priority: parsed.priority }),
@@ -1962,9 +1947,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
                 signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
             });
             const data = parseApiResponse(parsed.command, await parseHttpResponse(response, token));
-            writeJson(writeStdout, parsed.command !== 'goals-update' || parsed.priority === undefined
-                ? data
-                : withUpdatedGoalPriority(data, parsed.priority));
+            writeJson(writeStdout, data);
             return 0;
         }
         if (parsed.command === 'goals-delete') {
@@ -2059,7 +2042,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
                 signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
             });
             const data = parseApiResponse('goals-list', await parseHttpResponse(response, token));
-            writeJson(writeStdout, withListedGoalPriorities(data));
+            writeJson(writeStdout, data);
             return 0;
         }
         if (parsed.command === 'budget' || parsed.command === 'budget-status') {
@@ -2104,7 +2087,8 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
     catch (error) {
         const exitCode = error instanceof CliError ? error.exitCode : 1;
         const message = error instanceof Error ? error.message : String(error);
-        writeStderr(`${redact(message, token)}\n`);
+        const prefix = error instanceof ApiError && error.code ? `${error.code}: ` : '';
+        writeStderr(`${prefix}${redact(message, token)}\n`);
         return exitCode;
     }
 }

package/dist/contracts.js

@@ -610,6 +610,25 @@ function hasOnlyFields(value, fields) {
     const allowed = new Set(fields);
     return Object.keys(value).every((key) => allowed.has(key));
 }
+function isMonthKeyOrNull(value) {
+    return value === null || (typeof value === 'string'
+        && /^\d{4}-(0[1-9]|1[0-2])$/.test(value));
+}
+function isPlannedGoalFields(value) {
+    return (typeof value.name === 'string'
+        && value.name.trim().length > 0
+        && typeof value.targetAmount === 'number'
+        && Number.isFinite(value.targetAmount)
+        && value.targetAmount > 0
+        && isMonthKeyOrNull(value.targetMonthKey)
+        && isMonthKeyOrNull(value.forecastMonthKey)
+        && isGoalType(value.goalType)
+        && Number.isSafeInteger(value.effectivePriority)
+        && Number(value.effectivePriority) > 0
+        && isAccountRef(value.fundingAccountRef)
+        && typeof value.fundingAccountLabel === 'string'
+        && value.fundingAccountLabel.trim().length > 0);
+}
 function isGoal(value) {
     return (isObject(value)
         && hasOnlyFields(value, [
@@ -617,20 +636,17 @@ function isGoal(value) {
             'name',
             'targetAmount',
             'targetMonthKey',
+            'forecastMonthKey',
             'goalType',
             'spentAt',
             'sharedWithPartner',
+            'effectivePriority',
+            'fundingAccountRef',
+            'fundingAccountLabel',
         ])
         && typeof value.id === 'string'
         && value.id.trim().length > 0
-        && typeof value.name === 'string'
-        && value.name.trim().length > 0
-        && (value.targetAmount === null
-            || (typeof value.targetAmount === 'number' && Number.isFinite(value.targetAmount)))
-        && (value.targetMonthKey === null
-            || (typeof value.targetMonthKey === 'string'
-                && /^\d{4}-(0[1-9]|1[0-2])$/.test(value.targetMonthKey)))
-        && isGoalType(value.goalType)
+        && isPlannedGoalFields(value)
         && (value.goalType === 'spend'
             ? value.spentAt === null || isIsoDateTime(value.spentAt)
             : value.spentAt === null)
@@ -696,64 +712,6 @@ function isBudgetResponse(value) {
         && Array.isArray(value.categories)
         && value.categories.every(isBudgetCategory));
 }
-function isLegacyBudgetStatusResponse(value) {
-    if (!isObject(value)
-        || !hasOnlyFields(value, [
-            'scope',
-            'periodKey',
-            'periodStatus',
-            'currency',
-            'effectiveFromPeriodKey',
-            'funding',
-            'activity',
-            'refresh',
-            'categories',
-        ]))
-        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'
-        && isCurrency(value.currency)
-        && typeof value.effectiveFromPeriodKey === 'string'
-        && /^\d{4}-(0[1-9]|1[0-2])$/.test(value.effectiveFromPeriodKey)
-        && isBudgetFunding(value.funding)
-        && isObject(value.activity)
-        && hasOnlyFields(value.activity, [
-            'startDate',
-            'endDate',
-            'transactionCount',
-            'uncategorizedSpentPence',
-            'unmappedSpentPence',
-        ])
-        && isIsoDate(value.activity.startDate)
-        && isIsoDate(value.activity.endDate)
-        && value.activity.startDate <= value.activity.endDate
-        && isNonnegativeSafeInteger(value.activity.transactionCount)
-        && isSafeInteger(value.activity.uncategorizedSpentPence)
-        && isSafeInteger(value.activity.unmappedSpentPence)
-        && isRefreshStatus(value.refresh)
-        && Array.isArray(value.categories)
-        && value.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)));
-}
 function isActivityAmounts(value) {
     return isObject(value)
         && hasOnlyFields(value, ['moneyInPence', 'moneyOutPence', 'netPence'])
@@ -827,9 +785,6 @@ function isBudgetActivityStatusResponse(value) {
             ? value.refresh === null
             : isRefreshStatus(value.refresh));
 }
-function isBudgetStatusResponse(value) {
-    return isLegacyBudgetStatusResponse(value) || isBudgetActivityStatusResponse(value);
-}
 function isBudgetMovementResponse(value) {
     return (isObject(value)
         && hasOnlyFields(value, [
@@ -905,7 +860,7 @@ function isAccount(value) {
             'source',
             'lastBalanceUpdatedAt',
             'connectionState',
-            'isGoalSavingsSource',
+            'isGoalFundingAccount',
         ])
         && isAccountRef(value.accountRef)
         && isNullableNonEmptyString(value.accountName)
@@ -924,7 +879,7 @@ function isAccount(value) {
             || value.connectionState === 'expired'
             || value.connectionState === 'manual'
             || value.connectionState === 'unknown')
-        && typeof value.isGoalSavingsSource === 'boolean');
+        && typeof value.isGoalFundingAccount === 'boolean');
 }
 function isAccountsResponse(value) {
     return (isObject(value)
@@ -990,19 +945,55 @@ function isInvestmentsResponse(value) {
                 && holdings.every(isInvestmentHolding));
         }));
 }
+function isForecastBasis(value) {
+    return isObject(value)
+        && hasOnlyFields(value, [
+            'calculatedAt',
+            'activeScenarioRevision',
+            'projectionThroughMonthKey',
+        ])
+        && isIsoDateTime(value.calculatedAt)
+        && Number.isSafeInteger(value.activeScenarioRevision)
+        && Number(value.activeScenarioRevision) >= 0
+        && isMonthKeyOrNull(value.projectionThroughMonthKey) === true
+        && value.projectionThroughMonthKey !== null;
+}
+function isGoalPreview(value) {
+    return isObject(value)
+        && hasOnlyFields(value, [
+            'name',
+            'targetAmount',
+            'targetMonthKey',
+            'forecastMonthKey',
+            'goalType',
+            'effectivePriority',
+            'fundingAccountRef',
+            'fundingAccountLabel',
+        ])
+        && isPlannedGoalFields(value);
+}
 function isGoalsResponse(value) {
     return (isObject(value)
-        && hasOnlyFields(value, ['currency', 'goals'])
+        && hasOnlyFields(value, ['currency', 'forecastBasis', 'goals'])
         && isCurrency(value.currency)
+        && isForecastBasis(value.forecastBasis)
         && Array.isArray(value.goals)
         && value.goals.every(isGoal));
 }
 function isGoalMutationResponse(value) {
     return (isObject(value)
-        && hasOnlyFields(value, ['currency', 'goal'])
+        && hasOnlyFields(value, ['currency', 'forecastBasis', 'goal'])
         && isCurrency(value.currency)
+        && isForecastBasis(value.forecastBasis)
         && isGoal(value.goal));
 }
+function isGoalPreviewResponse(value) {
+    return isObject(value)
+        && hasOnlyFields(value, ['currency', 'forecastBasis', 'goal'])
+        && isCurrency(value.currency)
+        && isForecastBasis(value.forecastBasis)
+        && isGoalPreview(value.goal);
+}
 function isGoalDeleteResponse(value) {
     return (isObject(value)
         && hasOnlyFields(value, ['deleted', 'deletedGoalId'])
@@ -1071,7 +1062,7 @@ export function parseApiResponse(command, value) {
                     : command === 'budget' || command === 'budget-update'
                         ? isBudgetResponse(value)
                         : command === 'budget-status'
-                            ? isBudgetStatusResponse(value)
+                            ? isBudgetActivityStatusResponse(value)
                             : command === 'budget-move'
                                 ? isBudgetMovementResponse(value)
                                 : command === 'categories'
@@ -1104,9 +1095,11 @@ export function parseApiResponse(command, value) {
                                                                                         ? isPartnerResponse(value)
                                                                                         : command === 'goals-list'
                                                                                             ? isGoalsResponse(value)
-                                                                                            : command === 'goals-delete'
-                                                                                                ? isGoalDeleteResponse(value)
-                                                                                                : isGoalMutationResponse(value);
+                                                                                            : command === 'goals-preview'
+                                                                                                ? isGoalPreviewResponse(value)
+                                                                                                : command === 'goals-delete'
+                                                                                                    ? isGoalDeleteResponse(value)
+                                                                                                    : isGoalMutationResponse(value);
     if (!valid) {
         const label = command === 'assign' ? 'assignment' : command;
         throw new ApiError(`Invalid ${label} response from the Agent API`);

package/dist/errors.js

@@ -17,8 +17,10 @@ export class ConfigError extends CliError {
 }
 export class ApiError extends CliError {
     status;
-    constructor(message, status) {
+    code;
+    constructor(message, status, code) {
         super(message, 1);
         this.status = status;
+        this.code = code;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slothmoney/agent-cli",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {