makersclaw 0.8.0 → 0.8.2

package/templates/next/files/check/automation-package.ts

@@ -0,0 +1,142 @@
+// Copied from claw shared/src/automation-package.ts @ 33de2374. Never edit; refresh with scripts/sync-automation-format.mjs.
+/**
+ * An app package's automations (docs/AUTOMATIONS-PLAN.md phase 9, "App
+ * packages, and members editing them").
+ *
+ * What an app ships: `automations` in `app/makersclaw.json` and
+ * `store.json` `seeds.automations` (the same list, as `actions` is). Each
+ * entry is a definition (format 1, ./automation.ts) plus ONE field that is
+ * not part of it:
+ *
+ *   replaces_wake   the name of a legacy wake (`seeds.wakes`) this
+ *                   automation takes over. Adopt and the Update switch that
+ *                   wake off, so the job never fires twice, and the lift
+ *                   (phase 5) stops showing it. It lives in the package,
+ *                   not in the definition: the definition is what a member
+ *                   edits and what the three-way merge hashes, and "which
+ *                   old wake this replaces" is neither.
+ *
+ * One function checks the whole list, for every door that takes a package
+ * in: the template's `npm run check`, the store's `publish.mjs`, the
+ * registry sync and the install.
+ *
+ * Standalone, with no runtime import, so the template and the store can
+ * load a copy under plain node (type stripping): the format's own module
+ * is handed in as `fmt` (`import * as fmt from "./automation.ts"`), and
+ * only its TYPES are imported here (erased).
+ */
+import type { AutomationDef, Problem, ValidateOptions, validateAutomation, walkSteps, CODE_STEP_KINDS } from "./automation.js";
+
+export interface PackageAutomation {
+  automation: AutomationDef;
+  replaces_wake: string | null;
+}
+
+/** The pieces of `./automation.ts` this file calls. */
+export interface FormatModule {
+  validateAutomation: typeof validateAutomation;
+  walkSteps: typeof walkSteps;
+  CODE_STEP_KINDS: typeof CODE_STEP_KINDS;
+}
+
+export interface PackageContext {
+  /** The app's declared action names (`seeds.actions`). An `action` step
+   *  must name one. Absent: not checked. */
+  actionNames?: ReadonlySet<string> | null;
+  /** The output shape of an action (from its declaration), if known. */
+  actionShape?: ValidateOptions["actionShape"];
+  /** The package's wakes. `replaces_wake` must name a scheduled one
+   *  (advance or review): an event wake is fired by the app and the
+   *  engine does not claim its receipts yet. Absent: not checked. */
+  wakes?: readonly { name: string; kind?: string | null }[] | null;
+  /** The kinds of account a `tool` step may ask for (connection
+   *  categories). Absent: not checked. */
+  categories?: ReadonlySet<string> | null;
+  cronCheck?: ValidateOptions["cronCheck"];
+}
+
+export const PACKAGE_AUTOMATIONS_MAX = 20;
+/** A package's whole `automations` list, as JSON. */
+export const PACKAGE_AUTOMATIONS_BYTES = 400 * 1024;
+const WAKE_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]{0,59}$/;
+
+export type PackageResult = { ok: true; entries: PackageAutomation[] } | { ok: false; problems: Problem[] };
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/**
+ * Every rule for a package's list: the list's shape, unique keys, each
+ * definition through `validateAutomation` (the kinds an engine runs), the
+ * declared actions, the kinds of account, and `replaces_wake`. Problems name
+ * the entry: `automations[1] (friday-review).steps[0].action`.
+ */
+export function validatePackageAutomations(raw: unknown, ctx: PackageContext, fmt: FormatModule): PackageResult {
+  const problems: Problem[] = [];
+  const add = (path: string, message: string) => problems.push({ path, message });
+  if (raw === undefined || raw === null) return { ok: true, entries: [] };
+  if (!Array.isArray(raw)) return { ok: false, problems: [{ path: "automations", message: "automations is a list" }] };
+  if (raw.length > PACKAGE_AUTOMATIONS_MAX) add("automations", `at most ${PACKAGE_AUTOMATIONS_MAX} automations; this package ships ${raw.length}`);
+  let bytes = 0;
+  try {
+    bytes = JSON.stringify(raw).length;
+  } catch {
+    add("automations", "only JSON values");
+  }
+  if (bytes > PACKAGE_AUTOMATIONS_BYTES) add("automations", `the list is ${Math.round(bytes / 1024)} KB; at most ${Math.round(PACKAGE_AUTOMATIONS_BYTES / 1024)} KB`);
+  const entries: PackageAutomation[] = [];
+  const keys = new Set<string>();
+  const taken = new Map<string, string>();
+  raw.slice(0, PACKAGE_AUTOMATIONS_MAX).forEach((item, i) => {
+    const key = isObject(item) && typeof item.key === "string" ? item.key : null;
+    const where = key ? `automations[${i}] (${key})` : `automations[${i}]`;
+    if (!isObject(item)) return add(where, "an automation is a JSON object");
+    const { replaces_wake: replaces, ...definition } = item;
+    let replacesWake: string | null = null;
+    if (replaces !== undefined && replaces !== null) {
+      if (typeof replaces !== "string" || !WAKE_NAME.test(replaces)) add(`${where}.replaces_wake`, "replaces_wake is the name of one of the package's wakes");
+      else {
+        replacesWake = replaces;
+        const wake = ctx.wakes?.find((w) => w.name === replaces);
+        if (ctx.wakes && !wake) {
+          const names = ctx.wakes.map((w) => w.name);
+          add(`${where}.replaces_wake`, `"${replaces}" is not a wake of this package${names.length ? ` (its wakes: ${names.join(", ")})` : " (it has none)"}`);
+        } else if (wake && (wake.kind ?? "advance") === "event") {
+          add(`${where}.replaces_wake`, `"${replaces}" is an event wake: the app fires it, and an automation does not take its events yet`);
+        }
+        const other = taken.get(replaces);
+        if (other) add(`${where}.replaces_wake`, `"${replaces}" is already replaced by "${other}"`);
+        else taken.set(replaces, key ?? String(i));
+      }
+    }
+    const checked = fmt.validateAutomation(definition, {
+      kinds: fmt.CODE_STEP_KINDS,
+      ...(ctx.actionNames !== undefined ? { actionNames: ctx.actionNames } : {}),
+      ...(ctx.actionShape ? { actionShape: ctx.actionShape } : {}),
+      ...(ctx.cronCheck ? { cronCheck: ctx.cronCheck } : {}),
+    });
+    if (!checked.ok) {
+      for (const p of checked.problems) add(p.path ? `${where}.${p.path}` : where, p.message);
+      return;
+    }
+    const def = checked.automation;
+    if (keys.has(def.key)) add(`${where}.key`, `"${def.key}" is used by another automation of this package`);
+    keys.add(def.key);
+    const categories = ctx.categories;
+    fmt.walkSteps(def.steps, (s) => {
+      // An app's own automation acts on its own app (A4): it never names another.
+      if (s.kind === "action" && s.app) add(`${where}.steps.${s.id}.app`, "a package's automation runs its own app's actions: leave app out");
+      if (categories && s.kind === "tool" && !categories.has(s.needs.category)) {
+        add(`${where}.steps.${s.id}.needs`, `"${s.needs.category}" is not a kind of account (${[...categories].join(", ")})`);
+      }
+    });
+    entries.push({ automation: def, replaces_wake: replacesWake });
+  });
+  return problems.length ? { ok: false, problems } : { ok: true, entries };
+}
+
+/** Problems as one line each, for a refusal's text. */
+export function packageProblemLines(problems: readonly Problem[], max = 8): string[] {
+  const lines = problems.slice(0, max).map((p) => (p.path ? `${p.path}: ${p.message}` : p.message));
+  if (problems.length > max) lines.push(`and ${problems.length - max} more`);
+  return lines;
+}