nikos 0.0.6 → 0.1.0

package/dist/planning/krs.js

@@ -0,0 +1,73 @@
+// Key results in planning/krs/<id>.yaml: a baseline, a target and a date, and dated
+// check-ins that are only ever added to. Revising the target keeps the original.
+import { join } from "node:path";
+import { BET_ID } from "../lib/bets.js";
+import { DATE, checkKr, describeErrors, krText, loadKr, paths, today, writePlanning } from "./model.js";
+function checked(data) {
+    if (!checkKr(data))
+        throw new Error(`Not a valid key result: ${describeErrors(checkKr.errors).join("; ")}`);
+    return data;
+}
+export function newKr(input, root) {
+    if (!BET_ID.test(input.id))
+        throw new Error(`'${input.id}' is not a key result id (lowercase words joined by hyphens)`);
+    if (!input.title?.trim())
+        throw new Error("A key result needs a title (--title)");
+    if (!input.owner?.trim())
+        throw new Error("A key result needs an owner (--owner)");
+    if (!Number.isFinite(input.baseline) || !Number.isFinite(input.target))
+        throw new Error("A key result needs a numeric --baseline and --target");
+    if (!DATE.test(input.by ?? ""))
+        throw new Error("A key result needs a date (--by YYYY-MM-DD)");
+    const data = checked({
+        id: input.id,
+        title: input.title.trim(),
+        ...(input.objective ? { objective: input.objective } : {}),
+        owner: input.owner.trim(),
+        ...(input.unit !== undefined ? { unit: input.unit } : {}),
+        baseline: input.baseline,
+        target: input.target,
+        original_target: input.target,
+        by: input.by,
+        ...(input.alignsTo ? { aligns_to: input.alignsTo } : {}),
+        ...(input.staleAfterDays ? { stale_after_days: input.staleAfterDays } : {}),
+        checkins: [],
+    });
+    return writePlanning(root, join(paths(root).krs, `${input.id}.yaml`), krText(data), { create: true });
+}
+/** Add a dated check-in. Earlier check-ins are never changed. */
+export function checkIn(root, id, c) {
+    if (!Number.isFinite(c.value))
+        throw new Error("A check-in needs a numeric value");
+    const kr = loadKr(root, id);
+    const data = structuredClone(kr.data);
+    data.checkins = [
+        ...(data.checkins ?? []),
+        { date: c.date ?? today(), value: c.value, ...(c.note?.trim() ? { note: c.note.trim() } : {}), ...(c.evidence?.trim() ? { evidence: c.evidence.trim() } : {}) },
+    ];
+    return writePlanning(root, join(paths(root).krs, `${id}.yaml`), krText(checked(data)), { expect: c.expect ?? kr.hash });
+}
+/** Move the target. The original target stays recorded. */
+export function reviseTarget(root, id, target, expect) {
+    if (!Number.isFinite(target))
+        throw new Error("A target is a number");
+    const kr = loadKr(root, id);
+    const data = structuredClone(kr.data);
+    data.original_target ??= data.target;
+    data.target = target;
+    return writePlanning(root, join(paths(root).krs, `${id}.yaml`), krText(checked(data)), { expect: expect ?? kr.hash });
+}
+export const latest = (kr) => (kr.checkins?.length ? kr.checkins[kr.checkins.length - 1] : undefined);
+const days = (from, to) => Math.round((Date.parse(to) - Date.parse(from)) / 86_400_000);
+/** Stale when the last check-in (or, with none, nothing at all) is older than stale_after_days (default 14). */
+export function isStale(kr, on = today()) {
+    const last = latest(kr);
+    if (!last)
+        return true;
+    return days(last.date, on) > (kr.stale_after_days ?? 14);
+}
+/** Progress from baseline toward target, 0..1 (can pass 1). Works for targets below the baseline too. */
+export function progress(kr) {
+    const v = latest(kr)?.value ?? kr.baseline;
+    return kr.target === kr.baseline ? 1 : (v - kr.baseline) / (kr.target - kr.baseline);
+}

package/dist/planning/model.js

@@ -0,0 +1,164 @@
+// The planning/ folder: bet cards, key results and the planning context. Every write in
+// the pack (command line and dashboard) goes through here, so both get the same checks.
+import Ajv2020Module from "ajv/dist/2020.js";
+const Ajv2020 = Ajv2020Module.default ?? Ajv2020Module;
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Document, parse } from "yaml";
+import { parseFrontMatter } from "../lib/frontmatter.js";
+import { walk } from "../lib/project.js";
+const here = dirname(fileURLToPath(import.meta.url));
+// Works from src/ (tests) and dist/ (published): schemas sit at the package root.
+const schemaDir = [join(here, "../../schemas/planning"), join(here, "../schemas/planning")].find((d) => existsSync(d));
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+const schema = (name) => ajv.compile(JSON.parse(readFileSync(join(schemaDir, name), "utf8")));
+export const checkBet = schema("bet.schema.json");
+export const checkKr = schema("kr.schema.json");
+export const checkPlan = schema("plan.schema.json");
+export const DATE = /^\d{4}-\d{2}-\d{2}$/;
+export const today = () => new Date().toISOString().slice(0, 10);
+/** The repo root holding planning/ (and usually intent/): a repo root, or planning/ itself. */
+export function findRoot(start) {
+    const abs = resolve(start);
+    return basename(abs) === "planning" && !existsSync(join(abs, "planning")) ? dirname(abs) : abs;
+}
+export const paths = (root) => ({
+    planning: join(root, "planning"),
+    bets: join(root, "planning", "bets"),
+    krs: join(root, "planning", "krs"),
+    plan: join(root, "planning", "plan.yaml"),
+    views: join(root, "planning", "views"),
+    upstream: join(root, "planning", "upstream.yaml"),
+    lock: join(root, "planning", "upstream.lock"),
+    cache: join(root, ".nikos", "upstream"),
+    intent: join(root, "intent"),
+});
+export const hash = (text) => createHash("sha256").update(text).digest("hex").slice(0, 16);
+export function describeErrors(errors) {
+    return (errors ?? []).map((e) => {
+        const at = e.instancePath.replace(/^\//, "").split("/").join(".") || "(root)";
+        if (e.keyword === "additionalProperties")
+            return `${at === "(root)" ? "" : at + ": "}unknown field '${e.params.additionalProperty}'`;
+        if (e.keyword === "required")
+            return `${at === "(root)" ? "" : at + ": "}missing required field '${e.params.missingProperty}'`;
+        if (e.keyword === "enum")
+            return `${at} must be one of ${e.params.allowedValues.join(", ")}`;
+        return `${at} ${e.message}`;
+    });
+}
+/** A file inside planning/, refusing anything that would land outside it. */
+export function inside(root, ...parts) {
+    const base = paths(root).planning;
+    const path = resolve(base, ...parts);
+    if (path !== base && !path.startsWith(base + sep))
+        throw new Error(`Refusing to write outside planning/: ${parts.join("/")}`);
+    return path;
+}
+export class StaleError extends Error {
+    constructor(file) {
+        super(`${file} changed on disk since it was loaded; reload and try again`);
+    }
+}
+/** Write a planning file. With `expect`, refuse if the file on disk isn't the version that was loaded. */
+export function writePlanning(root, path, text, opts = {}) {
+    const rel = relative(root, path);
+    if (!path.startsWith(paths(root).planning + sep))
+        throw new Error(`Refusing to write outside planning/: ${rel}`);
+    if (opts.expect !== undefined) {
+        const current = existsSync(path) ? hash(readFileSync(path, "utf8")) : "";
+        if (current !== opts.expect)
+            throw new StaleError(rel);
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    try {
+        writeFileSync(path, text, opts.create ? { flag: "wx" } : undefined);
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            throw new Error(`${rel} already exists`);
+        throw err;
+    }
+    return rel;
+}
+const yamlText = (data, flow = []) => {
+    const doc = new Document(data);
+    for (const key of flow) {
+        const node = doc.getIn(key.split("."), true);
+        if (node && typeof node === "object" && "flow" in node)
+            node.flow = true;
+    }
+    return doc.toString({ lineWidth: 0, flowCollectionPadding: false });
+};
+export const betText = (meta, body) => `---\n${yamlText(meta, ["krs.also", "dependencies"])}---\n${body}`;
+export const krText = (data) => yamlText(data);
+export function loadBet(root, id) {
+    const path = join(paths(root).bets, `${id}.md`);
+    if (!existsSync(path))
+        throw new Error(`No bet called '${id}' (planning/bets/${id}.md)`);
+    const text = readFileSync(path, "utf8");
+    const fm = parseFrontMatter(text);
+    if (!fm)
+        throw new Error(`planning/bets/${id}.md has no front matter`);
+    return { meta: fm.meta, body: fm.body, file: relative(root, path), hash: hash(text) };
+}
+export function loadKr(root, id) {
+    const path = join(paths(root).krs, `${id}.yaml`);
+    if (!existsSync(path))
+        throw new Error(`No key result called '${id}' (planning/krs/${id}.yaml)`);
+    const text = readFileSync(path, "utf8");
+    return { data: parse(text), file: relative(root, path), hash: hash(text) };
+}
+export const betIds = (root) => walk(paths(root).bets, ".md").map((p) => basename(p, ".md")).sort();
+export const krIds = (root) => walk(paths(root).krs, ".yaml").map((p) => basename(p, ".yaml")).sort();
+export function loadPlan(root) {
+    const p = paths(root).plan;
+    return existsSync(p) ? parse(readFileSync(p, "utf8")) : undefined;
+}
+/** Check every planning file against its schema and the links between them. */
+export function validatePlanning(root) {
+    const issues = [];
+    const krs = new Set(krIds(root));
+    const plan = loadPlan(root);
+    if (plan !== undefined && !checkPlan(plan))
+        for (const m of describeErrors(checkPlan.errors))
+            issues.push({ file: "planning/plan.yaml", message: m });
+    for (const id of krIds(root)) {
+        let kr;
+        try {
+            kr = loadKr(root, id);
+        }
+        catch (err) {
+            issues.push({ file: `planning/krs/${id}.yaml`, message: err.message.split("\n")[0] });
+            continue;
+        }
+        if (!checkKr(kr.data))
+            for (const m of describeErrors(checkKr.errors))
+                issues.push({ file: kr.file, message: m });
+        else if (kr.data.id !== id)
+            issues.push({ file: kr.file, message: `id '${kr.data.id}' doesn't match the file name` });
+    }
+    for (const id of betIds(root)) {
+        let bet;
+        try {
+            bet = loadBet(root, id);
+        }
+        catch (err) {
+            issues.push({ file: `planning/bets/${id}.md`, message: err.message.split("\n")[0] });
+            continue;
+        }
+        if (!checkBet(bet.meta)) {
+            for (const m of describeErrors(checkBet.errors))
+                issues.push({ file: bet.file, message: m });
+            continue;
+        }
+        if (bet.meta.id !== id)
+            issues.push({ file: bet.file, message: `id '${bet.meta.id}' doesn't match the file name` });
+        for (const ref of [bet.meta.krs.primary, ...(bet.meta.krs.also ?? [])].filter(Boolean)) {
+            if (!ref.includes("#") && !krs.has(ref))
+                issues.push({ file: bet.file, message: `links key result '${ref}', which has no planning/krs/${ref}.yaml` });
+        }
+    }
+    return issues;
+}

package/dist/planning/server.js

@@ -0,0 +1,336 @@
+// The local planning dashboard: a server on 127.0.0.1 that shows the planning/ folder and
+// saves through the same model functions as the command line. Every save needs the token
+// printed at start; the static pages and the export need none. Also the one-file export and
+// the contract custom views are written against.
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { renderMap, storyMapOf } from "../commands/map.js";
+import { BET_ID } from "../lib/bets.js";
+import { editBet, reviewBet } from "./bets.js";
+import { delivery, describeDelivery } from "./delivery.js";
+import { checkIn, isStale, latest, progress } from "./krs.js";
+import { betIds, krIds, loadBet, loadKr, loadPlan, paths, StaleError, today } from "./model.js";
+import { loadUpstream } from "./upstream.js";
+import { renderDashboard } from "./ui.js";
+const MAX_BODY = 100_000;
+const VIEW_NAME = /^[a-z0-9-]+$/;
+const VIEW_FILE = /^[a-z0-9-]+\.html$/;
+const HTML = "text/html; charset=utf-8";
+const JS = "application/javascript; charset=utf-8";
+/** What a custom view can rely on. Keep this in step with VIEW_SCRIPT and the save kinds below. */
+export const VIEW_CONTRACT = `# Custom planning views
+
+A custom view is a page at planning/views/<name>.html (lowercase letters, digits and hyphens). It is served at /views/<name>, and the server adds /nikos-view.js and the dashboard token to it.
+
+window.nikos.data(): Promise<object>
+  The dashboard data: { project, today, plan, krs, bets, story, upstream, views, problems }.
+  krs[]: id, title, owner, unit, baseline, target, by, latest, latestValue, progress, stale, hash, checkins, upstream.
+  bets[]: id, owner, team, hypothesis, krs, starts, review_on, deadline, confidence, outcome, reviews, body, hash, delivery, releases.
+  upstream[] is read-only: plans synced from other repos. Never save to it.
+
+window.nikos.save(kind, payload): Promise<{ wrote: string }>
+  "checkin": { id, expect, value, note?, evidence? }
+  "bet": { id, expect, fields: { owner?, team?, hypothesis?, starts?, review_on?, deadline?, confidence?, dependencies?, outcome? } }
+  "review": { id, expect, decision: "continue" | "change" | "stop" | "complete", reason, outcome?: "won" | "lost" }
+
+expect is the hash of the item as data() returned it. A save rejected with status 409 means the file changed on disk: call data() again and apply the change to the new version. Other rejections carry the reason. Saves only ever write inside planning/.
+`;
+/** The script every custom view gets. It saves through the same endpoints, with the same token and hash checks. */
+const VIEW_SCRIPT = `(function () {
+  var meta = document.querySelector('meta[name="nikos-token"]');
+  var token = meta ? meta.getAttribute('content') : (new URLSearchParams(location.search).get('token') || '');
+  var paths = { checkin: '/api/checkin', bet: '/api/bet', review: '/api/review' };
+  window.nikos = {
+    data: function () {
+      return fetch('/api/data').then(function (r) {
+        if (!r.ok) throw new Error('Could not load the planning data (HTTP ' + r.status + ')');
+        return r.json();
+      });
+    },
+    save: function (kind, payload) {
+      var path = paths[kind];
+      if (!path) return Promise.reject(new Error('Unknown save kind "' + kind + '": use checkin, bet or review'));
+      return fetch(path, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-Nikos-Token': token },
+        body: JSON.stringify(payload || {})
+      }).then(function (r) {
+        return r.json().catch(function () { return {}; }).then(function (body) {
+          if (!r.ok) {
+            var err = new Error(body.error || 'HTTP ' + r.status);
+            err.status = r.status;
+            throw err;
+          }
+          return body;
+        });
+      });
+    }
+  };
+})();
+`;
+/** The upstream KR a KR aligns to, found in the read-only copies. */
+function upstreamRef(upstream, ref) {
+    if (!ref)
+        return null;
+    const [repo, id] = ref.split("#");
+    const plan = upstream.find((u) => u.repo === repo);
+    const kr = plan?.krs?.find((k) => k.id === id) ?? null;
+    return { ref, repo, commit: plan?.commit ?? null, found: kr !== null, kr, readOnly: true };
+}
+/** Everything the views need, as JSON. Files that fail to load are listed in `problems`, not thrown. */
+export function planningData(root) {
+    const plan = loadPlan(root) ?? null;
+    const story = storyMapOf(root);
+    const upstream = loadUpstream(root);
+    const problems = [];
+    const krs = krIds(root).flatMap((id) => {
+        try {
+            const kr = loadKr(root, id);
+            const d = kr.data;
+            const last = latest(d) ?? null;
+            return [
+                {
+                    id: d.id ?? id,
+                    title: d.title,
+                    objective: d.objective ?? "",
+                    owner: d.owner,
+                    unit: d.unit ?? "",
+                    baseline: d.baseline,
+                    target: d.target,
+                    original_target: d.original_target,
+                    by: d.by,
+                    stale_after_days: d.stale_after_days ?? 14,
+                    aligns_to: d.aligns_to ?? null,
+                    checkins: d.checkins ?? [],
+                    latest: last,
+                    latestValue: last ? last.value : d.baseline,
+                    progress: progress(d),
+                    stale: isStale(d),
+                    hash: kr.hash,
+                    file: kr.file,
+                    upstream: upstreamRef(upstream, d.aligns_to),
+                },
+            ];
+        }
+        catch (err) {
+            problems.push(err.message.split("\n")[0]);
+            return [];
+        }
+    });
+    const bets = betIds(root).flatMap((id) => {
+        try {
+            const bet = loadBet(root, id);
+            const m = bet.meta;
+            const d = delivery(root, id);
+            return [
+                {
+                    id: m.id ?? id,
+                    owner: m.owner,
+                    team: m.team ?? "",
+                    hypothesis: m.hypothesis,
+                    krs: { primary: m.krs?.primary ?? null, also: m.krs?.also ?? [] },
+                    starts: m.starts ?? null,
+                    review_on: m.review_on,
+                    deadline: m.deadline ?? null,
+                    confidence: m.confidence,
+                    dependencies: m.dependencies ?? [],
+                    outcome: m.outcome,
+                    reviews: m.reviews ?? [],
+                    body: bet.body.trim(),
+                    hash: bet.hash,
+                    file: bet.file,
+                    delivery: { ...d, text: describeDelivery(d) },
+                    releases: d.releases.map((n) => ({
+                        number: n,
+                        title: story.releases.find((r) => r.number === n)?.title ?? `Release ${n}`,
+                        href: `/map#release-${n}`,
+                    })),
+                },
+            ];
+        }
+        catch (err) {
+            problems.push(err.message.split("\n")[0]);
+            return [];
+        }
+    });
+    const viewsDir = paths(root).views;
+    const views = existsSync(viewsDir)
+        ? readdirSync(viewsDir)
+            .filter((f) => VIEW_FILE.test(f))
+            .map((f) => f.slice(0, -".html".length))
+            .sort()
+        : [];
+    return {
+        project: plan?.name ?? (story.project || basename(root)),
+        today: today(),
+        plan,
+        krs,
+        bets,
+        story: { activities: story.activities, releases: story.releases, unreleased: story.unreleased },
+        upstream,
+        views,
+        problems,
+    };
+}
+/** Write the whole dashboard as one offline HTML file. Warns first when other repos' plans are inside. */
+export function exportSnapshot(root, file) {
+    const out = resolve(file);
+    const upstream = loadUpstream(root);
+    const warned = upstream.length > 0;
+    if (warned) {
+        const names = upstream.map((u) => u.repo).join(", ");
+        process.stderr.write(`! This snapshot includes plans from other repos (${names}); share it only with people allowed to see them.\n`);
+    }
+    writeFileSync(out, renderDashboard({ data: planningData(root), readOnly: true }));
+    return { wrote: out, warned };
+}
+/** Start the dashboard on 127.0.0.1 with a fresh token. The url carries the token for the browser. */
+export async function startServer(root, opts = {}) {
+    const token = randomBytes(24).toString("hex");
+    let port = 0;
+    const server = createServer((req, res) => {
+        route(root, token, port, req, res).catch((err) => send(res, 500, { error: err.message }));
+    });
+    await new Promise((ok, fail) => {
+        server.once("error", fail);
+        server.listen(opts.port ?? 0, "127.0.0.1", () => ok());
+    });
+    port = server.address().port;
+    return {
+        url: `http://127.0.0.1:${port}/?token=${token}`,
+        token,
+        port,
+        close: () => new Promise((ok) => {
+            server.closeAllConnections();
+            server.close(() => ok());
+        }),
+    };
+}
+/** `nikos planning serve`: run the dashboard until Ctrl+C, or export it to one file. */
+export async function runServe(root, opts = {}) {
+    if (opts.exportTo) {
+        const { wrote } = exportSnapshot(root, opts.exportTo);
+        console.log(`Wrote ${wrote}`);
+        return 0;
+    }
+    const srv = await startServer(root, { port: opts.port });
+    console.log(`nikOS planning dashboard: ${srv.url}`);
+    console.log(`Saves write to ${relative(process.cwd(), paths(root).planning) || "planning"}/ only. Press Ctrl+C to stop.`);
+    return new Promise((ok) => {
+        const stop = () => {
+            srv.close().then(() => ok(0));
+        };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    });
+}
+function send(res, status, body, type = "application/json; charset=utf-8") {
+    const text = typeof body === "string" ? body : JSON.stringify(body);
+    res.writeHead(status, { "content-type": type, "cache-control": "no-store", "x-content-type-options": "nosniff" });
+    res.end(text);
+}
+const sameToken = (given, token) => {
+    const a = Buffer.from(given), b = Buffer.from(token);
+    return a.length === b.length && timingSafeEqual(a, b);
+};
+async function route(root, token, port, req, res) {
+    // Only this machine's own address: a page on another site can't reach the dashboard by DNS rebinding.
+    if (req.headers.host !== `127.0.0.1:${port}` && req.headers.host !== `localhost:${port}`) {
+        return send(res, 403, { error: "The dashboard only answers on its own address on this machine" });
+    }
+    const path = new URL(req.url ?? "/", "http://127.0.0.1").pathname;
+    if (req.method === "GET")
+        return serveGet(root, token, path, res);
+    if (req.method === "POST" && SAVES.has(path))
+        return saveRequest(root, token, path, req, res);
+    return send(res, 404, { error: "Not found" });
+}
+function serveGet(root, token, path, res) {
+    if (path === "/")
+        return send(res, 200, renderDashboard({ data: planningData(root), token, readOnly: false }), HTML);
+    if (path === "/api/data")
+        return send(res, 200, planningData(root));
+    if (path === "/map")
+        return send(res, 200, renderMap(root), HTML);
+    if (path === "/nikos-view.js")
+        return send(res, 200, VIEW_SCRIPT, JS);
+    const m = /^\/views\/([^/]+)$/.exec(path);
+    if (m && VIEW_NAME.test(m[1])) {
+        const file = join(paths(root).views, `${m[1]}.html`);
+        if (existsSync(file))
+            return send(res, 200, withViewScript(readFileSync(file, "utf8"), token), HTML);
+    }
+    return send(res, 404, { error: "Not found" });
+}
+/** Add the token and the contract script to a custom view's page. */
+function withViewScript(html, token) {
+    const tags = `<meta name="nikos-token" content="${token}"><script src="/nikos-view.js"></script>`;
+    return /<\/head>/i.test(html) ? html.replace(/<\/head>/i, `${tags}</head>`) : tags + html;
+}
+const numberOf = (v) => (typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v) : NaN);
+const textOf = (v) => (typeof v === "string" ? v : undefined);
+const SAVES = new Map([
+    ["/api/checkin", (root, b) => checkIn(root, b.id, { value: numberOf(b.value), note: textOf(b.note), evidence: textOf(b.evidence), expect: b.expect })],
+    [
+        "/api/bet",
+        (root, b) => {
+            if (!b.fields || typeof b.fields !== "object" || Array.isArray(b.fields))
+                throw new Error("fields must be an object of bet fields to change");
+            return editBet(root, b.id, b.fields, b.expect);
+        },
+    ],
+    ["/api/review", (root, b) => reviewBet(root, b.id, { decision: b.decision, reason: textOf(b.reason) ?? "", outcome: b.outcome, expect: b.expect })],
+]);
+class TooLarge extends Error {
+}
+function readBody(req) {
+    return new Promise((ok, fail) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (c) => {
+            size += c.length;
+            if (size > MAX_BODY)
+                return fail(new TooLarge("The request is too large"));
+            chunks.push(c);
+        });
+        req.on("end", () => ok(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", fail);
+    });
+}
+async function saveRequest(root, token, path, req, res) {
+    const given = req.headers["x-nikos-token"];
+    if (typeof given !== "string" || !sameToken(given, token)) {
+        return send(res, 403, { error: "Missing or wrong token. Open the dashboard from the link nikos planning serve printed." });
+    }
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch (err) {
+        res.setHeader("connection", "close");
+        return send(res, err instanceof TooLarge ? 413 : 400, { error: err.message });
+    }
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        return send(res, 400, { error: "The request body must be JSON" });
+    }
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return send(res, 400, { error: "The request body must be a JSON object" });
+    if (typeof body.id !== "string" || !BET_ID.test(body.id))
+        return send(res, 400, { error: `'${String(body.id)}' is not an id` });
+    if (typeof body.expect !== "string")
+        return send(res, 400, { error: "expect (the hash of the version you loaded) is required. Reload the dashboard." });
+    try {
+        return send(res, 200, { wrote: SAVES.get(path)(root, body) });
+    }
+    catch (err) {
+        if (err instanceof StaleError)
+            return send(res, 409, { error: err.message });
+        return send(res, 400, { error: err.message.split("\n")[0] });
+    }
+}