import { type AgentFolder } from '../agent/folder.js'; import { type Schedule } from '../agent/schedules.js'; import type { TimerPlan } from '../schedule/timer.js'; import { type WhichFn } from '../util/which.js'; /** `cradle schedule run` is NOT here: it executes the task in-process through `commands/run.ts`, so `cli.ts` routes it there instead. */ export type ScheduleAction = 'list' | 'install' | 'remove'; /** launchd (macOS) and systemd `--user` (Linux) are the only supported timer backends. */ type SupportedSchedulePlatform = 'darwin' | 'linux'; export interface ScheduleFlags { readonly dir: string; readonly action: ScheduleAction; /** Required for `run`; an optional filter for `install`/`remove` (every schedule when absent); unused for `list`, which always lists everything. */ readonly slug?: string; /** `install` only — print the write plan and touch nothing. */ readonly dryRun?: boolean; } interface ScheduleDeps { readonly cwd?: string; readonly home?: string; readonly which?: WhichFn; readonly platform?: NodeJS.Platform; readonly uid?: number; /** The OS account name `loginctl show-user ` checks — default the real login name. */ readonly user?: string; readonly now?: () => Date; } /** * How the timer on disk relates to what this schedule file would compile to * now. `stale` is the state that matters: the files exist, so the schedule * looks live, but they were emitted from an older version of the `.md` and * the OS is still firing the old cron. */ export type TimerStatus = 'installed' | 'stale' | 'not-installed'; /** One `cradle schedule list` row — a broken cron is reported inline rather than aborting the whole listing. */ export interface ScheduleRow { readonly slug: string; readonly name: string; readonly cron: string; readonly cwd: string; readonly cronError?: string; readonly nextFire: Date | null; readonly status: TimerStatus; } /** One resolved schedule's composed timer, for `install`/`remove`/`run`. */ interface ScheduleTarget { readonly schedule: Schedule; readonly timerPlan: TimerPlan; /** Not carried by `TimerPlan` itself — `materializeSchedule` `mkdir -p`s its parent before running `installSteps`. */ readonly logPath: string; } export interface SchedulePlan { readonly action: ScheduleAction; readonly folder: AgentFolder; readonly platform: SupportedSchedulePlatform; /** Populated for `list` only. */ readonly rows: readonly ScheduleRow[]; /** Populated for `install`/`remove`/`run` — every selected schedule with its composed `TimerPlan`. */ readonly targets: readonly ScheduleTarget[]; readonly warnings: readonly string[]; readonly dryRun: boolean; /** `install` on Linux only — `materializeSchedule` runs this first and warns `LINGER_HINT` when lingering is off. */ readonly lingerCheckArgv: readonly string[] | null; } /** * Resolve the ref, load the agent folder's `schedule/`, and — for every * action but `list` — compose the selected schedule(s)' `TimerPlan`s. `list` * never throws on a single bad schedule (see `buildScheduleRow`); every other * action does, since installing/removing/firing a broken timer can't proceed. */ export declare function planSchedule(flags: ScheduleFlags, deps?: ScheduleDeps): Promise; /** Format `list`'s rows into the printed report — pure, mirroring `doctor.ts`'s `runDoctor`/`formatDoctorReport` split. */ export declare function formatScheduleList(rows: readonly ScheduleRow[]): string; export interface ScheduleRunResult { readonly exitCode: number; readonly stdout: string; readonly stderr: string; } export interface MaterializeScheduleDeps { /** Runs one launchctl/systemctl/loginctl argv, capturing both streams; `cli.ts` passes `runCaptureAll` from `util/proc.js`. */ readonly run?: (argv: readonly string[]) => Promise; } export interface MaterializeScheduleResult { readonly warnings: string[]; } /** * Apply a non-`list` plan's side effects. The caller is responsible for * skipping this entirely on `--dry-run` (`plan.dryRun`) — same precedent as * `commands/run.ts`'s `materializeRun`, which `cli.ts` never calls when * `plan.dryRun` is set. */ export declare function materializeSchedule(plan: SchedulePlan, deps?: MaterializeScheduleDeps): Promise; export {};