syndai 0.3.0 → 0.4.1

package/src/schedules.js

@@ -0,0 +1,377 @@
+// `syndai schedule` (a project's recurring runs) and `syndai repeat` (repeat a run you liked).
+//
+// The server owns cron: it labels a cadence (`cadence_label`) and lists the next fires
+// (`upcoming`), so nothing here parses cron. The only mapping is the presets the portal's
+// Repeats field offers (apps/portal-v2/src/lib/cadence.ts `toCron`), with Sunday = 0.
+// Merge and skip policy are edited in the portal or with `syndai api updateSchedule`.
+
+import { ApiError, CliError, EXIT } from "./errors.js";
+import { projectLabel, resolveProject } from "./projects.js";
+import { ask, ulid } from "./ui.js";
+
+const DAYS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+const MAX_PAGES = 50;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PAUSE_REASONS = {
+  consecutive_failures: "it failed 5 times in a row",
+  invalid_trigger: "its schedule is no longer valid",
+};
+const CADENCE_HELP = 'hourly --at :MM, daily|weekdays --at HH:MM, weekly --at "mon HH:MM", or a 5-field cron';
+
+// --- cadence -------------------------------------------------------------------------------
+
+/** The IANA zone to use: --tz (checked), else this computer's. */
+export function timeZoneOf(flags) {
+  const zone = flags.tz ?? (Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC");
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: zone });
+  } catch {
+    throw new CliError(EXIT.USAGE, `Unknown time zone "${zone}"; use an IANA name like Europe/Berlin.`);
+  }
+  return zone;
+}
+
+/** Wall-clock hour, minute, second and weekday (0 = Sunday) of `now` in `zone`. */
+function clock(now, zone) {
+  const parts = Object.fromEntries(
+    new Intl.DateTimeFormat("en-US", {
+      timeZone: zone,
+      hourCycle: "h23",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      weekday: "short",
+    })
+      .formatToParts(new Date(now))
+      .map((p) => [p.type, p.value]),
+  );
+  return {
+    hh: Number(parts.hour) % 24,
+    mm: Number(parts.minute),
+    ss: Number(parts.second),
+    dow: DAYS.indexOf(parts.weekday.slice(0, 3).toLowerCase()),
+  };
+}
+
+/**
+ * `--every` (+ `--at`) -> a 5-field cron, as the portal's `toCron` writes it. `--at` defaults
+ * to the next quarter hour in the schedule's zone (the portal's `defaultCadence`).
+ */
+export function cronFor({ every, at }, now, zone) {
+  const fail = (why) => new CliError(EXIT.USAGE, `${why} --every takes ${CADENCE_HELP}.`);
+  if (!every) throw fail("How often?");
+  const fields = every.trim().split(/\s+/);
+  if (fields.length === 5) {
+    if (at !== undefined) throw fail("--at does not go with a cron expression.");
+    return fields.join(" ");
+  }
+  const preset = every.trim().toLowerCase();
+  if (!["hourly", "daily", "weekdays", "weekly"].includes(preset)) throw fail(`"${every}" is not a cadence.`);
+
+  const c = clock(now, zone);
+  const minutes = (Math.ceil((c.hh * 60 + c.mm + (c.ss > 0 ? 1 : 0)) / 15) * 15) % 1440;
+  let hh = Math.floor(minutes / 60);
+  let mm = minutes % 60;
+  let dow = c.dow;
+  if (at !== undefined) {
+    const text = at.trim().toLowerCase();
+    let match;
+    if (preset === "hourly") {
+      match = /^:?(\d{1,2})$/.exec(text);
+      if (!match || Number(match[1]) > 59) throw fail(`--at for hourly is :MM, not "${at}".`);
+      mm = Number(match[1]);
+    } else {
+      const shape = preset === "weekly" ? /^([a-z]+|[0-6])\s+(\d{1,2}):(\d{2})$/ : /^()(\d{1,2}):(\d{2})$/;
+      match = shape.exec(text);
+      const day = match?.[1] ? dayIndex(match[1]) : dow;
+      if (!match || Number(match[2]) > 23 || Number(match[3]) > 59 || day < 0) {
+        throw fail(`--at for ${preset} is ${preset === "weekly" ? '"mon HH:MM"' : "HH:MM"}, not "${at}".`);
+      }
+      [hh, mm, dow] = [Number(match[2]), Number(match[3]), day];
+    }
+  }
+  return {
+    hourly: `${mm} * * * *`,
+    daily: `${mm} ${hh} * * *`,
+    weekdays: `${mm} ${hh} * * 1-5`,
+    weekly: `${mm} ${hh} * * ${dow}`,
+  }[preset];
+}
+
+function dayIndex(text) {
+  if (/^[0-6]$/.test(text)) return Number(text);
+  const short = text.slice(0, 3);
+  const full = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
+  const index = DAYS.indexOf(short);
+  return index >= 0 && full[index].startsWith(text) ? index : -1;
+}
+
+/** `--budget 5` -> 5; `--budget none` -> null (no per-run cap) where allowed. */
+function budgetOf(text, { allowNone }) {
+  if (text === undefined) return undefined;
+  if (allowNone && text.trim().toLowerCase() === "none") return null;
+  const value = Number(text.replace(/^\$/, ""));
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new CliError(EXIT.USAGE, `--budget is a dollar amount per run${allowNone ? ", or none" : ""}, not "${text}".`);
+  }
+  return value;
+}
+
+function triggerOf(ctx, { every, at, tz }) {
+  const zone = timeZoneOf({ tz });
+  if (tz === undefined && zone === "UTC" && ctx.ui.interactive) {
+    ctx.ui.progress(ctx.ui.dim("(your system time zone is UTC; pass --tz to change)"));
+  }
+  return { kind: "cron", expr: cronFor({ every, at }, ctx.io.now(), zone), timezone: zone };
+}
+
+// --- printing ------------------------------------------------------------------------------
+
+function when(iso, zone) {
+  if (!iso) return "-";
+  return new Intl.DateTimeFormat("en-US", {
+    timeZone: zone,
+    weekday: "short",
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+  }).format(new Date(iso));
+}
+
+const labelOf = (s) => `${s.cadence_label ?? s.trigger.expr} ${s.trigger.timezone}`;
+const firstLine = (text) => (text ?? "").split("\n")[0].slice(0, 60);
+
+function stateOf(s) {
+  if (s.status !== "paused") return `next ${when(s.upcoming?.[0] ?? s.next_fire_at, s.trigger.timezone)}`;
+  const why = s.pause_reason && s.pause_reason !== "user" ? (PAUSE_REASONS[s.pause_reason] ?? s.pause_reason) : null;
+  return why ? `paused (${why})` : "paused";
+}
+
+function row(s) {
+  const last = s.last_occurrence ? (s.last_occurrence.summary ?? s.last_occurrence.disposition) : "";
+  return `${s.id.slice(0, 8)}  ${labelOf(s)}  ${stateOf(s)}  "${firstLine(s.prompt)}"${last ? `  ${last}` : ""}`;
+}
+
+function upcomingLine(s) {
+  const times = (s.upcoming ?? []).map((t) => when(t, s.trigger.timezone));
+  return times.length ? `Next: ${times.join(" · ")}` : "Next: -";
+}
+
+function card(s, occurrences = []) {
+  const lines = [`${labelOf(s)} · ${stateOf(s)}`, `"${firstLine(s.prompt)}"`];
+  if (s.repo_name) lines.push(`Project ${s.repo_name}`);
+  if (s.occurrence_budget_usd !== null && s.occurrence_budget_usd !== undefined) {
+    lines.push(`Cap $${s.occurrence_budget_usd} per run`);
+  }
+  if (s.status !== "paused") lines.push(upcomingLine(s));
+  lines.push("", occurrences.length ? "History:" : "History: none yet");
+  for (const o of occurrences) {
+    const parts = [when(o.slot_ts, s.trigger.timezone), o.disposition, o.summary, o.coding_run_id].filter(Boolean);
+    lines.push(`  ${parts.join(" · ")}`);
+  }
+  return lines.join("\n");
+}
+
+// --- API -----------------------------------------------------------------------------------
+
+async function listAll(ctx, query) {
+  const schedules = [];
+  let cursor;
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const res = await ctx.client.call("listSchedules", { query: { ...query, limit: 100, cursor } });
+    schedules.push(...res.schedules);
+    cursor = res.next_cursor;
+    if (!cursor) break;
+  }
+  return schedules;
+}
+
+/** A full id, or the 8-character prefix `schedule list` prints. */
+async function scheduleId(ctx, ref) {
+  if (!ref) throw new CliError(EXIT.USAGE, "Which schedule? Its id is in `syndai schedule list`.");
+  if (UUID.test(ref)) return ref;
+  const hits = (await listAll(ctx, {})).filter((s) => s.id.startsWith(ref.toLowerCase()));
+  if (hits.length === 1) return hits[0].id;
+  throw new CliError(EXIT.USAGE, hits.length ? `"${ref}" matches ${hits.length} schedules; use more of the id.` : `No schedule "${ref}".`, {
+    next: "syndai schedule list --all",
+  });
+}
+
+/**
+ * Create with a fresh request id (so a retried POST is the same create). A replay answers
+ * 409 + Location: that schedule is the result. A 409 without one is a changed replay.
+ */
+async function create(ctx, body) {
+  const res = await ctx.client.call("createSchedule", {
+    body: { ...body, client_request_id: `cli:${ulid()}` },
+    retry: true,
+    raw: true,
+  });
+  if (res.status < 300) return res.body;
+  const location = res.status === 409 ? res.headers.get("location") : null;
+  if (location) return (await ctx.client.send("GET", new URL(location, ctx.baseUrl).pathname)).schedule;
+  throw new ApiError(res.status, res.body, res.headers);
+}
+
+function printCreated(ctx, s, heading) {
+  ctx.ui.result(
+    s,
+    [heading, `${labelOf(s)}: "${firstLine(s.prompt)}"`, upcomingLine(s), `Manage: syndai schedule show ${s.id}`].join("\n"),
+  );
+  return EXIT.OK;
+}
+
+// --- commands ------------------------------------------------------------------------------
+
+export async function schedule(ctx, [action, ...rest]) {
+  const handler = ACTIONS[action];
+  if (!handler) {
+    throw new CliError(EXIT.USAGE, "Usage: syndai schedule list|show|add|edit|pause|resume|run-now|delete", {
+      next: "syndai schedule list",
+    });
+  }
+  return handler(ctx, rest);
+}
+
+const ACTIONS = {
+  async list(ctx) {
+    const { flags, ui } = ctx;
+    if (flags.all && flags.app) throw new CliError(EXIT.USAGE, "Pick one of --app and --all.");
+    const project = flags.all ? null : await resolveProject(ctx, { app: flags.app });
+    const schedules = await listAll(ctx, project ? { coding_repository_id: project.id } : {});
+    const where = project ? projectLabel(project) : "any project";
+    ui.result(
+      { project_id: project?.id ?? null, schedules },
+      schedules.length
+        ? schedules.map(row).join("\n")
+        : `Nothing repeats on ${where} yet. Add one: syndai schedule add "<what>" --every daily`,
+    );
+    return EXIT.OK;
+  },
+
+  async show(ctx, [ref]) {
+    const id = await scheduleId(ctx, ref);
+    const detail = await ctx.client.call("getSchedule", { params: { schedule_id: id } });
+    ctx.ui.result(detail, card(detail.schedule, detail.occurrences));
+    return EXIT.OK;
+  },
+
+  async add(ctx, words) {
+    const { flags } = ctx;
+    const prompt = words.join(" ").trim();
+    if (!prompt) throw new CliError(EXIT.USAGE, 'Say what to run: syndai schedule add "<what>" --every daily');
+    const trigger = triggerOf(ctx, flags);
+    const budget = budgetOf(flags.budget, { allowNone: false });
+    const project = await resolveProject(ctx, { app: flags.app });
+    const created = await create(ctx, {
+      prompt,
+      coding_repository_id: project.id,
+      trigger,
+      ...(budget === undefined ? {} : { occurrence_budget_usd: budget }),
+    });
+    return printCreated(ctx, created, `Repeats on ${projectLabel(project)}.`);
+  },
+
+  async edit(ctx, [ref]) {
+    const { client, flags, ui } = ctx;
+    const id = await scheduleId(ctx, ref);
+    if ([flags.prompt, flags.every, flags.at, flags.tz, flags.budget].every((v) => v === undefined)) {
+      throw new CliError(EXIT.USAGE, "Nothing to change: pass --prompt, --every, --at, --tz or --budget.");
+    }
+    if (flags.at !== undefined && flags.every === undefined) {
+      throw new CliError(EXIT.USAGE, "--at goes with --every (the cadence it sets the time of).");
+    }
+    const { schedule: current } = await client.call("getSchedule", { params: { schedule_id: id } });
+    const patch = {};
+    if (flags.prompt !== undefined && flags.prompt !== current.prompt) patch.prompt = flags.prompt;
+    if (flags.every !== undefined || flags.tz !== undefined) {
+      const zone = timeZoneOf({ tz: flags.tz ?? current.trigger.timezone });
+      const expr = flags.every === undefined ? current.trigger.expr : cronFor(flags, ctx.io.now(), zone);
+      if (expr !== current.trigger.expr || zone !== current.trigger.timezone) {
+        patch.trigger = { kind: "cron", expr, timezone: zone };
+      }
+    }
+    const budget = budgetOf(flags.budget, { allowNone: true });
+    if (budget !== undefined && budget !== (current.occurrence_budget_usd ?? null)) {
+      patch.occurrence_budget_usd = budget;
+    }
+    if (Object.keys(patch).length === 0) {
+      ui.result(current, `Nothing changed. ${row(current)}`);
+      return EXIT.OK;
+    }
+    const updated = await client.call("updateSchedule", { params: { schedule_id: id }, body: patch });
+    ui.result(updated, `Updated. ${row(updated)}`);
+    return EXIT.OK;
+  },
+
+  async pause(ctx, [ref]) {
+    const id = await scheduleId(ctx, ref);
+    const s = await ctx.client.call("pauseSchedule", { params: { schedule_id: id } });
+    ctx.ui.result(s, `Paused. ${row(s)}`);
+    return EXIT.OK;
+  },
+
+  async resume(ctx, [ref]) {
+    const id = await scheduleId(ctx, ref);
+    const s = await ctx.client.call("resumeSchedule", { params: { schedule_id: id } });
+    ctx.ui.result(s, `Resumed. ${row(s)}`);
+    return EXIT.OK;
+  },
+
+  async "run-now"(ctx, [ref]) {
+    const id = await scheduleId(ctx, ref);
+    const res = await ctx.client.call("runScheduleNow", { params: { schedule_id: id }, raw: true });
+    if (res.status >= 400 && res.status !== 409) throw new ApiError(res.status, res.body, res.headers);
+    const already = res.status === 409;
+    ctx.ui.result(
+      { schedule_id: id, started: !already, already_started: already },
+      `${already ? "It already started this minute." : "Started."} Its run shows in: syndai schedule show ${id}`,
+    );
+    return EXIT.OK;
+  },
+
+  async delete(ctx, [ref]) {
+    const { flags, ui, io } = ctx;
+    const id = await scheduleId(ctx, ref);
+    if (!flags.yes) {
+      if (!ui.interactive) {
+        throw new CliError(EXIT.USAGE, "Deleting a schedule needs --yes when nobody can confirm it.", {
+          next: `syndai schedule delete ${id} --yes`,
+        });
+      }
+      const answer = await ask(io, `Delete schedule ${id.slice(0, 8)} and its history? [y/N] `);
+      if (!/^y/i.test(answer)) {
+        ui.result({ schedule_id: id, deleted: false }, "Kept.");
+        return EXIT.OK;
+      }
+    }
+    await ctx.client.call("deleteSchedule", { params: { schedule_id: id } });
+    ui.result({ schedule_id: id, deleted: true }, "Deleted.");
+    return EXIT.OK;
+  },
+};
+
+/**
+ * Repeat a run: the server copies its original prompt and project (`from_coding_run_id`).
+ * The first run is the next scheduled time, never now: re-running a run that just finished
+ * would charge twice.
+ */
+export async function repeat(ctx, [runId]) {
+  const { client, flags } = ctx;
+  if (!runId) throw new CliError(EXIT.USAGE, "Which run? syndai repeat <run> --every weekly");
+  const trigger = triggerOf(ctx, flags);
+  const budget = budgetOf(flags.budget, { allowNone: false });
+  const { run } = await client.call("getRun", { params: { coding_run_id: runId } });
+  const created = await create(ctx, {
+    from_coding_run_id: runId,
+    trigger,
+    ...(budget === undefined ? {} : { occurrence_budget_usd: budget }),
+  });
+  const cost = typeof run.cost_usd === "number" ? ` (last run cost $${run.cost_usd.toFixed(2)})` : "";
+  return printCreated(
+    ctx,
+    created,
+    `Repeating "${firstLine(run.title ?? run.prompt)}"${cost}. First run ${when(created.upcoming?.[0], created.trigger.timezone)}.`,
+  );
+}

package/src/settings.js

@@ -1,4 +1,4 @@
-// `syndai settings` (one project's owner settings) and `syndai api` (the escape hatch).
+// `syndai settings`: one project's owner settings.
 //
 // Settings live in four places server-side:
 //   autonomy          repo-scoped policy default       GET/PUT policy/defaults
@@ -128,33 +128,3 @@ async function orNull(promise) {
     throw err;
   }
 }
-
-export async function api(ctx, [method, target]) {
-  const { client, flags, io, ui } = ctx;
-  const verb = method?.toUpperCase();
-  if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(verb) || !target) {
-    throw new CliError(EXIT.USAGE, "Usage: syndai api <METHOD> <path> [--json body]", {
-      next: "syndai api GET /runs",
-    });
-  }
-  const full = target.startsWith("/api/") ? target : `/api/v1/external/coding/${target.replace(/^\/+/, "")}`;
-  const [pathOnly, search = ""] = full.split("?");
-  let body;
-  if (typeof flags.json === "string") {
-    try {
-      body = JSON.parse(flags.json);
-    } catch {
-      throw new CliError(EXIT.USAGE, "--json must be valid JSON.");
-    }
-  }
-  const res = await client.send(verb, pathOnly, {
-    query: Object.fromEntries(new URLSearchParams(search)),
-    body,
-    raw: true,
-  });
-  io.stdout.write(`${JSON.stringify(res.body, null, ui.json ? 0 : 2)}\n`);
-  if (res.status < 400) return EXIT.OK;
-  const { exitCode, message } = explain(new ApiError(res.status, res.body, res.headers));
-  ui.progress(`error: ${message}`);
-  return exitCode;
-}

package/src/store.js

@@ -2,6 +2,7 @@
 //   $XDG_CONFIG_HOME/syndai/credentials.json  keys, by workspace (customer), mode 0600
 //   $XDG_CONFIG_HOME/syndai/links.json        directory -> project
 //   $XDG_STATE_HOME/syndai/pending/*.json     a change's request id, written BEFORE its POST
+//   $XDG_CACHE_HOME/syndai/openapi-<host>.json the live API description (24h)
 
 import fs from "node:fs";
 import { homedir } from "node:os";
@@ -14,11 +15,13 @@ export function storePaths(env) {
   const home = env.HOME || homedir();
   const config = path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), "syndai");
   const state = path.join(env.XDG_STATE_HOME || path.join(home, ".local", "state"), "syndai");
+  const cache = path.join(env.XDG_CACHE_HOME || path.join(home, ".cache"), "syndai");
   return {
     home,
     credentials: path.join(config, "credentials.json"),
     links: path.join(config, "links.json"),
     pending: path.join(state, "pending"),
+    cache,
   };
 }
 

package/src/ui.js

@@ -5,6 +5,8 @@
 
 import { spawn } from "node:child_process";
 import { getRandomValues } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
 import { createInterface } from "node:readline";
 import { CliError, EXIT } from "./errors.js";
 import { interrupted } from "./http.js";
@@ -131,3 +133,24 @@ export function hostOf(url) {
     return null;
   }
 }
+
+export async function readAll(stream) {
+  let text = "";
+  for await (const chunk of stream) text += chunk;
+  return text;
+}
+
+/** `--input FILE|-` as parsed JSON (`-` reads stdin). */
+export async function readJsonInput(io, source) {
+  let text;
+  try {
+    text = source === "-" ? await readAll(io.stdin) : readFileSync(path.resolve(io.cwd, source), "utf8");
+  } catch (err) {
+    throw new CliError(EXIT.USAGE, `Cannot read --input ${source} (${err.code ?? err.message}).`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new CliError(EXIT.USAGE, `--input ${source} is not valid JSON.`);
+  }
+}

package/src/watch.js

@@ -14,7 +14,7 @@ const MIN_POLL_GAP_MS = 1000;
 const DEADLINE_GRACE_MS = 2000;
 const TIMED_OUT = Symbol("timed out");
 
-// Exit code per ChangeState state (docs: cli.mdx "Exit codes").
+// Exit code per ChangeState state (docs: syndai.ai/docs/cli, "Exit codes").
 const STATE_EXIT = {
   needs_input: EXIT.NEEDS_YOU,
   held: EXIT.NEEDS_YOU,
@@ -202,11 +202,18 @@ async function askInput(ctx, input) {
     }
   }
   ui.progress(input.prompt);
-  for (const [i, option] of options.entries()) ui.progress(`  ${i + 1}. ${option.label}`);
+  const defaults = new Set(input.default_option_ids ?? []);
+  for (const [i, option] of options.entries()) {
+    ui.progress(`  ${i + 1}. ${defaults.has(option.id) ? "[x] " : ""}${option.label}`);
+  }
   const multi = input.kind === "multi_choice";
   const hint = multi ? "numbers, comma-separated" : "a number";
+  const keep = defaults.size ? ", Enter keeps [x]" : "";
   for (;;) {
-    const answer = await ask(io, `Pick ${hint}${textAllowed ? " or type an answer" : ""}${optional}: `);
+    const answer = await ask(io, `Pick ${hint}${textAllowed ? " or type an answer" : ""}${keep}${optional}: `);
+    if (!answer && defaults.size) {
+      return { input_id: input.input_id, selected_option_ids: options.filter((o) => defaults.has(o.id)).map((o) => o.id) };
+    }
     if (!answer && !input.required) return null;
     const picks = answer.split(",").map((part) => Number(part.trim()) - 1);
     const valid = picks.every((i) => Number.isInteger(i) && options[i]) && (multi || picks.length === 1);