recess-cli 3.3.0 → 3.3.1

package/dist/args.js

@@ -6,6 +6,7 @@ import { CliError } from "./errors.js";
  */
 export const REPEATABLE_FLAGS = new Set(["kid", "unassign"]);
 const BOOLEAN_FLAGS = new Set([
+    "zero-balance",
     "allow-assigned-edits",
     "all-references",
     "allow-strand",

package/dist/cli.js

@@ -255,7 +255,8 @@ async function localWriteCommand(parsed, preview, execute) {
             fingerprint,
             target: preview.target,
             ...(preview.action.startsWith("mastery.") ||
-                preview.request.attendanceTakenAt
+                preview.request.attendanceTakenAt ||
+                preview.request.zeroBalance === "true"
                 ? { preview }
                 : {}),
         });
@@ -3045,6 +3046,24 @@ export async function executeRecessCommand(argv, options = {}) {
             const account = unwrap(await api.client.GET("/admin/payout/recipient/", {
                 params: { query: { id: accountId, includeArchived: "true" } },
             })).recipients[0];
+            const zeroBalance = hasFlag(parsed, "zero-balance");
+            // Keep the approved before-balance on retries, so the server can replay
+            // a completed operation after the account has already been zeroed.
+            const operationKey = flagString(parsed, "operation-key");
+            const stored = zeroBalance && hasFlag(parsed, "confirm") && operationKey
+                ? await getJob(operationKey)
+                : undefined;
+            const approvedBalance = stored?.history.find((event) => event.preview?.request.zeroBalance === "true")?.preview?.request.expectedBalanceCents;
+            const expectedBalanceCents = typeof approvedBalance === "number"
+                ? approvedBalance
+                : account.accountBalance;
+            const removalQuery = zeroBalance
+                ? {
+                    zeroBalance: "true",
+                    reason: flagString(parsed, "reason", { required: true }),
+                    expectedBalanceCents,
+                }
+                : {};
             const effects = action === "archive"
                 ? "Archive payout account, end all schedules and cancel all draft/review invoices. Stops new Recess accruals; preserves payment history and the guide login."
                 : action === "unarchive"
@@ -3055,18 +3074,27 @@ export async function executeRecessCommand(argv, options = {}) {
                             ? "Add active payout account to recurring schedule. Future payroll cycles will accrue compensation in Recess."
                             : "Remove account from this payroll cycle and cancel its draft/review invoices. Future cycles are unchanged; regeneration will not re-add this account.";
             return writeCommand(parsed, {
-                action: effects,
+                action: effects +
+                    (zeroBalance
+                        ? " OVERRIDE: cancel unpaid OPEN invoices in this scope and set the entire account balance to zero. Invoice amounts and payment history are preserved; no money is sent. Pending payments and obligations outside this scope must be resolved first."
+                        : ""),
                 target: {
                     accountId,
                     ...(payRunId ? { payRunId } : {}),
                     ...(scheduleId ? { scheduleId } : {}),
                 },
-                request: { action },
-                details: { accountName: account.name, user: account.user },
+                request: { action, ...removalQuery },
+                details: {
+                    accountName: account.name,
+                    user: account.user,
+                    ...(zeroBalance
+                        ? { previousBalanceCents: expectedBalanceCents, balanceCents: 0 }
+                        : {}),
+                },
             }, async () => {
                 if (action === "archive")
                     return unwrap(await api.client.DELETE("/admin/payout/recipient/{accountId}", {
-                        params: { path: { accountId } },
+                        params: { path: { accountId }, query: removalQuery },
                     }));
                 if (action === "unarchive")
                     return unwrap(await api.client.POST("/admin/payout/recipient/{accountId}/unarchive", { params: { path: { accountId } } }));
@@ -3075,8 +3103,18 @@ export async function executeRecessCommand(argv, options = {}) {
                         body: { accountId, scheduleId: scheduleId },
                     }));
                 if (action === "remove-schedule")
-                    return unwrap(await api.client.DELETE("/admin/payout/schedule/{targetId}/recipient/{accountId}", { params: { path: { accountId, targetId: scheduleId } } }));
-                return unwrap(await api.client.DELETE("/admin/payout/cycle/{targetId}/recipient/{accountId}", { params: { path: { accountId, targetId: payRunId } } }));
+                    return unwrap(await api.client.DELETE("/admin/payout/schedule/{targetId}/recipient/{accountId}", {
+                        params: {
+                            path: { accountId, targetId: scheduleId },
+                            query: removalQuery,
+                        },
+                    }));
+                return unwrap(await api.client.DELETE("/admin/payout/cycle/{targetId}/recipient/{accountId}", {
+                    params: {
+                        path: { accountId, targetId: payRunId },
+                        query: removalQuery,
+                    },
+                }));
             });
         }
         if (area === "invoices" && action === "list") {

package/dist/command-schema.js

@@ -1,6 +1,7 @@
 import { CliError } from "./errors.js";
 export const AGENT_CONTEXT_SCHEMA_VERSION = "4";
 const BOOLEAN_FLAGS = new Set([
+    "zero-balance",
     "allow-possible-duplicate",
     "allow-state-modification",
     "allow-assigned-edits",

package/dist/help.js

@@ -134,11 +134,11 @@ Usage:
     [--limit 20] [--cursor <id>]
   recess [--json] payout invoices list [--payrun <id>] [--recipient <account-id>]
     [--user <id>] [--status A,B]   (at least one filter)
-  recess [--json] payout recipients archive <account-id> [--confirm]
+  recess [--json] payout recipients archive <account-id> [--zero-balance] [--confirm]
   recess [--json] payout recipients unarchive <account-id> [--confirm]
-  recess [--json] payout recipients remove-schedule <account-id> --schedule <id> [--confirm]
+  recess [--json] payout recipients remove-schedule <account-id> --schedule <id> [--zero-balance] [--confirm]
   recess [--json] payout recipients add-schedule <account-id> --schedule <id> [--confirm]
-  recess [--json] payout payruns remove-account <payrun-id> --recipient <account-id> [--confirm]
+  recess [--json] payout payruns remove-account <payrun-id> --recipient <account-id> [--zero-balance] [--confirm]
   recess [--json] payout invoices get <invoice-id>
   recess [--json] payout invoices set-status <invoice-id>
     --status IN_REVIEW|OPEN|PAID|CANCELED [--send-email] [--confirm]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recess-cli",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "description": "Safe Recess administration and family AI tools from the command line.",
   "license": "UNLICENSED",
   "repository": {