@amenophis1er/foreman 0.1.16 → 0.1.18

package/src/store.test.ts

@@ -4,7 +4,7 @@ import { mkdtemp, rm } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { RunStore, newRunId } from './store.js';
-import type { RunMeta } from './types.js';
+import type { RunMeta, Schedule } from './types.js';
 
 function meta(id: string, over: Partial<RunMeta> = {}): RunMeta {
   return {
@@ -151,3 +151,83 @@ test('sweepOrphans leaves a running run alone while another live process owns it
   assert.equal((await store.readMeta(theirs))!.status, 'running');
   await rm(root, { recursive: true, force: true });
 });
+
+function schedule(over: Partial<Schedule> = {}): Omit<Schedule, 'id' | 'createdAt'> & { createdAt?: number } {
+  return {
+    projectId: 'p-1', name: 'nightly', brief: 'tidy the tests', budgetUsd: 3,
+    cadence: { kind: 'daily', at: '03:00' } as unknown as Schedule['cadence'],
+    enabled: true, nextRunAt: 1000, consecutiveFailures: 0, pausedReason: null,
+    ...over,
+  };
+}
+
+test('schedules: add generates an id, list is per project and oldest first', async () => {
+  const { store, root } = await tmpStore();
+  const a = await store.addSchedule(schedule({ createdAt: 2000 }));
+  const b = await store.addSchedule(schedule({ createdAt: 1000, name: 'weekly' }));
+  const other = await store.addSchedule(schedule({ projectId: 'p-2' }));
+
+  assert.match(a.id, /^s-[0-9a-f]{12}$/);
+  assert.notEqual(a.id, b.id);
+  assert.deepEqual((await store.listSchedules()).map((s) => s.id), [b.id, a.id, other.id]);
+  assert.deepEqual((await store.listSchedules('p-1')).map((s) => s.name), ['weekly', 'nightly']);
+  assert.deepEqual(await store.getSchedule(a.id), a);
+  assert.equal(await store.getSchedule('s-missing'), null);
+  await rm(root, { recursive: true, force: true });
+});
+
+test('schedules: update merges, and null clears where undefined leaves alone', async () => {
+  const { store, root } = await tmpStore();
+  const s = await store.addSchedule(schedule({ pausedReason: 'failures', consecutiveFailures: 3 }));
+
+  const paused = await store.updateSchedule(s.id, { lastOutcome: 'error' });
+  assert.equal(paused?.pausedReason, 'failures', 'an absent key is left alone');
+  assert.equal(paused?.lastOutcome, 'error');
+
+  const resumed = await store.updateSchedule(s.id, {
+    pausedReason: null, nextRunAt: null, consecutiveFailures: 0,
+  });
+  assert.equal(resumed?.pausedReason, null);
+  assert.equal(resumed?.nextRunAt, null);
+  assert.equal(resumed?.consecutiveFailures, 0);
+  // And it survived the write, not just the returned object.
+  assert.equal((await store.getSchedule(s.id))?.nextRunAt, null);
+
+  assert.equal(await store.updateSchedule('s-missing', { enabled: false }), null);
+  await rm(root, { recursive: true, force: true });
+});
+
+test('schedules: remove reports whether it existed', async () => {
+  const { store, root } = await tmpStore();
+  const a = await store.addSchedule(schedule());
+  const b = await store.addSchedule(schedule({ name: 'other' }));
+  assert.equal(await store.removeSchedule(a.id), true);
+  assert.equal(await store.removeSchedule(a.id), false);
+  assert.deepEqual((await store.listSchedules()).map((s) => s.id), [b.id]);
+  await rm(root, { recursive: true, force: true });
+});
+
+test('schedules: unlinking a project takes its schedules with it', async () => {
+  const { store, root } = await tmpStore();
+  const p = await store.addProject('/tmp/sched-proj');
+  const q = await store.addProject('/tmp/other-proj');
+  await store.addSchedule(schedule({ projectId: p.id }));
+  await store.addSchedule(schedule({ projectId: p.id, name: 'second' }));
+  const keep = await store.addSchedule(schedule({ projectId: q.id }));
+
+  assert.equal(await store.removeProject(p.id), true);
+  assert.deepEqual((await store.listSchedules()).map((s) => s.id), [keep.id]);
+  assert.deepEqual(await store.listSchedules(p.id), []);
+  await rm(root, { recursive: true, force: true });
+});
+
+test('schedules: a corrupt schedules.json reads as empty rather than throwing', async () => {
+  const { store, root } = await tmpStore();
+  const { writeFile } = await import('node:fs/promises');
+  await writeFile(path.join(root, 'schedules.json'), '{not json');
+  assert.deepEqual(await store.listSchedules(), []);
+  // And a write over it recovers the file.
+  const s = await store.addSchedule(schedule());
+  assert.deepEqual((await store.listSchedules()).map((x) => x.id), [s.id]);
+  await rm(root, { recursive: true, force: true });
+});

package/src/store.ts

@@ -7,6 +7,7 @@
  *   <root>/runs/<runId>/events.jsonl  — one ForemanEvent per line, append-only
  *   <root>/chats/<projectId>/…        — same two files for a project's
  *                                       planning conversation
+ *   <root>/schedules.json             — every Schedule, one JSON array
  *
  * Design notes for reviewers:
  *  - The event log is the source of truth for the UI; meta.json is a derived
@@ -24,7 +25,7 @@ import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import type {
-  ChatMeta, ForemanEvent, Project, ProviderRef, RunMeta, RunSummary, SettingsFile,
+  ChatMeta, ForemanEvent, Project, ProviderRef, RunMeta, RunSummary, Schedule, SettingsFile,
 } from './types.js';
 
 const RUN_ID_RE = /^[0-9]{13}-[0-9a-f]{8}$/;
@@ -142,11 +143,16 @@ export class RunStore {
   }
 
   /** Unlinks a project (run history is kept). Returns whether it existed. */
-  removeProject(projectId: string): Promise<boolean> {
-    return this.mutateProjects((projects) => {
+  async removeProject(projectId: string): Promise<boolean> {
+    const existed = await this.mutateProjects((projects) => {
       const rest = projects.filter((p) => p.id !== projectId);
       return { projects: rest, result: rest.length !== projects.length };
     });
+    // Its schedules go with it: a standing instruction to run missions in a
+    // folder Foreman no longer knows about has nowhere to fire. Sequential and
+    // not nested inside the mutate, because both writes share one chain.
+    await this.removeProjectSchedules(projectId);
+    return existed;
   }
 
   async getProject(projectId: string): Promise<Project | null> {
@@ -183,6 +189,114 @@ export class RunStore {
     return task;
   }
 
+  // -- schedules ------------------------------------------------------------
+
+  /**
+   * Every schedule lives in one small file, not a directory per schedule:
+   * there are a handful of them, the ticker reads all of them on every tick to
+   * decide what is due, and a single array is one read and one atomic write.
+   * It shares `projectsChain` with projects.json and settings.json so a write
+   * here can never interleave with one of those.
+   */
+  private get schedulesFile(): string {
+    return path.join(this.root, 'schedules.json');
+  }
+
+  /** All schedules, or one project's; oldest first so the list never reorders
+   *  itself under the human between visits. A missing or unparseable file is
+   *  an empty list — the ticker must keep running, not crash on a bad byte. */
+  async listSchedules(projectId?: string): Promise<Schedule[]> {
+    const raw = await readFile(this.schedulesFile, 'utf8').catch(() => null);
+    let all: Schedule[] = [];
+    if (raw) {
+      try {
+        const parsed: unknown = JSON.parse(raw);
+        if (Array.isArray(parsed)) all = parsed as Schedule[];
+      } catch {
+        all = [];
+      }
+    }
+    const wanted = projectId ? all.filter((s) => s.projectId === projectId) : all;
+    return [...wanted].sort((a, b) => a.createdAt - b.createdAt);
+  }
+
+  /** Atomically rewrites schedules.json through `mutate`; returns its result. */
+  private mutateSchedules<T>(
+    mutate: (schedules: Schedule[]) => { schedules: Schedule[]; result: T },
+  ): Promise<T> {
+    const task = this.projectsChain.then(async () => {
+      const { schedules, result } = mutate(await this.listSchedules());
+      await mkdir(this.root, { recursive: true });
+      const tmp = path.join(this.root, `.schedules.${crypto.randomBytes(4).toString('hex')}.tmp`);
+      await writeFile(tmp, JSON.stringify(schedules, null, 2));
+      await rename(tmp, this.schedulesFile);
+      return result;
+    });
+    this.projectsChain = task.catch(() => {});
+    return task;
+  }
+
+  async getSchedule(id: string): Promise<Schedule | null> {
+    return (await this.listSchedules()).find((s) => s.id === id) ?? null;
+  }
+
+  /** Records a new schedule. The id and creation time are the store's to give,
+   *  like a project's; callers may pass them when restoring a known record. */
+  addSchedule(
+    s: Omit<Schedule, 'id' | 'createdAt'> & { id?: string; createdAt?: number },
+  ): Promise<Schedule> {
+    return this.mutateSchedules((schedules) => {
+      const schedule: Schedule = {
+        ...s,
+        id: s.id ?? `s-${crypto.randomBytes(6).toString('hex')}`,
+        createdAt: s.createdAt ?? Date.now(),
+      };
+      return { schedules: [...schedules, schedule], result: schedule };
+    });
+  }
+
+  /**
+   * Merges a partial change. `undefined` means "leave it alone" and `null` is
+   * a value in its own right — `pausedReason` and `nextRunAt` are both cleared
+   * by writing null, and a spread alone would let an absent key erase them.
+   * Identity (id, project, creation) is not patchable; a schedule that moved
+   * project would silently start running missions in another folder.
+   */
+  updateSchedule(
+    id: string,
+    patch: Partial<Omit<Schedule, 'id' | 'projectId' | 'createdAt'>>,
+  ): Promise<Schedule | null> {
+    return this.mutateSchedules((schedules) => {
+      const i = schedules.findIndex((s) => s.id === id);
+      if (i === -1) return { schedules, result: null };
+      const next: Schedule = { ...schedules[i] };
+      for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined) continue;
+        (next as unknown as Record<string, unknown>)[key] = value;
+      }
+      const updated = [...schedules];
+      updated[i] = next;
+      return { schedules: updated, result: next };
+    });
+  }
+
+  /** Forgets one schedule. Returns whether it existed. */
+  removeSchedule(id: string): Promise<boolean> {
+    return this.mutateSchedules((schedules) => {
+      const rest = schedules.filter((s) => s.id !== id);
+      return { schedules: rest, result: rest.length !== schedules.length };
+    });
+  }
+
+  /** Forgets a project's schedules; returns how many went. Called when a
+   *  project is unlinked, so no schedule outlives the project it fires in. */
+  removeProjectSchedules(projectId: string): Promise<number> {
+    return this.mutateSchedules((schedules) => {
+      const rest = schedules.filter((s) => s.projectId !== projectId);
+      return { schedules: rest, result: schedules.length - rest.length };
+    });
+  }
+
   // -- runs -----------------------------------------------------------------
 
   private runDir(runId: string): string {

package/src/types.ts

@@ -5,6 +5,17 @@
  * broadcast to connected SSE clients *and* appended to the run's event log,
  * so replaying a log reproduces exactly what a live client observed.
  */
+import type { Cadence } from './schedule.js';
+import type { CrewPreset, ReviewVerdict } from './crew.js';
+
+/** Re-exported so callers can name a schedule's cadence without reaching past
+ *  this module for it; the rules that interpret one live in schedule.ts. */
+export type { Cadence };
+
+/** Re-exported on the same principle: a record can be described without
+ *  reaching past this module, while crew.ts stays the definition site and
+ *  keeps the rules that read them. */
+export type { CrewPreset, ReviewVerdict };
 
 export type RunStatus = 'running' | 'done' | 'error' | 'interrupted';
 
@@ -27,6 +38,44 @@ export interface Project {
   claudeInstance?: ClaudeInstanceRef;
 }
 
+/**
+ * A standing instruction to start a mission on a cadence. Foreman's own
+ * record, never the project's repo: a schedule is an operator's decision about
+ * a machine, not something a checkout should carry to whoever clones it.
+ *
+ * The fields after `enabled` are the ticker's memory. It is stateless between
+ * ticks — every question it asks ("is this one due?", "has it been failing?")
+ * is answered from here, so nothing is lost across a restart.
+ */
+export interface Schedule {
+  /** `s-<hex>`, generated by the store like a project's id. */
+  id: string;
+  projectId: string;
+  name: string;
+  /** The mission text, sent verbatim to the director on every firing. */
+  brief: string;
+  cadence: Cadence;
+  /** Budget for one run, not for the schedule's life. */
+  budgetUsd: number;
+  directorModel?: ModelChoice;
+  workerModel?: ModelChoice;
+  directorProviderId?: string;
+  workerProviderId?: string;
+  enabled: boolean;
+  createdAt: number;
+  lastRunId?: string;
+  lastRunAt?: number;
+  lastOutcome?: 'done' | 'error' | 'interrupted' | 'skipped';
+  /** Why the last tick did nothing, when it did nothing ("project busy"). */
+  lastNote?: string;
+  /** Next firing, ms epoch; null when disabled or nothing is scheduled. */
+  nextRunAt: number | null;
+  /** Failures in a row, reset by a success. What auto-pausing counts. */
+  consecutiveFailures: number;
+  /** Not running, and why — so the UI can say what would un-pause it. */
+  pausedReason: null | 'failures' | 'monthly-cap' | 'human';
+}
+
 /**
  * @deprecated The pre-provider shape, still read from records written before
  * {@link ProviderRef} existed. Never written. See providerFromLegacy().
@@ -206,6 +255,14 @@ export interface WorkerMeta {
   status: WorkerStatus;
   costUsd: number;
   sessionId?: string;
+  /**
+   * The crew preset this worker IS, when it is a reviewer rather than an
+   * ordinary worker. Persisted — unlike the launch overrides, which hold a
+   * live credential — so a resumed run can rebuild the read-only policy, the
+   * model and the provider from the frozen crew instead of resuming a
+   * reviewer as a worker that may write.
+   */
+  crewPresetId?: string;
   /** First 500 chars of the task brief, for run-history display. */
   task: string;
   /**
@@ -274,6 +331,20 @@ export interface RunMeta {
   title?: string;
   /** Owning project; absent on runs recorded before projects existed. */
   projectId?: string;
+  /**
+   * The schedule that started this run, when one did. Kept on the run rather
+   * than only on the schedule because a schedule has many runs and one
+   * `lastRunId`: this is what lets the history page group them.
+   */
+  scheduleId?: string;
+  /**
+   * How the run began. Absent means 'human' — every record made before
+   * schedules existed, and the reason this is not required: an unattended run
+   * and one someone is watching deserve different treatment (timeouts,
+   * notifications), and guessing from the presence of other fields would get
+   * it wrong for the old records.
+   */
+  startedBy?: 'human' | 'phone' | 'schedule' | 'mcp';
   /** Model override for the director session. */
   directorModel?: ModelChoice;
   /** Model override for worker sessions (cost lever). */
@@ -296,6 +367,19 @@ export interface RunMeta {
   provider?: ProviderRef;
   /** @deprecated Pre-provider pin, still read for runs recorded before providers. */
   claudeInstance?: ClaudeInstanceRef;
+  /**
+   * Crew presets frozen onto the run at dispatch: a later edit of a preset
+   * must not change a running or past run. Absent means the run was dispatched
+   * with no crew chosen — which is every run recorded before presets existed,
+   * and the reason the gate reads an absent field as "nothing required".
+   */
+  crew?: CrewPreset[];
+  /**
+   * Review verdicts this run collected, appended in order. Kept whole rather
+   * than reduced to a pass/fail: the gate needs the diff each verdict was
+   * about, and the human reading the record afterwards needs the findings.
+   */
+  reviews?: ReviewVerdict[];
   /** Number of times this run was resumed after an interruption. */
   resumes?: number;
   /**
@@ -314,6 +398,12 @@ export interface RunMeta {
    * human already answered.
    */
   allowedRoots?: string[];
+  /**
+   * The subset of `allowedRoots` Foreman opened by itself rather than the
+   * human (today: a worktree's parent repository). Kept apart so it can be
+   * withdrawn when the reason for it stops holding — a human's grant never is.
+   */
+  autoRoots?: string[];
   /** Dev servers the crew exposed through Foreman's proxy (see services.ts). */
   services?: Array<{ port: number; label: string; path: string; since: number; pid?: number }>;
   /**
@@ -463,6 +553,8 @@ export interface MissionProposal {
   directorProviderId?: string;
   workerProviderId?: string;
   modelRationale?: string;
+  /** Preset ids the planner may suggest; the human's toggles decide. */
+  crew?: string[];
   createdAt: number;
 }