@ahpd/server 0.1.0 → 0.3.0

package/src/cron.ts

@@ -1,251 +0,0 @@
-/** Five-field AHP cron: what an expression means, and when it next comes round. */
-
-/**
- * A parsed expression, as the sets each field allows.
- *
- * Sets rather than the source text, because the question asked of this a
- * thousand times a day is "does this minute match" and not "what did somebody
- * type" - and because parsing once is what makes a bad expression a refusal at
- * the moment it is written rather than a schedule that silently never fires.
- */
-export interface Cron {
-  minutes: ReadonlySet<number>;
-  hours: ReadonlySet<number>;
-  doms: ReadonlySet<number>;
-  months: ReadonlySet<number>;
-  dows: ReadonlySet<number>;
-  /**
-   * Whether the day fields were narrowed, which decides how they combine.
-   *
-   * Unix cron's one genuine oddity: when both day-of-month and day-of-week are
-   * restricted, an occurrence matches when *either* does - `0 0 1 * 1` is the
-   * first of the month **and** every Monday. When one is `*` the other simply
-   * applies. Getting this backwards turns a weekly job into a yearly one.
-   */
-  domRestricted: boolean;
-  dowRestricted: boolean;
-}
-
-const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
-const DAYS = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
-
-/** One field's bounds, and the names it also accepts. */
-interface Field {
-  name: string;
-  min: number;
-  max: number;
-  names?: string[];
-}
-
-const FIELDS: Field[] = [
-  { name: 'minute', min: 0, max: 59 },
-  { name: 'hour', min: 0, max: 23 },
-  { name: 'day of month', min: 1, max: 31 },
-  { name: 'month', min: 1, max: 12, names: MONTHS },
-  // 7 as well as 0, both meaning Sunday, which is what every crontab accepts.
-  { name: 'day of week', min: 0, max: 7, names: DAYS },
-];
-
-/** A single value, by number or by name. */
-function valueOf(text: string, field: Field): number {
-  const named = field.names?.indexOf(text.toLowerCase());
-  if (named !== undefined && named >= 0) return named + (field.names === MONTHS ? 1 : 0);
-  if (!/^\d+$/.test(text)) throw new Error(`${text} is not a ${field.name}`);
-  const value = Number(text);
-  if (value < field.min || value > field.max) {
-    throw new Error(`${value} is out of range for ${field.name} (${field.min}-${field.max})`);
-  }
-  return value;
-}
-
-/** One field: a comma-separated list of values, ranges and steps. */
-function parseField(text: string, field: Field): Set<number> {
-  const out = new Set<number>();
-  for (const term of text.split(',')) {
-    if (term === '') throw new Error(`Empty ${field.name}`);
-    const [range, step] = term.split('/') as [string, string | undefined];
-    if (term.split('/').length > 2) throw new Error(`${term} has more than one step`);
-    let by = 1;
-    if (step !== undefined) {
-      if (!/^\d+$/.test(step) || Number(step) === 0) {
-        throw new Error(`${step} is not a step for ${field.name}; a step must be a positive integer`);
-      }
-      by = Number(step);
-    }
-    let from: number;
-    let to: number;
-    if (range === '*') {
-      from = field.min;
-      to = field.max;
-    }
-    else if (range.includes('-')) {
-      const [a, b] = range.split('-') as [string, string];
-      if (range.split('-').length > 2) throw new Error(`${range} is not a range`);
-      from = valueOf(a, field);
-      to = valueOf(b, field);
-      if (to < from) throw new Error(`${range} runs backwards`);
-    }
-    else {
-      from = valueOf(range, field);
-      // A step on a single value means from there to the end of the field,
-      // which is what crontab does with `5/10`.
-      to = step === undefined ? from : field.max;
-    }
-    for (let at = from; at <= to; at += by) out.add(at);
-  }
-  return out;
-}
-
-/**
- * Read an expression, or say what is wrong with it.
- *
- * Throws rather than returning undefined: an unparseable schedule is a thing
- * somebody typed and must be told about, and the one place it is read is the
- * moment they write it.
- */
-export function parseCron(expression: string): Cron {
-  const fields = expression.trim().split(/\s+/);
-  if (fields.length !== 5) {
-    throw new Error(`A schedule has five fields; ${expression.trim() === '' ? 'this one has none' : `this one has ${fields.length}`}`);
-  }
-  const [minute, hour, dom, month, dow] = fields as [string, string, string, string, string];
-  const dows = parseField(dow, FIELDS[4] as Field);
-  // Both spellings of Sunday collapse to one, so a weekday test is a lookup.
-  if (dows.has(7)) { dows.delete(7); dows.add(0); }
-  return {
-    minutes: parseField(minute, FIELDS[0] as Field),
-    hours: parseField(hour, FIELDS[1] as Field),
-    doms: parseField(dom, FIELDS[2] as Field),
-    months: parseField(month, FIELDS[3] as Field),
-    dows,
-    domRestricted: dom !== '*',
-    dowRestricted: dow !== '*',
-  };
-}
-
-// ------------------------------------------------------------- the time zone
-
-/** A wall-clock reading: what a clock on that wall says. */
-interface Wall {
-  year: number;
-  month: number;
-  day: number;
-  hour: number;
-  minute: number;
-}
-
-const readers = new Map<string, Intl.DateTimeFormat>();
-
-/** Cached, because this is called once per candidate day and building one is not free. */
-function readerFor(timeZone: string): Intl.DateTimeFormat {
-  let held = readers.get(timeZone);
-  if (!held) {
-    held = new Intl.DateTimeFormat('en-US', {
-      timeZone,
-      hourCycle: 'h23',
-      year: 'numeric',
-      month: '2-digit',
-      day: '2-digit',
-      hour: '2-digit',
-      minute: '2-digit',
-    });
-    readers.set(timeZone, held);
-  }
-  return held;
-}
-
-/** What the clock in that zone said at that instant. */
-function wallAt(instant: number, timeZone: string): Wall {
-  const parts = readerFor(timeZone).formatToParts(new Date(instant));
-  const found: Record<string, number> = {};
-  for (const part of parts) {
-    if (part.type !== 'literal') found[part.type] = Number(part.value);
-  }
-  return {
-    year: found.year as number,
-    month: found.month as number,
-    day: found.day as number,
-    hour: found.hour as number,
-    minute: found.minute as number,
-  };
-}
-
-/** That zone's offset from UTC, in minutes, at that instant. */
-function offsetAt(instant: number, timeZone: string): number {
-  const wall = wallAt(instant, timeZone);
-  const asUtc = Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute);
-  // To the minute: the reading has no seconds, so the instant must not either.
-  return (asUtc - Math.floor(instant / 60000) * 60000) / 60000;
-}
-
-/**
- * The instant at which that zone's clock reads that.
- *
- * Two passes, because the offset depends on the answer: the first guess uses
- * the offset in force at roughly the right time and the second uses the one in
- * force at the instant the first produced, which is what gets the hour after a
- * DST change right. Returns undefined for a wall time that does not exist -
- * the hour a spring-forward skips - because a schedule pointing into the gap
- * has no occurrence that day rather than an occurrence at some other time.
- */
-function instantOf(wall: Wall, timeZone: string): number | undefined {
-  const guess = Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute);
-  let instant = guess - offsetAt(guess, timeZone) * 60000;
-  const again = guess - offsetAt(instant, timeZone) * 60000;
-  if (again !== instant) instant = again;
-  const back = wallAt(instant, timeZone);
-  if (back.hour !== wall.hour || back.minute !== wall.minute || back.day !== wall.day) return undefined;
-  return instant;
-}
-
-// ------------------------------------------------------------- the next time
-
-/** How far ahead to look before calling an expression unreachable. `0 0 30 2 *` is. */
-const HORIZON_DAYS = 1500;
-
-/** Whether that calendar day is one this expression fires on. */
-function dayMatches(cron: Cron, year: number, month: number, day: number): boolean {
-  if (!cron.months.has(month)) return false;
-  const dow = new Date(Date.UTC(year, month - 1, day)).getUTCDay();
-  const byDom = cron.doms.has(day);
-  const byDow = cron.dows.has(dow);
-  if (cron.domRestricted && cron.dowRestricted) return byDom || byDow;
-  if (cron.domRestricted) return byDom;
-  if (cron.dowRestricted) return byDow;
-  return true;
-}
-
-/**
- * The first occurrence strictly after that instant, or undefined.
- *
- * Walked a day at a time rather than a minute at a time: a minute-by-minute
- * search over the horizon is half a million time-zone conversions to answer a
- * question about February.
- */
-export function nextOccurrence(cron: Cron, after: Date, timeZone: string): Date | undefined {
-  const from = after.getTime();
-  const start = wallAt(from, timeZone);
-  const minutes = [...cron.minutes].sort((a, b) => a - b);
-  const hours = [...cron.hours].sort((a, b) => a - b);
-
-  for (let ahead = 0; ahead <= HORIZON_DAYS; ahead++) {
-    // Calendar arithmetic in UTC on the *wall* date, which is date arithmetic
-    // and not instant arithmetic - adding 24 hours to an instant lands on the
-    // same date twice a year.
-    const at = new Date(Date.UTC(start.year, start.month - 1, start.day + ahead));
-    const year = at.getUTCFullYear();
-    const month = at.getUTCMonth() + 1;
-    const day = at.getUTCDate();
-    if (!dayMatches(cron, year, month, day)) continue;
-    for (const hour of hours) {
-      for (const minute of minutes) {
-        const instant = instantOf({ year, month, day, hour, minute }, timeZone);
-        // Undefined is the spring-forward gap; earlier than `after` is the
-        // hour a fall-back repeats, where the first pass is already behind us.
-        if (instant === undefined || instant <= from) continue;
-        return new Date(instant);
-      }
-    }
-  }
-  return undefined;
-}

package/src/git.ts

@@ -1,132 +0,0 @@
-/** What git can say about a directory the host serves. */
-
-import { execFile } from 'node:child_process';
-import type { DirectoryFacts } from './types/host.js';
-
-/**
- * The branch each served directory is on, as a host's `DirectoryFacts`.
- *
- * Deliberately not part of `createHost`: it spawns `git`, which is a binary
- * rather than a runtime API and may not be installed at all. The daemon wires
- * it in, a library caller opts in, and a host without it still names its
- * projects - so nothing here is load-bearing for the protocol.
- *
- * ```ts
- * createHost({ path, agents: [claude({ paths })], directories: gitBranches() });
- * ```
- */
-export function gitBranches(): DirectoryFacts {
-  /*
-   * The branch, per *directory* rather than per session.
-   *
-   * A host serving one repository with ninety-eight sessions in it would
-   * otherwise ask git ninety-eight times for one answer.
-   */
-  const facts = new Map<string, Record<string, unknown>>();
-
-  /** Run git in a directory and answer what it said, or nothing at all. */
-  const git = (dir: string, args: string[]): Promise<string | undefined> =>
-    new Promise((answer) => {
-      execFile('git', ['-C', dir, ...args], { timeout: 2000 }, (error, out) => {
-        answer(error ? undefined : out.toString().trim());
-      });
-    });
-
-  /**
-   * The owner and repository of a GitHub remote, if the remote is one.
-   *
-   * Both URL forms git writes: `git@github.com:owner/repo.git` and
-   * `https://github.com/owner/repo`. Anything else is a remote this says
-   * nothing about rather than one it guesses at.
-   */
-  const github = (url: string | undefined): { owner: string; repo: string } | undefined => {
-    const found = /github\.com[:/]([^/]+)\/(.+?)(?:\.git)?$/.exec(url ?? '');
-    return found ? { owner: found[1] as string, repo: found[2] as string } : undefined;
-  };
-
-  /**
-   * Ask git, and answer whether what it said differs from what was held.
-   *
-   * A directory that is not a repository, or one whose HEAD is detached, has
-   * no branch and is remembered as having none: `rev-parse --abbrev-ref` says
-   * `HEAD` for a detached head, and reporting that would draw a branch called
-   * HEAD.
-   */
-  const refresh = async (dir: string): Promise<boolean> => {
-    const said = await git(dir, ['rev-parse', '--abbrev-ref', 'HEAD']);
-    const branchName = said === undefined || said === '' || said === 'HEAD' ? undefined : said;
-    if (branchName === undefined) {
-      const had = facts.has(dir);
-      facts.delete(dir);
-      return had;
-    }
-    /*
-     * The rest in two more calls, both cheap and both answering a question a
-     * client draws something from.
-     *
-     * `status -sb --porcelain` names the upstream and the ahead/behind counts
-     * on its first line and one file per line after it, so the count of
-     * uncommitted changes comes out of the same call. `remote get-url` is the
-     * only way to know whether this is a GitHub repository, which is what
-     * turns a client's pull-request affordances on.
-     */
-    const [status, origin] = await Promise.all([
-      git(dir, ['status', '-sb', '--porcelain']),
-      git(dir, ['remote', 'get-url', 'origin']),
-    ]);
-    const lines = (status ?? '').split('\n');
-    const head = lines[0] ?? '';
-    const upstream = /^## [^.]*\.\.\.(\S+)/.exec(head)?.[1];
-    const ahead = Number(/\[.*?ahead (\d+)/.exec(head)?.[1] ?? 0);
-    const behind = Number(/\[.*?behind (\d+)/.exec(head)?.[1] ?? 0);
-    const owner = github(origin);
-    const now: Record<string, unknown> = {
-      branchName,
-      /*
-       * The drift, and only where there is something to drift from.
-       *
-       * A branch with no upstream is not zero ahead and zero behind, it is
-       * neither - and a client draws these as arrows beside the branch, so a
-       * pair of zeroes is two arrows saying nothing. The reference host omits
-       * them the same way.
-       */
-      ...(upstream === undefined ? {} : {
-        upstreamBranchName: upstream,
-        incomingChanges: behind,
-        outgoingChanges: ahead,
-      }),
-      uncommittedChanges: lines.slice(1).filter((one) => one.trim() !== '').length,
-      hasGitHubRemote: owner !== undefined,
-      ...(owner ? { githubOwner: owner.owner, githubRepo: owner.repo } : {}),
-    };
-    const before = facts.get(dir);
-    if (before !== undefined && JSON.stringify(before) === JSON.stringify(now)) return false;
-    facts.set(dir, now);
-    return true;
-  };
-
-  return {
-    /*
-     * `git` is the well-known key, and the field names are the reference host's.
-   *
-   * Not the protocol's: it declares no `_meta` keys at all. The names come
-   * from a capture of the other implementation - `branchName`,
-   * `upstreamBranchName`, `incomingChanges`, `outgoingChanges`,
-   * `uncommittedChanges`, `hasGitHubRemote`, `githubOwner`, `githubRepo` -
-   * because a client reads one spelling, and this host used to write `branch`
-   * where that client looks for `branchName` and so said nothing at all.
-   *
-   * Written whole, and correct only because this is the only producer of
-   * `_meta` here.
-     *
-     * Correct only because this is the only producer of `_meta` here:
-     * `session/metaChanged` replaces the map entirely, so a host with two of
-     * them would have to merge before dispatching rather than after.
-     */
-    meta: (dir) => {
-      const held = facts.get(dir);
-      return held === undefined ? undefined : { git: { ...held } };
-    },
-    refresh,
-  };
-}