@augurworks/augur 0.15.2 → 0.15.4

package/scripts/lib/marks.mjs

@@ -1,107 +0,0 @@
-// Working marks, client side — one definition of the path spelling and one of the phrasing.
-//
-// `F-presence-marks`. Three commands surface marks (`mark`, `status`, `pull`) and a fourth
-// will. If each spelled a path its own way, two agents naming the same folder would write
-// two rows and read past each other — which is the exact failure the feature exists to
-// prevent, arriving through the tool that was supposed to prevent it. So the normalization
-// here MIRRORS `normalizeMarkPath` in src/_worker.js on purpose, and the server's answer is
-// always the one printed back: the client never assumes its own spelling won.
-//
-// ⚠️ A MARK REFUSES NOTHING. Nothing in this file returns a verdict, sets an exit code, or
-// gives a caller something to branch on that would let it block. It reads, and it prints.
-
-/** Leading and trailing slash. Same rule as the worker, for the same containment reason. */
-export function normalizeMarkPath(p) {
-  const s = String(p == null ? "" : p).trim().slice(0, 300);
-  if (!s) return "";
-  const t = s.replace(/^\.\//, "").replace(/\/{2,}/g, "/");
-  if (!t || t === "/") return "/";
-  return `/${t.replace(/^\/+/, "").replace(/\/+$/, "")}/`;
-}
-
-/**
- * A REPO folder, as the URL it publishes to.
- *
- * `<project>/prototypes/<name>` is the nesting `discoverSpaces()` looks in, and it is
- * served at `/<project>/<name>/`. An agent has just been editing the folder, so it is the
- * folder it will type; taking it without translation would mark a path no card and no
- * published unit will ever match.
- */
-export function markPathFor(input) {
-  return normalizeMarkPath(String(input == null ? "" : input).replace(/\/prototypes\//g, "/"));
-}
-
-/** Does either path contain the other? The whole overlap test. */
-export function marksOverlap(a, b) {
-  const x = normalizeMarkPath(a), y = normalizeMarkPath(b);
-  if (!x || !y) return false;
-  return x === y || x.startsWith(y) || y.startsWith(x);
-}
-
-/**
- * Of the marks that were there before you wrote yours, whose are worth telling you about.
- *
- * ⚠️ "SOMEBODY ELSE" IS DECIDED BY WHO, NEVER BY WHERE, and this function exists so that
- * decision has somewhere to be tested. The obvious way to stop your own renewal warning at
- * you is to drop the exact path from the list — and that silently drops the ONE case the
- * whole feature exists to surface: two agents on the same prototype. It shipped that way
- * once and printed nothing at all for an exact collision, which is worse than not having
- * the warning, because it reads as an all-clear.
- *
- * `mine` is the id the INSTANCE resolved from the credential and handed back, never one the
- * client worked out for itself — the same rule the row's authorship follows.
- */
-export function othersOverlapping(before, path, mine) {
-  return (before || []).filter((m) => m && m.personId !== mine && marksOverlap(m.path, path));
-}
-
-/**
- * Every live mark at an instance. NEVER THROWS: a `status` or a `pull` that died because
- * the coordination note could not be fetched would make the note the most fragile thing in
- * the toolchain. An older instance answers 404 and gets an empty list, which reads exactly
- * like "nobody is working on anything" — and is the right answer there, because on that
- * instance nobody can be.
- */
-export async function fetchMarks(req) {
-  try {
-    const r = await req("_marks/list");
-    const body = await r.json();
-    return Array.isArray(body.marks) ? body.marks : [];
-  } catch (e) { return []; }
-}
-
-const plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
-
-/** "4 minutes ago" / "just now", from a millisecond age. */
-export function since(ms) {
-  const s = Math.max(0, Math.round(ms / 1000));
-  if (s < 45) return "just now";
-  if (s < 5400) return `${plural(Math.round(s / 60), "minute")} ago`;
-  return `${plural(Math.round(s / 3600), "hour")} ago`;
-}
-
-/**
- * "for another 6 minutes", from a millisecond remainder.
- *
- * Switches to hours at exactly 3600s rather than at the 90 minutes `since` uses, because
- * a mark's ceiling IS an hour: at the other threshold the longest mark anybody can ask
- * for would read "for another 60 minutes", and the hours branch could never fire at all.
- */
-export function forAnother(ms) {
-  const s = Math.max(0, Math.round(ms / 1000));
-  if (s < 60) return `for another ${plural(s, "second")}`;
-  if (s < 3600) return `for another ${plural(Math.round(s / 60), "minute")}`;
-  return `for another ${plural(Math.round(s / 3600), "hour")}`;
-}
-
-/**
- * One line per mark. `by` is null when the id behind the mark resolves to nobody on the
- * roster — a token an admin labelled by hand, or somebody who has since left — and
- * "Someone" is the honest rendering of that, never a guess.
- */
-export function markLine(m) {
-  const who = m.by || "Someone";
-  const started = Date.parse(m.startedAt);
-  const age = Number.isFinite(started) ? since(Date.now() - started) : "";
-  return `${m.path}  ${who}${age ? ` · started ${age}` : ""} · ${forAnother(m.expiresIn)}`;
-}

package/scripts/mark.mjs

@@ -1,112 +0,0 @@
-#!/usr/bin/env node
-/**
- * augur mark — say what you are about to work on, and read what everyone else is.
- *
- *   augur mark                       what is being worked on right now
- *   augur mark <path> [--ttl <s>]    leave a mark on it, then start
- *   augur mark <path> --clear        take yours down early
- *   augur mark … --json              the same answer, for a tool to read
- *
- * `F-presence-marks`. Nothing anywhere said what was already being worked on. Two agents
- * on two machines, both told to improve the checkout flow, would each open the folder,
- * each edit it, and find out at publish time — where the answer is a fork and a conflict
- * file nobody asked for.
- *
- * ⚠️ THIS IS NOT A LOCK AND IT MUST NEVER BECOME ONE. Marking a path grants nothing and
- * refuses nothing: a marked path can still be edited, published and shipped by anybody, and
- * this command exits 0 whatever it finds. The protocol is social and it is one sentence —
- * READ THE MARKS BEFORE YOU START, LEAVE ONE WHEN YOU DO. What happens when coordination
- * fails anyway is the composed publish's problem, and it settles it on evidence rather than
- * on a claim.
- *
- * ⚠️ AND IT EXPIRES BY ITSELF. A mark carries how long it is good for — ten minutes by
- * default, an hour at the most — and the instance stops reporting it the moment that
- * passes, whether or not anything ever clears it. That is the point rather than a detail:
- * the thing leaving marks is a process that can be killed, and a claim that outlives the
- * claimant is worse than no claim at all. `--clear` is a courtesy, never the guarantee.
- *
- * A path is a URL path (`/checkout/flow/`). A repo folder is accepted and translated, so
- * `checkout/prototypes/flow` — the folder you were just editing — marks the URL it
- * publishes to. The line printed back is always the instance's own spelling.
- */
-import { target, apiClient } from "./lib/store.mjs";
-import { fetchMarks, markPathFor, othersOverlapping, markLine, forAnother } from "./lib/marks.mjs";
-
-const C = { dim: "\x1b[2m", ok: "\x1b[32m", warn: "\x1b[33m", off: "\x1b[0m" };
-const log = (m) => console.log(`\x1b[35m[mark]\x1b[0m ${m}`);
-const die = (m) => { console.error(`\x1b[31m[mark] ${m}\x1b[0m`); process.exit(1); };
-
-const argv = process.argv.slice(2);
-const flag = (n) => argv.includes(n);
-const opt = (n, d = null) => { const i = argv.indexOf(n); return i > -1 && argv[i + 1] ? argv[i + 1] : d; };
-const JSON_OUT = flag("--json");
-const CLEAR = flag("--clear");
-const positional = argv.filter((a, i) => !a.startsWith("--") && !(i > 0 && argv[i - 1] === "--ttl"));
-
-async function main() {
-  const { origin, token } = target({ needToken: true });
-  const req = apiClient(origin, token);
-
-  const raw = positional[0] || "";
-  const path = raw ? markPathFor(raw) : "";
-  if (raw && !path) die(`"${raw}" is not a path anything could be working on.`);
-
-  // ── list ──────────────────────────────────────────────────────────────────
-  if (!path) {
-    const marks = await fetchMarks(req);
-    if (JSON_OUT) { console.log(JSON.stringify({ origin, marks }, null, 2)); return; }
-    if (!marks.length) { log(`${C.dim}nobody is working on anything at ${origin} right now${C.off}`); return; }
-    log(`being worked on at ${origin}:`);
-    for (const m of marks) console.log(`  ${markLine(m)}`);
-    console.log(`\n${C.dim}Nothing here stops you. Pick a different path, or go ahead and expect to merge.${C.off}`);
-    return;
-  }
-
-  // ── clear ─────────────────────────────────────────────────────────────────
-  if (CLEAR) {
-    const r = await req("_marks/clear", {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ path }),
-    });
-    const body = await r.json();
-    if (JSON_OUT) { console.log(JSON.stringify({ origin, path, ...body }, null, 2)); return; }
-    if (body.cleared) log(`${C.ok}${path} released${C.off}`);
-    else if (body.reason === "not-yours") log(`${C.dim}${path} is somebody else's mark — left alone. It expires on its own.${C.off}`);
-    else log(`${C.dim}no mark of yours on ${path}${C.off}`);
-    return;
-  }
-
-  // ── set ───────────────────────────────────────────────────────────────────
-  const ttlArg = opt("--ttl");
-  const ttl = ttlArg ? Math.round(Number(ttlArg) * 1000) : undefined;
-  if (ttlArg && !Number.isFinite(ttl)) die(`--ttl takes seconds, not "${ttlArg}".`);
-
-  // WHO ELSE IS ALREADY HERE — read BEFORE writing, because that is the whole protocol and
-  // an agent that only ever writes is an agent that has learned nothing. Taken before the
-  // write and not after: the write replaces the row for this path, so a read afterwards
-  // could no longer see the person this is worth telling you about.
-  const before = await fetchMarks(req);
-
-  const r = await req("_marks/set", {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ path, ...(ttl ? { ttl } : {}) }),
-  });
-  const body = await r.json();
-  if (body.error) die(`${origin} refused the mark: ${body.error}`);
-
-  // Who was already here that is not you. The rule, and the trap inside it, are on
-  // `othersOverlapping` — it is a pure function precisely so the trap has a test.
-  const overlapping = othersOverlapping(before, body.mark.path, body.mark.personId);
-
-  if (JSON_OUT) { console.log(JSON.stringify({ origin, overlapping, ...body }, null, 2)); return; }
-  log(`${C.ok}${body.mark.path}${C.off} marked ${forAnother(body.mark.expiresIn)}`);
-  if (overlapping.length) {
-    console.log(`\n  ${C.warn}somebody is already working here${C.off}`);
-    for (const m of overlapping) console.log(`  ${markLine(m)}`);
-    console.log(`\n${C.dim}Your mark went down anyway — marks never refuse. Pick a different path, wait it out, or carry on knowing you will be merging.${C.off}`);
-  }
-}
-
-main().catch((e) => die(e && e.stack ? e.stack : String(e)));