recess-cli 2.0.0 → 2.2.0

package/dist/commands/school.js

@@ -0,0 +1,465 @@
+import { unwrap } from "../api.js";
+import { flagList, flagString, hasFlag } from "../args.js";
+import { CliError } from "../errors.js";
+import { assertChoice, flagInteger, flagIsoInstant, positional, readJsonFile, } from "./shared.js";
+const SCHOOL_TIERS = [
+    "social",
+    "academics",
+    "lite",
+    "complete",
+    "platform",
+];
+const RESOLVE_ACTIONS = ["waive", "cancel"];
+const RECONCILIATION_OUTCOMES = ["refunded", "kept", "written_off"];
+/** post.start-memberships.ts caps the body at ten kids per call. */
+const MEMBERSHIP_KID_LIMIT = 10;
+function dollars(cents) {
+    return `$${(cents / 100).toFixed(2)}`;
+}
+function kidName(firstName, lastName, fallback) {
+    return [firstName, lastName].filter(Boolean).join(" ") || fallback;
+}
+/**
+ * `"<kid-id>:<tier>[:<slots>[:<enrollment-cents>]]"` — the same
+ * colon-delimited per-kid spec `applications enroll --kid` uses. The 4th field
+ * is the child's own first-month charge (":0" = free); OMITTING it inherits the
+ * family-level default, and when neither is given the server refuses the whole
+ * conversion as PRICE_UNDECIDED rather than guessing a price.
+ */
+function parseKidTierSpec(spec) {
+    const [kidId, tier, slots, cents, ...rest] = spec.split(":");
+    if (!kidId || !tier || rest.length > 0) {
+        throw new CliError("invalid_arguments", `--kid "${spec}" must be "<kid-id>:<tier>[:<slots>[:<enrollment-cents>]]".`);
+    }
+    const number = (value, label) => {
+        const parsed = Number(value);
+        if (!Number.isInteger(parsed) || parsed < 0) {
+            throw new CliError("invalid_arguments", `--kid "${spec}": ${label} must be a nonnegative integer.`);
+        }
+        return parsed;
+    };
+    return {
+        kidId,
+        tierId: assertChoice(tier, SCHOOL_TIERS, `--kid "${spec}" tier`),
+        ...(slots ? { slotsPerKid: number(slots, "slots") } : {}),
+        ...(cents
+            ? { enrollmentPaymentCents: number(cents, "enrollment cents") }
+            : {}),
+    };
+}
+export async function runSchoolCommand({ parsed, api, writeCommand, }) {
+    const verb = parsed.positionals[1] ?? "";
+    /**
+     * The school roster is the ONE read behind every command here: it carries the
+     * institution, each family's stage/account state and kids, the live
+     * enrollment payment, and the open reconciliation items. Every write below
+     * previews from this same response, so the approval names the same facts the
+     * dashboard shows rather than a second, differently-shaped guess.
+     */
+    const roster = async (slug) => unwrap(await api.client.GET("/admin/partner/{slug}/families", {
+        params: { path: { slug } },
+    }));
+    const requireSlug = () => flagString(parsed, "school", { required: true });
+    if (verb === "families") {
+        return roster(requireSlug());
+    }
+    if (verb === "list") {
+        return unwrap(await api.client.GET("/admin/partner/"));
+    }
+    if (verb === "family-search") {
+        const search = flagString(parsed, "query", { required: true });
+        const limit = flagInteger(parsed, "limit", { min: 1, max: 100 });
+        return unwrap(await api.client.GET("/admin/partner/{slug}/family-search", {
+            params: {
+                path: { slug: requireSlug() },
+                query: { search, ...(limit !== undefined ? { limit } : {}) },
+            },
+        }));
+    }
+    if (verb === "convert") {
+        const familyId = positional(parsed, 2, "family ID");
+        const slug = requireSlug();
+        const kids = flagList(parsed, "kid").map(parseKidTierSpec);
+        if (kids.length === 0) {
+            throw new CliError("invalid_arguments", '--kid is required, once per kid: "<kid-id>:<tier>[:<slots>[:<enrollment-cents>]]". Every kid in the family must be assigned a tier, same rule as enrollment.');
+        }
+        const creditAmountCents = flagInteger(parsed, "credit-cents", {
+            min: 0,
+            max: 1_000_000,
+        });
+        const enrollmentPaymentCentsPerKid = flagInteger(parsed, "enrollment-payment-cents", { min: 0 });
+        const note = flagString(parsed, "note");
+        const body = {
+            familyId,
+            kids,
+            ...(creditAmountCents !== undefined ? { creditAmountCents } : {}),
+            ...(enrollmentPaymentCentsPerKid !== undefined
+                ? { enrollmentPaymentCentsPerKid }
+                : {}),
+            ...(note ? { note } : {}),
+        };
+        const unpriced = kids.filter((kid) => kid.enrollmentPaymentCents === undefined &&
+            enrollmentPaymentCentsPerKid === undefined);
+        if (unpriced.length > 0) {
+            throw new CliError("invalid_arguments", `No first-month price decided for ${unpriced
+                .map((kid) => kid.kidId)
+                .join(", ")}. Give each kid a 4th spec field (":0" for free) or pass --enrollment-payment-cents for the family; the server refuses an undecided price (PRICE_UNDECIDED).`);
+        }
+        // Read-only preflight on the family's own state — the roster cannot help
+        // here, because a family being converted INTO the program is not on it yet.
+        const status = unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/status", {
+            params: { path: { familyId } },
+        }));
+        const familyKidIds = new Set(status.kids.map((kid) => kid.id));
+        const foreign = kids
+            .map((kid) => kid.kidId)
+            .filter((id) => !familyKidIds.has(id));
+        if (foreign.length > 0) {
+            throw new CliError("invalid_arguments", `Not kids in this family: ${foreign.join(", ")}.`);
+        }
+        const missing = status.kids.filter((kid) => !kids.some((k) => k.kidId === kid.id));
+        return writeCommand(parsed, {
+            action: "convert this marketplace family INTO the school program (links the institution, funds tokens, cancels live memberships)",
+            target: { familyId, slug, familyName: status.familyName },
+            request: body,
+            details: {
+                kids: kids.map((kid) => ({
+                    kid: status.kids.find((row) => row.id === kid.kidId)?.firstName ??
+                        kid.kidId,
+                    tier: kid.tierId,
+                    slots: kid.slotsPerKid ?? "the tier default",
+                    firstMonth: kid.enrollmentPaymentCents === undefined
+                        ? enrollmentPaymentCentsPerKid === undefined
+                            ? "undecided"
+                            : `${dollars(enrollmentPaymentCentsPerKid)} (family default)`
+                        : dollars(kid.enrollmentPaymentCents),
+                })),
+                ...(missing.length > 0
+                    ? {
+                        unassignedKids: missing.map((kid) => kid.firstName ?? kid.id),
+                        unassignedWarning: "These kids of the family were NOT given a tier here. They come out unassigned with 0 slots until an admin picks one.",
+                    }
+                    : {}),
+                consequences: [
+                    "Cancels live membership subscriptions at period end and turns off membership credits.",
+                    "Funds each kid top-up-to-target for the month; a lower --credit-cents is NOT topped back up until the next UTC month (it shares the cron's idempotency key).",
+                    "Existing cohort-enrollment subscriptions are deliberately left running — they migrate to token rails at their next renewal.",
+                    "Any nonzero total holds the family at PENDING_PAYMENT and gates them out of the parent app until they pay at /school/pay.",
+                    "ADMIN-only (exact-admin): a GUIDE or PROGRAM session gets 403.",
+                ],
+                reverse: `The inverse is \`school revert ${familyId} --school ${slug}\`, which is fenced off in production.`,
+            },
+        }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/convert-family", {
+            params: { path: { slug } },
+            body,
+        })));
+    }
+    if (verb === "revert") {
+        const familyId = positional(parsed, 2, "family ID");
+        const slug = requireSlug();
+        const revokeTokens = !hasFlag(parsed, "keep-tokens");
+        const note = flagString(parsed, "note");
+        const { institution, families } = await roster(slug);
+        const family = families.find((row) => row.id === familyId);
+        if (!family) {
+            throw new CliError("invalid_arguments", `Family ${familyId} is not in ${institution.name} (${slug}). Revert only applies to a family currently in that school program.`);
+        }
+        return writeCommand(parsed, {
+            action: "convert this family OUT of the school program and back to marketplace billing",
+            target: { familyId, slug, familyName: family.name },
+            request: { familyId, revokeTokens, ...(note ? { note } : {}) },
+            details: {
+                institution: institution.name,
+                accountState: family.accountState,
+                onboardingStage: family.onboardingStage,
+                kids: family.kids.map((kid) => ({
+                    id: kid.id,
+                    name: kidName(kid.firstName, kid.lastName, kid.id),
+                    creditBalance: kid.creditBalance,
+                })),
+                revokeTokens,
+                liveEnrollmentPayment: family.liveEnrollmentPayment
+                    ? {
+                        id: family.liveEnrollmentPayment.id,
+                        status: family.liveEnrollmentPayment.status,
+                        amountDue: dollars(family.liveEnrollmentPayment.amountDueCents),
+                    }
+                    : null,
+                consequences: [
+                    revokeTokens
+                        ? "Revokes each kid's remaining school token balance (shown above)."
+                        : "LEAVES each kid's school token balance in place (--keep-tokens).",
+                    "Cancels the family's program membership; kids come out with NO membership. The follow-up is `school start-memberships`, which charges their card.",
+                    "Class registrations keep running on purpose — they start billing the family's own card at renewal.",
+                    "ADMIN-only (exact-admin): a GUIDE or PROGRAM session gets 403.",
+                ],
+                fence: "Gated on SCHOOL_REVERT_ENABLED, which is fail-closed and unset in every deployed environment — production refuses until settlement ships. A 409 here is that door, not a bad request.",
+                retry: "A 409 `revert_in_flight` means an earlier attempt is still settling; rerun the unchanged command with the SAME operation key rather than minting a new one.",
+            },
+        }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/revert-family", {
+            params: { path: { slug } },
+            // Announce that this client reads the two-phase union; without the
+            // header the server sends the pre-union façade, which reports a
+            // still-settling revert as finished (revert-wire.ts).
+            headers: { "x-recess-revert-union": "1" },
+            body: { familyId, revokeTokens, ...(note ? { note } : {}) },
+        })));
+    }
+    if (verb === "start-memberships") {
+        const familyId = positional(parsed, 2, "family ID");
+        // --kid is REPEATABLE: read every occurrence, not just the last one.
+        const kidIds = flagList(parsed, "kid");
+        if (kidIds.length === 0) {
+            throw new CliError("invalid_arguments", "--kid is required: name each kid whose membership should start.");
+        }
+        if (kidIds.length > MEMBERSHIP_KID_LIMIT) {
+            throw new CliError("invalid_arguments", `--kid accepts at most ${MEMBERSHIP_KID_LIMIT} kids per call.`);
+        }
+        // Family-scoped, not slug-scoped: by the time this runs the family is no
+        // longer linked to a partner institution, so the roster read above cannot
+        // see it. The onboarding status is the read that still resolves.
+        const status = unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/status", {
+            params: { path: { familyId } },
+        }));
+        const known = new Map(status.kids.map((kid) => [kid.id, kid]));
+        const unknown = kidIds.filter((id) => !known.has(id));
+        if (unknown.length > 0) {
+            throw new CliError("invalid_arguments", `Not kids in this family: ${unknown.join(", ")}. The server refuses the whole call when one id is foreign.`);
+        }
+        return writeCommand(parsed, {
+            action: "start a paid membership subscription for these kids, CHARGING the family's card on file",
+            target: { familyId, familyName: status.familyName },
+            request: { familyId, kidIds },
+            details: {
+                kids: kidIds.map((id) => kidName(known.get(id)?.firstName ?? null, null, id)),
+                billing: "Default membership price unless the family is grandfathered onto one, with a 1-day trial, confirmed against the customer's saved default payment method.",
+                note: "A kid whose membership is already ACTIVE comes back `skipped_active` rather than being charged twice; per-kid failures are reported in `results`, not thrown.",
+            },
+        }, async () => unwrap(await api.client.POST("/admin/memberships/start", {
+            body: { familyId, kidIds },
+        })));
+    }
+    if (verb === "resolve-payment") {
+        const paymentId = positional(parsed, 2, "enrollment payment ID");
+        const slug = requireSlug();
+        const action = assertChoice(flagString(parsed, "action", { required: true }), RESOLVE_ACTIONS, "--action");
+        const note = flagString(parsed, "note");
+        const { institution, families } = await roster(slug);
+        const family = families.find((row) => row.liveEnrollmentPayment?.id === paymentId);
+        const payment = family?.liveEnrollmentPayment;
+        if (!family || !payment) {
+            throw new CliError("invalid_arguments", `No live enrollment payment ${paymentId} under ${institution.name} (${slug}). Run \`school families --school ${slug}\` and read \`liveEnrollmentPayment\`; a payment already resolved is not resolvable again.`);
+        }
+        return writeCommand(parsed, {
+            action: action === "waive"
+                ? "WAIVE this enrollment charge — record it as collected off-platform and lift the paywall"
+                : "CANCEL this enrollment charge — drop the requirement entirely and lift the paywall",
+            target: {
+                paymentId,
+                slug,
+                familyId: family.id,
+                familyName: family.name,
+            },
+            request: { action, ...(note ? { note } : {}) },
+            details: {
+                institution: institution.name,
+                status: payment.status,
+                amountDue: dollars(payment.amountDueCents),
+                lines: payment.lines.map((line) => ({
+                    kid: line.firstName ?? line.kidId ?? "unassigned",
+                    amount: dollars(line.amountCents),
+                })),
+                stripeInvoiceId: payment.stripeInvoiceId,
+                effect: "The family stops being redirected to /school/pay and class registration reopens — but ONLY if no other PENDING enrollment payment remains on the family.",
+                accountState: "PENDING_PAYMENT is walked back; a family separately set to PAUSED or BOOTED keeps that state.",
+                ...(action === "cancel"
+                    ? {
+                        cancelCaveat: "If a charge already landed, compensation is unproven and the wire status comes back CANCEL_REQUESTED — the row is still live and still blocking. That is not a failed call.",
+                    }
+                    : {}),
+            },
+        }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/enrollment-payments/{paymentId}/resolve", {
+            params: { path: { slug, paymentId } },
+            body: { action, ...(note ? { note } : {}) },
+        })));
+    }
+    if (verb === "close-reconciliation") {
+        const paymentId = positional(parsed, 2, "enrollment payment ID");
+        const slug = requireSlug();
+        const outcome = assertChoice(flagString(parsed, "outcome", { required: true }), RECONCILIATION_OUTCOMES, "--outcome");
+        const note = flagString(parsed, "note");
+        const { institution, families } = await roster(slug);
+        const family = families.find((row) => row.reconciliationItems.some((item) => item.paymentId === paymentId));
+        const item = family?.reconciliationItems.find((row) => row.paymentId === paymentId);
+        if (!family || !item) {
+            throw new CliError("invalid_arguments", `No reconciliation item for payment ${paymentId} under ${institution.name} (${slug}). Run \`school families --school ${slug}\` and read \`reconciliationItems\`.`);
+        }
+        if (item.resolution) {
+            throw new CliError("invalid_arguments", `That reconciliation item was already closed as ${item.resolution.outcome} at ${item.resolution.resolvedAt}. The close is conditional and irreversible — a second one 409s.`);
+        }
+        return writeCommand(parsed, {
+            action: `close this reconciliation item as ${outcome} (a money decision, and irreversible)`,
+            target: {
+                paymentId,
+                slug,
+                familyId: family.id,
+                familyName: family.name,
+            },
+            request: { outcome, ...(note ? { note } : {}) },
+            details: {
+                institution: institution.name,
+                amountPaid: dollars(item.amountPaidCents),
+                openedBecause: item.reason,
+                openedAt: item.openedAt,
+                paymentStatus: item.status,
+                invoiceId: item.invoiceId,
+                meaning: {
+                    refunded: "the money was returned to the family",
+                    kept: "the family genuinely owed it, so the charge stands",
+                    written_off: "neither — the business absorbed it",
+                }[outcome],
+                scope: "Bookkeeping only: this annotates the item, never deletes it, and does NOT settle a debt, unblock a family, or move the payment's status.",
+                irreversible: "The write is conditional on the item still being open, so every later attempt 409s and the item drops out of triage.",
+            },
+        }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/enrollment-payments/{paymentId}/close-reconciliation", {
+            params: { path: { slug, paymentId } },
+            body: { outcome, ...(note ? { note } : {}) },
+        })));
+    }
+    if (verb === "codes") {
+        const subverb = parsed.positionals[2] ?? "";
+        const slug = requireSlug();
+        const codeId = () => positional(parsed, 3, "invite code ID");
+        if (subverb === "list") {
+            return unwrap(await api.client.GET("/admin/partner/{slug}/codes", {
+                params: { path: { slug } },
+            }));
+        }
+        if (subverb === "get") {
+            return unwrap(await api.client.GET("/admin/partner/{slug}/codes/{id}", {
+                params: { path: { slug, id: codeId() } },
+            }));
+        }
+        if (subverb === "create") {
+            const count = flagInteger(parsed, "count", { min: 1 });
+            const expiresAt = flagIsoInstant(parsed, "expires-at");
+            const note = flagString(parsed, "note");
+            const creditAmountCents = flagInteger(parsed, "credit-cents", { min: 0 });
+            const tierRaw = flagString(parsed, "tier");
+            const slotsPerKid = flagInteger(parsed, "slots", { min: 0, max: 20 });
+            const enrollmentPaymentCentsPerKid = flagInteger(parsed, "enrollment-payment-cents", { min: 0 });
+            const dataFile = flagString(parsed, "data-file");
+            // The preconfigured-invite `family` block (parent identity + the kid
+            // roster with per-kid tier and price) is a nested object, so it arrives
+            // as JSON the way `quotes create` takes its body. Without it this mints
+            // blank codes; with it, one addressed invite that emails the parent.
+            const family = dataFile
+                ? (await readJsonFile(dataFile, "Preconfigured invite file"))
+                : undefined;
+            const body = {
+                ...(count !== undefined ? { count } : {}),
+                ...(expiresAt ? { expiresAt } : {}),
+                ...(note ? { note } : {}),
+                ...(creditAmountCents !== undefined ? { creditAmountCents } : {}),
+                ...(tierRaw
+                    ? { tierId: assertChoice(tierRaw, SCHOOL_TIERS, "--tier") }
+                    : {}),
+                ...(slotsPerKid !== undefined ? { slotsPerKid } : {}),
+                ...(enrollmentPaymentCentsPerKid !== undefined
+                    ? { enrollmentPaymentCentsPerKid }
+                    : {}),
+                ...(family ? { family } : {}),
+            };
+            return writeCommand(parsed, {
+                action: family
+                    ? "mint a preconfigured school invite for this family and EMAIL the parent their claim link"
+                    : `mint ${count ?? 1} blank school invite code(s)`,
+                target: { slug },
+                request: body,
+                details: {
+                    expiresAt: expiresAt ?? "the institution default",
+                    firstMonthPerKid: enrollmentPaymentCentsPerKid === undefined
+                        ? "not set at the family level — each kid in --data-file must carry its own price"
+                        : dollars(enrollmentPaymentCentsPerKid),
+                    ...(family
+                        ? {
+                            duplicateGuard: "The create 409s when the parent email already has a Recess account or another live invite. That is the guard, not a transient failure.",
+                        }
+                        : {
+                            blank: "No --data-file, so these are blank codes: nobody is emailed and no roster is preconfigured.",
+                        }),
+                },
+            }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/codes", {
+                params: { path: { slug } },
+                body,
+            })));
+        }
+        if (subverb === "set-kids") {
+            const id = codeId();
+            const body = (await readJsonFile(flagString(parsed, "data-file", { required: true }), "Invite roster file"));
+            return writeCommand(parsed, {
+                action: "edit an UNREDEEMED invite's roster in place — the parent's existing link keeps working",
+                target: { slug, codeId: id },
+                request: body,
+                details: {
+                    semantics: "The body is the FULL roster, not a diff: a student absent from the list is removed. `enrollmentPaymentCents` is required per student (null or 0 = that student enrolls free) so the paywall cannot be dropped by omission.",
+                    outOfScope: "Parent identity, note, credit and expiry are not editable here — changing WHO the invite is for is `codes replace`.",
+                    refusal: "Editing after redemption is refused outright; the accounts and the charge already exist.",
+                },
+            }, async () => unwrap(await api.client.PATCH("/admin/partner/{slug}/codes/{id}", {
+                params: { path: { slug, id } },
+                body,
+            })));
+        }
+        if (subverb === "replace") {
+            const id = codeId();
+            const body = (await readJsonFile(flagString(parsed, "data-file", { required: true }), "Replacement invite file"));
+            return writeCommand(parsed, {
+                action: "REPLACE this unredeemed invite: delete the old code and mint a new one, emailing the parent a fresh link",
+                target: { slug, codeId: id },
+                request: body,
+                details: {
+                    atomicity: "Delete and create run in ONE transaction, so a failure rolls back and the OLD invite survives — a failed replace is plainly retryable and never leaves the family with no invite.",
+                    whenToUse: "Use replace when the parent's identity or email changes; use `codes set-kids` to edit the roster without invalidating the link the parent already holds.",
+                    inherits: "Fields omitted from the body (note, credit) inherit from the old row read inside the transaction.",
+                },
+            }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/codes/{id}/replace", {
+                params: { path: { slug, id } },
+                body,
+            })));
+        }
+        if (subverb === "resend") {
+            const id = codeId();
+            return writeCommand(parsed, {
+                action: "re-email this invite's claim link to the parent on file",
+                target: { slug, codeId: id },
+                request: {},
+                details: {
+                    outwardEmail: "This sends mail to a real family. The code itself is unchanged — use `codes replace` to mint a new one.",
+                },
+            }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/codes/{id}/resend", {
+                params: { path: { slug, id } },
+            })));
+        }
+        if (subverb === "revoke") {
+            const id = codeId();
+            const existing = unwrap(await api.client.GET("/admin/partner/{slug}/codes/{id}", {
+                params: { path: { slug, id } },
+            }));
+            return writeCommand(parsed, {
+                action: "HARD-DELETE this unredeemed invite code",
+                target: { slug, codeId: id },
+                request: {},
+                details: {
+                    code: existing,
+                    irreversible: "The row is REMOVED, not soft-deleted: there is no deletedAt on TalentSchoolInviteCode and no undo. The parent's link stops working immediately.",
+                },
+            }, async () => unwrap(await api.client.DELETE("/admin/partner/{slug}/codes/{id}", {
+                params: { path: { slug, id } },
+            })));
+        }
+        throw new CliError("invalid_arguments", "Use school codes list|get|create|set-kids|replace|resend|revoke.");
+    }
+    throw new CliError("invalid_arguments", "Unknown school command. Run `recess school --help` for the current command list.");
+}
+//# sourceMappingURL=school.js.map

package/dist/commands/shared.js

@@ -0,0 +1,100 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { flagNumber, flagString } from "../args.js";
+import { CliError } from "../errors.js";
+export function positional(parsed, index, label) {
+    const value = parsed.positionals[index];
+    if (!value) {
+        throw new CliError("invalid_arguments", `Missing ${label}.`);
+    }
+    return value;
+}
+export function assertChoice(value, choices, label) {
+    if (!choices.includes(value)) {
+        throw new CliError("invalid_arguments", `${label} must be one of: ${choices.join(", ")}.`);
+    }
+    return value;
+}
+export function flagIdList(parsed, name) {
+    const raw = flagString(parsed, name);
+    if (raw === undefined)
+        return [];
+    const ids = raw
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (ids.length === 0) {
+        throw new CliError("invalid_arguments", `--${name} requires a value.`);
+    }
+    return ids;
+}
+export function flagBooleanValue(parsed, name) {
+    const raw = flagString(parsed, name);
+    if (raw === undefined)
+        return undefined;
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    throw new CliError("invalid_arguments", `--${name} must be true or false.`);
+}
+export function flagInteger(parsed, name, options = {}) {
+    const value = flagNumber(parsed, name);
+    if (value === undefined) {
+        if (options.required) {
+            throw new CliError("invalid_arguments", `Missing required --${name}.`);
+        }
+        return undefined;
+    }
+    if (!Number.isInteger(value) ||
+        (options.min !== undefined && value < options.min) ||
+        (options.max !== undefined && value > options.max)) {
+        const bounds = options.min !== undefined && options.max !== undefined
+            ? ` from ${options.min} through ${options.max}`
+            : options.min !== undefined
+                ? ` of at least ${options.min}`
+                : options.max !== undefined
+                    ? ` no greater than ${options.max}`
+                    : "";
+        throw new CliError("invalid_arguments", `--${name} must be an integer${bounds}.`);
+    }
+    return value;
+}
+export function flagIsoInstant(parsed, name, options = {}) {
+    const raw = flagString(parsed, name, options);
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d{4}-\d{2}-\d{2}T/.test(raw) || Number.isNaN(Date.parse(raw))) {
+        throw new CliError("invalid_arguments", `--${name} must be a full ISO-8601 datetime with a timezone.`);
+    }
+    return raw;
+}
+export async function readJsonValue(filePath, label) {
+    const absolutePath = path.resolve(filePath);
+    let raw;
+    try {
+        raw = await fs.readFile(absolutePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new CliError("invalid_arguments", `${label} does not exist: ${absolutePath}`);
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new CliError("invalid_arguments", `${label} is not valid JSON (${absolutePath}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return { absolutePath, raw, parsed };
+}
+export async function readJsonFile(filePath, label) {
+    const { absolutePath, parsed } = await readJsonValue(filePath, label);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliError("invalid_arguments", `${label} must be a JSON object (${absolutePath}).`);
+    }
+    return parsed;
+}
+//# sourceMappingURL=shared.js.map