@coryrylan/cradle 1.3.1 → 1.4.1

package/dist/schedule/cron.d.ts

@@ -0,0 +1,22 @@
+/** A parsed cron field: the allowed values, or `null` meaning "every". */
+export type CronField = readonly number[] | null;
+export interface CronFields {
+    readonly minute: CronField;
+    readonly hour: CronField;
+    readonly dayOfMonth: CronField;
+    readonly month: CronField;
+    readonly dayOfWeek: CronField;
+}
+/**
+ * Parse a 5-field cron expression or a `@`-macro into structured fields.
+ * Throws a named error when the expression is malformed, or when
+ * day-of-month and day-of-week are both restricted (see the check below).
+ */
+export declare function parseCron(expression: string): CronFields;
+/**
+ * The next occurrence strictly after `from`, in local time, truncated to the
+ * minute. Returns `null` when nothing matches within 366 days — the guard
+ * against an expression that can never fire, such as day-of-month 30 paired
+ * with February.
+ */
+export declare function nextFire(fields: CronFields, from: Date): Date | null;

package/dist/schedule/launchd.d.ts

@@ -0,0 +1,12 @@
+import type { CronFields } from './cron.js';
+import type { TimerContext, TimerPlan } from './timer.js';
+/** Thrown when a cron expression's constrained fields would expand past `MAX_CALENDAR_INTERVALS` dicts. */
+export declare class LaunchdIntervalOverflowError extends Error {
+    constructor(dictCount: number);
+}
+/**
+ * Compose the LaunchAgent plist plus its `launchctl` install/remove steps. `dayOfMonth`/`dayOfWeek` are never both constrained (`parseCron`
+ * rejects that combination), so the cartesian product below never needs to
+ * reproduce cron's OR semantics between them.
+ */
+export declare function composeLaunchdTimer(context: TimerContext, fields: CronFields): TimerPlan;

package/dist/schedule/systemd.d.ts

@@ -0,0 +1,17 @@
+import type { CronFields } from './cron.js';
+import type { TimerContext, TimerPlan } from './timer.js';
+/** Thrown when a value bound for a unit file contains a raw newline, which would corrupt the ini-style syntax. */
+export declare class SystemdUnitValueError extends Error {
+    constructor(value: string);
+}
+/**
+ * Compose the `.service`/`.timer` unit pair plus their `systemctl --user`
+ * install/remove steps. `dayOfMonth`/`dayOfWeek` are never both
+ * constrained (`parseCron` rejects that combination), so `OnCalendar=`
+ * below never needs to reproduce cron's OR semantics between them.
+ */
+export declare function composeSystemdTimer(context: TimerContext, fields: CronFields): TimerPlan;
+/** `loginctl show-user <user> --property=Linger` — user timers do not fire without a session unless lingering is on. */
+export declare function composeLingerCheckArgv(user: string): readonly string[];
+/** One-line hint for the command layer to surface when lingering is off. */
+export declare const LINGER_HINT = "systemd user timers stop firing once you log out unless lingering is enabled \u2014 run `loginctl enable-linger <user>` to keep them running";

package/dist/schedule/timer.d.ts

@@ -0,0 +1,34 @@
+import type { Schedule } from '../agent/schedules.js';
+/** Everything both timer emitters need to compose their platform's artifacts. */
+export interface TimerContext {
+    readonly schedule: Schedule;
+    /** From `agent/state.ts`'s `agentId()` — e.g. `my-agent-a1b2c3d4`. Keeps two same-named folders from colliding. */
+    readonly agentId: string;
+    readonly agentDir: string;
+    /** Absolute path to the `cradle` binary — launchd and systemd load no shell profile, so this is never a bare name. */
+    readonly cradleBin: string;
+    /** Where the task's stdout/stderr is captured. */
+    readonly logPath: string;
+    readonly home: string;
+    /** launchd domain target (`gui/<uid>`); systemd ignores it. */
+    readonly uid: number;
+}
+/** One file the command layer must write before running `installSteps`. */
+export interface TimerFile {
+    readonly path: string;
+    readonly content: string;
+}
+/** One argv to run, in order, as part of installing, removing, or one-shot firing a timer. */
+export interface TimerStep {
+    readonly argv: readonly string[];
+    /** A non-zero exit is expected and must be ignored — e.g. `launchctl bootout` when nothing is loaded yet. */
+    readonly ignoreFailure?: boolean;
+}
+/** The platform-neutral result of composing a schedule's OS timer — the command layer's only input. */
+export interface TimerPlan {
+    /** The launchd label or the systemd unit base name — shown in `cradle schedule list`. */
+    readonly id: string;
+    readonly files: readonly TimerFile[];
+    readonly installSteps: readonly TimerStep[];
+    readonly removeSteps: readonly TimerStep[];
+}

package/dist/util/proc.d.ts

@@ -14,8 +14,11 @@ export declare function killOn(proc: Killable, signal: ForwardableSignal): () =>
  *
  * `env` entries override the inherited `process.env` (used for the
  * sandboxed-run `MISE_CACHE_DIR`, see `agent/launch.ts`'s `composeEnv`).
+ * `cwd`, when given, is `RunPlan.cwd` — the effective working directory,
+ * which differs from `process.cwd()` only for a `--schedule` run (see
+ * `commands/run.ts`'s `resolveScheduledRun`).
  */
-export declare function runForeground(argv: readonly string[], env?: Record<string, string>): Promise<number>;
+export declare function runForeground(argv: readonly string[], env?: Record<string, string>, cwd?: string): Promise<number>;
 /**
  * Run a setup command silently, capturing stderr for the caller's error
  * message — the sbx create/policy/provision sequence, see
@@ -27,6 +30,19 @@ export declare function runCapture(argv: readonly string[]): Promise<{
     exitCode: number;
     stderr: string;
 }>;
+/**
+ * Run a command capturing BOTH streams — `commands/schedule.ts`'s
+ * launchctl/systemctl/loginctl steps, which (unlike `runCapture`'s
+ * sbx setup, stderr-only) need stdout too: the linger check
+ * (`loginctl show-user --property=Linger`) reports its answer there. Never
+ * throws on a non-zero exit; the caller decides which failures matter
+ * (`TimerStep.ignoreFailure`).
+ */
+export declare function runCaptureAll(argv: readonly string[]): Promise<{
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}>;
 /** Run a package install (e.g. `npm install`) in `cwd`, inheriting output; throws on non-zero exit. */
 export declare function runInstall(command: readonly string[], cwd: string): Promise<void>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coryrylan/cradle",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "description": "A runtime for portable agents defined as folders — launches the pi coding agent configured from an agent folder, sandboxed with nono",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -45,7 +45,7 @@
   },
   "homepage": "https://github.com/coryrylan/cradle/tree/main/projects/cli#readme",
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "publishConfig": {
     "access": "public"
@@ -226,7 +226,7 @@
     "@coryrylan/tools": "1.1.1",
     "@eslint/js": "10.0.1",
     "@eslint/json": "2.0.1",
-    "@types/bun": "1.4.0",
+    "@types/bun": "1.4.2",
     "@types/yargs": "17.0.35",
     "eslint": "10.9.1",
     "eslint-plugin-jsdoc": "64.2.1",