@t4dhg/mcp-factorial 8.2.0 → 10.0.0

package/dist/attendance/gate.js

@@ -0,0 +1,63 @@
+/**
+ * Target-identity confirmation gate for attendance writes.
+ *
+ * The policy gate in tools/shared.ts (checkConfirmation) is static per
+ * operation and cannot express "depends on who the target is" or "depends on
+ * how many records". This gate can. A first call without a token writes
+ * nothing and returns a preview plus a token bound to a fingerprint of what
+ * would be written; the confirming call re-derives the fingerprint and
+ * refuses if it changed. A `confirm: true` boolean cannot bypass it, because
+ * there is no token to pass on a first call.
+ */
+import { createHash } from 'node:crypto';
+import { confirmationManager } from '../confirmation.js';
+import { ConfirmationExpiredError } from '../errors.js';
+import { isConfiguredIdentity } from './identity.js';
+/** Stable digest of an arbitrary payload */
+export function payloadFingerprint(payload) {
+    return createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+}
+function issue(request, prefix = '') {
+    const token = confirmationManager.createConfirmation(request.operation, { fingerprint: request.fingerprint, employeeId: request.employeeId }, {
+        operation: 'create',
+        entityType: 'shift',
+        entityId: request.employeeId,
+        entityName: request.preview.split('\n')[0],
+        warnings: [],
+    });
+    return {
+        proceed: false,
+        message: `${prefix}${request.preview}\n\nNothing has been written. ` +
+            `To proceed, call this action again with the same arguments and confirmation_token: ${token}\n` +
+            'The token is valid for 5 minutes and for exactly this plan.',
+    };
+}
+/**
+ * Decide whether a write may proceed. Writes aimed at the configured identity
+ * pass without a token unless `always` is set; every other write, and every
+ * write when FACTORIAL_EMPLOYEE_ID is unset, needs one.
+ */
+export function requireTargetConfirmation(request) {
+    const gated = request.always === true || !isConfiguredIdentity(request.employeeId);
+    if (!gated)
+        return { proceed: true };
+    if (!request.token)
+        return issue(request);
+    let pending;
+    try {
+        pending = confirmationManager.confirm(request.token);
+    }
+    catch (error) {
+        if (error instanceof ConfirmationExpiredError) {
+            return issue(request, 'The confirmation token was invalid or had expired. Here is the current plan.\n\n');
+        }
+        throw error;
+    }
+    if (pending.operation !== request.operation ||
+        pending.payload.fingerprint !== request.fingerprint) {
+        return issue(request, 'The plan changed between the preview and this call (someone wrote in the meantime, or the ' +
+            'arguments differ). The old token has been discarded. Here is the current plan.\n\n');
+    }
+    return { proceed: true };
+}
+//# sourceMappingURL=gate.js.map

package/dist/attendance/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/attendance/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAmBrD,4CAA4C;AAC5C,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC5E,CAAC;AAED,SAAS,KAAK,CAAC,OAAoB,EAAE,MAAM,GAAG,EAAE;IAC9C,MAAM,KAAK,GAAG,mBAAmB,CAAC,kBAAkB,CAClD,OAAO,CAAC,SAAS,EACjB,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,EACpE;QACE,SAAS,EAAE,QAAQ;QACnB,UAAU,EAAE,OAAO;QACnB,QAAQ,EAAE,OAAO,CAAC,UAAU;QAC5B,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC1C,QAAQ,EAAE,EAAE;KACb,CACF,CAAC;IACF,OAAO;QACL,OAAO,EAAE,KAAK;QACd,OAAO,EACL,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,gCAAgC;YAC3D,sFAAsF,KAAK,IAAI;YAC/F,6DAA6D;KAChE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAoB;IAC5D,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACnF,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAErC,IAAI,CAAC,OAAO,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC;IAE1C,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,wBAAwB,EAAE,CAAC;YAC9C,OAAO,KAAK,CACV,OAAO,EACP,kFAAkF,CACnF,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IAED,IACE,OAAO,CAAC,SAAS,KAAK,OAAO,CAAC,SAAS;QACvC,OAAO,CAAC,OAAO,CAAC,WAAW,KAAK,OAAO,CAAC,WAAW,EACnD,CAAC;QACD,OAAO,KAAK,CACV,OAAO,EACP,4FAA4F;YAC1F,oFAAoF,CACvF,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC"}

package/dist/attendance/identity.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Who "I" am for attendance actions.
+ *
+ * A company-scoped API key carries no employee: /api_public/credentials
+ * returns employee_id null. The optional FACTORIAL_EMPLOYEE_ID variable
+ * supplies the default target for every attendance action, and every write
+ * aimed at anyone else is treated as aimed at another person by the safety
+ * gate in tools/attendance.ts.
+ */
+/** Read and validate FACTORIAL_EMPLOYEE_ID; undefined when unset */
+export declare function getConfiguredEmployeeId(): number | undefined;
+/**
+ * Resolve the employee an action targets: the explicit argument wins, then the
+ * configured default. With neither, the caller must name someone.
+ */
+export declare function resolveTargetEmployeeId(explicit: number | undefined): number;
+/** True when the target is the configured identity (never true when unset) */
+export declare function isConfiguredIdentity(employeeId: number): boolean;
+/**
+ * Resolve an employee id to a display name through the employees API, cached
+ * for the life of the process. Fails loudly when the id does not resolve, so a
+ * mistyped FACTORIAL_EMPLOYEE_ID cannot silently write onto a colleague.
+ */
+export declare function resolveEmployeeName(employeeId: number): Promise<string>;
+/** Forget resolved names (tests) */
+export declare function clearResolvedNames(): void;
+//# sourceMappingURL=identity.d.ts.map

package/dist/attendance/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/attendance/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,oEAAoE;AACpE,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,SAAS,CAU5D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAc5E;AAED,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAGhE;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB7E;AAED,oCAAoC;AACpC,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/attendance/identity.js

@@ -0,0 +1,73 @@
+/**
+ * Who "I" am for attendance actions.
+ *
+ * A company-scoped API key carries no employee: /api_public/credentials
+ * returns employee_id null. The optional FACTORIAL_EMPLOYEE_ID variable
+ * supplies the default target for every attendance action, and every write
+ * aimed at anyone else is treated as aimed at another person by the safety
+ * gate in tools/attendance.ts.
+ */
+import { getEmployee } from '../api/employees.js';
+let resolvedNames = new Map();
+/** Read and validate FACTORIAL_EMPLOYEE_ID; undefined when unset */
+export function getConfiguredEmployeeId() {
+    const raw = process.env.FACTORIAL_EMPLOYEE_ID;
+    if (raw === undefined || raw.trim() === '')
+        return undefined;
+    if (!/^[1-9]\d*$/.test(raw.trim())) {
+        throw new Error(`FACTORIAL_EMPLOYEE_ID must be a positive integer employee id, got "${raw}". ` +
+            'Unset it to require employee_id on every attendance action.');
+    }
+    return Number(raw.trim());
+}
+/**
+ * Resolve the employee an action targets: the explicit argument wins, then the
+ * configured default. With neither, the caller must name someone.
+ */
+export function resolveTargetEmployeeId(explicit) {
+    if (explicit !== undefined) {
+        if (!Number.isInteger(explicit) || explicit <= 0) {
+            throw new Error('employee_id must be a positive integer');
+        }
+        return explicit;
+    }
+    const configured = getConfiguredEmployeeId();
+    if (configured === undefined) {
+        throw new Error('employee_id is required: FACTORIAL_EMPLOYEE_ID is not set, so there is no default identity.');
+    }
+    return configured;
+}
+/** True when the target is the configured identity (never true when unset) */
+export function isConfiguredIdentity(employeeId) {
+    const configured = getConfiguredEmployeeId();
+    return configured !== undefined && configured === employeeId;
+}
+/**
+ * Resolve an employee id to a display name through the employees API, cached
+ * for the life of the process. Fails loudly when the id does not resolve, so a
+ * mistyped FACTORIAL_EMPLOYEE_ID cannot silently write onto a colleague.
+ */
+export async function resolveEmployeeName(employeeId) {
+    const cached = resolvedNames.get(employeeId);
+    if (cached)
+        return cached;
+    let name;
+    try {
+        const employee = await getEmployee(employeeId);
+        name = employee.full_name || `${employee.first_name ?? ''} ${employee.last_name ?? ''}`.trim();
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Employee ${employeeId} could not be resolved (${reason}). ` +
+            'Check the employee_id argument or the FACTORIAL_EMPLOYEE_ID setting.');
+    }
+    if (!name)
+        name = `employee ${employeeId}`;
+    resolvedNames.set(employeeId, name);
+    return name;
+}
+/** Forget resolved names (tests) */
+export function clearResolvedNames() {
+    resolvedNames = new Map();
+}
+//# sourceMappingURL=identity.js.map

package/dist/attendance/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/attendance/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,IAAI,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;AAE9C,oEAAoE;AACpE,MAAM,UAAU,uBAAuB;IACrC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;IAC9C,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAC7D,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,sEAAsE,GAAG,KAAK;YAC5E,6DAA6D,CAChE,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAA4B;IAClE,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;YACjD,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAC5D,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,MAAM,UAAU,GAAG,uBAAuB,EAAE,CAAC;IAC7C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,6FAA6F,CAC9F,CAAC;IACJ,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,oBAAoB,CAAC,UAAkB;IACrD,MAAM,UAAU,GAAG,uBAAuB,EAAE,CAAC;IAC7C,OAAO,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,UAAU,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,UAAkB;IAC1D,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC7C,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,UAAU,CAAC,CAAC;QAC/C,IAAI,GAAG,QAAQ,CAAC,SAAS,IAAI,GAAG,QAAQ,CAAC,UAAU,IAAI,EAAE,IAAI,QAAQ,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;IACjG,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,IAAI,KAAK,CACb,YAAY,UAAU,2BAA2B,MAAM,KAAK;YAC1D,sEAAsE,CACzE,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,IAAI;QAAE,IAAI,GAAG,YAAY,UAAU,EAAE,CAAC;IAC3C,aAAa,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IACpC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,oCAAoC;AACpC,MAAM,UAAU,kBAAkB;IAChC,aAAa,GAAG,IAAI,GAAG,EAAE,CAAC;AAC5B,CAAC"}

package/dist/attendance/planner.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Backfill planner for attendance shifts (registro horario).
+ *
+ * Everything in this module is pure: no network, no clock, no configuration.
+ * The caller gathers facts from the API (worked_times, estimated_times,
+ * existing shifts, approved leaves) and the planner turns them plus the
+ * requested segments into an explicit list of writes and skips. Every rule is
+ * a unit test in src/__tests__/unit/attendance/planner.test.ts.
+ */
+/** A working segment on one day, in company local wall-clock time */
+export interface Segment {
+    clock_in: string;
+    clock_out: string;
+}
+/** One planned shift record */
+export interface PlannedWrite extends Segment {
+    date: string;
+}
+/** What is known about one calendar day for one employee */
+export interface DayFacts {
+    /** worked_times.day_type: workday | saturday | sunday | bank_holiday */
+    day_type: string;
+    /** estimated_times.expected_minutes, from the contract pattern */
+    expected_minutes: number;
+    /** worked_times.tracked_minutes */
+    tracked_minutes: number;
+}
+/** An existing shift as the API reports it; clock_out null means still open */
+export interface ExistingShift {
+    date: string;
+    clock_in: string;
+    clock_out: string | null;
+}
+/** How an approved leave covers a date */
+export type LeaveCover = 'full' | 'beggining_of_day' | 'end_of_day';
+/** The subset of a leave record the planner needs */
+export interface LeaveLike {
+    start_on: string;
+    finish_on: string;
+    half_day: string | null;
+    approved: boolean | null;
+    deleted_at: string | null;
+}
+export interface PlanFacts {
+    /** Today's date, YYYY-MM-DD, in the zone the caller considers local */
+    today: string;
+    /** Per-date facts; a date missing from the map has no contract data */
+    days: Map<string, DayFacts>;
+    /** Existing shifts for the employee within the planned dates */
+    shifts: ExistingShift[];
+    /** Approved leave cover per date, see expandLeaves */
+    leaves: Map<string, LeaveCover>;
+}
+export interface RangeRequest {
+    mode: 'range';
+    employee_id: number;
+    dates: string[];
+    segments: Segment[];
+    skip_leave: boolean;
+}
+export interface DaysRequest {
+    mode: 'days';
+    employee_id: number;
+    days: Array<{
+        date: string;
+        segments: Segment[];
+    }>;
+    skip_leave: boolean;
+}
+export type PlanRequest = RangeRequest | DaysRequest;
+export type SkipReason = 'future_date' | 'weekend' | 'bank_holiday' | 'not_workable' | 'on_leave' | 'half_day_leave';
+export interface SkippedDay {
+    date: string;
+    reason: SkipReason;
+    detail?: string;
+}
+export interface SkippedSegment extends Segment {
+    date: string;
+    reason: 'overlaps_existing';
+    detail: string;
+}
+export interface BackfillPlan {
+    writes: PlannedWrite[];
+    skippedDays: SkippedDay[];
+    skippedSegments: SkippedSegment[];
+    totals: {
+        days: number;
+        records: number;
+        minutes: number;
+    };
+}
+export interface Gap {
+    date: string;
+    expected_minutes: number;
+    tracked_minutes: number;
+    missing_minutes: number;
+    half_day_leave: 'beggining_of_day' | 'end_of_day' | null;
+}
+/** Parse "HH:MM" into minutes since midnight; anything else is rejected */
+export declare function parseHHMM(value: string): number;
+/** True when two [start, end) intervals share any time; touching does not count */
+export declare function intervalsOverlap(a: [number, number], b: [number, number]): boolean;
+/** Every date from start to end inclusive */
+export declare function enumerateDates(start: string, end: string): string[];
+/**
+ * Validate the segments of one day: HH:MM only, clock_in strictly before
+ * clock_out, no overnight shifts, no overlap between segments.
+ */
+export declare function validateSegments(segments: Segment[]): void;
+/**
+ * Turn leave records into a per-date cover map. Only approved, undeleted
+ * leaves count; a pending (approved: null) or rejected leave does not block
+ * anything. A later leave over the same date never downgrades a full cover.
+ */
+export declare function expandLeaves(leaves: LeaveLike[]): Map<string, LeaveCover>;
+/**
+ * Build the plan. Skip reasons are evaluated in the documented order and the
+ * first match wins. Explicit days skip the weekday, holiday and workability
+ * rules on purpose: migration must be able to write a Saturday someone worked.
+ */
+export declare function buildBackfillPlan(request: PlanRequest, facts: PlanFacts): BackfillPlan;
+/**
+ * Stable digest of who and what a plan writes, including the note stored on
+ * every record; the confirmation token is bound to it.
+ */
+export declare function planFingerprint(employeeId: number, writes: PlannedWrite[], observations?: string): string;
+/**
+ * Workdays up to today where the contract expects more than was tracked and no
+ * full-day leave applies. Future dates are left out, since log_range would
+ * refuse them anyway.
+ */
+export declare function computeGaps(facts: PlanFacts): Gap[];
+/** 720 -> "12h", 750 -> "12h30" */
+export declare function hours(minutes: number): string;
+/**
+ * Render the plan the way the confirmation step shows it. It always names the
+ * person, because the company-wide key makes writing someone else's hours the
+ * mistake worth catching.
+ */
+export declare function formatPlanPreview(plan: BackfillPlan, employee: {
+    id: number;
+    name: string;
+}, range: {
+    start: string;
+    end: string;
+}, request: PlanRequest, observations?: string): string;
+//# sourceMappingURL=planner.d.ts.map

package/dist/attendance/planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../src/attendance/planner.ts"],"names":[],"mappings":"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"}

package/dist/attendance/planner.js

@@ -0,0 +1,316 @@
+/**
+ * Backfill planner for attendance shifts (registro horario).
+ *
+ * Everything in this module is pure: no network, no clock, no configuration.
+ * The caller gathers facts from the API (worked_times, estimated_times,
+ * existing shifts, approved leaves) and the planner turns them plus the
+ * requested segments into an explicit list of writes and skips. Every rule is
+ * a unit test in src/__tests__/unit/attendance/planner.test.ts.
+ */
+import { createHash } from 'node:crypto';
+const HHMM = /^([01]\d|2[0-3]):([0-5]\d)$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const END_OF_DAY = 24 * 60;
+/** Parse "HH:MM" into minutes since midnight; anything else is rejected */
+export function parseHHMM(value) {
+    const match = HHMM.exec(value);
+    if (!match) {
+        throw new Error(`Time "${value}" must be HH:MM in 24-hour company local time`);
+    }
+    return Number(match[1]) * 60 + Number(match[2]);
+}
+/** True when two [start, end) intervals share any time; touching does not count */
+export function intervalsOverlap(a, b) {
+    return a[0] < b[1] && b[0] < a[1];
+}
+function assertDate(value) {
+    if (!DATE.test(value) || Number.isNaN(Date.parse(`${value}T00:00:00Z`))) {
+        throw new Error(`Date "${value}" must be YYYY-MM-DD`);
+    }
+}
+/** Every date from start to end inclusive */
+export function enumerateDates(start, end) {
+    assertDate(start);
+    assertDate(end);
+    if (start > end) {
+        throw new Error(`start_on ${start} is after end_on ${end}`);
+    }
+    const dates = [];
+    const cursor = new Date(`${start}T00:00:00Z`);
+    const last = new Date(`${end}T00:00:00Z`);
+    while (cursor <= last) {
+        dates.push(cursor.toISOString().slice(0, 10));
+        cursor.setUTCDate(cursor.getUTCDate() + 1);
+    }
+    return dates;
+}
+/**
+ * Validate the segments of one day: HH:MM only, clock_in strictly before
+ * clock_out, no overnight shifts, no overlap between segments.
+ */
+export function validateSegments(segments) {
+    if (segments.length === 0) {
+        throw new Error('segments must contain at least one {clock_in, clock_out} entry');
+    }
+    const intervals = segments.map(segment => {
+        const start = parseHHMM(segment.clock_in);
+        const end = parseHHMM(segment.clock_out);
+        if (end < start) {
+            throw new Error(`Segment ${segment.clock_in}-${segment.clock_out} ends before it starts. Overnight shifts ` +
+                'are not supported by the bulk actions; use the create action with reference_date instead.');
+        }
+        if (end === start) {
+            throw new Error(`Segment ${segment.clock_in}-${segment.clock_out}: clock_in must be before clock_out`);
+        }
+        return [start, end];
+    });
+    for (let i = 0; i < intervals.length; i++) {
+        for (let j = i + 1; j < intervals.length; j++) {
+            if (intervalsOverlap(intervals[i], intervals[j])) {
+                throw new Error(`Segments ${segments[i].clock_in}-${segments[i].clock_out} and ` +
+                    `${segments[j].clock_in}-${segments[j].clock_out} overlap each other`);
+            }
+        }
+    }
+}
+/**
+ * Turn leave records into a per-date cover map. Only approved, undeleted
+ * leaves count; a pending (approved: null) or rejected leave does not block
+ * anything. A later leave over the same date never downgrades a full cover.
+ */
+export function expandLeaves(leaves) {
+    const cover = new Map();
+    for (const leave of leaves) {
+        if (leave.approved !== true || leave.deleted_at !== null)
+            continue;
+        const kind = leave.half_day === 'beggining_of_day' || leave.half_day === 'end_of_day'
+            ? leave.half_day
+            : 'full';
+        for (const date of enumerateDates(leave.start_on, leave.finish_on)) {
+            const existing = cover.get(date);
+            if (existing === 'full')
+                continue;
+            cover.set(date, kind);
+        }
+    }
+    return cover;
+}
+function daySkipReason(date, request, facts) {
+    if (date > facts.today) {
+        return {
+            date,
+            reason: 'future_date',
+            detail: `today is ${facts.today} in the zone of the machine running the server`,
+        };
+    }
+    const day = facts.days.get(date);
+    if (request.mode === 'range') {
+        if (day?.day_type === 'saturday' || day?.day_type === 'sunday') {
+            return { date, reason: 'weekend' };
+        }
+        if (day?.day_type === 'bank_holiday') {
+            return { date, reason: 'bank_holiday' };
+        }
+        if (!day || day.expected_minutes <= 0) {
+            return {
+                date,
+                reason: 'not_workable',
+                detail: day ? 'contract expects 0 minutes' : 'no contract data for this date',
+            };
+        }
+    }
+    if (request.skip_leave) {
+        const cover = facts.leaves.get(date);
+        if (cover === 'full') {
+            return { date, reason: 'on_leave', detail: 'approved leave' };
+        }
+        if (cover && request.mode === 'range') {
+            return {
+                date,
+                reason: 'half_day_leave',
+                detail: `approved half-day leave (${cover}); write it with log_days if the other half was worked`,
+            };
+        }
+    }
+    return null;
+}
+function existingIntervals(shifts, date) {
+    return shifts
+        .filter(shift => shift.date === date)
+        .map(shift => {
+        let start;
+        let end;
+        try {
+            start = parseHHMM(shift.clock_in);
+            end = shift.clock_out === null ? END_OF_DAY : parseHHMM(shift.clock_out);
+        }
+        catch {
+            throw new Error(`An existing shift on ${date} has times the planner cannot read ` +
+                `(${shift.clock_in}-${shift.clock_out ?? 'open'}). Fix or delete that record first.`);
+        }
+        // An overnight existing shift (clock_out before clock_in) occupies to end of day.
+        if (end < start)
+            end = END_OF_DAY;
+        const label = `${shift.clock_in}-${shift.clock_out ?? 'open'}`;
+        return [start, end, label];
+    });
+}
+/**
+ * Build the plan. Skip reasons are evaluated in the documented order and the
+ * first match wins. Explicit days skip the weekday, holiday and workability
+ * rules on purpose: migration must be able to write a Saturday someone worked.
+ */
+export function buildBackfillPlan(request, facts) {
+    const requested = request.mode === 'range'
+        ? request.dates.map(date => ({ date, segments: request.segments }))
+        : request.days;
+    if (request.mode === 'range') {
+        validateSegments(request.segments);
+    }
+    else {
+        const seen = new Set();
+        for (const day of request.days) {
+            assertDate(day.date);
+            if (seen.has(day.date)) {
+                throw new Error(`Date ${day.date} appears more than once in days`);
+            }
+            seen.add(day.date);
+            validateSegments(day.segments);
+        }
+    }
+    const writes = [];
+    const skippedDays = [];
+    const skippedSegments = [];
+    const writtenDates = new Set();
+    let minutes = 0;
+    for (const { date, segments } of requested) {
+        const skip = daySkipReason(date, request, facts);
+        if (skip) {
+            skippedDays.push(skip);
+            continue;
+        }
+        const existing = existingIntervals(facts.shifts, date);
+        for (const segment of segments) {
+            const interval = [
+                parseHHMM(segment.clock_in),
+                parseHHMM(segment.clock_out),
+            ];
+            const clash = existing.find(([start, end]) => intervalsOverlap(interval, [start, end]));
+            if (clash) {
+                skippedSegments.push({
+                    date,
+                    ...segment,
+                    reason: 'overlaps_existing',
+                    detail: `overlaps existing ${clash[2]}`,
+                });
+                continue;
+            }
+            writes.push({ date, ...segment });
+            writtenDates.add(date);
+            minutes += interval[1] - interval[0];
+        }
+    }
+    return {
+        writes,
+        skippedDays,
+        skippedSegments,
+        totals: { days: writtenDates.size, records: writes.length, minutes },
+    };
+}
+/**
+ * Stable digest of who and what a plan writes, including the note stored on
+ * every record; the confirmation token is bound to it.
+ */
+export function planFingerprint(employeeId, writes, observations) {
+    const canonical = writes
+        .map(w => `${w.date} ${w.clock_in} ${w.clock_out}`)
+        .sort()
+        .join('\n');
+    return createHash('sha256')
+        .update(`${employeeId}\n${observations ?? ''}\n${canonical}`)
+        .digest('hex');
+}
+/**
+ * Workdays up to today where the contract expects more than was tracked and no
+ * full-day leave applies. Future dates are left out, since log_range would
+ * refuse them anyway.
+ */
+export function computeGaps(facts) {
+    const gaps = [];
+    for (const [date, day] of [...facts.days.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        if (date > facts.today)
+            continue;
+        if (day.day_type !== 'workday')
+            continue;
+        if (day.expected_minutes <= day.tracked_minutes)
+            continue;
+        const cover = facts.leaves.get(date);
+        if (cover === 'full')
+            continue;
+        gaps.push({
+            date,
+            expected_minutes: day.expected_minutes,
+            tracked_minutes: day.tracked_minutes,
+            missing_minutes: day.expected_minutes - day.tracked_minutes,
+            half_day_leave: cover ?? null,
+        });
+    }
+    return gaps;
+}
+/** 720 -> "12h", 750 -> "12h30" */
+export function hours(minutes) {
+    const whole = Math.floor(minutes / 60);
+    const rest = minutes % 60;
+    return rest === 0 ? `${whole}h` : `${whole}h${String(rest).padStart(2, '0')}`;
+}
+function countBy(items) {
+    const counts = new Map();
+    for (const item of items)
+        counts.set(item.reason, (counts.get(item.reason) ?? 0) + 1);
+    return counts;
+}
+/**
+ * Render the plan the way the confirmation step shows it. It always names the
+ * person, because the company-wide key makes writing someone else's hours the
+ * mistake worth catching.
+ */
+export function formatPlanPreview(plan, employee, range, request, observations) {
+    const lines = [];
+    lines.push(`Plan for ${employee.name} (${employee.id})`);
+    lines.push(`${range.start} .. ${range.end}`);
+    lines.push('');
+    lines.push(`  ${plan.totals.days} days to write, ${plan.totals.records} shift records, ${hours(plan.totals.minutes)}`);
+    if (request.mode === 'range') {
+        lines.push(`  ${request.segments.map(s => `${s.clock_in}-${s.clock_out}`).join(' and ')}`);
+    }
+    if (observations) {
+        lines.push(`  Note on every record: "${observations}"`);
+    }
+    if (plan.skippedDays.length > 0) {
+        lines.push('');
+        lines.push(`  Skipping ${plan.skippedDays.length} days:`);
+        const byReason = countBy(plan.skippedDays);
+        const labels = {
+            future_date: 'in the future',
+            weekend: 'weekend',
+            bank_holiday: 'bank holiday',
+            not_workable: 'not workable under the contract',
+            on_leave: 'approved leave',
+            half_day_leave: 'half-day leave, write it with log_days if the other half was worked',
+        };
+        for (const [reason, count] of byReason) {
+            const dates = plan.skippedDays.filter(d => d.reason === reason).map(d => d.date);
+            const suffix = reason === 'weekend' ? '' : ` (${dates.join(', ')})`;
+            lines.push(`    ${count} ${labels[reason]}${suffix}`);
+        }
+    }
+    if (plan.skippedSegments.length > 0) {
+        lines.push('');
+        lines.push(`  Skipping ${plan.skippedSegments.length} segments that overlap existing shifts:`);
+        for (const segment of plan.skippedSegments) {
+            lines.push(`    ${segment.date} ${segment.clock_in}-${segment.clock_out} ${segment.detail}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=planner.js.map